Groups

What are groups?

Groups are collections of Game objects. There are several benefits to using groups instead of custom arrays:

• Objects will be removed from groups automatically if they are destroyed or moved to another group
• Groups allow rapid access to the objects within them via enumGroup(), whereas custom arrays would require lots of function calls
• Groups persist the save/load cycle, whereas custom arrays would prove problematic
• Map-placed objects can be grouped and exposed to scripts via Labels (retrieve a Group Object using getObject()).

Note: Groups in the scripting environment are not the same as groups that a human player can set, they do not have shortcut keys, etc.

Which objects can be grouped?

How do I create groups?

There are four ways to create groups:

• Use a map editor, like FlaME, to group objects (the groups are stored in labels.ini)
• Define them manually in the labels.ini file associated with a map
• Use the newGroup() function to create a group at runtime
• Put an object in a group that doesn't exist yet (requires Warzone 3.2 or above)

What happens if objects get destroyed or transferred?

If an object is destroyed or transferred to another player (either via Nexus Link or donateObject()) it will be removed from the group its in.

In both cases, eventGroupLoss() will be triggered.

In the case of a group object being destroyed, eventGroupLoss() will be triggered before eventDestroyed().

Are they private to my scripts?

Groups created by your script are private and only your script can see them.

Groups defined by a map (in labels.ini) are available to all players, however:

• They are copied to each script environment (so each script has it's own private copy of the group)
• Their group IDs are multiplied by -1 to avoid conflict with script-created groups.

This means that groups defined in labels.ini have negative indices in the groupSizes[] array – bear this in mind if you're iterating the array.

Are they persistent?

The groups and objects they contain will survive the save/load cycle.

When you start a new game, the original map-defined groups (in labels.ini) will be reinstated.