Bukkit

Constructs

Constructs are the major addition to scripting that makes advanced scripting advanced! A construct is defined as a statement surrounded by [square brackets] which controls the flow of the script. Some constructs have blocks of code they run, some don't.

Below is a list of the various constructs that you can use when scripting!

If Construct

[if x = y] #equals comparison
[if x != y] #not equals comparison
[if x > y] #greater than
[if x < y] #less than
[if x >= y] #greater than or equal to
[if x <= y] #less than or equal to
[if x] #boolean check
[!if x = y] #not if form
[unless x = y] #unless form

The if construct takes the form "[if <condition>]" and requires a block or line of code following immediately afterward to run. Currently supported conditions include comparison conditions (including equals to and order comparisons), check conditions (checks true or false, along with if the variable is not empty), and has conditions (see below).

The if construct can be negated by placing a exclamation point (!) in front of the word "if". The if construct also comes in an alternate form, "[unless <condition>]" which also negates the if statements. The line "[!unless x]" is equivalent to the line "[if x]".

Has Construct

[has x] #shortcut permission check
[if has x] #check current player permission
[if P has x] #check another player permission
[if !has x] #not has form

The has construct (or has condition) takes the form "[if <PlayerName> has <permission>]", and requires a block or line of code following immediately afterward to run. The PlayerName argument defaults to the command-issuing player if not supplied. The Has construct is actually a pseudo-construct, as it parses out to a condition in an if statement. The shortcut syntax cannot be used to check a player other than the command-issuing player.

The has construct uses Bukkits built-in permission system to check permissions, so any permissions plugins you are using must support that (if there are any that don't anymore).

The has construct and condition can be negated by placing a exclamation point (!) in front of the word "has". This combines with any negation to the if construct; the line "[!if !has x]" is equivalent to the line "[if has x]".

Loop Construct

[loop @var = x to y]
[loop @var = x to y step z]

The loop construct takes the form "[loop @<varname> = <start> to <end> step <step>]" and requires a block or line of code following immediately afterward to run. The start, end, and step arguments must be numbers or the script will not parse. The step argument defaults to 1 if it is not supplied, and cannot be 0. The start argument must be smaller than the end argument if step is positive, and must be bigger than the end argument if step is negative.

The variable @varname is set to the number of the current loop on every loop, is available inside the loop's body only (see variable scoping), and, if changed, will not affect the loop. The variable is for your use only; the loop uses an internal variable to keep track of the loop count. Break statements (see below) will stop the loop prematurely.

ForEach Construct

[foreach @var in x]

The foreach construct takes the form "[foreach @<varname> in <expression>]" and requires a block or line of code following immediately afterward to run. The expression must parse out at runtime to a valid collection; checking cannot happen when parsing. This is usually a call to an environment variable returning a collection, such as "server.players".

The variable @varname is set to one of the strings in the collection on every loop, and is available inside the loop's body only (see variable scoping). Collections by definition have no defined order, but a collection will always have the same order as long as it is not modified between foreach loops. Break statements (see below) will stop the loop prematurely.

While Construct

[while x = y] #equals comparison
[while x > y] #greater than
[while x < y] #less than
[while x >= y] #greater than or equal to
[while x <= y] #less than or equal to
[while x] #boolean check
[!while x] #not while form
[until x] #until form

The while construct takes the form "[while <condition>]" and requires a block or line of code following immediately afterward to run. The conditions used in while loops are the same as the condition used in an if construct. Think of a while construct as an if construct that loops while the condition is true.

The while construct can be negated by placing a exclamation point (!) in front of the word "while". The while construct also comes in an alternate form, "[until <condition>]" which also negates the while statements. The line "[!until x]" is equivalent to the line "[while x]".

Break statements (see below) will stop the loop prematurely. Note that for stability purposes, the while loop is limited to 200 loops before a script error is thrown. This cap can be modified with the looplim directive.

Break Construct

[break]

The break construct takes the form "[break]" and is stand alone. Any arguments given to the break construct will cause a parsing error. The break construct breaks the script execution out of the current loop or script. If used inside a loop, such as the while construct, the script will stop execution of the contents of the loop immediately and continue after the loop. If used somewhere where no loop is present, it will stop execution of the script (equivalent to a return statement in another language).

Run Construct

[run x]

The run construct takes the form "[run <alias>]" and is stand alone. The run construct will call to the script engine and ask for another script with the given alias, and proceed to run it. The called script will run as if it were a block in your script, with access to the same variables and state. Break statements (see above) will break out of the called script and continue execution after the run statement.

Note that for stability purposes, the run statement is limited to 10 recursive calls before a script error is thrown. This cap can be modified with the runlim directive.