Script:Variables
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:
| Comand | Description |
|---|---|
| ++ <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.
The following system variables are implemented in Arx Libertatis:
| 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) | ✓ |
^¶m<i>
|
number
|
event parameter for the given number starting with 1 (^¶m4 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 a repairable item or fully repaired) | ✓ |
^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.
Global variables
Scripts can define arbitrary global variables and none are predefined by the engine. The following is a (incomplete) list of global variables used in Arx Fatalis:
| Variable | Description |
|---|---|
| #krahoz_zohark_on | The number of Krahoz and Zohark rings equipped by the player. |
| #player_on_quest | The state of the main quest. |
| #troll_quest | The state of the troll quest. |
Entity variables
Scripts can define arbitrary entity variables and none are predefined by the engine. The following is a (incomplete) list of entity variables used in Arx Fatalis:
| Variable | Description |
|---|---|
| £type | The entity class sub-type. |