Hytale Plugin Template

A ready-to-use starting point for creating Hytale server plugins with Java, or Kotlin. If you've been using the Asset Editor and want to start writing server-side logic — custom commands, event handling, gameplay systems — this is the simplest place to begin.

This template uses the Hytale Gradle Plugin, a Gradle plugin maintained by AzureDoom for Hytale mod/plugin development. It handles the repetitive project setup work for you, including manifest generation, validation, local server runs, IDE source setup, and optional hosted Hytale Javadoc injection.

How to start

1. Copy the template by downloading it or using the Use this template button.

2. Configure or install the Java SDK to use Java 25. JetBrains Runtime is recommended for the best hot-reload/debugging experience.

3. Open the project in your favorite IDE. We recommend IntelliJ IDEA.

4. Update the project values in gradle.properties:

   • rootProject.name in settings.gradle.kts
   • group
   • manifest_group
   • mod_name
   • mod_id
   • main_class
   • mod_author
   • mod_description
   • mod_url

5. Optionally run ./gradlew if your IDE does not automatically sync the project.

6. Prepare the Hytale development environment:

   ./gradlew setupHytaleDev

7. Run the local development server:

   ./gradlew runServer

On Windows, use ./gradlew.bat or gradlew.bat instead of ./gradlew. The Gradle wrapper is included so you do not need to install Gradle separately; only Java is required.

When the server starts, the output may prompt you to authorize your Hytale server. After that, you can begin developing your plugin while the server handles local development runs.

From here, the HytaleModding guides cover more details.

Hytale Gradle Plugin

This template is built around AzureDoom's com.azuredoom.hytale-tools Gradle plugin.

The plugin is configured in build.gradle.kts:

plugins {
    idea
    java
    id("com.azuredoom.hytale-tools") version "1.+"
}

The AzureDoom Maven repository is configured in settings.gradle.kts:

pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
        maven {
            name = "AzureDoom Maven"
            url = uri("https://maven.azuredoom.com/mods")
        }
    }
}

Most plugin-specific settings are controlled from gradle.properties and passed into the hytaleTools block in build.gradle.kts. This keeps common project metadata in one easy-to-edit place.

For full plugin documentation, configuration options, tasks, and multi-project setup, visit the Hytale Gradle Plugin repository.

Useful commands

# Sync/setup the local Hytale development environment
./gradlew setupHytaleDev

# Run the local Hytale server
./gradlew runServer

# Run the server with debugging and hot swap enabled
./gradlew runServer -Ddebug=true -Dhotswap=true

# Check your JVM and hot swap setup
./gradlew hytaleJvmDoctor

# Build the plugin
./gradlew build

# Refresh dependencies if something fails to resolve
./gradlew build --refresh-dependencies

Project structure

src/main/java/        Plugin source code
src/main/resources/   Plugin resources, including manifest.json
gradle.properties     Main template configuration
build.gradle.kts      Gradle build and Hytale Gradle Plugin configuration
settings.gradle.kts   Plugin repositories and project name

Manifest configuration

The generated manifest.json is driven by the values in gradle.properties, including:

• manifest_group
• mod_id
• version
• mod_description
• mod_author
• mod_url
• main_class
• manifest_dependencies
• manifest_opt_dependencies
• manifestServerVersion

After changing these values, run:

./gradlew updatePluginManifest

Troubleshooting

• Gradle sync fails in IntelliJ — Check that Java 25 is installed and configured under File → Project Structure → SDKs.
• The Hytale Gradle Plugin does not resolve — Make sure settings.gradle.kts includes the AzureDoom Maven repository at https://maven.azuredoom.com/mods.
• Build fails with missing dependencies — Run ./gradlew build --refresh-dependencies and make sure you have internet access.
• Permission denied on ./gradlew — Run chmod +x gradlew on macOS/Linux.
• Hot reload or enhanced class redefinition does not work — Use JetBrains Runtime and try ./gradlew hytaleJvmDoctor to verify your JVM setup.

Resources

• Hytale Gradle Plugin
• Hytale Modding Guides
• Hytale Modding Discord

License

Add your own license after copying the template. We recommend MIT, BSD, or Apache to keep the modding community open.