groupSizes[]

An array of group sizes...

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...

Iterating through the groupSizes array...

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:

Fast way to find next free group...

// 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):

Slower way to find next free group...

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