Script:Variables

From Arx Libertatis Wiki
Jump to navigation Jump to search

This page describes variables in the Arx scripting language.

Variable types

Arx scripts know three basic data types:

int 32-bit signed integer
number 32-bit IEEE 754 floating-point number
string arbitrary-length string

Variables can be either global (shared between all entities) or entity-specific. There are also special system variables than can only be read. The variable type is defined by the first character of the variable name. Non-ASCII characters are encoded as ISO-8859-15.

Char Byte Scope Type
# 0x23 global int
& 0x26 global number
$ 0x24 global string
§ 0xA7 entity int
@ 0x40 entity number
£ 0xA3 entity string
^ 0x5E system (mixed)

While variables in Arx scripts are typed, there are no type restrictions for where variables are used: the types are converted automatically.

Setting variables

Global and entity variables can be modified with the following script commands:

ComandDescription
++ <variable>Increment a number or int script variable.
-- <variable>Decrement a number or int script variable.
dec <variable> <value>Subtract a value from a number or int script variable.
div <variable> <value>Divide a number or int script variable by a value.
inc <variable> <value>Add a value to a number or int script variable.
mul <variable> <value>Multiply a number or int script variable with a value.
set <variable> <value*>Set a script variable.
unset <variable>Remove a script variable.

System variables (those starting with ^) cannot be modified.

Using variables

The pattern ~variable~ will be replaced with the value of the variable named variable (converted to a string) when it occurs in a script command parameter. 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.

Additonally, some parameters will automatically dereference variables if passed a variable name: All number and int variables will dereference system, number or int, but not string variables and parameters marked with a * will automatically dereference any variable. Automatic dereferencing of variables happens after ~variable~ expansion.

System variables

System variables don't always have the value type in the name. Some return results specific to the calling object, others are global. Some system variable prefixes (denoted with a * in the following table) work as functions with the remainder used as the parameters.

