AddCommand

Category: Objects / Commands
Since engine version: 4.6.5.0 CP (extended in 4.9.1.0 GWE) (extended in 4.9.5.0 CE)

Description

Adds a command to the top of the command stack of an object (also see AppendCommand). This command will be executed first, then the object will continue with the existing commands. If the command stack is empty, AddCommand does the same as SetCommand.
For the list of commands see SetCommand

Syntax

bool AddCommand (object pObj, string szCommand, object pTarget, int iX, int iY, object pTarget2, int iInterval, any Data, int iRetries, int iBaseMode);

Parameters

pObj:
Object for which the command is given.
szCommand:
Command name (as string). See the table below
pTarget:
[opt] target object for the command
iX:
[opt] X target coordinate
iY:
[opt] Y target coordinate
pTarget2:
[opt] secondary target object
iInterval:
[opt] Time (in ticks or frames) until the command is automatically aborted. Execution will continue with the next command in the stack.
Data:
[opt] additional data for the command
iRetries:
[opt] Number of retries if the command fails, until the command fails completely.
iBaseMode:
[opt] Determines the behaviour if the command fails.

iBaseMode Name Description Failure messages and CallFailed calls Next command
0 C4CMD_SilentSub Silent command Only if this is the last command Fails
3 C4CMD_Sub Command If the next command has no retries left or this is the last command Fails
2 C4CMD_SilentBase Silent base command Never Does not fail
1 C4CMD_Base Base command Always Does not fail

Remark

Commands added using AddCommand are not passed to controlled vehicles (see VehicleControl).

Example

Timer:
  var obj = FindObject(0, -20, -40, 40, 40, OCF_CrewMember();
  if(obj)
    if(GetComDir(obj) == COMD_Right())
      AddCommand(obj, "Jump");
  return();
If called from an object on the ground, this timer script makes any clonk passing the object from left to right jump. To do this, crew member objects are searched above the object. If one is found and he is moving from left to right (ComDir), he is given a 'Jump' command. Notice that this does not affect the previously set commands of the clonk - after completing the jump command, the clonk will continue with his previous commands. Using this script, you could e.g. ensure that clonks will always jump a given gap in the landscape.
See also: AppendCommand, FinishCommand, GetCommand, PlayerObjectCommand, SetCommand
PeterW, November 2001
Günther, Januar 2005