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 ($ & or #) 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
^$param<i> string event parameter for the given number starting with 1 (^$param4 and higher added in Arx Libertatis 1.3)
^&param<i> number event parameter for the given number starting with 1 (^&param4 and higher added in Arx Libertatis 1.3)
^#param<i> int event parameter for the given number starting with 1 (^#param4 and higher added in Arx Libertatis 1.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 entity 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
^amount int number of items in the stack if the caller is an item (stack), 0 otherwise
^angle number yaw of the caller (Added in Arx Libertatis 1.2)
^angle_<entity> number yaw of the given entity (Added in Arx Libertatis 1.2)
^angleto_<entity> number direction (yaw) from the caller to the given entity (Added in Arx Libertatis 1.3)
^anglex_<entity> number X component of the 2D direction vector of the given entity (Added in Arx Libertatis 1.2)
^anglez_<entity> number Z component of the 2D direction vector of the given entity (Added in Arx Libertatis 1.2)
^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)
^behavior string current behavior of the caller NPC
^camera entity ID of the active camera or none (Added in Arx Libertatis 1.2)
^caster entity the caster of the caller or none if the caller is not a summoned entity (Added in Arx Libertatis 1.3)
^caster_<entity> entity the caster of the given summoned entity or none if it does not exist or is not summoned (Added in Arx Libertatis 1.3)
^caster_<spell> entity the caster of the given spell or none if the spell does not exist (Added in Arx Libertatis 1.3)
^class entity the class name of the caller (Added in Arx Libertatis 1.3)
^class_<entity> entity the class name of the given entity (Added in Arx Libertatis 1.3)
^class_<spell> entity the spell name of the given spell (Added in Arx Libertatis 1.3)
^demo int 1 if using the demo data (as indicated by the PAK
^dist_<entity> number distance between the caller and the entity with the given ID, 99999999999.0 on error
^dragged entity ID of item being dragged by the player or none (Added in Arx Libertatis 1.2)
^durability number current durability value of the caller
^fighting int 1 if the player is in combat mode, 0 otherwise
^focal number the current camera's focal value
^gamedays int in-game time since the start of the playthough, in days (in 10-days before Arx Libertatis 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
^gore int 0 for low-violence versions, 1 for normal versions (Arx Libertatis always reports 1)
^hover entity entity under the mouse cursor or crosshair (Added in Arx Libertatis 1.3)
^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
^inzone_<zone> int 1 if the caller is in the area with the given ID, 0 otherwise
^last_spawned entity ID of the last entity spawned by a script
^life number current health value of the caller NPC
^mana number current mana value of the caller NPC
^maxdurability number maximum durability value of the caller
^maxlife number maximum health value of the caller NPC
^maxmana number maximum mana value of the caller NPC
^me entity ID of the caller
^myspell_<name> int 1 if the caller is casting a spell with the given spell name, 0 otherwise
^npcinsight entity ID of the first NPC seen by the caller, or "none"
^offscreen int the visibility of the caller (Added in Arx Libertatis 1.3)
^offscreen_<entity> int the visibility of the given entity (Added in Arx Libertatis 1.3)
^onscreen int the visibility of the caller (Added in Arx Libertatis 1.3)
^onscreen_<entity> int the visibility of the given entity (Added in Arx Libertatis 1.3)
^player_attribute_<attribute> number player attribute, including modifiers
^player_gold number amount of gold carried by the player
^player_hunger number the player's hunger value
^player_life number the player's current full life (at the start of the frame?)
^player_mana number the player's current mana level (Added in Arx Libertatis 1.3)
^player_maxlife number the player's maximum life
^player_maxmana number the player's maximum mana level (Added in Arx Libertatis 1.3)
^player_skill_<skill> number player skill, including modifiers
^player_zone string ID of the zone the player is in, "none" if in no zone
^playercasting int 1 if the player is casting a life_drain, harm, fire/ice_field or (mass_)lightning_strike spell
^playerspell_<name> int 1 if the player is casting a spell with the given spell name (or for "invisibility" if invisibility > 0.3)
^poisoned number the poisoned value of the caller NPC
^possess_<entity> int 1 if the given item is in the player inventory, 2 if it is equipped by the player, 0 otherwise
^price number price in gold of the caller Item
^player_poison number the player's poisoned value
^poisonous number the poisonous value of the caller Item
^realdist_<entity> number portal-based walking distance between the caller and the entity with the given ID
^repairprice_<entity> number cost in gold for the caller to repair the item with the given id (-1.f if not an item)
^rnd_<max> number random number between 0 and the given max (to be determined if inclusive/exclusive)
^rune_<name> int 0 if the player *doesn't* have the given rune, and unspecified non-zero value otherwise
^scale number scale of the caller, in percent
^sender entity ID of the entity that sent the current event
^speaking int 1 if the caller is currently speaking, 0 otherwise
^spell spell the last spell cast by the caller which is still active, or none (Added in Arx Libertatis 1.3)
^spell_<entity> spell the last spell cast by the given entity which is still active, or none (Added in Arx Libertatis 1.3)
^spelllevel number the player's current caster level (Added in Arx Libertatis 1.3)
^spelllevel_<spell> number the caster level of the given spell or -1 if the spell does not exist (Added in Arx Libertatis 1.3)
^target entity ID of the caller's current target, or "none"
^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_<entity> number X component of the 3D view direction vector of the given entity (Added in Arx Libertatis 1.2)
^viewy_<entity> number Y component of the 3D view direction vector of the given entity (Added in Arx Libertatis 1.2)
^viewz_<entity> 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.

Visibility

The ^onscreen and ^onscreen_<entity> system variables allow scripts to determine if the calling or given entity is currently shown on the screen. The following visibility values are defined:

Value Description
-2 The game is not currently in a state where any entities are shown, e.g. because a 2D cinematic is playing.
-1 The entity is not visible at all because it is outside the view frustum or fully occluded
0 The entity may be visible but is at least partially occluded
1 The entity is at least partially visible but may be partially occluded
2 The entity's head is visible (if it has one) and the player is looking at the entity

Items in inventories are considered to be visible and looked at (2) if the inventory is open and not visible (-1) otherwise. The entity being dragged is considered to be visible (2) even if it is only shown as an icon.

Player equipment is considered to be visible and looked at (2) if the player book is open.

Point entities like markers and cameras will always have their visibility known (never 0).

Because determining the entity visibility requires a number of calculations it is recommended to not read these system variables more often than necessary.

The ^offscreen and ^offscreen_<entity> system variables are the same as their ^onscreen counterparts, but inverted and without expensive tests to check if the entity is really visible. This leaves the following values:

Value Description
0 The entity may be visible but could be fully occluded
1 The entity is not visible at all because it is outside the view frustum or fully occluded
2 The game is not currently in a state where any entities are shown, e.g. because a 2D cinematic is playing.

Determining that an entity is fully occluded (^onscreen < 0 or ^offscreen > 0) uses portals and therefore the quality of the results depends on how well the portals are placed. There is an F11 debug display for entity visibility that may help understand the results.