Name Type Description Used
^$param1 string event parameter 1
^$param2 string event parameter 2
^$param3 string event parameter 3
^&param1 number event parameter 1
^&param2 number event parameter 2
^&param3 number event parameter 3
^#param1 int event parameter 1
^#param2 int event parameter 2
^#param3 int event parameter 3
^#timer1 int elapsed time in milliseconds since the last starttimer timer1 call (or 0 if the stopwatch is stopped)
^#timer2 int elapsed time in milliseconds since the last starttimer timer2 call (or 0 if the stopwatch is stopped)
^#timer3 int elapsed time in milliseconds since the last starttimer timer3 call (or 0 if the stopwatch is stopped)
^#timer4 int elapsed time in milliseconds since the last starttimer timer4 call (or 0 if the stopwatch is stopped)
^$objontop string ID of the entity above the caller (or "none")
^&playerdist number distance between the caller and the player
^#playerdist int distance between the caller and the player
^gore int 0 for low-violence versions, 1 for normal versions (Arx Libertatis always reports 1)
^gamedays int in-game time since the start of the playthough, in days (in 10-days before AL 1.2)
^gamehours int in-game time since the start of the playthough, in hours
^gameminutes int in-game time since the start of the playthough, in minutes
^gameseconds int in-game time since the start of the playthough, in seconds
^amount int number of items in the stack if the caller is an item (stack), 0 otherwise
^arxdays int in-game time since the start of the playthough, in in-universe days
^arxhours int in-game time since the start of the playthough, in in-universe hours
^arxminutes int in-game time since the start of the playthough, in in-universe minutes
^arxseconds int in-game time since the start of the playthough, in in-universe seconds
^arxtime_hours int time of the day, in in-universe hours (1-12, 0 at the start of the game)
^arxtime_minutes int time of the day, in in-universe minutes (1-60, 0 at the start of the game)
^arxtime_seconds int time of the day, in in-universe seconds (1-60, 0 at the start of the game)
^realdist_* number portal-based walking distance between the caller and the entity with the given ID
^repairprice_* number cost in gold for the caller to repair the item with the given id (-1.f if not an item)
^rnd_* number random number between 0 and the given max (to be determined if inclusive/exclusive)
^rune_* int 0 if the player *doesn't* have the given rune, and unspecified non-zero value otherwise
^inzone_* int 1 if the caller is in the area with the given ID, 0 otherwise
^player_zone string ID of the zone the player is in, "none" if in no zone
^ininitpos int 1 if the caller is exactly at it's initial position, 0 otherwise
^inplayerinventory int 1 if the caller is in the player inventory, 0 otherwise
^possess_* int 1 if the given item is in the player inventory, 2 if it is equipped by the player, 0 otherwise
^behavior string current behavior of the caller NPC
^sender string ID of the entity that sent the current event
^scale number scale of the caller, in percent
^speaking int 1 if the caller is currently speaking, 0 otherwise
^me string ID of the caller
^life number current health value of the caller NPC
^maxlife number maximum health value of the caller NPC
^player_life number the player's current full life (at the start of the frame?)
^player_maxlife number the player's maximum life
^player_hunger number the player's hunger value
^mana number current mana value of the caller NPC
^maxmana number maximum mana value of the caller NPC
^myspell_* int 1 if the caller is casting a spell with the given name, 0 otherwise
^playerspell_* int 1 if the player is casting a spell with the given name (or for "invisibility" if invisibility > 0.3)
^playercasting int 1 if the player is casting a life_drain, harm, fire/ice_field or (mass_)lightning_strike spell
^durability number current durability value of the caller
^maxdurability number maximum durability value of the caller
^last_spawned string ID of the last entity spawned by a script
^dist_* number distance between the caller and the entity with the given ID, 99999999999.0 on error
^demo int 1 if using the demo data (as indicated by the PAK
^price number price in gold of the caller Item
^poisoned number the poisoned value of the caller NPC
^player_poison number the player's poisoned value
^poisonous number the poisonous value of the caller Item
^player_gold number amount of gold carried by the player
^player_attribute_* number player attribute (strength, dexterity, constitution, mind), incl. modifiers
^player_skill_* number player skill, incl. modifiers
^npcinsight string ID of the first NPC seen by the caller, or "none"
^target string ID of the caller's current target, or "none"
^focal number the current camera's focal value
^fighting int 1 if the player is in combat mode, 0 otherwise
^camera string ID of the active camera or none (Added in Arx Libertatis 1.2)
^dragged string ID of item being dragged by the player or none (Added in Arx Libertatis 1.2)
^angle number Yaw of the caller (Added in Arx Libertatis 1.2)
^angle_* number Yaw of the given entity (Added in Arx Libertatis 1.2)
^anglex_* number X component of the 2D direction vector of the given entity (Added in Arx Libertatis 1.2)
^anglez_* number Z component of the 2D direction vector of the given entity (Added in Arx Libertatis 1.2)
^viewx number X component of the 3D view direction vector of the caller (Added in Arx Libertatis 1.2)
^viewy number Y component of the 3D view direction vector of the caller (Added in Arx Libertatis 1.2)
^viewz number Z component of the 3D view direction vector of the caller (Added in Arx Libertatis 1.2)
^viewx_* number X component of the 3D view direction vector of the given entity (Added in Arx Libertatis 1.2)
^viewy_* number Y component of the 3D view direction vector of the given entity (Added in Arx Libertatis 1.2)
^viewz_* number Z component of the 3D view direction vector of the given entity (Added in Arx Libertatis 1.2)

System variables marked as unused may be removed in a future version of Arx Libertatis.

In-universe time

In-universe time runs 6 times faster than real time and has only 12 hours per day. Since these variables are not actually used and NPCs use quest progress instead of time for their day/night cycle this can be considered non-canonical. There is also an unused arx_bell entity class that simulates a day/night cycle with 60 seconds per in-universe day plus 60 seconds per in-universe night.