159 lines
5.2 KiB
Plaintext
159 lines
5.2 KiB
Plaintext
---
|
|
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>
|