groupAddArea()

Overview

Add all your droids (with some exceptions) in a specific area of the map to a group.

You can only add your own droids to your own groups. You can't add your droids to other players' groups, or their droids to your groups.

Also, some specific types of droid won't be added to the group:

DROID_COMMAND – A commander unit, to which other units can be assigned.
DROID_TRANSPORTER – A cyborg transporter (or possibly a super transporter in Warzone 3.1 Beta 4 and earlier), capable of airlifting droids to some other location on the map.
DROID_SUPERTRANSPORTER – A heavy transport unit, capable of airlifting any type of droid (including VTOLs) to some other location on the map...

This is really useful because it means you can find the location of a commander/transporter then calculate an area around them, grab all droids in that area and assign them to a commander or embark them on a transport, etc.

Availability

Warzone 3.1 Beta 1 and above.

Syntax

groupAddArea(group, x1, y1, x2, y2);

Parameters

Parameter	Type	Description	Game version
group	Number	The unique ID of the group. The ID is the return value of the newGroup() function called when creating the group.	3.1 Beta 1
x1	Number	The x co-ordinate of the top-left corner	3.1 Beta 1
y1	Number	The y co-ordinate of the top-left corner	3.1 Beta 1
x2	Number	The x co-ordinate of the bottom-right corner	3.1 Beta 1
y2	Number	The y co-ordinate of the bottom-right corner	3.1 Beta 1

Return value

Value	Type	Description	Game version
`undefined`	Undefined	The droids, if any, were added to the group	3.1 Beta 1
<error>	Error	Either the group doesn't exist, you don't own the group, or you don't own the droid.	3.1 Beta 1

Example

Respond heavily to attacks every so often

// note: I've not tested this code yet
if (!DORDER_DROIDREPAIR) {
  const DORDER_DROIDREPAIR = 26; // not currently defined by JS API
}
 
var unusedGroup = newGroup();
var localGroup = newGroup();

var lastResponseTime = gameTime;
 
function eventAttacked(victim, attacker) {
  var responseGroup;
  // only do this sort of support response once per minute (60s = 60000ms)
  if (gameTime - lastResponseTime > 60000) {
    // ensure we don't do this again for a while:
    lastResponseTime = gameTime;
    // clear our localGroup by moving any droids in it to the unusedGroup:
    enumGroup(localGroup).forEach(
      function(droid) {
        groupAddDroid(droid,unusedGroup);
      }
    );
    // now get droids local to the attack
    groupAddArea(localGroup,victim.x-20,victim.y-20,victim.x+20,victim.y+20);
    // attack the attacker, repair the victim:
    responseGroup = enumGroup(localGroup);
    if (!responseGroup.length) {
      // might want to call in external support?
    } else {
      responseGroup.forEach(
        function(droid) {
          // is the droid healthy enough to participate?
          if (droid.health < 40) return; // skip badly damaged droids
          // can our droid attack the enemy?
          if (droid.droidType == DROID_WEAPON || droid.droidType == DROID_CYBORG) {
            if ( (isVTOL(attacker) && !!droid.canHitAir) || ((!isVTOL(attacker)) && droid.canHitLand) ) {
              orderDroidObj(droid,DORDER_ATTACK,attacker);
            }
          }
          // is it worth repairing victim & can our droid repair the victim?
          if (victim.health < 80) {
            if (victim.type == STRUCTURE && droid.droidType == DROID_CONSTRUCT) {
              orderDroidObj(droid,DORDER_REPAIR,victim);
            } else if (victim.type == DROID && droid.droidType == DROID_REPAIR) {
              orderDroidObj(droid,DORDER_DROIDREPAIR,victim);
            }
          }
        }
      );
    }
  }
}