---
title: Getting Started
description: Get started with Shulkerscript
---
import { Steps, FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
import OsTabSwitcher from '../../../components/OsTabSwitcher.astro';

## Installation

To get started with Shulkerscript, you need to install the Shulkerscript CLI.
You can either [download](#download-from-github) the latest release from the GitHub releases page or [build it from source](#building-from-source).

:::tip
If you want to try out Shulkerscript without installing anything, you can use the [online playground](../../playground) right in your browser.
:::

### Quickinstall script *(recommended)*
<OsTabSwitcher />
<Steps>
1. <Tabs>
        <TabItem label="Windows" icon="seti:windows">
            Open a PowerShell terminal and run
            ```powershell
            iex (iwr "https://raw.githubusercontent.com/moritz-hoelting/shulkerscript-cli/main/install.ps1").Content
            ```
        </TabItem>
        <TabItem label="Linux / macOS" icon="linux">
            Open a bash terminal and run
            ```bash
            curl -sfSL https://raw.githubusercontent.com/moritz-hoelting/shulkerscript-cli/main/install.sh | bash
            ```
        </TabItem>
    </Tabs>
2. Test the installation by running
    ```bash
    shulkerscript --version
    ```
</Steps>

:::note[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
<Steps>
1. Make sure you have [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) installed. If not, follow the [installation instructions](https://github.com/cargo-bins/cargo-binstall?tab=readme-ov-file#installation).
2. Run
    ```bash
    cargo-binstall --locked --git https://github.com/moritz-hoelting/shulkerscript-cli shulkerscript-cli
    ```
3. Test the installation by running
    ```bash
    shulkerscript --version
    ```
</Steps>

### Download from GitHub
<Steps>
1. Go to the [GitHub releases page](https://github.com/moritz-hoelting/shulkerscript-cli/releases) and download the latest release for your platform.
2. Extract the downloaded archive.
3. Move the extracted binary to a directory in your [PATH](https://en.wikipedia.org/wiki/PATH_(variable)) *(required for the CLI to be accessible from anywhere)*.
4. Test the installation by running
    ```bash
    shulkerscript --version
    ```
    You should see the version of the CLI printed to the console.
</Steps>

### 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.
:::
<Steps>
1. Make sure you have [Rust and Cargo](https://rustup.rs) installed.
2. Install the CLI by running
    ```bash
    cargo install --locked --git https://github.com/moritz-hoelting/shulkerscript-cli
    ```
3. Test the installation by running
    ```bash
    shulkerscript --version
    ```
</Steps>

## 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](https://marketplace.visualstudio.com/items?itemName=moritz-hoelting.shulkerscript-lang).

## Creating a new project
<Steps>
1. Create a new directory for your project.
2. Navigate into the directory.
3. Run
    ```bash
    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.
</Steps>

The project structure should look like this:
<FileTree>
- src/
  - main.shu
- .gitignore
- pack.toml
- pack.png
</FileTree>

:::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:
```shulkerscript title="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
<Steps>
1. Navigate into the project directory.
2. Run
    ```bash
    shulkerscript build
    ```
    This will compile the project and output the result to the `dist` directory.
3. Alternatively you can run
    ```bash
    shulkerscript watch
    ```
    to automatically rebuild the project when a file changes.
</Steps>

## Distributing the project
<Steps>
1. Navigate into the project directory.
2. Run
    ```bash
    shulkerscript build --zip
    ```
    This will create a ZIP archive in the `dist` directory containing the compiled project.
3. You can now distribute the archive to your users.
</Steps>