Hytale Plugin Development

Create server-side plugins for Hytale using Java 25 and Gradle.

Overview

Hytale uses a server-side first modding approach. All plugins run on the server – players don’t need to install anything to join modded servers.

Tech Stack:

• Java 25 – Required JDK version
• Gradle 9.2 – Build system
• Antigravity – Recommended IDE (AI-assisted development!)

First-Time Setup Flow

When a user asks to create a plugin, guide them through this:

Step 1: Prerequisites Check

I'll help you create that plugin! First, let me verify your setup:

Prerequisites:
1. Java 25 (download from Adoptium or Oracle)
2. Gradle (I can run commands for you in Antigravity!)

If you're using Antigravity, you're all set - I can handle builds directly!

Step 2: Install Java 25

Windows:

# Download from Adoptium
winget install EclipseAdoptium.Temurin.25.JDK

Or download manually from: https://adoptium.net/

Step 3: Create Project from Template

The easiest way to start – use the community template:

# Clone the official template (Darkhax/Jared)
git clone https://github.com/Darkhax-Hytale/HytalePluginTemplate.git MyPlugin
cd MyPlugin

Or create manually with this structure:

MyPlugin/
├── build.gradle.kts
├── settings.gradle.kts
├── gradle.properties
└── src/
    └── main/
        └── java/
            └── com/
                └── yourname/
                    └── myplugin/
                        └── MyPlugin.java

Step 4: Open in Antigravity

1. Open the project folder in Antigravity
2. I’ll automatically detect the Gradle project
3. Use gradle build via run_command to build
4. I can help you write, debug, and test code!

Alternative: IntelliJ IDEA

1. Open IntelliJ IDEA
2. File → Open → Select project folder
3. File → Project Structure → Project → SDK → Select Java 25
4. Let Gradle sync complete

Plugin Lifecycle

Every plugin extends JavaPlugin with these lifecycle methods:

package com.yourname.myplugin;

import com.hytale.server.plugin.JavaPlugin;

public class MyPlugin extends JavaPlugin {
    
    @Override
    public void setup() {
        // Called during server setup phase
        // Register commands, events, configs here
        getLogger().info("MyPlugin setting up...");
    }
    
    @Override
    public void start() {
        // Called when server starts
        // Initialize runtime features
        getLogger().info("MyPlugin started!");
    }
    
    @Override
    public void shutdown() {
        // Called during server shutdown
        // Clean up resources, save data
        getLogger().info("MyPlugin shutting down...");
    }
}

Lifecycle Order

Server Boot → setup() → start() → [Running] → shutdown() → Server Stop

Command Registration

Register custom commands in setup():

@Override
public void setup() {
    registerCommand("hello", (sender, args) -> {
        sender.sendMessage("Hello from MyPlugin!");
        return true;
    });
    
    registerCommand("spawn", (sender, args) -> {
        if (sender instanceof Player player) {
            player.teleportToSpawn();
            player.sendMessage("Teleported to spawn!");
        }
        return true;
    });
}

Command with Arguments

registerCommand("give", (sender, args) -> {
    if (args.length < 2) {
        sender.sendMessage("Usage: /give <player> <item>");
        return false;
    }
    String playerName = args[0];
    String itemId = args[1];
    // Implementation...
    return true;
});

Event System

Event Types

Registering Event Listeners

@Override
public void setup() {
    registerEventListener(PlayerJoinEvent.class, event -> {
        Player player = event.getPlayer();
        getServer().broadcastMessage(player.getName() + " joined!");
    });
    
    registerEventListener(BlockBreakEvent.class, event -> {
        if (event.getBlock().getType().equals("diamond_ore")) {
            event.getPlayer().sendMessage("You found diamonds!");
        }
    });
}

Cancellable Events

registerEventListener(BlockBreakEvent.class, event -> {
    if (isProtectedArea(event.getBlock().getPosition())) {
        event.setCancelled(true);
        event.getPlayer().sendMessage("This area is protected!");
    }
});

Entity Component System (ECS)

Hytale uses ECS architecture for entities:

Core Concepts

• Entity: Unique ID, no data or behavior
• Component: Data container (health, position, inventory)
• System: Logic that operates on components

Working with Components

// Get a component from an entity
HealthComponent health = entity.getComponent(HealthComponent.class);
if (health != null) {
    health.setHealth(health.getHealth() + 10);
}

// Check if entity has component
if (entity.hasComponent(FlyingComponent.class)) {
    // Handle flying entity
}

Gradle Build Configuration

Setting Up Dependencies (Critical!)

The official maven repo has been unstable. Use this local-first strategy:

Step 1: Extract API from HytaleServer.jar

# Windows - find the server JAR:
# %appdata%\Hytale\Hytale\install\release\package\game\latest\Server\HytaleServer.jar

# Install to local Maven cache:
mvn install:install-file \
    -Dfile="PATH_TO_JAR/HytaleServer.jar" \
    -DgroupId=com.hypixel.hytale \
    -DartifactId=Server \
    -Dversion=1.0-SNAPSHOT \
    -Dpackaging=jar

build.gradle.kts

plugins {
    `java-library`
    id("hytale-mod") version "0.+" // Community tooling
}

group = "com.yourname"
version = "1.0.0"

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(25)) // Required!
    }
}

repositories {
    mavenLocal() // Priority 1: Local cache (from extracted JAR)
    mavenCentral()
    
    // Priority 2: Community mirror (more stable than official)
    maven("https://maven.hytale-modding.info/releases") {
        content {
            includeGroup("com.hypixel.hytale")
        }
    }
    
    // JitPack for GitHub-hosted community libs
    maven("https://jitpack.io")
}

dependencies {
    // MUST be compileOnly - server provides at runtime
    compileOnly("com.hypixel.hytale:Server:1.0-SNAPSHOT")
}

Important: Use compileOnly for the server dependency. Bundling it causes ClassCastExceptions.

Building

# Build the plugin JAR
gradle build

# Output: build/libs/MyPlugin-1.0.0.jar

Installing

For client mods: %APPDATA%/Hytale/UserData/Mods/

For server plugins: Copy to server/mods/ folder (NOT plugins/)

Project Structure

MyPlugin/
├── build.gradle.kts          # Gradle build script
├── settings.gradle.kts       # Gradle settings
├── gradle.properties         # Gradle properties
├── src/
│   └── main/
│       ├── java/
│       │   └── com/yourname/myplugin/
│       │       ├── MyPlugin.java        # Main plugin class
│       │       ├── commands/            # Command handlers
│       │       ├── events/              # Event listeners
│       │       └── systems/             # ECS systems
│       └── resources/
│           └── plugin.json              # Plugin metadata
└── build/
    └── libs/
        └── MyPlugin-1.0.0.jar           # Built plugin

Quick Reference

Resources

• Community Mirror Maven: https://maven.hytale-modding.info/releases
• Example Plugin (Kaupenjoe): GitHub
• SimpleClaims (Buuz135): GitHub
• Hytale Modding Bible: Community API reference on Reddit
• Kytale Framework: CurseForge
• Imperat Command Framework: Multi-platform command lib
• Java 25 Reference: See java-25-hytale skill
• Gradle Reference: See gradle-hytale skill