Script:Commands

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
spell	ID of an active spell
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 an 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.
addbag	Ignored	Add a bag to the player inventory.
addgold <amount>	Ignored	Add gold to the player's purse.
addxp <amount>	Ignored	Add to the player's experience points.
cameraactivate <camera> cameraactivate none	For self	Switch to a camera.
camerasmoothing <value> camerasmoothing none	Cameras	Set rotation smoothing when tracking a target.
damager [-fmplcgewsaornu] <damage>	Any Entity	Set the collision damage.
dec <variable> <value>	Any Entity	Subtract a value from a number or int script variable.
destroy <entity> destroy <spell>	For self	Destroy an entity or spell.
div <variable> <value>	Any Entity	Divide a number or int script variable by a value.
dodamage [-fmplcgewsaornu] <target> <damage>	For self	Damage other entities.
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.
quest <textkey>	Ignored	Append an entry to the quest log.
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.
ridiculous	Ignored	Reset the player character stats.
rotate <dpitch> <dyaw> <droll>	Any Entity	Adjust the orientation.
rune -a <rune> rune -r <rune> rune all	Ignored	Add or remove runes from the spell book.
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 [-dxmsfzo] [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