Variables

Syntax

Variables are stored on the stack. While other high-level languages only store certain objects like numbers and booleans on the stack, Amethyst stores all NBT objects on the stack. This includes strings, lists, and compounds. Therefore these objects are pass-by-value (see references for passing values by reference). The only exceptions to this rule are entities and classes.

int x = 7;
string y;
var str = "foo";

The variable is set to a default value if there is no initializer. Objects with a constructor must have an initializer.

The var keyword can be used to inference the type of the variable using the initializer.

Constant Variables

Variables can be marked constant via the const storage modifier. Constants can only be literal values and must have an initializer.

const int x = 7;

Static Variables

Static variables work similarly to how they do in C. They act exactly like global variables except they are defined inside of functions.

void func() {
    static string str = "Hi";
    str = "Hi2"; // str is now "Hi2" until the next reload. Static variable initializers are optional.
}

Scopes

Variable obey the traditional rules of scoping, so variables can be redefined inside of scopes and can be accessed from descendent scopes.

int x = 7;
int y = 3;

{
    // Valid, x is now a long in this scope
    long x = 2;
    print(y);
}

Casting

Values can attempt to be casted to other types. There are two main types of casting: implicit and explicit. Implicit casting, as the name suggests, is done automatically where applicable. Explicit casting happens when using the cast expression:

string str = "Hi";
int x = (int)str;

info

Explicit casting is mainly used for casting down an inheritance tree. However some types have special explicit casting rules. For instance, casting anything to an int will effectively use /execute store. So for most values, it will call /data get and store that into a score.

Math

All the normal operators work as expected.

Amethyst also provides the following unary operators:

• ++x
• --x
• !x
• -x

note

Postfix increment and decrement (x++) does not exist due to clarity concerns. This may change in the future.

warning

Minecraft may handle integer division slightly differently than the languages you are used to.

Strings

Strings in Amethyst are implemented using NBT strings. Only double quotes are supported for now.

string str = "Hello World";

tip

All Minecraft string escape codes can be used.

qstring

Minecraft un-escapes strings when passing them as macros and does not provide an efficient way to escape them. As such, normal strings are not allowed to be passed as macro arguments. Amethyst provides a solution through qstrings. A qstring is a special type of string that cannot have double quotes in it. Technically this restriction can be bypassed relatively easily through casting, but doing so will likely cause a runtime error.

note

Programmers are not good at coming up with names, so qstring may be renamed in the future.

Methods

• int str.length(): String length. Compiles internally as (int)str.

Lists

Lists store an ordered collection of values. Untyped lists (using list) are unsupported currently.

int[] list = [-7];

list.add(10);
list.add(5);
list.add(x * y);

print(list[2]);

Methods

• void T[].add(T val): Add a value to the end of the list.
• void T[].remove_at(int index): Remove a value at an index.
• T T[].pop(): Pop a value from the end of the list.
• int T[].size(): Get the size of the list.
• T[] T[].where(nbt predicate): Get a copy of a subset of the list that matches a predicate. Uses NBT paths of the form list[predicate]. Only works on lists of compounds, maps, or structs.
• T^ T[].all(): Get a special reference using an NBT path of the form list[]. This allows modifying the properties of all NBT compounds in a list at once.

warning

There are currently no bounds checks. Eventually it will be included in debug builds and optionally in release mode builds.

Maps

Maps act like dictionaries in other languages except only unsafe_strings can be used as keys. To create one, append {} to the desired value type:

int{} map = { one: 1, two: 2, three: 3 };
map["four"] = 4;

Objects

Typeless NBT compounds can be created using the nbt type:

nbt x = { thing1: 7, thing2: 6s };
x.property = "Hi";
print(x);

Maps, NBT compounds, and derivative types have a contains method for checking if a property is defined.

print(x.contains("thing1"));