Other great resources: Official JS API docs, Scripting Forum
groupSizes[]
- Aubergine
Â
Syntax
// size of a group var size = groupSizes[id]; // will throw error if element missing  // next available group ID var numGroups = groupSizes.length;
Properties
Property | Type | Mandatory | Description | Game version |
---|---|---|---|---|
id | Number | Specify the group ID that you want to query the size of (see "Notes" below for important information). | 3.2 | |
length | Number | Returns the next available group ID, which can be used to create a completely new group. | 3.2 |
Return values
Value | Type | Notes | Game version |
---|---|---|---|
<size> | Number | If the group id has been used, it's current size is returned as an integer that is ≥ 0. | 3.2 |
undefined | Undefined | The array element exists, but that group has never been used. | 3.2 |
<error> | ReferenceError | The array element does not exist and therefore it's value cannot be referenced. | 3.2 |
Notes
The groupSizes[]
global is a "sparse" array – there might be gaps in the numbering of it's elements, which means that groupSizes.length
is not representative of the number of groups you've actually used.
All elements up to groupSizes.length - 1
 will be defined, but only groups that have been used will have a numeric value (the others will have a value of undefined
).
It's recommended to use the forEach() method when iterating the array (see example below).
Note also that groups defined in labels.ini will have negative indices in the array (which I'm not sure if .forEach() will process?).
Example
The .forEach() method simplifies iteration of sparse arrays – it will skip any undefined
elements...
groupSizes.forEach( function get(groupSize, groupID) { // any unused groups will be skipped, so this // groupID has been used, and groupSize will be ≥ 0 } );
When you need a new group, you can either use newGroup() or simply add stuff to a group that doesn't yet exist:
// add a structure to a new group var newGroup = groupSizes.length;  groupSizes[newGroup]; // ReferenceError - no such element  groupAdd(newGroup, someStructure);  groupSizes[newGroup]; // 1  groupSizes.length; // == newGroup + 1
If you want to find the next free group that's already defined, you can do something like this (not recommended):
var i = 0, nextUnused = groupSizes.length;  while (i < nextUnused) { (typeof groupSizes[i] != "number") ? nextUnused = i : ++i; }  // 'nextUnused' now contains the numeric ID of the next unused group  groupAdd(nextUnused, someObject); // create group by adding someObject to it
Availability 3.2+
Requires:
- Warzone 3.2 and above.
Earlier versions:
- Warzone 3.1 – use groupSize() instead
Contents
Jump to:
Scripting: Groups
Related Objects:
 Create them:
- newGroup() – create a new group
- WZ 3.2+ – add to a group that doesn't exist yet
- labels.ini – group map-placed objects
Add things to them:
- groupAdd() – add any Game object
- groupAddDroid() – add a Droid object
- groupAddArea() – add Game objects within an area of the map
Remove things from them:
- Put them in some other group
Count objects in them:
- groupSize() – get number of items in a group
- groupSizes[] – iterate group sizes
List them:
- groupSizes[] – elements are group ids
- getObject() – retrieve a group by its label
Retrieve their objects:
- enumGroup() – retrieve objects in a group
Monitor them:
- eventGroupLoss() – triggers when an object is removed from a group
Remove them:
- not currently possible
Â