5 min

Getting Started

Set up your first Hytale server plugin in minutes. This guide covers project structure, compilation, and deployment.

Prerequisites

Before you start, ensure you have the following installed:

requirementversionnotes
Java JDK25 (recommended) or 21Adoptium recommended
HytaleServer.jarLatestThe server API JAR
Text Editor/IDEAnyIntelliJ IDEA recommended
java version
Hytale officially recommends Java 25. However, Java 21 LTS works fine for development and may be preferable on some VPS providers with limited Java 25 support.

Project Structure

A minimal Hytale plugin requires two files:

1. Main Plugin Class

MyPlugin.javajava
1public class MyPlugin extends JavaPlugin {
2    
3    public MyPlugin(JavaPluginInit init) {
4        super(init);
5    }
6    
7    @Override
8    protected void setup() {
9        // Called when plugin loads
10        getLogger().info("Plugin is setting up...");
11    }
12    
13    @Override
14    protected void start() {
15        // Called when server is ready
16        getLogger().info("Plugin started!");
17    }
18    
19    @Override
20    protected void shutdown() {
21        // Called on server stop
22        getLogger().info("Plugin shutting down...");
23    }
24}

2. Plugin Manifest

important
The manifest file must be named manifest.json, NOT plugin.json.
manifest.jsonjson
1{
2    "Group": "com.example",
3    "Name": "my-plugin",
4    "Version": "1.0.0",
5    "Main": "com.example.MyPlugin"
6}

Compilation

Compile your plugin against the HytaleServer.jar:

Terminalbash
1# Create build directory
2mkdir -p build/classes
3
4# Compile Java files (use 25 or 21 depending on your JDK)
5javac --release 21 \
6  -cp "/path/to/HytaleServer.jar" \
7  -d build/classes \
8  src/com/example/*.java
9
10# Package into JAR
11jar cvf my-plugin.jar \
12  -C build/classes . \
13  manifest.json

Deployment

Deploy your plugin by copying the JAR to the server mods folder:

1# Copy to local server
2cp my-plugin.jar /path/to/Server/mods/
3
4# Or deploy to remote server
5scp my-plugin.jar user@server:~/hytale/Server/mods/
hot reload
Currently, you need to restart the server to load new plugins. Hot reload may be available in future Hytale versions.

Verify Installation

Start your server and check the logs for your plugin messages:

1[INFO] Loading plugin: my-plugin v1.0.0
2[INFO] Plugin is setting up...
3[INFO] Plugin started!

Next Steps

Now that your plugin is running, learn about the plugin lifecycle and the critical threading model before writing more complex code.