Script:Commands

From Arx Libertatis Wiki
Jump to navigation Jump to search

Commands in the Arx scripting language are invoked by entity scripts to perform some action.

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.

ComandContextDescription
++ <variable>Any EntityIncrement a number or int script variable.
-- <variable>Any EntityDecrement a number or int script variable.
acceptIgnoredEnd script event execution with a positive result.
cameraactivate <camera>
cameraactivate none
For selfSwitch to a camera.
camerasmoothing <value>
camerasmoothing none
CamerasSet rotation smoothing when tracking a target.
dec <variable> <value>Any EntitySubtract a value from a number or int script variable.
div <variable> <value>Any EntityDivide a number or int script variable by a value.
elseIgnoredSkip the next command block.
forceangle <yaw>Any EntitySet the orientation.
forceanim <animslot>Any EntityForce play an animation.
gosub <label>IgnoredJump to a label and add a return point.
goto <label>IgnoredJump 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 selfConditionally execute or skip the next command block.
ifexistinternal <entity>IgnoredSkip the next command block if an entity doesn't exist in the current level.
ifvisible <entity>Any EntitySkip the next command block unless an entity is inside the cone of vision.
inc <variable> <value>Any EntityAdd a value to a number or int script variable.
loadanim [-p] <animslot> <file>Any EntityLoad an animation into a slot.
move <dx> <dy> <dz>Any EntityAdjust the world position.
mul <variable> <value>Any EntityMultiply a number or int script variable with a value.
nopIgnoredDo nothing.
playanim [-123lnpe] <animslot> [e?command...]
playanim [-123p] none
Any EntityPlay an animation.
random <chance>IgnoredRandomly execute or skip the next command block.
refuseIgnoredEnd script event execution with a negative result.
returnIgnoredJump to just after the previous gosub command.
rotate <dpitch> <dyaw> <droll>Any EntityAdjust 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 EntitySend an event to one or more entities.
set <variable> <value*>Any EntitySet a script variable.
setangular <enable>Any EntityEnables or disables angular lighting.
setcontrolledzone <zone>Any EntitySet the controlling entity of a zone.
setevent <event> <enable>Any EntityEnable or disable an event.
setgroup [-r] <group*>Any EntityAdd or remove a group.
setmainevent <event>Any EntitySet an event to be sent periodically.
setpath [-wf] <path>
setpath none
Any EntityStart or stop following a path.
setstatus <event>Any EntitySet an event to be sent periodically.
spellcast [-dxmsfz] [d?duration] <level> <spell> <target>
spellcast -k <spell>
Any EntityCast spells or cancel active spells.
starttimer <stopwatch>Any EntityStart a stopwatch.
stoptimer <stopwatch>Any EntityStop a stopwatch.
unset <variable>Any EntityRemove a script variable.
unsetcontrolledzone <zone>IgnoredRemove the controlling entity from a zone.
usepath <direction>Any EntityChange 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.