---
title: Building and Running
type: docs
weight: 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](https://github.com/hytale-france/example-mod) template which includes an automated setup script.

### 1. Clone the Repository

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

Or download the latest release from [GitHub Releases](https://github.com/hytale-france/example-mod/releases).

### 2. Download Tools (Once)

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

```bash
./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:

```bash
./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:

```bash
./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

```bash
# 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:

```bash
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:

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

### 2. Start the Server

```bash
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:

```bash
./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:

```bash
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:

```bash
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/](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](../plugin-lifecycle) - Understand setup, start, and shutdown
- [Commands](../../commands) - Create custom commands
- [Events](../../events) - Listen to game events