Getting Started

Setting Up

Not every feature is covered in the tutorial yet. 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 and more in the future.

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.9 through 26.2, 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 or symlink 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.

warning

Note that on Windows, building directly into the datapacks folder will likely freeze the compiler due to Windows file locking mechanics. The easiest way to get around this is to create a symlink to the zipped data pack. A solution will be provided in the future.

Your First Project

Navigate to a new folder in your terminal and run the following:

amethyst shard init

Once you provide all the information, Amethyst will generate a project for you. The structure should look something like this:

<directory>
├── data
├── shard.json
└── src
    └── main.ame

Test your project by running amethyst build --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.

note

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.

The most important file created is shard.json. Amethyst calls projects/packages shards (because why not). Inside you will find important information like the shard name, target pack format, and dependences. Amethyst automatically generates a dependency to libminecraft which houses block data, entity data, and more for the selected Minecraft version. libminecraft is aliased as simply minecraft in the dependencies section.

warning

Package management and libminecraft are currently works in progress. As of writing, data definitions are not available for use. Create them manually as needed until libminecraft available.

The data folder is used to add additional files into the final data pack. Anything placed inside will be added to the data pack with no modification.

The src folder contains all of the .ame files to compile. New projects generate a simple src/main.ame file.

Writing Code

Inside the src/main.ame file, you will find a Hello World program.

namespace tutorial;

The first line tells the compiler what namespace to put the functions into. By default, the namespace is the name of the project you chose during creation. 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() {
    print("Hello World!");
    amethyst:exit();
}

The next part is the main function. All logic must be placed into a function. In this case, Amethyst 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 remove this line.