Controlling the Troops: SetWorkArmy, ChangeArmy

Controlling the Troops

SetWorkArmy

This procedure sets the "active army" filter for the subsequent usage in many trigger functions and procedures. It sets the currently active army for the current trigger or trigger instance.

This procedure is necessary because during the game, units can change their armies, but they keep their identifiers. Thus a captured unit that changed to a new army can still accept and execute commands coming from the old army (because of the unit's identifier). Using the procedure SetWorkArmy removes these mistakes.

It is recommended to call this procedure at the beginning of a trigger.

Functions and procedures using the "active army" are especially marked in this document.

Syntax:

SetWorkArmy <ObjectType> <ArmyID>

<ObjectType> - "ARMY"

<ArmyID> - identifier of the army (an integer constant or variable)

Example:

[Trigger]

SetWorkArmy ( ARMY , 1 )

Halt

ChangeArmy

Changes the army of the given unit set. Can be 1 unit (with the unit identifier), unit group or the whole army.

Syntax:

ChangeArmy <ObjectType> <ObjectID> <NewArmyID>

This function/procedure uses the army identifier set with the help of the procedure SetWorkArmy with no influence exerted upon ObjectType - "ARMY"

<ObjectType> - "UNIT" || "GROUP" || "ARMY"

<ObjectID> - identifier of an object of the specified type (a constant or variable)

<NewArmyID> - identifier of a new army (an integer constant or variable)

Example:

[Trigger]

ChangeArmy ( UNIT , 1 , 2 )

// Changing the army of the unit with the identifier 1 to army 2

Halt

[Trigger]

ChangeArmy ( GROUP , "Group_01" , 2 )

// Changing the army of the group with the identifier Group_01 to army 2

Halt

[Trigger]

ChangeArmy ( ARMY , 1 , 2 )

// Changing the army's identifier from 1 to 2

Halt

[Trigger]

SET @groupName = "Group_01"

SET @newArmyIndex = 2

ChangeArmy ( 'GROUP" , @groupName , @newArmyIndex )

// Changing the army of the group with the identifier Group_01 to army 2

Halt

DamageObject

Inflicts damage on an object

Syntax:

DamageObject ( <ObjectType> <ObjectID> , <dHP> )

This function/procedure uses the army identifier set with the help of the procedure SetWorkArmy with no influence exerted upon ObjectType - "ARMY"

<ObjectType> - "UNIT" || "GROUP" || "ARMY"

<ObjectID> - identifier of an object of the specified type (a constant or a name of a variable)

<dHP> - number of inflicted damage in percent.

Example:

[Trigger]

DamageObject ( UNIT , 129 , 100 )

// The object with the identification number 129 receives 100% of damage

Halt

[Trigger]

SET @unitEnemyGroupKV1 = 'Group8'

DamageObject ( GROUP , @unitEnemyGroupKV1 , 75 )

// The group of objects receives 75% of damage

Halt

Distance

Returns the distance between the specified objects

Syntax:

Distance ( <ObjectType_1> <ObjectID_1> , <ObjectType_2> < ObjectID_2>

<ObjectType> - "UNIT" || "POINT" || "RECT"

<ObjectID> - identifier of an object of the specified type (a constant or variable)

Example:

[Trigger]

Set @dist = Distance ( UNIT , 179 , POINT , 'point' )

// The local variable dist is set to the distance from the object with the identification number 179 to the named point - point

Halt

[Trigger]

SET @mainUnit = 12

SET @ptTarget = "Point0"

SET @dist = Distance ( UNIT , @mainUnit , POINT , @ptTarget )

// The local variable dist is set to the distance from the object with the identification number 12 to the named point Point0

EntityCountItems

Returns the current quantity of items in the specified object's inventory

Syntax:

EntityCountItems ( <ObjectType> <ObjectID> , <ItemSID>

<ObjectType> - "UNIT"

<ObjectID> - identifier of an object of the specified type (a constant or variable)

<ItemSID>- string identifier of an object (a string constant or variable starting with the prefix "Magazines" or "Weapons").

Example:

[Trigger]

Set @num =

EntityCountItems ( UNIT , 1 , "MagazinesGer75mm_PzGr_40_42_(APCR)" )

// The local variable num is set to the number of the magazines MagazinesGer75mm_PzGr_40_42_(APCR) kept by the unit with the identification number 1

Halt

[Trigger]

SET @unitToTest = 69

SET @num = EntityCountItems ( UNIT , @unitToTest , 'Magazines/Fr/MLE_1935S' )

Halt

// The local variable num is set to the number of the magazines Magazines/Fr/MLE_1935S kept by the unit with the identification number 69

[Trigger]

SET @weaponItemName = 'Weapons/Fr/MLE_1935S'

SET @num = EntityCountItems ( UNIT , 1 , @weaponItemName )

Halt

// The local variable num is set to the number of the guns 'Weapons/Fr/MLE_1935S' kept by the unit with the identification number 1

FireMode

Toggles the type of fire (open fire, hold fire)

Syntax:

FireMode ( <ObjectType> , <ObjectID> , <FireMode>

This function/procedure uses the army identifier set with the help of the procedure SetWorkArmy with no influence exerted upon ObjectType - "ARMY"

<ObjectType> - "UNIT" || "GROUP" || "ARMY"

<ObjectID> - identifier of an object of the specified type (a constant or variable)

<FireMode> - "FREE" || "HOLD"

Example:

[Trigger]

FireMode ( UNIT , 4 , "HOLD" )

// The unit with the identification number 4 was set to the hold fire state

Halt

[Trigger]

SET @groupVar = 'Group1'

FireMode ( GROUP , @groupVar , "FREE" )

// The group of units Group1 was allowed to shoot

Halt

GetCurrentCommand

Returns the current state (current order) of a unit, group, or army

Note: only to be used for live units

Syntax:

GetCurrentCommand ( <ObjectType> , <ObjectID>

<ObjectType> - "UNIT"

<ObjectID> - identifier of an object of the specified type (a constant or variable)

The returned value:

"ATTACK" || "ATTACK_GROUND" || "DEFEND" || "IN_CREW" || "MOVE" || "RETREAT" || "ROTATE" || "STORM" || "ATTACH" || 'DETACH'

Example:

[Trigger]

Set @command = GetCurrentCommand ( UNIT , 1 )

// The local variable command is set to the name (string) of the command being exectued by the unit with the identification number 1

Halt

[Trigger]

Set @firstUnit = 1

Set @command = GetCurrentCommand ( UNIT , @firstUnit )

// The local variable command is set to the name (string) of the command being executed by the unit with the identification number 1

Halt

GetNUnitsInArea

Returns the number of units within the given area

Syntax:

GetNUnitsInArea ( <ObjectType> <ObjectID> , <UnitType> <RectID> , <Filter>

This function/procedure uses the army identifier set with the help of the procedure SetWorkArmy with no influence exerted upon ObjectType - "ARMY"

<ObjectType> - "UNIT" || "GROUP" || "ARMY"

<ObjectID> - identifier of an object of the specified type (a constant or variable)

<UnitType> - "ALL" || "ARMOREDCAR" || "ARTILLERY" || "CAR" || "FLAK" || "FORTIFICATION" || "HMG" || "HUMAN" || "SPG" || "TANKS"

<RectID> - identifier of the bounding rectangular area (a string constant or variable)

<Filter> - set of filters separated by spaces (commas): ( "EMPTY" || "NOT_EMPTY" )

"CREW" BROKEN_WEAPON" || "OK_WEAPON" ) || ( "BROKEN_ENGINE" || "OK_ENGINE" ) || "PANIC" || "NO_PANIC"

These filters are used as follows:

The list of units within the given rectangular (area) is determined

If the filter (EMPTY (the unit is empty) || NOT_EMPTY (the unit is not empty)) is set then the list of units will count the units meeting this condition

If the filter CREW is set then the list of units is complemented by the units that are vehicle crew members or passengers

If the filter (BROKEN_WEAPON (the unit's weapon is broken) || OK_WEAPON (the unit's weapon is active)) is set then the list of units will count the units meeting this condition

If the filter (BROKEN_ENGINE (the movement is impossible) || OK_ ENGINE (the movement is possible)) is set then the list of units will count the units meeting this condition

Example:

[Trigger]

Set @num = GetNUnitsInArea ( ARMY , 1 , HUMAN , 'Rect' , CREW )

// The number of people is determined in army 1 within the rectangular named Rect including all the people who are crew members or passengers in the vehicles

Halt

[Trigger]

SET @armyID = 1

SET @result = GetNUnitsInArea ( ARMY , @armyID , ALL , 'Rect5' )

// The number of units from army 1 is determined within the rectangular "Rect5"

Halt

[Trigger]

SET @rectVar = "Rect"

Set @num = GetNUnitsInArea ( ARMY , 1 , HUMAN , @rectVar , CREW )

// The number of people is determined in army 1 within the rectangular named Rect including all the people who are crew members or passengers in the vehicles

Halt

GetNUnitsOutOfArea

Returns the number of units outside the given area

Syntax:

GetNUnitsInArea ( <ObjectType> <ObjectID> , <UnitType> <RectID> , <Filter>

This function/procedure uses the army identifier set with the help of the procedure SetWorkArmy with no influence exerted upon ObjectType - "ARMY"

<ObjectType> - "UNIT" || "GROUP" || "ARMY"

<ObjectID> - identifier of an object of the specified type (a constant or variable)

<UnitType> - "ALL" || "ARMOREDCAR" || "ARTILLERY" || "CAR" || "FLAK" || "FORTIFICATION" || "HMG" || "HUMAN" || "SPG" || "TANKS"

<RectID> - identifier of the bounding rectangular (a constant or variable)

<Filter> - set of filters separated by spaces (commas): "BROKEN_WEAPON" || "OK_WEAPON" || "BROKEN_ENGINE" || "OK_ENGINE" || "EMPTY" || "NOT_EMPTY" || "CREW" || "PANIC" || "NO_PANIC"

The filter behavior is described in paragraph 3.5.9 GetNUnitsInArea

Example:

[Trigger]

Set @num = GetNUnitsOutOfArea (GROUP , "Group" , TANKS , 'Rect' , "OK_WEAPON" )

// The number of tanks with active weapons in the group Group is determined that are outside the rectangular named Rect

Halt

[Trigger]

SET @unitID= 12

SET @result = GetNUnitsOutOfArea ( UNIT , @unitID , ALL , 'Rect' )

// It is determined whether the unit 12 is outside the rectangular "Rect" ( if the value is 1 then it is outside the rectangular )

Halt

[Trigger]

SET @rectID Rect"

SET @result = GetNUnitsOutOfArea ( GROUP , "Group" , ALL , @rectID )

// The number of units from the group Group is determined that are outside the rectangular @rectID

Halt

GetNUnits

Returns the number of units in an army or group

Syntax:

GetNUnits ( <ObjectType> <ObjectID> , <UnitType> <Filter>

This function/procedure uses the army identifier set with the help of the procedure SetWorkArmy with no influence exerted upon ObjectType - "ARMY"

<ObjectType> - "UNIT" || "GROUP" || "ARMY"

<ObjectID> - identifier of an object of the specified type (a constant or variable)

<UnitType> - "ALL" || "ARMOREDCAR" || "ARTILLERY" || "CAR" || "FLAK" || "FORTIFICATION" || "HMG" || "HUMAN" || "SPG" || "TANKS"

<Filter> - set of filters separated by spaces (commas): "BROKEN_WEAPON" || "OK_WEAPON" || "BROKEN_ENGINE" || "OK_ENGINE" || "EMPTY" || "NOT_EMPTY" || "CREW" || "PANIC" || "NO_PANIC"

The filter behavior is described in paragraph 3.5.9 GetNUnitsInArea

Example:

[Trigger]

Set @num = GetNUnits ( GROUP , "Group" , SPG , "NOT_EMPTY" , "OK_WEAPON" , "OK_ENGINE" )

// The number of SPGs in the group named Group is determined that have crews and active weapons and are able to move

Halt

[Trigger]

SET @groupVar = 'Group1'

SET @num = GetNUnits ( GROUP , @groupVar , ALL )

// The number of units is determined in the group named Group1

Halt

ObjectChangePosition

Moves a unit or a group of units to the specified point

Syntax:

ObjectChangePosition ( <ObjectType> <ObjectID> , <TargetPoint> <LookPoint>

This function/procedure uses the army identifier set with the help of the procedure SetWorkArmy with no influence exerted upon ObjectType - "ARMY"

<ObjectType>     - "UNIT" || "GROUP"

<ObjectID>    - identifier of an object of the specified type (a constant or variable)

<TargetPoint> point where the object is moved (a string constant or variable)

<LookPoint>    - point where the object is looking (a string constant or variable); this is an optional parameter

Example:

[Trigger]

ObjectChangePosition ( GROUP , "Group" , "Point" , "LookPoint" )

Halt

[Trigger]

SET @unitToChangePosition = 41

ObjectChangePosition ( UNIT , @unitToChangePosition , 'Point0' , 'Point1' )

Halt

[Trigger]

SET @positionPoint = "Point0"

ObjectChangePosition ( UNIT , 88 , @positionPoint )

Halt

[Trigger]

SET @positionPoint = "Point0"

SET @directionPoint = "Point1"

ObjectChangePosition ( UNIT , , @positionPoint , @directionPoint )

Halt

ProcessMinefield

Destroys a random object within the specified zone with the specified probability

Syntax:

ProcessMinefield ( <ObjectType> <ObjectID> , <UnitType> , <Rect> <Probability>

<ObjectType> - "UNIT" || "GROUP" || "ARMY"

<ObjectID> - identifier of an object of the specified type (a constant or variable)

<UnitType> - "ALL" || "ARMOREDCAR" || "ARTILLERY" || "CAR" || "FLAK" || "FORTIFICATION" || "HMG" || "HUMAN" || "SPG" || "TANKS"

<Rect> - named zone where a minefield is established (a string constant or variable)

<Probability> - percentage probability of an explosion

Example:

[Minefield]

Set @num = GetNUnitsInArea ( ARMY , 1 , ALL , 'Minefield_00' )

// It is determined whether units of army 1 get into the minefield rectangular (area)

if ( @num > 0 ) then

ProcessMinefield ( ARMY , 1 , ALL , 'Minefield_00' , 50 )

// The explosion process is launched for army 1 with a probability of 50%; in this case units of army 2 will move through the minefield freely

Delay )

else

Delay )

endif

[Trigger]

SET @groupToDestroy = "Group"

ProcessMinefield ( GROUP , @groupToDestroy , ALL , 'Minefield' , 75 )

// A random unit from the group Group that is within the rectangular Minefield is inflicted damage with a probability of 75%

Halt

[Trigger]

SET @rectToDestroy = 'rectToDestroyUnits'

ProcessMinefield ( ARMY , 1 , ALL , @rectToDestroy , 20 )

// A random unit from army 1 that is within the rectangular rectToDestroyUnits is inflicted damage with a probability of 20%

Halt

RunCommand

Execution of AI commands by the given objects

Syntax:

RunCommand ( <ObjectType> <ObjectID> <Command> <ArgumentType> [ <ArgumentID> ] ] , [ <DirectionType> , <direction>]

This function/procedure uses the army identifier set with the help of the procedure SetWorkArmy with no influence exerted upon ObjectType - "ARMY"

The army identifier only influences ObjectType and does not influence ArgumentType

<ObjectType> - "UNIT" || "GROUP" || "ARMY"

<ObjectID> - identifier of an object of the specified type (a constant or variable)

<Command> - type of the AI command (see the table)

<ArgumentType> - type of the argument for the AI command (see the table)

<ArgumentID> - value of the argument for the AI command (a constant or variable)

<DirectionType> - "POINT" || "ANGLE" type of the <direction> argument.

<direction> - name of the point or angle in degrees setting the formation direction

<Command> <ArgumentType>

ATTACK    POINT, RECT, UNIT, GROUP

ATTACK_GROUND    POINT (a constant or variable)

DEFEND    none (no arguments), UNIT, GROUP

IN_CREW    UNIT, GROUP

MOVE POINT, RECT

OUT_CREW    ALL, PASSENGER , CREW

RETREAT    POINT, RECT

ROTATE    POINT

STORM    POINT, RECT, UNIT, GROUP

ATTACH    UNIT

DETACH    UNIT

If a group of units executes STORM, ATTACK, MOVE or RETREAT and moves to a POINT target, it uses the formation type set by SetGroupFormation procedure. A direction of the formation is defined by the <direction> parameter.

If a group of units moves to a RECT target, the formation is not used (a random point of RECT is picked). In this case <direction> parameter is ignored.

If a group of units follows the ARRAY (a list of POINTs and RECTs), the formation set by SetGroupFormation procedure is used for the POINT elements and is not used for the RECT elements. If the first element of ARRAY is of a POINT type, the <direction> parameter defines the direction of the formation for this POINT. As for the other POINTs in the ARRAY, the direction of the formation is defined by the direction of the units' path from the previous target point.

The units formation is not constructed for a single unit and for the whole army.

Example:

[Trigger]

RunCommand ( GROUP , 'Group_01' , IN_CREW , UNIT , 5 )

// Making the group Group_01 mount into the unit with the identification number 5

RunCommand ( UNIT , 123 , ATTACK , RECT , "Rect" )

// Unit 123 attacks the rectangular named Rect

RunCommand ( ARMY , 2 , STORM , UNIT , 15 )

// Army 2 assaults the unit with the identification number 15

RunCommand ( GROUP , "Group" , MOVE , ARRAY , arWaypoints )

// Group "Group" moves its units along the arWaypoints path

RunCommand ( ARMY , 1 , DEFEND )

// Army 1 starts to defend

RunCommand ( GROUP , "Group" , OUT_CREW , PASSENGER )

// Passengers get out of the vehicles in the group Group

SET @groupToOrder = "Group"

SET @pntTarget = "Point0"

RunCommand ( GROUP , @groupToOrder , ATTACK , POINT , @pntTarget )

// The group Group attacks the point Point0

SET @groupToOrder = "Group"

SET @pntTarget = "Point0"

SET @pntDir = "Point1"

RunCommand ( GROUP , @groupToOrder , ATTACK , POINT , @pntTarget , POINT , @pntDir )

// The group Group attacks the point Point0; the formation angle at the end of the path is the same as the direction angle from the point pntTarget to the point pntDir

Halt

UnitsIsVisible

Returns the string "TRUE" if at least one of the specified units of the first set sees at least one of the units of the second set and "FALSE" otherwise

Syntax:

UnitsIsVisible ( <ObjectType_1> <ObjectID_1> <ObjectType_2> < ObjectID_2> , <UnitType_2> , <filter>

<ObjectType> - "UNIT" || "GROUP" || "ARMY"

<ObjectID> - identifier of an object of the specified type (a constant or variable)

<UnitType_2> - "ALL" || "ARMOREDCAR" || "ARTILLERY" || "CAR" || "FLAK" || "FORTIFICATION" || "HMG" || "HUMAN" || "SPG" || "TANKS" - type of the objects of the second set

<Filter> - set of filters separated by spaces (commas) for the objects of the second set: "BROKEN_WEAPON" || "OK_WEAPON" || "BROKEN_ENGINE" || "OK_ENGINE" || "EMPTY" || "NOT_EMPTY" || "CREW" || "PANIC" || "NO_PANIC"

The filter behavior is described in paragraph 3.5.9 GetNUnitsInArea

Note: it is highly recommended not to use the Army - Army check.

Attention: when UNIT/GROUP is used the additional affiliation with the required army is not verified.

Example:

[Trigger]

SET @num = UnitsIsVisible ( ARMY , 1 , GROUP , "Group" , ALL )

// The local variable num is set to the value TRUE or FALSE depending upon whether army 1 sees the group named Group

If ( @num = "TRUE" ) then

Delay )

endif

Halt

[Trigger]

SET @armyID = 1

SET @groupID = "Group"

SET @result = UnitsIsVisible ( ARMY , @armyID, GROUP , @groupID , ALL )

// The local variable result is set to the value TRUE if at least one unit of army 1 sees at least one unit of the group Group; otherwise result = FALSE

Halt

PositionMode

Sets the movement modus for a unit, group, or army

Syntax:

PositionMode ( <ObjectType> <ObjectID> <Mode>

This function/procedure uses the army identifier set with the help of the procedure SetWorkArmy with no influence exerted upon ObjectType - "ARMY"

<ObjectType> - "UNIT" || "GROUP" || "ARMY"

<ObjectID> - identifier of an object of the specified type (a constant or variable)

<Mode> - "HOLD (hold position)" || "FREE" (movement is allowed)

Example:

[Trigger]

PositionMode ( UNIT , 4 , "HOLD" )

// The unit with the identification number 4 was set to the hold position

Halt

[Trigger]

SET @groupVar = "Group"

PositionMode ( GROUP , @groupVar , FREE )

// The group of units "Group" was allowed to move

Halt

BodyMode

Sets the movement modus for a unit, group, or army (only for infantrymen)

Syntax:

BodyMode ( <ObjectType> <ObjectID> <Mode>

This function/procedure uses the army identifier set with the help of the procedure SetWorkArmy with no influence exerted upon ObjectType - "ARMY"

<ObjectType> - "UNIT" || "GROUP" || "ARMY"

<ObjectID> - identifier of an object of the specified type (a constant or variable)

<Mode> - STAY || KNEE || LAY || FREE

Example:

[Trigger]

BodyMode ( ARMY , 2 , "KNEE" )

Halt

[Trigger]

SET @UnitIDToSTAY = 29

BodyMode ( UNIT , @UnitIDToSTAY , STAY )

Halt