Getting Started

Installation

To get started with Shulkerscript, you need to install the Shulkerscript CLI. You can either download the latest release from the GitHub releases page or build it from source.

Tip

If you want to try out Shulkerscript without installing anything, you can use the online playground right in your browser.

Quickinstall script (recommended)

1. Windows

   Open a PowerShell terminal and run

   iex (iwr "https://raw.githubusercontent.com/moritz-hoelting/shulkerscript-cli/main/install.ps1").Content

   Linux / macOS

   Open a bash terminal and run

   curl -sfSL https://raw.githubusercontent.com/moritz-hoelting/shulkerscript-cli/main/install.sh | bash

2. Test the installation by running

   shulkerscript --version

Info

The script will check if you have cargo-binstall installed and use it if available. Otherwise it will download the binary from GitHub if available for your platform. As a fallback it will build the CLI from source if Rust is installed.

Download with cargo-binstall

1. Make sure you have cargo-binstall installed. If not, follow the installation instructions.
2. Run

   cargo-binstall --git https://github.com/moritz-hoelting/shulkerscript-cli shulkerscript-cli

3. Test the installation by running

   shulkerscript --version

Download from GitHub

1. Go to the GitHub releases page and download the latest release for your platform.
2. Extract the downloaded archive.
3. Move the extracted binary to a directory in your PATH (required for the CLI to be accessible from anywhere).
4. Test the installation by running

   shulkerscript --version

   You should see the version of the CLI printed to the console.

Building from source

Caution

This method takes the longest. If you have no reason to build from source, you may want to take a look at the other installation methods.

1. Make sure you have Rust and Cargo installed.
2. Install the CLI by running

   cargo install --git https://github.com/moritz-hoelting/shulkerscript-cli

3. Test the installation by running

   shulkerscript --version

Installing the VS Code extension (optional)

To get syntax highlighting and snippets for Shulkerscript files in Visual Studio Code, you can install the official extension.

Creating a new project

1. Create a new directory for your project.
2. Navigate into the directory.
3. Run

   shulkerscript init

   This will create a new Shulkerscript project in the current directory.
4. Open the pack.toml file in your favorite text editor and configure the project to your liking.

The project structure should look like this:

• Directorysrc/

  • main.shu
• .gitignore
• pack.toml
• pack.png

Note

All files in the src directory with the .shu extension will be processed and neccessary functions generated.

Writing your first script

After opening the file src/main.shu in your favorite text editor, you should see the following content:

src/main.shu

namespace "your-name";

#[tick]
fn main() {
    /say Hello, world!
}

The annotation #[tick] tells the compiler that this function should be executed every tick. Every line that starts with a / is a command that will included in the output. You can add as many commands as you like. To begin with, you can change the message in the /say command to something else.

Caution

Only functions annotated with #[tick], #[load], #[deobfuscate] or called from generated functions will be included in the output.

Building the project

1. Navigate into the project directory.
2. Run

   shulkerscript build

   This will compile the project and output the result to the dist directory.
3. Alternatively you can run

   shulkerscript watch

   to automatically rebuild the project when a file changes.

Distributing the project

1. Navigate into the project directory.
2. Run

   shulkerscript build --zip

   This will create a ZIP archive containing the compiled project.
3. You can now distribute the archive to your users.