Bukkit

Variables

Variables are named locations where to store data. Variables are essential to nearly any advanced operation you want to do. Here's how Commander script handles variables:

What They Are

In Commander Script, a variable is defined by using an at sign (@) and following it with the name of the variable you wish to use. Nearly anywhere where a literal string or number can be placed, a variable can be placed. So you can assign values to variables and put them directly into a command to be executed. The value of the variable will replace the name of it before the command is sent to the server. For example:

@a = hello world
say @a

This code will execute the command "say hello world"!

How to Use Them

To assign a variable, simply use a line like the following:

@name = Something to Store

This will assign the string "Something to Store" to the variable named "name". Note that assignments must be on their own line and must start with the at sign that defines a variable. If the variable was never used before, it is created. If it has been used before, the value inside is replaced.

You can also increment or decrement a variable as well, if it contains a number:

@time = 10
@time++    #now it is 11
@time--    #now it is back to 10

What They Contain

Variables in Commander Script can contain a string, a whole number, a boolean value (true or false), or a collection (see below). Variables can switch between these types on the fly as well, if it makes sense.

Technical details (skip over if your eyes glaze over): Though Commander (and Minecraft) is implemented in type-safe Java, Commander's variables are "dynamic". Everything prints to a string regardless, so it can all be put into commands. If a construct in Commander can manipulate a variable as if it were another type besides a String (like, for example, the increment/decrement above, or comparing two numbers in an if statement) it will convert the variable to the other type.

Scoping

The variables in Commander are scoped, that is, their existence is limited based on where they were first defined. Variables only exist within the block they were first defined in. Example code:

@x = 12
{
    say @x    # prints "12"
    @y = 10
    @x = 24
    say @x, @y    #prints "24, 10"
}
say @x, @y    #prints "24, ø"

So, in the example above, @x is defined first outside the code block, where as @y is first defined inside the block. @x can be modified from inside the block and will keep its value when the code leaves the block. But @y loses its value once it leaves the block. (Variables that are not defined print out as "ø", meaning empty set or null).

This is most often noticeable in loop constructs:

[loop @x = 1 to 10] {    #variables defined inside constructs are part of the block
    say @x      #prints out the numbers from 1 to 10
}
say @x      #prints out "ø"

Collections

Collections are special variables. They contain a bunch of strings that can be iterated over using the For Each Construct. If you attempt to print out a collection, you'll just get strange garbage that Commander uses internally to identify the collection.

You'll most often find collections when you are using Environment Variables; the server.players variable returns a collection of online players. From there, you can use code like the following:

[foreach @player in $(server.players)] {
    tell @player *you feel a chill run down your back*
}

This will whisper this phrase to everyone on the server at the moment. Chilling.