Hytale Modding Docs

Prerequisites

Before you start, ensure you have the following installed:

requirement	version	notes
Java JDK	21+	Required for compilation
HytaleServer.jar	Latest	The server API JAR
Text Editor/IDE	Any	IntelliJ IDEA recommended

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
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.