Documentation/content/getting-started/building-and-running.en.md

title, type, weight

title	type	weight
Building and Running	docs	2

This guide covers how to set up your development environment, build your plugin, and deploy it to a Hytale server.

Quick Start with example-mod

The easiest way to start plugin development is using the example-mod template which includes an automated setup script.

1. Clone the Repository

git clone https://github.com/hytale-france/example-mod.git
cd example-mod

Or download the latest release from GitHub Releases.

2. Download Tools (Once)

Download the required tools (hytale-downloader and CFR decompiler):

./setup.sh --download

This creates a .bin/ directory with:

• hytale-downloader-* - Official Hytale server downloader
• cfr-0.152.jar - Java decompiler for reference sources

3. Download the Server

Download and extract the Hytale server:

./setup.sh --setup

The server will be available in server/Server/HytaleServer.jar.

4. Generate Reference Sources (Optional)

Decompile the server JAR to get API reference sources:

./setup.sh --decompile

This creates src-ref/ with decompiled Java sources for IDE autocompletion and documentation.

Project Structure

After setup, your project will look like this:

example-mod/
├── app/
│   ├── src/main/java/org/example/
│   │   └── ExamplePlugin.java
│   ├── src/main/resources/
│   │   └── manifest.json
│   └── build.gradle.kts
├── server/
│   ├── Server/
│   │   └── HytaleServer.jar
│   └── Assets.zip
├── src-ref/                    # Decompiled reference sources
├── .bin/                       # Downloaded tools
├── setup.sh                    # Setup automation script
├── build.gradle.kts
├── settings.gradle.kts
└── gradlew

Building the Plugin

1. Build with Gradle

# On Linux/macOS
./gradlew build

# On Windows
gradlew.bat build

2. Locate the Built JAR

After a successful build, your plugin JAR will be in:

app/build/libs/ExamplePlugin-1.0.0.jar

Running the Server

1. Initial Server Setup

Start the server for the first time:

cd server
java -jar Server/HytaleServer.jar --assets Assets.zip

2. Authenticate

Once the server console is ready, run the authentication command:

/auth login device

Follow the instructions to authenticate with your Hytale account.

{{< callout type="warning" >}} Authentication Required: If no server tokens are configured, you will see a warning at startup:

No server tokens configured. Use /auth login to authenticate.

You must authenticate before players can join the server in non-singleplayer mode. {{< /callout >}}

3. Stop the Server

After authentication, you can stop the server:

• Linux/macOS: Press Ctrl+C
• Windows: Press Ctrl+C or close the terminal

Deploying Your Plugin

1. Copy the JAR

Copy the built JAR to the mods folder:

cp app/build/libs/ExamplePlugin-1.0.0.jar server/mods/

2. Start the Server

cd server
java -jar Server/HytaleServer.jar --assets Assets.zip

3. Verify Loading

You should see your plugin loading in the console:

[INFO] [PluginManager] Loading pending plugins from directory: mods
[INFO] [PluginManager] - org.example:ExamplePlugin from path ExamplePlugin-1.0.0.jar

Updating the Server

When a new Hytale version is released:

./setup.sh --update

This will download the latest server version and update your installation.

Common Issues

Java Version Mismatch

{{< callout type="error" >}} Error: Unsupported class file major version 69 {{< /callout >}}

Ensure you're using Java 25:

java --version

Manifest Not Found

{{< callout type="error" >}} Error: Failed to load manifest file! {{< /callout >}}

Make sure manifest.json is in src/main/resources/ and included in the JAR.

Setup Script Not Found

{{< callout type="error" >}} Error: ./setup.sh: Permission denied {{< /callout >}}

Make the script executable:

chmod +x setup.sh

Manual Setup (Alternative)

If you prefer manual setup without the script:

Locating Hytale Installation

Find your Hytale installation directory:

{{< tabs items="Windows,Linux,macOS" >}} {{< tab >}}

%appdata%\Hytale\install\release\package\game\latest

{{< /tab >}} {{< tab >}}

$XDG_DATA_HOME/Hytale/install/release/package/game/latest

Or typically:

~/.local/share/Hytale/install/release/package/game/latest

{{< /tab >}} {{< tab >}}

~/Application Support/Hytale/install/release/package/game/latest

{{< /tab >}} {{< /tabs >}}

Manual Server Setup

1. Copy Server/ and Assets.zip from your Hytale installation
2. Download CFR from https://www.benf.org/other/cfr/
3. Decompile: java -jar cfr.jar HytaleServer.jar --outputdir src-ref

Next Steps

Now that you can build and run your plugin, explore:

• Plugin Lifecycle - Understand setup, start, and shutdown
• Commands - Create custom commands
• Events - Listen to game events