Script:Commands
Commands in the Arx scripting language are invoked by entity scripts to perform some action.
Contents
Syntax
commandname [-flags] [parameters...]
All underscores in the command name are ignored: _a_cool__c_o_m_m_a_n_d and acoolcommand call the same command.
Arx Libertatis includes a helper script to find uses of a command in the game's script files: find-script-command
Flags
Script commands can accept an optional set of flags denoted by a - character. Each flag is a single character and the order of the flags doesn't matter. Flags always come before all other parameters.
Parameters
Commands can have parameters following the command name, separated by white-space, ( or ). The number of parameters for a command is fixed fixed for each set of flags except for special invocations with a fixed value for the first parameter (e.g. none for some commands). This means all optional parameters need to be enabled with a flag.
The following parameters types exist:
| int | A whole number |
| number | Any number |
| string | An arbitrary string |
| text | Key for localized text |
| bool | A boolean value: on/yes or off/no
|
| entity | ID of an entity or none or self/me
|
| path | Absolute or relative path to some resource file |
| command... | One or more script commands without line breaks |
| label | The name of a label marking a script position |
| event | The name of a script event |
| variable | The name of a script variable |
Variable expansion
Parameters can be quoted or unquoted: Quoted parameters start with " and end with the next " on the same line. Unquoted start with any non-white-space character other than " parameters end at the next white-space, ( or ) character or // comment. No parameters can contain " characters or newlines.
Both quoted and unquoted parameters can contain ~variable~ expressions, which will be replaced with the contents of the given variable converted to a string. Spaces in the value will not cause it to be split into multiple parameters, even when the parameter is unquoted. Non-existent system and unset number and int variables will be replaced with 0, unset string variables will be replaced with void, and ~variable~ where variable is an invalid variable name will be replaced with variable.
Parameters expecting an int or number will automatically use the contents the given system, number or int variable if they, after ~variable~ expansion, start with ^, #, § (0xA7), & or @. This is done for both quoted and unquoted parameters. String variables starting with $ or £ (0xA3) are not automatically de-referenced without ~. All other text is converted to a 32-bit floating-point number.
Non-number parameters do not automatically de-reference any variables unless specified.
Other commands as parameters
Some commands can take another command as their last parameter. For such commands all following commands on the same line will be skipped during normal execution. Then after some action started by the command is completed these commands will be executed using the special executeline event.
Care needs to be taken when modifying scripts with such commands as the byte position of the delayed command is stored in save files.
List
The following is a (incomplete) list of supported commands.
<parameter> denotes a required parameter while [f?parameter] is an optional parameter enabled with flag -f. (a|b) means a or b.
* at the end of a parameter name indicates that the parameter is interpreted as a variable name if it, after ~variable~ expansion, starts with ^, #, § (0xA7), &, @, $ or £ (0xA3). This is always the case for int and number parameters so the * indicator is omitted for those.
| Comand | Context | Description |
|---|---|---|
| ++ <variable> | Any Entity | Increment a number or int script variable. |
| -- <variable> | Any Entity | Decrement a number or int script variable. |
| accept | Ignored | End script event execution with a positive result. |
| cameraactivate <camera> cameraactivate none | For self | Switch to a camera. |
| camerasmoothing <value> camerasmoothing none | Cameras | Set rotation smoothing when tracking a target. |
| dec <variable> <value> | Any Entity | Subtract a value from a number or int script variable. |
| div <variable> <value> | Any Entity | Divide a number or int script variable by a value. |
| else | Ignored | Skip the next command block. |
| forceangle <yaw> | Any Entity | Set the orientation. |
| forceanim <animslot> | Any Entity | Force play an animation. |
| gosub <label> | Ignored | Jump to a label and add a return point. |
| goto <label> | Ignored | Jump to a label. |
| if <needle*> iselement <haystack*> if <needle*> isin <haystack*> if <stringa*> isclass <stringb*> if <entity*> [!]isgroup <group*> if <entity*> istype <type*> if <stringa*> (==|!=) <stringb*> if <numbera*> (==|!=|<=|<|>=|>) <numberb*> | For self | Conditionally execute or skip the next command block. |
| ifexistinternal <entity> | Ignored | Skip the next command block if an entity doesn't exist in the current level. |
| ifvisible <entity> | Any Entity | Skip the next command block unless an entity is inside the cone of vision. |
| inc <variable> <value> | Any Entity | Add a value to a number or int script variable. |
| loadanim [-p] <animslot> <file> | Any Entity | Load an animation into a slot. |
| move <dx> <dy> <dz> | Any Entity | Adjust the world position. |
| mul <variable> <value> | Any Entity | Multiply a number or int script variable with a value. |
| nop | Ignored | Do nothing. |
| playanim [-123lnpe] <animslot> [e?command...] playanim [-123p] none | Any Entity | Play an animation. |
| random <chance> | Ignored | Randomly execute or skip the next command block. |
| refuse | Ignored | End script event execution with a negative result. |
| return | Ignored | Jump to just after the previous gosub command. |
| rotate <dpitch> <dyaw> <droll> | Any Entity | Adjust the orientation. |
| sendevent <event> <entity*> <parameters> sendevent -z[gfin] [g?group*] <event> <zone*> <parameters> sendevent -r[gfin] [g?group*] <event> <radius> <parameters> sendevent -g <group*> <event> <parameters> | Any Entity | Send an event to one or more entities. |
| set <variable> <value*> | Any Entity | Set a script variable. |
| setangular <enable> | Any Entity | Enables or disables angular lighting. |
| setcontrolledzone <zone> | Any Entity | Set the controlling entity of a zone. |
| setevent <event> <enable> | Any Entity | Enable or disable an event. |
| setgroup [-r] <group*> | Any Entity | Add or remove a group. |
| setmainevent <event> | Any Entity | Set an event to be sent periodically. |
| setpath [-wf] <path> setpath none | Any Entity | Start or stop following a path. |
| setstatus <event> | Any Entity | Set an event to be sent periodically. |
| spellcast [-dxmsfz] [d?duration] <level> <spell> <target> spellcast -k <spell> | Any Entity | Cast spells or cancel active spells. |
| starttimer <stopwatch> | Any Entity | Start a stopwatch. |
| stoptimer <stopwatch> | Any Entity | Stop a stopwatch. |
| unset <variable> | Any Entity | Remove a script variable. |
| unsetcontrolledzone <zone> | Ignored | Remove the controlling entity from a zone. |
| usepath <direction> | Any Entity | Change the direction to move along a path. |
Additionally, the following commands will be accepted but do nothing. They are only supported to not break older scripts.
- attachnpctoplayer
- detachnpcfromplayer
- gmode <mode>
- say
- setdetachable <enable>
- setinternalname <name>
- setlefthand <enable>
- setonehanded
- setrighthand <enable>
- setshield <enable>
- setstackable <enable>
- settwohanded
