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)	✓
^&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 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.