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 parameters 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.

If you are interested in specific command categories, check out the category pages:

• Script commands creating entities
• Script commands destroying entities
• Script commands linking entities
• Script control flow
• Script delayed execution

Otherwise, here is a full list:

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.
activatephysics	Any Entity	Enable gravity.
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.
ambiance [-vn] [v?volume*] <ambiance> ambiance kill	Ignored	Play or stop an ambiance.
anchorblock <block>	Any Entity	Block or unblock pathfinding nodes.
attach <source> <sourcevertex> <target> <targetvertex>	For self	Link the position and rotation of an entity to another entity.
attractor <entity> <power*> <radius*> attractor <entity> off	For self	Pull/push the player towards/away from an entity.
book [-aem] open book [-aem] close book [-aem] change	Ignored	Open/close the player book and/or change the page.
cameraactivate <camera> cameraactivate none	For self	Switch to a camera.
camerafocal <focal*>	Cameras	Set the focal length.
camerasmoothing <value*> camerasmoothing none	Cameras	Set rotation smoothing when tracking a target.
cameratranslatetarget <dx*> <dy*> <dz*>	Cameras	Target position offset.
cine [-p] <cinematic> cine play cine kill	Ignored	Play or stop a cinematic.
cinemascope [-s] <enable>	Ignored	Enable or disable cinematic borders.
closestealbag	Ignored	Close any non-player inventory in the HUD if the player is stealing.
collision <enable>	Any Entity	Enable or disable collisions.
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.
detach <source> <target>	For self	Unlink the position and rotation of an entity from another entity.
div <variable> <value*>	Any Entity	Divide a number or int script variable by a value.
dodamage [-fmplcgewsaornu] <target> <damage*>	For self	Damage other entities.
drawsymbol <rune> <duration*>	Any Entity	Draw a rune symbol as if casting a spell.
else	Ignored	Skip the next command block.
endgame	Ignored	End the game and roll the credits.
endintro	Ignored	End the game without showing credits.
equip [-r] player	Any Entity	Make the player equip or unequip the caller.
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.
herosay [-d] <textkey*>	Ignored	Show a message at the top of the screen.
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.
inventory add <script>	Any Entity	Create a single new item and place it into the inventory.
inventory addfromscene <item>	Any Entity	Add an existing item to the inventory.
inventory addmulti <script> <count*>	Any Entity	Create a new item stack and place it into the inventory.
inventory close	Any Entity	Close any non-player inventory in the HUD.
inventory create	Any Entity	Enable and clear the inventory.
inventory destroy	Any Entity	Disable the inventory.
inventory open	Any Entity	Open the inventory in the HUD.
inventory playeradd <script>	Ignored	Create a single new item and place it into the player inventory.
inventory playeraddfromscene <item>	For self	Add an existing item to the player inventory.
inventory playeraddmulti <script> <count*>	Ignored	Create a new item stack and place it into the player inventory.
inventory skin <skin>	Any Entity	Change the inventory background.
invulnerability [-p] <enable>	Ignored	Allow or prevent damage from affecting the caller or player.
keyringadd <key*>	Ignored	Add a key to the player's keyring.
linkobjtome <source*> <vertex>	Any Entity	Link the position and rotation of an entity to the caller.
loadanim [-p] <animslot> <file>	Any Entity	Load an animation into a slot.
magic <enable>	Ignored	Enable or disable spellcasting.
mapmarker <x*> <y*> <maplevel*> <textkey> mapmarker -r <textkey>	Ignored	Add a ✗ marker to the map.
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.
note <type> <textkey>	Ignored	Show the contents of a note or book.
objecthide [-m] <target> <hide>	For self	Hide the caller from view and optionally disable script events.
physical off physical on physical height <collisionheight*> physical radius <collisionradius*>	NPCs	Temporarily or disable NPC movement and set the collision cylinder size.
play [-ilpo] <sfx*> play -s	Any Entity	Play a sound effect file.
playanim [-123lnpe] <animslot> [e?command...] playanim [-123p] none	Any Entity	Play an animation.
playerinterface [-s] hide playerinterface [-s] show	Ignored	Hide or show the HUD.
playerlookat <target>	For self	Rotate the player camera to look at an entity.
playermanadrain <enable>	Ignored	Allow or prevent mana drain damage from affecting the player.
playspeech <speech>	Any Entity	Play a speech sound file.
poison <amount*>	Ignored	Poison the player.
precast [-df] [d?duration*] <spelllevel*> <spell>	Any Entity	Add a spell to the player's precast list.
quake <intensity*> <duration*> <frequency*>	Ignored	Shake the camera to simulate an earthquake.
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.
replaceme <script>	Any Entity	Create a new replacement entity.
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 player 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 asynchronously to one or more entities.
set <variable> <value*>	Any Entity	Set a script variable.
setangular <enable>	Any Entity	Enable or disable angular lighting.
setcontrolledzone <zone>	Any Entity	Set the controlling entity of a zone.
setelevator <enable>	Any Entity	Push entities standing on top when animating.
setevent <event> <enable>	Any Entity	Enable or disable an event.
setgore <enable>	NPCs	Disable dismemberment.
setgroup [-r] <group*>	Any Entity	Add or remove a group.
sethunger <food*>	Ignored	Set the player's food energy level.
setmainevent <event>	Any Entity	Set an event to be sent periodically.
setpath [-wf] <path> setpath none	Any Entity	Start or stop following a path.
setplatform <enable>	Any Entity	Use special platform collision detection.
setplayercontrols <enable>	Ignored	Enable or disable player input.
setplayertweak mesh <newmesh> setplayertweak skin <oldskin> <newskin>	Any Entity	Set an alternate mesh or texture to use for the player while equipped.
setshop <enable>	Any Entity	Set the inventory to act as a shop.
setspeakpitch <pitch*>	NPCs	Sets the playback speed for speech samples.
setstatus <event>	Any Entity	Set an event to be sent periodically.
setstrikespeech <speech*>	Any Entity	Set the speech to play when the striking while equipped.
setweapon [-h] <class>	NPCs	Create and equip a weapon.
shopcategory <group>	Any Entity	Limit the group of items that the player can put into a shop inventory.
shopmultiply <multiplier*>	Any Entity	Set the price multiplier for items bought from or sold to a shop inventory.
showglobals	Ignored	Print all global variables to the log.
showlocals	Any Entity	Print all local variables of this entity to the log.
showvars	Any Entity	Print global and local variables for this entity to the log.
spawn fireball	Any Entity	Create a fireball projectile.
spawn item <script> <target>	For self	Create a new item entity.
spawn npc <script> <target>	For self	Create a new NPC entity.
speak [-tuphao] <speech*> <command...> speak -c[tuphao] keep <speech*> <command...> speak -c[tuphao] zoom <p0*> <y0*> <p1*> <y1*> <d0*> <d1*> <speech*> <command...> speak -c[tuphao] <mode> <target> <d0*> <d1*> <speech*> <command...> speak [] speak killall	Any Entity	Speak a line with text and/or sound.
specialfx fiery	Any Entity	Ignite the caller.
specialfx fieryoff	Any Entity	Douse the caller.
specialfx heal <amount*>	Ignored	heal or damage the player.
specialfx mana <amount*>	Ignored	Restore or drain the player's mana.
specialfx newspell <ignored>	Ignored	Show a new spell effect on the book icon in the HUD.
specialfx player_appears	Any Entity	Show a spawn visual effect.
specialfx torch	Items	Equip or unequip the caller as a torch.
specialfx torchoff	Ignored	Unequip and douse the torch currently equipped by the player.
specialfx ylside_death	Any Entity	Activate the Ylside death sequence.
spellcast [-dxmsfzo] [d?duration*] <spelllevel*> <spell> <target> spellcast -k <spell>	Any Entity	Cast spells or cancel active spells.
starttimer <stopwatch>	Any Entity	Start a stopwatch.
stealnpc	Any Entity	Set the inventory that the player can steal from.
stoptimer <stopwatch>	Any Entity	Stop a stopwatch.
targetplayerpos	Any Entity	Set the player as the target.
teleport [-api] [a?angle*] [!i?target] teleport [-a] [a?angle*] behind teleport -l[an] [a?angle*] <area*> <target>	Any Entity	Move the caller or player to a new position or area.
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.
viewblock <enable>	Any Entity	Block the view of NPCs.
weapon <drawn>	NPCs	Draw or sheathe the equipped wapon.
worldfade out <duration*> <r*> <g*> <b*> worldfade in <duration*>	Ignored	Fade to/from black or another color.
zoneparam ambiance <ambiance>	Ignored	Change the active zone ambiance.

Additionally, the following commands will be accepted but do nothing. They are only supported to not break older scripts.

• attachnpctoplayer
• conversation off
• detachnpcfromplayer
• gmode <mode>
• popup <message>
• say
• setdetachable <enable>
• setinternalname <name>
• setlefthand <enable>
• setonehanded
• setrighthand <enable>
• setshield <enable>
• setstackable <enable>
• settwohanded
• specialfx torchon