Arx scripting language: Difference between revisions
No edit summary |
mNo edit summary |
||
(23 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
This article describes the scripting language used in Arx Fatalis and Arx Libertatis. | This article describes the scripting language used in Arx Fatalis and Arx Libertatis. Arx scripting language files use the <code>.asl</code> file extension. | ||
= | = Syntax = | ||
Scripts are case insensitive - Arx Libertatis converts the entire script source to lowercase. | |||
== Events == | == Events == | ||
Line 15: | Line 13: | ||
{{Main|Script:Variables}} | {{Main|Script:Variables}} | ||
Arx scripts know three basic data types: {{int}}, {{ | Arx scripts know three basic data types: {{int}}, {{number}} and {{string}}. Variables can be either global (shared between all entities) or entity-specific. There are also special [[Script:Variables#System variables|system variables]] than can only be read. The variable type is defined by the first character of the variable name. | ||
{| class="wikitable" style="text-align:center;" | {| class="wikitable" style="text-align:center;" | ||
Line 22: | 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> || [[Script:Variables#System variables|system]] || (mixed) | ||
|} | |} | ||
Line 40: | Line 38: | ||
{{Main|Script:Commands}} | {{Main|Script:Commands}} | ||
== Comments == | |||
Comments start with <code>//</code> and go until the end of the line. Because scripts are not properly parsed, <code>//</code> in unquoted parameters will be treated as a comment. There are no multi-line comments, but two tricks can be used to skip multiple lines of code: | |||
Because [[Script:Commands#Other commands as parameters|delayed command execution]] requires the byte position of these commands to no change to preserve save file compatibility, Arx Fatalis scripts will often contain events or labels with the first character of the name changed to <code>_</code>. | |||
Another way to unconditionally skip execution of some code is to surround it with {{Command|else|{}} and <code>}</code> without any preceding {{Command|if}} or other conditional command. | |||
== Control flow == | == Control flow == | ||
{{Main|:Category:Script control flow}} | |||
Execution of the current event is terminated with the {{Command|accept}} or {{Command|refuse}} commands. For entity instance scripts, {{Command|refuse}} ends event execution completely while {{Command|accept}} allows execution to continue in the entity class script. | |||
=== Blocks === | |||
The {{Command|if}}, {{Command|else}}, {{Command|random}}, {{Command|ifvisible}} and {{Command|ifexistinternal}} commands will skip the next block under certain conditions. A block is either a series of commands on the same line <code>{</code> followed by all commands until the next matching <code>}</code>. If the next command after a skipped block is {{Command|else}}, that command will be skipped as well and the following block (which would normally be skipped by {{Command|else}}) will be executed. | |||
=== Labels === | |||
The two characters <code>>></code> followed directly by a name define a label. These are skipped when encountered during normal execution but can serve as the target to jump to for a {{Command|goto}} or {{Command|gosub}} command. Execution of the next command after {{Command|gosub}} can be resumed using the {{Command|return}} command | |||
Arx Libertatis ignores labels inside [[#Comments|comments]] while Arx Fatalis 1.21 will happily jump to them. | |||
=== Commands as parameters === | |||
{{Main|Script:Commands#Other commands as parameters}} | |||
== Search script files | [[:Category:Script delayed execution|Some commands]] take another command as their last parameter. For such commands all following commands on the same line will be skipped during normal execution. Then after some action started by the command is completed these commands will be executed using the special {{Event|executeline}} event. | ||
= Examples = | |||
See the [https://github.com/arx-tools/asl-cookbook ASL Cookbook] for examples of useful commands. | |||
= Search script files = | |||
mkdir assets | mkdir assets | ||
Line 52: | Line 77: | ||
arxunpak ~/.local/share/arx/{data,loc,data2,sfx,speech}.pak | arxunpak ~/.local/share/arx/{data,loc,data2,sfx,speech}.pak | ||
grep -rP -ia 's_*p_*e_*c_*i_*a_*l_*f_*x' graph/obj3d/interactive/ | grep -rP -ia 's_*p_*e_*c_*i_*a_*l_*f_*x' graph/obj3d/interactive/ | ||
Arx Libertatis comes with the <code>find-script-command</code> helper in the scripts directory to allow searching for script commands without manually creating a grep expression like the one above. | |||
[[Category:Scripting]] | [[Category:Scripting]] |
Latest revision as of 00:24, 10 March 2024
This article describes the scripting language used in Arx Fatalis and Arx Libertatis. Arx scripting language files use the .asl
file extension.
Syntax
Scripts are case insensitive - Arx Libertatis converts the entire script source to lowercase.
Events
- Main article: Script:Events.
Variables
- Main article: Script:Variables.
Arx scripts know three basic data types: int
, number
and 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.
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.
Commands
- Main article: Script:Commands.
Comments
Comments start with //
and go until the end of the line. Because scripts are not properly parsed, //
in unquoted parameters will be treated as a comment. There are no multi-line comments, but two tricks can be used to skip multiple lines of code:
Because delayed command execution requires the byte position of these commands to no change to preserve save file compatibility, Arx Fatalis scripts will often contain events or labels with the first character of the name changed to _
.
Another way to unconditionally skip execution of some code is to surround it with else {
and }
without any preceding if
or other conditional command.
Control flow
- Main article: Category:Script control flow.
Execution of the current event is terminated with the accept
or refuse
commands. For entity instance scripts, refuse
ends event execution completely while accept
allows execution to continue in the entity class script.
Blocks
The if
, else
, random
, ifvisible
and ifexistinternal
commands will skip the next block under certain conditions. A block is either a series of commands on the same line {
followed by all commands until the next matching }
. If the next command after a skipped block is else
, that command will be skipped as well and the following block (which would normally be skipped by else
) will be executed.
Labels
The two characters >>
followed directly by a name define a label. These are skipped when encountered during normal execution but can serve as the target to jump to for a goto
or gosub
command. Execution of the next command after gosub
can be resumed using the return
command
Arx Libertatis ignores labels inside comments while Arx Fatalis 1.21 will happily jump to them.
Commands as parameters
- Main article: Script:Commands#Other commands as parameters.
Some commands take another command as their last parameter. For such commands all following commands on the same line will be skipped during normal execution. Then after some action started by the command is completed these commands will be executed using the special executeline
event.
Examples
See the ASL Cookbook for examples of useful commands.
Search script files
mkdir assets cd assets arxunpak ~/.local/share/arx/{data,loc,data2,sfx,speech}.pak grep -rP -ia 's_*p_*e_*c_*i_*a_*l_*f_*x' graph/obj3d/interactive/
Arx Libertatis comes with the find-script-command
helper in the scripts directory to allow searching for script commands without manually creating a grep expression like the one above.