Page tree
Skip to end of metadata
Go to start of metadata

Introduced in



Description:Applies a custom formation to a group.

Formations can only be selected for the "AWARE", "COMBAT", or "STEALTH" behaviors (see behaviour). For "CARELESS" and "SAFE" behaviors, the AI always moves in a column formation. Wheeled vehicles ignore formation in "AWARE", and must be in "COMBAT", or "STEALTH" to move in formation. If the group leader changes direction, it takes a while for the group to catch up with them, and for everyone to be in the correct formation position again (not functional in V2.00 - V2.08).


Syntax:grp setCustomFormation formation
  • grp: Group - Group to which the formation is applied.
  • formation: Array - Array of formation definitions, one for each group member, in relation to the leader: [x-offset, y-offset, z-offset, view direction]. If no view direction is specified, units look into the formation direction. If no formation definition exists for a group member, they  stay in the original formation. An empty formation array resets the formation for the whole group, and it is required to select default formations again.
Return Value:Nothing

Alternative Syntax

Syntax:grp setCustomFormation [formation, soldiers, update] (V3.7+)
  • grp: Group - Group to which the formation is applied.
  • formation: Array - Array of formation definitions (see default syntax for details).
  • soldiers: Array of Object - List of units to use for the custom formation. Their order in the array corresponds to the positions defined in formation . If units are in group grp , but are not specified in the soldiers  array, then they stay in their default formation.
  • update: Boolean - If true, and a unit specified in the soldiers array dies (or is removed from the group), then any unassigned units in group grp take over its place. If false, then the formation place of the dead unit stays empty (optional, default: true). 
Return Value:Nothing


Aligns 3 members on the right of the leader, with different view directions:
groupOne setCustomFormation [[2,0,0,90],[4,0,0,180],[6,0,0,270]];

Use units u2, u4, u8, and u9, to create a square formation around the leader, with each one looking into a different direction:
(group u1) setCustomFormation [[[-10,10,0,315], [10,10,0,45], [10,-10,0,135], [-10,-10,0,135]], [u2, u4, u8, u9]];

Reset the formation to default:
groupOne setCustomFormation []

Mission to demonstrate the use of custom formations:

Additional Information

See also: Nothing