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
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:

Otherwise, here is a full list:

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.
activatephysicsAny EntityEnable gravity.
addbagIgnoredAdd a bag to the player inventory.
addgold <amount*>IgnoredAdd gold to the player's purse.
addxp <amount*>IgnoredAdd to the player's experience points.
ambiance [-vn] [v?volume*] <ambiance>
ambiance kill
IgnoredPlay or stop an ambiance.
anchorblock <block>Any EntityBlock or unblock pathfinding nodes.
attach <source> <sourcevertex> <target> <targetvertex>For selfLink the position and rotation of an entity to another entity.
attractor <entity> <power*> <radius*>
attractor <entity> off
For selfPull/push the player towards/away from an entity.
book [-aem] open
book [-aem] close
book [-aem] change
IgnoredOpen/close the player book and/or change the page.
cameraactivate <camera>
cameraactivate none
For selfSwitch to a camera.
camerafocal <focal*>CamerasSet the focal length.
camerasmoothing <value*>
camerasmoothing none
CamerasSet rotation smoothing when tracking a target.
cameratranslatetarget <dx*> <dy*> <dz*>CamerasTarget position offset.
cine [-p] <cinematic>
cine play
cine kill
IgnoredPlay or stop a cinematic.
cinemascope [-s] <enable>IgnoredEnable or disable cinematic borders.
closestealbagIgnoredClose any non-player inventory in the HUD if the player is stealing.
collision <enable>Any EntityEnable or disable collisions.
damager [-fmplcgewsaornu] <damage*>Any EntitySet the collision damage.
dec <variable> <value*>Any EntitySubtract a value from a number or int script variable.
destroy <entity>
destroy <spell>
For selfDestroy an entity or spell.
detach <source> <target>For selfUnlink the position and rotation of an entity from another entity.
div <variable> <value*>Any EntityDivide a number or int script variable by a value.
dodamage [-fmplcgewsaornu] <target> <damage*>For selfDamage other entities.
drawsymbol <rune> <duration*>Any EntityDraw a rune symbol as if casting a spell.
elseIgnoredSkip the next command block.
endgameIgnoredEnd the game and roll the credits.
endintroIgnoredEnd the game without showing credits.
equip [-r] playerAny EntityMake the player equip or unequip the caller.
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.
herosay [-d] <textkey*>IgnoredShow 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 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.
inventory add <script>Any EntityCreate a single new item and place it into the inventory.
inventory addfromscene <item>Any EntityAdd an existing item to the inventory.
inventory addmulti <script> <count*>Any EntityCreate a new item stack and place it into the inventory.
inventory closeAny EntityClose any non-player inventory in the HUD.
inventory createAny EntityEnable and clear the inventory.
inventory destroyAny EntityDisable the inventory.
inventory openAny EntityOpen the inventory in the HUD.
inventory playeradd <script>IgnoredCreate a single new item and place it into the player inventory.
inventory playeraddfromscene <item>For selfAdd an existing item to the player inventory.
inventory playeraddmulti <script> <count*>IgnoredCreate a new item stack and place it into the player inventory.
inventory skin <skin>Any EntityChange the inventory background.
invulnerability [-p] <enable>IgnoredAllow or prevent damage from affecting the caller or player.
keyringadd <key*>IgnoredAdd a key to the player's keyring.
linkobjtome <source*> <vertex>Any EntityLink the position and rotation of an entity to the caller.
loadanim [-p] <animslot> <file>Any EntityLoad an animation into a slot.
magic <enable>IgnoredEnable or disable spellcasting.
mapmarker <x*> <y*> <maplevel*> <textkey>
mapmarker -r <textkey>
IgnoredAdd a marker to the map.
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.
note <type> <textkey>IgnoredShow the contents of a note or book.
objecthide [-m] <target> <hide>For selfHide the caller from view and optionally disable script events.
physical off
physical on
physical height <collisionheight*>
physical radius <collisionradius*>
NPCsTemporarily or disable NPC movement and set the collision cylinder size.
play [-ilpo] <sfx*>
play -s
Any EntityPlay a sound effect file.
playanim [-123lnpe] <animslot> [e?command...]
playanim [-123p] none
Any EntityPlay an animation.
playerinterface [-s] hide
playerinterface [-s] show
IgnoredHide or show the HUD.
playerlookat <target>For selfRotate the player camera to look at an entity.
playermanadrain <enable>IgnoredAllow or prevent mana drain damage from affecting the player.
playspeech <speech>Any EntityPlay a speech sound file.
poison <amount*>IgnoredPoison the player.
precast [-df] [d?duration*] <spelllevel*> <spell>Any EntityAdd a spell to the player's precast list.
quake <intensity*> <duration*> <frequency*>IgnoredShake the camera to simulate an earthquake.
quest <textkey>IgnoredAppend an entry to the quest log.
random <chance*>IgnoredRandomly execute or skip the next command block.
refuseIgnoredEnd script event execution with a negative result.
replaceme <script>Any EntityCreate a new replacement entity.
returnIgnoredJump to just after the previous gosub command.
ridiculousIgnoredReset the player character stats.
rotate <dpitch*> <dyaw*> <droll*>Any EntityAdjust the orientation.
rune -a <rune>
rune -r <rune>
rune all
IgnoredAdd 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 EntitySend an event asynchronously to one or more entities.
set <variable> <value*>Any EntitySet a script variable.
setangular <enable>Any EntityEnable or disable angular lighting.
setcontrolledzone <zone>Any EntitySet the controlling entity of a zone.
setelevator <enable>Any EntityPush entities standing on top when animating.
setevent <event> <enable>Any EntityEnable or disable an event.
setgore <enable>NPCsDisable dismemberment.
setgroup [-r] <group*>Any EntityAdd or remove a group.
sethunger <food*>IgnoredSet the player's food energy level.
setmainevent <event>Any EntitySet an event to be sent periodically.
setpath [-wf] <path>
setpath none
Any EntityStart or stop following a path.
setplatform <enable>Any EntityUse special platform collision detection.
setplayercontrols <enable>IgnoredEnable or disable player input.
setplayertweak mesh <newmesh>
setplayertweak skin <oldskin> <newskin>
Any EntitySet an alternate mesh or texture to use for the player while equipped.
setshop <enable>Any EntitySet the inventory to act as a shop.
setspeakpitch <pitch*>NPCsSets the playback speed for speech samples.
setstatus <event>Any EntitySet an event to be sent periodically.
setstrikespeech <speech*>Any EntitySet the speech to play when the striking while equipped.
setweapon [-h] <class>NPCsCreate and equip a weapon.
shopcategory <group>Any EntityLimit the group of items that the player can put into a shop inventory.
shopmultiply <multiplier*>Any EntitySet the price multiplier for items bought from or sold to a shop inventory.
showglobalsIgnoredPrint all global variables to the log.
showlocalsAny EntityPrint all local variables of this entity to the log.
showvarsAny EntityPrint global and local variables for this entity to the log.
spawn fireballAny EntityCreate a fireball projectile.
spawn item <script> <target>For selfCreate a new item entity.
spawn npc <script> <target>For selfCreate 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 EntitySpeak a line with text and/or sound.
specialfx fieryAny EntityIgnite the caller.
specialfx fieryoffAny EntityDouse the caller.
specialfx heal <amount*>Ignoredheal or damage the player.
specialfx mana <amount*>IgnoredRestore or drain the player's mana.
specialfx newspell <ignored>IgnoredShow a new spell effect on the book icon in the HUD.
specialfx player_appearsAny EntityShow a spawn visual effect.
specialfx torchItemsEquip or unequip the caller as a torch.
specialfx torchoffIgnoredUnequip and douse the torch currently equipped by the player.
specialfx ylside_deathAny EntityActivate the Ylside death sequence.
spellcast [-dxmsfzo] [d?duration*] <spelllevel*> <spell> <target>
spellcast -k <spell>
Any EntityCast spells or cancel active spells.
starttimer <stopwatch>Any EntityStart a stopwatch.
stealnpcAny EntitySet the inventory that the player can steal from.
stoptimer <stopwatch>Any EntityStop a stopwatch.
targetplayerposAny EntitySet the player as the target.
teleport [-api] [a?angle*] [!i?target]
teleport [-a] [a?angle*] behind
teleport -l[an] [a?angle*] <area*> <target>
Any EntityMove the caller or player to a new position or area.
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.
viewblock <enable>Any EntityBlock the view of NPCs.
weapon <drawn>NPCsDraw or sheathe the equipped wapon.
worldfade out <duration*> <r*> <g*> <b*>
worldfade in <duration*>
IgnoredFade to/from black or another color.
zoneparam ambiance <ambiance>IgnoredChange the active zone ambiance.

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