This reference will explain the uses of SimGroups. First some info on SimGroups:

Info about Objects:

Everything the game tracks, from visibile objects such as armors to vehicles to projectiles, to invisible objects such as clients and triggers are tracked by identification numbers. That's what's passed in %obj, and created as %p (in the case of projectiles). From the id number, the game can look up the info needed for any object, as long as that object still exists.

What is a SimGroup?

SimGroups are how the engine groups pretty much every object in the game. All Simgroups are created with names, hence they can all be called via thier name or ID number.

First, some common groups to be aware of that I've found. Just about every object you can search for using TypeMasks can be found in specific groups, or subgroups of those groups. All objects that can be destroyed, including all deployables, armors, projectiles, vehicles, ect can be found in the 'MissionCleanup' group. Deployables can be derived from MissionCleanup/Deployables or direcly from Deployables. All static objects associated with teams, such as base interiors, permanent sensors stations and turrets, ect can be found in subgroups of groups 'Team1' and 'Team2' (oddly, vehicle pads are found in MissionCleanup, though the interior around them are a part of Team1 or Team2). Terrain can be found simply by its name 'Terrain' or in the group 'MissionGroup' (which also has the sky, and a couple others). Also, every client connected to the game can be found in ClientGroup.

Now that we have some common groups, here's functions used to deal with them: (Note: in place of GroupName, type in the name of the group. such as MissionCleanup);

GroupName.getCount() returns how many objects are in a group, this counts any subgroups in this group as an object.

GroupName.getObject(count) returns the object id of any object in the group (where count is a number between 0 and one less then the total number of objects in the group, use getCount() to get the total).

GroupName.getID() return the identification number of the group. (Note: This can also be used to get id's from the name of objects such as Terrain.getID());

GroupName.getGroup() returns the ID number of the parent group, assuming there is one. (Note: this can also be used on objects to get the group they belong to).

GroupName.isMember(object) returns a true or false based on whether the object is already a member of the group (where object is the ID number of an object). Use this to prevent console errors when adding or removing objects from groups if they exist in it already or not.

isObject(Object) returns a true or false based on whether the object still exists (where object is the ID number of an object). Use this first as a check to prevent console spam where objects may have been deleted.

getType() returns the type an object is (such as certain number represents VehicleObjectTypes). This is important to groups, because subgroups are the only objects I'm aware of to return a Type = 0. You can use this to tell which objects are subgroups inside a group.

ID.getName() returns the name of an object or group if it has one. Say you want to know the name of the group an object belongs to, use this: %obj.getGroup().getName();

Next, let's look at creating our own SimGroups:

new SimGroup(GroupName); creates a new SimGroup of name GroupName (replace GroupName with whatever you want to call it).

GroupName.add(object); adds the object to the group (where Object is the ID number of the object). You may have noticed this command when creating projectiles as other objects as MissionCleanup.add(%p).

GroupName.remove(object); removes the object from the group (where Object is the ID number of the object).

So, why are simgroups important to me?

Well, depending on how deep you get into them, they may have no importance, or may have a lot. The reason I discovered them was because I wanted to create new search types beyond initContainerRadiusSearch and containerRayCast, but to do it, I had to have a way to look up all objects of specific types. Now I have a way to find the objects, and even pre-group them into my own groups when the mission loads, so they can be easily searched through when needed. Also, I have used SimGroups for searching for both forcefields and deployables in my bunker tut.

Now a simple example on working with SimGroups. This will look through all clients and add them to your own team groups based on what team they're on. Note, this only creates the groups once, you would need additional checks if people changed teams or quit after this is run to keep it updated. And, considering you can dynamically make up teams at any time by simply looking at all the clients in ClientGroup, this function actually has little use.

function createInitialTeams()
{
   new SimGroup(Team1Players);
   new SimGroup(Team2Players);
   new SimGroup(Observers);
   for (%i = 0 ; %i < ClientGroup.getCount(); %i++)
   {
      %obj = ClientGroup.getObject(%i);
      if (isObject(%obj))
      {
         if (%obj.team == 1)
         {
            if (!(Team1Players.isMember(%obj)))
               Team1Players.add(%obj);
         }
         else if (%obj.team == 2)
         {
            if (!(Team2Players.isMember(%obj)))
               Team2Players.add(%obj);
         }
         else
         {
            if (!(Observers.isMember(%obj)))
               Observers.add(%obj);
         }
      }
   }
}