Script:Variables: Difference between revisions
No edit summary |
mNo edit summary Tag: Manual revert |
||
(42 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
This page describes variables in the [[Arx scripting language]]. | This page describes variables in the [[Arx scripting language]]. | ||
= Variable types = | |||
Arx scripts know three basic data types: | Arx scripts know three basic data types: | ||
Line 8: | Line 8: | ||
| {{int}} || 32-bit signed integer | | {{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- | 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-[[wp:ASCII|ASCII]] characters are encoded as [[wp:ISO/IEC 8859-15|ISO-8859-15]]. | ||
{| class="wikitable" style="text-align:center;" | {| class="wikitable" style="text-align:center;" | ||
Line 20: | Line 20: | ||
| <code>#</code> || <code>0x23</code> || global || {{int}} | | <code>#</code> || <code>0x23</code> || global || {{int}} | ||
|- | |- | ||
| <code>&</code> || <code>0x26</code> || global || {{ | | <code>&</code> || <code>0x26</code> || global || {{number}} | ||
|- | |- | ||
| <code>$</code> || <code>0x24</code> || global || {{ | | <code>$</code> || <code>0x24</code> || global || {{string}} | ||
|- | |- | ||
| <code>§</code> || <code>0xA7</code> || entity || {{int}} | | <code>§</code> || <code>0xA7</code> || entity || {{int}} | ||
|- | |- | ||
| <code>@</code> || <code>0x40</code> || entity || {{ | | <code>@</code> || <code>0x40</code> || entity || {{number}} | ||
|- | |- | ||
| <code>£</code> || <code>0xA3</code> || entity || {{ | | <code>£</code> || <code>0xA3</code> || entity || {{string}} | ||
|- | |- | ||
| <code>^</code> || <code>0x5E</code> || system || (mixed) | | <code>^</code> || <code>0x5E</code> || system || (mixed) | ||
Line 35: | Line 35: | ||
While variables in Arx scripts are typed, there are no type restrictions for where variables are used: the types are converted automatically. | While variables in Arx scripts are typed, there are no type restrictions for where variables are used: the types are converted automatically. | ||
= | = Setting 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 <code> | Global and [[entity]] variables can be modified with the following script commands: | ||
{{#ask: [[Category:Script commands]] [[obsolete::false]] [[has variable param::true]] | |||
|?Usage=Comand | |||
|?Description | |||
|mainlabel=- | |||
|limit=1000 | |||
|format=table | |||
|class=sortable wikitable smwtable code_0 | |||
}} | |||
System variables (those starting with ^) cannot be modified. | |||
= Using variables = | |||
The pattern <code>~variable~</code> will be replaced with the value of the variable named <code>variable</code> (converted to a string) when it occurs in a script command [[Script:Commands#Parameters|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 <code>0</code>, unset {{string}} variables will be replaced with <code>void</code>, and <code>~variable~</code> where <code>variable</code> is an invalid variable name will be replaced with <code>variable</code>. | |||
Additonally, some [[Script:Commands#Parameters|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 <code>*</code> will automatically dereference any variable. Automatic dereferencing of variables happens after <code>~variable~</code> 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 <code><…></code> in the following table) work as functions with the remainder used as the parameters. | |||
The following system variables are implemented in Arx Libertatis: | |||
{{#ask: [[Category:System variables]] | |||
|?Usage=Variable | |||
|?Description | |||
|mainlabel=- | |||
|limit=1000 | |||
|format=table | |||
|class=sortable wikitable smwtable code_0 | |||
}} | |||
{| class="wikitable" | {| class="wikitable" | ||
Line 45: | Line 77: | ||
! Used | ! Used | ||
|- | |- | ||
| <code>^$ | | <code>^$param{{Highlight|number|<i>}}</code> | ||
| {{ | | {{string}} | ||
| [[Script: | | [[Script:Events|event]] parameter for the given number starting with 1 (^$param4 and higher added in {{Changelog|1.3}}) | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^¶m{{Highlight|number|<i>}}</code> | ||
| {{ | | {{number}} | ||
| [[Script: | | [[Script:Events|event]] parameter for the given number starting with 1 (^¶m4 and higher added in {{Changelog|1.3}}) | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^#param{{Highlight|number|<i>}}</code> | ||
| | |||
| {{int}} | | {{int}} | ||
| [[Script: | | [[Script:Events|event]] parameter for the given number starting with 1 (^#param4 and higher added in {{Changelog|1.3}}) | ||
| | |||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^#timer1</code> | | <code>^#timer1</code> | ||
| {{int}} | | {{int}} | ||
| | | elapsed time in milliseconds since the last {{Command|starttimer|timer1}} call (or 0 if the stopwatch is stopped) | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^#timer2</code> | | <code>^#timer2</code> | ||
| {{int}} | | {{int}} | ||
| | | elapsed time in milliseconds since the last {{Command|starttimer|timer2}} call (or 0 if the stopwatch is stopped) | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^#timer3</code> | | <code>^#timer3</code> | ||
| {{int}} | | {{int}} | ||
| | | elapsed time in milliseconds since the last {{Command|starttimer|timer3}} call (or 0 if the stopwatch is stopped) | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^#timer4</code> | | <code>^#timer4</code> | ||
| {{int}} | | {{int}} | ||
| | | elapsed time in milliseconds since the last {{Command|starttimer|timer4}} call (or 0 if the stopwatch is stopped) | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^$objontop</code> | | <code>^$objontop</code> | ||
| {{ | | <code>{{Highlight|entity}}</code> | ||
| ID of the entity above the caller (or "none") | | ID of the entity above the caller (or "none") | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^&playerdist</code> | | <code>^&playerdist</code> | ||
| {{ | | {{number}} | ||
| distance between the caller and the player | | distance between the caller and the player | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
Line 125: | Line 127: | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^amount</code> | ||
| {{int}} | | {{int}} | ||
| | | number of items in the stack if the caller is an item (stack), 0 otherwise | ||
| align="center" | {{ | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^angle</code> | ||
| {{ | | {{number}} | ||
| | | yaw of the caller (Added in {{Changelog|1.2}}) | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^angle_{{Highlight|entity|<entity>}}</code> | ||
| {{ | | {{number}} | ||
| | | yaw of the given entity (Added in {{Changelog|1.2}}) | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^angleto_{{Highlight|entity|<entity>}}</code> | ||
| {{ | | {{number}} | ||
| | | direction (yaw) from the caller to the given entity (Added in {{Changelog|1.3}}) | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^anglex_{{Highlight|entity|<entity>}}</code> | ||
| {{ | | {{number}} | ||
| | | X component of the 2D direction vector of the given entity (Added in {{Changelog|1.2}}) | ||
| align="center" | {{ | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^anglez_{{Highlight|entity|<entity>}}</code> | ||
| {{ | | {{number}} | ||
| | | Z component of the 2D direction vector of the given entity (Added in {{Changelog|1.2}}) | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
Line 190: | Line 192: | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^behavior</code> | ||
| {{ | | {{string}} | ||
| | | current behavior of the caller NPC | ||
| align="center" | {{N}} | |||
|- | |||
| <code>^camera</code> | |||
| <code>{{Highlight|entity}}</code> | |||
| ID of the active camera or <code>none</code> (Added in {{Changelog|1.2}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^caster</code> | |||
| <code>{{Highlight|entity}}</code> | |||
| the caster of the caller or none if the caller is not a summoned entity (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^caster_{{Highlight|entity|<entity>}}</code> | |||
| <code>{{Highlight|entity}}</code> | |||
| the caster of the given summoned entity or none if it does not exist or is not summoned (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^caster_{{Highlight|spell|<spell>}}</code> | |||
| <code>{{Highlight|entity}}</code> | |||
| the caster of the given spell or none if the spell does not exist (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^class</code> | |||
| <code>{{Highlight|entity}}</code> | |||
| the class name of the caller (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^class_{{Highlight|entity|<entity>}}</code> | |||
| <code>{{Highlight|entity}}</code> | |||
| the class name of the given entity (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^class_{{Highlight|spell|<spell>}}</code> | |||
| <code>{{Highlight|entity}}</code> | |||
| the [[Script:spellcast#Spell_names|spell name]] of the given spell (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^demo</code> | |||
| {{int}} | |||
| 1 if using the demo data (as indicated by the PAK | |||
| align="center" | {{Y}} | |||
|- | |||
| <code>^dist_{{Highlight|entity|<entity>}}</code> | |||
| {{number}} | |||
| distance between the caller and the entity with the given ID, 99999999999.0 on error | |||
| align="center" | {{Y}} | |||
|- | |||
| <code>^dragged</code> | |||
| <code>{{Highlight|entity}}</code> | |||
| ID of item being dragged by the player or <code>none</code> (Added in {{Changelog|1.2}}) | |||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^durability</code> | ||
| {{ | | {{number}} | ||
| | | current durability value of the caller | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^fighting</code> | ||
| {{ | | {{int}} | ||
| | | 1 if the player is in combat mode, 0 otherwise | ||
| align="center" | {{Y}} | |||
|- | |||
| <code>^focal</code> | |||
| {{number}} | |||
| the current camera's focal value | |||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^gamedays</code> | ||
| {{int}} | | {{int}} | ||
| | | in-game time since the start of the playthough, in days (in 10-days before {{Changelog|1.2}}) | ||
| align="center" | {{N}} | |||
|- | |||
| <code>^gamehours</code> | |||
| {{int}} | |||
| in-game time since the start of the playthough, in hours | |||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^gameminutes</code> | ||
| {{int}} | | {{int}} | ||
| | | in-game time since the start of the playthough, in minutes | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^gameseconds</code> | ||
| {{ | | {{int}} | ||
| | | in-game time since the start of the playthough, in seconds | ||
| align="center" | {{Y}} | |||
|- | |||
| <code>^gore</code> | |||
| {{int}} | |||
| 0 for low-violence versions, 1 for normal versions (Arx Libertatis always reports 1) | |||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |||
| <code>^hover</code> | |||
| <code>{{Highlight|entity}}</code> | |||
| entity under the mouse cursor or crosshair (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |- | ||
| <code>^ininitpos</code> | | <code>^ininitpos</code> | ||
Line 230: | Line 302: | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^inzone_{{Highlight|string|<zone>}}</code> | ||
| {{int}} | | {{int}} | ||
| 1 | | 1 if the caller is in the area with the given ID, 0 otherwise | ||
| align="center" | {{ | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^last_spawned</code> | ||
| {{ | | <code>{{Highlight|entity}}</code> | ||
| | | ID of the last entity spawned by a script | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^life</code> | ||
| {{ | | {{number}} | ||
| | | current health value of the caller NPC | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^mana</code> | ||
| {{ | | {{number}} | ||
| | | current mana value of the caller NPC | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^maxdurability</code> | ||
| {{ | | {{number}} | ||
| | | maximum durability value of the caller | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |||
| <code>^maxlife</code> | |||
| {{number}} | |||
| maximum health value of the caller NPC | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^maxmana</code> | |||
| {{number}} | |||
| maximum mana value of the caller NPC | |||
| align="center" | {{N}} | |||
|- | |- | ||
| <code>^me</code> | | <code>^me</code> | ||
| {{ | | <code>{{Highlight|entity}}</code> | ||
| ID of the caller | | ID of the caller | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^myspell_{{Highlight|string|<name>}}</code> | ||
| {{ | | {{int}} | ||
| | | 1 if the caller is casting a spell with the given [[Script:spellcast#Spell_names|spell name]], 0 otherwise | ||
| align="center" | {{Y}} | |||
|- | |||
| <code>^npcinsight</code> | |||
| <code>{{Highlight|entity}}</code> | |||
| ID of the first NPC seen by the caller, or "none" | |||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^offscreen</code> | ||
| {{ | | {{int}} | ||
| | | the [[#Visibility|visibility]] of the caller (Added in {{Changelog|1.3}}) | ||
| align="center" | {{N}} | |||
|- | |||
| <code>^offscreen_{{Highlight|entity|<entity>}}</code> | |||
| {{int}} | |||
| the [[#Visibility|visibility]] of the given entity (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^onscreen</code> | |||
| {{int}} | |||
| the [[#Visibility|visibility]] of the caller (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^onscreen_{{Highlight|entity|<entity>}}</code> | |||
| {{int}} | |||
| the [[#Visibility|visibility]] of the given entity (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^player_attribute_{{Highlight|string|<attribute>}}</code> | ||
| {{ | | {{number}} | ||
| | | [[Attributes|player attribute]], including modifiers | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^player_gold</code> | ||
| {{ | | {{number}} | ||
| the player | | amount of gold carried by the player | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^player_hunger</code> | | <code>^player_hunger</code> | ||
| {{ | | {{number}} | ||
| the player's hunger value | | the player's hunger value | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^player_life</code> | ||
| {{ | | {{number}} | ||
| current mana | | the player's current full life (at the start of the frame?) | ||
| align="center" | {{Y}} | |||
|- | |||
| <code>^player_mana</code> | |||
| {{number}} | |||
| the player's current mana level (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^player_maxlife</code> | |||
| {{number}} | |||
| the player's maximum life | |||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^player_maxmana</code> | ||
| {{ | | {{number}} | ||
| maximum mana | | the player's maximum mana level (Added in {{Changelog|1.3}}) | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^player_skill_{{Highlight|string|<skill>}}</code> | ||
| {{ | | {{number}} | ||
| | | [[Skills|player skill]], including modifiers | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^player_zone</code> | ||
| {{ | | {{string}} | ||
| | | ID of the zone the player is in, "none" if in no zone | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^playercasting</code> | | <code>^playercasting</code> | ||
| {{int}} | | {{int}} | ||
| 1 if the player is casting a life_drain, harm, fire/ice_field | | 1 if the player is casting a life_drain, harm, fire/ice_field or (mass_)lightning_strike spell | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^playerspell_{{Highlight|string|<name>}}</code> | ||
| {{ | | {{int}} | ||
| | | 1 if the player is casting a spell with the given [[Script:spellcast#Spell_names|spell name]] (or for "invisibility" if invisibility > 0.3) | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^poisoned</code> | ||
| {{ | | {{number}} | ||
| | | the poisoned value of the caller NPC | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^possess_{{Highlight|entity|<entity>}}</code> | ||
| {{int}} | | {{int}} | ||
| 1 if | | 1 if the given item is in the player inventory, 2 if it is equipped by the player, 0 otherwise | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^price</code> | | <code>^price</code> | ||
| {{ | | {{number}} | ||
| price in gold of the caller Item | | price in gold of the caller Item | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^player_poison</code> | | <code>^player_poison</code> | ||
| {{ | | {{number}} | ||
| the player's poisoned value | | the player's poisoned value | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^poisonous</code> | | <code>^poisonous</code> | ||
| {{ | | {{number}} | ||
| the poisonous value of the caller Item | | the poisonous value of the caller Item | ||
| align="center" | {{N}} | | align="center" | {{N}} | ||
|- | |- | ||
| <code>^ | | <code>^realdist_{{Highlight|entity|<entity>}}</code> | ||
| {{ | | {{number}} | ||
| | | portal-based walking distance between the caller and the entity with the given ID | ||
| align="center" | {{N}} | |||
|- | |||
| <code>^repairprice_{{Highlight|entity|<entity>}}</code> | |||
| {{number}} | |||
| cost in gold for the caller to [[Script:setblacksmith|repair]] the item with the given id (-1.f if not a repairable item or fully repaired) | |||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^rnd_{{Highlight|number|<max>}}</code> | ||
| {{ | | {{number}} | ||
| | | random number between 0 and the given max (to be determined if inclusive/exclusive) | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^rune_{{Highlight|string|<name>}}</code> | ||
| {{ | | {{int}} | ||
| | | 0 if the player *doesn't* have the given rune, and unspecified non-zero value otherwise | ||
| align="center" | {{N}} | |||
|- | |||
| <code>^scale</code> | |||
| {{number}} | |||
| scale of the caller, in percent | |||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^sender</code> | ||
| {{ | | <code>{{Highlight|entity}}</code> | ||
| ID of the | | ID of the entity that sent the current [[Script:Events|event]] | ||
| align="center" | {{Y}} | |||
|- | |||
| <code>^speaking</code> | |||
| {{int}} | |||
| 1 if the caller is currently speaking, 0 otherwise | |||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |||
| <code>^spell</code> | |||
| <code>{{Highlight|spell}}</code> | |||
| the last spell cast by the caller which is still active, or none (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^spell_{{Highlight|entity|<entity>}}</code> | |||
| <code>{{Highlight|spell}}</code> | |||
| the last spell cast by the given entity which is still active, or none (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^spelllevel</code> | |||
| {{number}} | |||
| the player's current [[caster level]] (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^spelllevel_{{Highlight|spell|<spell>}}</code> | |||
| {{number}} | |||
| the [[caster level]] of the given spell or -1 if the spell does not exist (Added in {{Changelog|1.3}}) | |||
| align="center" | {{N}} | |||
|- | |- | ||
| <code>^target</code> | | <code>^target</code> | ||
| {{ | | <code>{{Highlight|entity}}</code> | ||
| ID of the caller's current target, or "none" | | ID of the caller's current target, or "none" | ||
| align="center" | {{Y}} | | align="center" | {{Y}} | ||
|- | |- | ||
| <code>^ | | <code>^viewx</code> | ||
| {{ | | {{number}} | ||
| the | | X component of the 3D view direction vector of the caller (Added in {{Changelog|1.2}}) | ||
| align="center" | {{Y}} | | align="center" | {{N}} | ||
|- | |||
| <code>^viewy</code> | |||
| {{number}} | |||
| Y component of the 3D view direction vector of the caller (Added in {{Changelog|1.2}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^viewz</code> | |||
| {{number}} | |||
| Z component of the 3D view direction vector of the caller (Added in {{Changelog|1.2}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^viewx_{{Highlight|entity|<entity>}}</code> | |||
| {{number}} | |||
| X component of the 3D view direction vector of the given entity (Added in {{Changelog|1.2}}) | |||
| align="center" | {{N}} | |||
|- | |||
| <code>^viewy_{{Highlight|entity|<entity>}}</code> | |||
| {{number}} | |||
| Y component of the 3D view direction vector of the given entity (Added in {{Changelog|1.2}}) | |||
| align="center" | {{N}} | |||
|- | |- | ||
| <code>^ | | <code>^viewz_{{Highlight|entity|<entity>}}</code> | ||
| {{ | | {{number}} | ||
| | | Z component of the 3D view direction vector of the given entity (Added in {{Changelog|1.2}}) | ||
| align="center" | {{ | | align="center" | {{N}} | ||
|} | |} | ||
Line 396: | Line 548: | ||
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 <code>arx_bell</code> entity class that simulates a day/night cycle with 60 seconds per in-universe day plus 60 seconds per in-universe night. | 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 <code>arx_bell</code> entity class that simulates a day/night cycle with 60 seconds per in-universe day plus 60 seconds per in-universe night. | ||
=== Visibility === | |||
The <code>^onscreen</code> and <code>^onscreen_{{Highlight|entity|<entity>}}</code> system variables allow scripts to determine if the calling or given entity is currently shown on the screen. The following visibility values are defined: | |||
{| class="wikitable" | |||
! 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 <code>^offscreen</code> and <code>^offscreen_{{Highlight|entity|<entity>}}</code> system variables are the same as their <code>^onscreen</code> counterparts, but inverted and without expensive tests to check if the entity is really visible. This leaves the following values: | |||
{| class="wikitable" | |||
! 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 (<code>^onscreen < 0</code> or <code>^offscreen > 0</code>) uses portals and therefore the quality of the results depends on how well the portals are placed. There is an [[Debugging#Debug views|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: | |||
{{#ask: [[Category:Global variables]] | |||
|?Usage=Variable | |||
|?Description | |||
|mainlabel=- | |||
|limit=1000 | |||
|format=table | |||
|class=sortable wikitable smwtable code_0 | |||
}} | |||
= 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: | |||
{{#ask: [[Category:Entity variables]] | |||
|?Usage=Variable | |||
|?Description | |||
|mainlabel=- | |||
|limit=1000 | |||
|format=table | |||
|class=sortable wikitable smwtable code_0 | |||
}} | |||
[[Category:Scripting]] | [[Category:Scripting]] |
Latest revision as of 22:25, 2 January 2024
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. |