The script system is extremely simple and executes instructions based on preprogrammed commands which perform a specific task. A few conditional features are provided, but complex control structures may be difficult to achieve.
Detailed Command Reference
Directives and Metadata
Brief Command Reference
Strings, variables, integer lists, and labels are typically assigned when encountered by the compiler and can be used in further instructions.
Variable names should not contain punctuation.
It is good practice to initialize them at the beginning of a script using the set command.
Variables are case sensitive. If call one VAR and another var, they are not the same.
Example:
set var 0
set varb 4
When defining labels in the script, prepend a colon (:). Leave out the colon when using the label in a command.
Example:
:begin
; ... other stuff here
goto begin
Some of the new features added may not be fully functional, so be sure to thoroughly test any scripts which use them.
This includes the following commands: else (if/else/endif), iarrappend, iarrdelete, iarrvalue, iarrclear, iarrsize, queue_event, exec_queue.
And includes the following directives: #symbol, #queue_jumps.
Integer Arrays aren't really useful on their own, but were implemented because some augmented script commands required them, like creature searches that needed to return multiple results.
This command can be useful to reset execution and jump out of deeply nested control statements and call operations.
:begin
reset_goto begin
Retrieves the value of an internal server variable and place the result into the destination variable.
getappvar "somevar" var
Call commands may be nested to facilitate implementation of more complex logic or pseudo-functions. The stack is limited to hold a maximum of 16 return positions.
Every block of code jumped to by call must encounter a return command. It is strongly recommended that you do not use goto to leave the block. It may cause a stack overflow if a call is never completed.
In the event of a stack overflow or corrupted stack, script execution may become erratic or halt entirely.
Example:
:begin
call subroutine ; stack +1
; safely returns to the beginning, since the call stack is empty.
goto begin
:subroutine
; do stuff
return ;stack -1
See the call command for an explanation and example.
if [value] [comparator] [value]The following mathematical comparators are allowed: {=,!=,<,<=,>,>=}
Use endif to close an if block.
Recent changes Script Core allow nested if statements. Each one must be closed by a corresponding endif.
Also new, optionally you may use the else keyword to separate blocks for true or false. Only use one else per if block.
Other parameter types and complex expressions are not supported.
Example:
inc var
if var >= 5
print "blah!"
else
print "nope"
endif
See the example for the if command.
iarrappend [intarr] [intstk]Appends a value to an integer array.
Example:
set VAR 2
iarrappend iarr 1
iarrappend iarr VAR
Produces an array of [1,2]
iarrdelete [intarr] [intstk]Removes an index (not a specific value) from an integer array. Arrays are indexed beginning at zero, so [0] is the first item, [1] is the second, etc.
Example:
iarrappend iarr 10
iarrappend iarr 20
iarrappend iarr 30
iarrdelete iarr 0
Produces an array of [20,30].
iarrvalue [intarr] [intstk] [variable]Find the of an integer array, at a specific index (zero based) and place the result into a variable.
Example:
iarrappend iarr 10
iarrappend iarr 20
iarrvalue iarr 1 VAR
VAR will now hold the value of 20.
iarrclear [intarr]The queue has a hardcoded maximum of 16 events.
Example:
queue_event "Something" 0
Example:
queue_event "event" 5000
:main
exec_queue
goto main
:event
queue_event "event" 5000
return
This example initially queues up an event to trigger in 5 seconds. When the event is called, it adds itself back to the queue, triggering it every 5 seconds indefinitely as long as the script is running.
pushvar [variable]The stack only holds 16 elements, and other functions like if use the stack as well.
pushint [integer]
Example:
pushint 5
pop VAR
VAR will now be 5.
These are not instructions, but signal certain global features that are assigned during the compilation phase. They help control how the script compiles or executes, in the ways that the server program itself accesses and controls the scripts from outside the script itself.
#name [string]
Example:
#name 4_druid_melee_30
Example:
#symbol BASH 288
use BASH
This example is used in the context of an AI script. When the compiler encounters BASH, it will automatically substitute 288 (the ability ID). So the lines
use BASH
use 288
compile into the same instruction.
Every cycle (or frame) of the server will process a certain number of instructions to avoid consuming too much CPU power, especially in the case of infinite loops.
This is most commonly used in more intricate scripts that contain heavy use of conditional branches, jumps and calls. The common if command compiles into three instructions which set up the data before the comparison is made. These conditionals can have a major impact on the total number of instructions, and thus increase the number of server frames which are required to run a full cycle of the script. Detailed AI scripts in particular will run noticeably slower, and will require a higher #speed allocation to help them run more smoothly, and react faster.
Example:
#speed 10
This field is of particular use to AI Scripts. Refer to the AI Script documentation for details.
Example:
#idlespeed 1
The string can be one of two things "call" or "goto". Using call means that exec_queue will interpret the jump as a call instruction to the appropriate label, requiring a return to unwind. Using goto means that the jump will be interpreted as goto and will require another goto to jump back.
By default, queued jumps are set to false and the call style is set to "call". Using queue_jumps sets queued jumps to true. Queued jumps determine how the server handles explicit jumps to labels within the script.
For instance scripts, when mobs are killed it will generate a label name based from the mob type. If the label is found in the script, the script will jump to that label to perform any creature-specific processing, like tracking step-up spawns.
If queued jumps are false (the default state), then the jump will be abrupt, interrupting any prior execution chain, and clearing and the variable and call stacks.
If queued jumps are enabled, the script will resume execution as normal (finishing whatever operation it was currently doing). However, the script must have exec_queue in its main loop to process the jump, otherwise nothing will happen.
A maximum of 16 events may be queued at once.
Examples:
#queue_jumps goto
OR
#queue_jumps call
report_end report_label report_all
The value can be set to 1 to enable, or 0 to disable, although flags are disabled by default.
If report_end is activated, a debug message will be printed when the script ends.
If report_label is activated, a debug message will be printed if a requested jump label doesn't exist in the script.
report_all will activate both flags.
Example:
#flag report_end 1