Getting Started

Setting Up

Not every feature is covered in the tutorial. The handbook is still a valuable resource and you should read it to get the full picture.

Visual Studio Code

It is recommended to use Visual Studio Code since an extension exists to provide syntax highlighting. As of now, the extension is not available in the marketplace and has to be installed manually.

The latest version can be found in Github Actions. Extract the .vsix file and install it by either running code --install-extension amethyst-language-<version>.vsix or by opening the containing folder in VS Code and right-clicking the .vsix file.

note

The extension's version does not match up with the compiler's version. An update is only made to the extension when the Amethyst syntax changes. If you encounter incorrect highlighting, try updating the extension.

Minecraft

This version of Amethyst is tested on Minecraft 1.21.10, but can theoretically work in versions as early as 1.20.5 or so.

There are two main ways to run an Amethyst program:

1. Create a Minecraft world and build the data pack into the datapacks folder in your world.
2. Use an automatically configured Minecraft server with the built-in daemon mode.

To use the second option, run amethyst setup --eula to install the Minecraft server. An appropriate version of Java must be installed on the machine for this to work. See the documentation for configuration options.

Your First Program

Create a file called tutorial.ame and copy the following program into it:

namespace tutorial;

#load
void main() {
    print("Hello World");
    amethyst:exit();
}

Then open a terminal in the same directory as tutorial.ame and run the following:

amethyst build tutorial.ame -o out.zip --run

If everything was configured correctly, your console should say Hello World after a few seconds. Subsequent runs will be faster since Amethyst keeps the Minecraft server alive for a while.

If you did not set up a Minecraft server, copy or symlink the data pack to the datapacks folder of your Minecraft world and then run /reload.

Let's break down the program.

namespace tutorial;

The first line tells the compiler what namespace to put the functions into. In this case, we use the tutorial namespace. If you were to omit this line, then everything would be put into the minecraft namespace.

See Namespaces for more information on namespaces.

#load
void main() {
    
}

The next part is the main function. All logic must be placed into a function. In this case, we chose the tutorial:main function. A function is not just some abstraction that Amethyst makes, it is just a .mcfunction file and can be called like any other data pack function.

There is nothing special about the name main. The function could as very well been called anything. The reason it was ran automatically on load is because it had the #load tag. Putting a tag before the return type adds the function to a function tag. #load and #tick are shortcuts for #minecraft:load and #minecraft:tick, respectively.

print("Hello World");

The first line of the function prints Hello World to the chat since print uses /tellraw @a under the hood. Variables and other non-string constants can also be passed into print. All of its arguments are concatenated together with no spaces.

amethyst:exit();

The last line has no impact on the effect of the function. Its only purpose is to tell amethyst run that the program as terminated. Otherwise the program in the terminal will never stop unless you hit Ctrl-C. If you are not using amethyst run, then you can omit this line.