Modding: Create Your First Hytale Plugin

Dreaming of customizing your Hytale experience, adding new features, or creating unique mechanics? Java plugin development is the gateway to infinite possibilities. This guide is designed to walk you through creating your very first plugin, step-by-step, using the official community template optimized for a quick start.

Hytale Modding: A “Server-First” Approach

Before starting, it is essential to understand a fundamental concept: in Hytale, everything is managed server-side. Even when playing solo, your game runs on a local server. Your plugins therefore run on this server, ensuring that all connected players experience the exact same gameplay without needing to download client-side mods.

Prerequisites: Essential Tools

To follow this guide, you must install two specific tools:

1. Java 25 JDK: Hytale requires this specific version of Java. Ensure you have JDK 25 installed.
2. IntelliJ IDEA: The recommended Integrated Development Environment (IDE). The Community version (free) is sufficient.

Step 1: Project Preparation (Crucial!)

To avoid technical errors, we use a pre-configured template. Please follow this specific order:

1. Download the template: Get the template from the GitHub repository.
2. Extract the archive into your development folder.
3. Configure BEFORE opening IntelliJ:
   • Open the settings.gradle file with a text editor (Notepad, VS Code) and change rootProject.name = 'MyFirstPlugin'.
   • Open gradle.properties to define your maven_group (e.g., com.username).
   • Note: This step is vital to avoid cache conflicts within IntelliJ later on.
4. Import into IntelliJ: Open IntelliJ, select “Open”, choose the project folder, and let Gradle download the dependencies.

Step 2: The Manifest (manifest.json)

This is your plugin’s identity card, located in src/main/resources/manifest.json. Make sure the “Main” field points exactly to your Java class.

{
  "Name": "MyFirstPlugin",
  "Version": "1.0.0",
  "Main": "com.hytalegame.myfirstplugin.MyFirstPlugin",
  "Description": "My first test plugin",
  "Authors": [ { "Name": "YourUsername" } ],
  "Dependencies": {},
  "OptionalDependencies": {}
}

Step 3: The Java Code (Lifecycle)

Create your main class that inherits from JavaPlugin.

package com.hytalegame.myfirstplugin;

import com.hypixel.hytale.server.core.plugin.JavaPlugin;
import java.util.logging.Level;

public class MyFirstPlugin extends JavaPlugin {

    @Override
    public void start() {
        // Called when the plugin starts
        getLogger().at(Level.INFO).log("MyFirstPlugin has started successfully!");
        
        // Registering the command (see Step 4)
        getCommandRegistry().registerCommand(new SimpleCommand());
    }

    @Override
    public void shutdown() {
        getLogger().at(Level.INFO).log("Plugin stopping.");
    }
}

Step 4: Your First Command

Create a SimpleCommand class inheriting from AbstractCommand.

package com.hytalegame.myfirstplugin;

import com.hypixel.hytale.server.core.command.system.AbstractCommand;
import com.hypixel.hytale.server.core.command.system.CommandContext;
import com.hypixel.hytale.server.core.Message;
import java.util.concurrent.CompletableFuture;

public class SimpleCommand extends AbstractCommand {

    public SimpleCommand() {
        super("myplugin", "Displays a welcome message.");
    }

    @Override
    protected CompletableFuture<Void> execute(CommandContext context) {
        context.sender().sendMessage(Message.raw("Congrats! Your plugin works!"));
        return null;
    }
}

Step 5: Launch & Authentication (New!)

Here is where the template magic happens. You do not need to manually compile a JAR file to test.

1. Launch the Test Server Once the project is imported, look at the top right of IntelliJ. You should see a run configuration named “HytaleServer”.

• Click the Play button (Green) next to “HytaleServer”.
• The console will open, and the server will start.

2. Authenticate the Server (First Launch Only) On the very first launch, you won’t be able to connect immediately. Watch the IntelliJ console; the server will ask you to authenticate.

• Type in the console: auth login device
• Follow the link provided to log in with your Hytale account.
• Once validated, type: auth persistence Encrypted to save the connection.

3. Test In-Game

• Launch your Hytale client.
• Connect to the local server (IP: 127.0.0.1 or localhost).
• Type your command: /myplugin
• Admire the result!

Step 6: Compile for Distribution

Once your plugin is finished, if you want to share it with friends or put it on a production server:

1. Open the Gradle tab on the right side of IntelliJ.
2. Navigate to Tasks -> build -> build.
3. Retrieve your .jar file from the build/libs/ folder.
4. Simply drop it into the Mods/ folder of the destination server.

What Now?

Congratulations! You now master the modern workflow: Code > Launch via IntelliJ > Test.

However, this is just scratching the surface of what the API offers. To transform your ideas into complete mods (inventory management, entity creation, complex event listeners), you will need precise references.

🚀 Go Further with Full Documentation For detailed guides, advanced code examples, and development best practices, check out the official community documentation: 👉 Hytale Modding Documentation