Development Environment Setup

Requirements

Java 25 is required. JetBrains Runtime is recommended for DCEVM hot-swap support, but any Java 25 JDK works for compilation.

Recommended distributions:

• JetBrains Runtime (preferred — enables hot-reload)
• Eclipse Temurin (Adoptium)
• Amazon Corretto

java -version
# Expected: openjdk version "25.x.x" or similar

An IDE with Java support is strongly recommended. IntelliJ IDEA Community Edition works well. You do not need to install Gradle — the template bundles its own wrapper.

Getting Started with the Template

The fastest way to start is the official plugin template. It uses the ScaffoldIt Gradle plugin (version "0.2.+") which handles dependency resolution, manifest generation, and dev server setup automatically.

1. Clone the template:

   git clone https://github.com/HytaleModding/plugin-template.git MyPlugin
   cd MyPlugin

2. Build it to verify everything works:

   ./gradlew build

   On Windows, use gradlew.bat build instead. This should succeed on the first attempt with zero configuration.

3. Customize your plugin identity in settings.gradle.kts:

   hytale {
       usePatchline("release")
       useVersion("latest")
   
       manifest {
           Group = "com.yourname"
           Name = "MyPlugin"
           Main = "com.yourname.myplugin.MyPlugin"
       }
   }

4. Rename the Java package under src/main/java/ to match your Main class path, and update the code accordingly.

5. Update src/main/resources/manifest.json with your plugin details, or run ./gradlew generateManifest to regenerate it from your settings.

Note

You may see JetBrains JDK not found, falling back to default JDK 25. DCEVM hot-swap won't be available. — this is informational only. Compilation works fine without JetBrains Runtime; you just won’t get live code hot-swap during development.

For the official setup walkthrough, see also the HytaleModding setup guide.

Project Structure

After cloning, the template looks like this:

• DirectoryMyPlugin/

  • Directoryassets/ (optional — for plugins with asset packs)

    • …
  • build.gradle.kts
  • settings.gradle.kts
  • gradle.properties
  • gradlew
  • gradlew.bat
  • Directorysrc/

    • Directorymain/

      • Directoryjava/

        • Directorydev/

          • Directoryhytalemodding/

            • ExamplePlugin.java
            • Directorycommands/

              • ExampleCommand.java
            • Directoryevents/

              • ExampleEvent.java
      • Directoryresources/

        • manifest.json
  • Directorygradle/

    • Directorywrapper/

      • gradle-wrapper.jar
      • gradle-wrapper.properties

The build.gradle.kts is intentionally minimal — the ScaffoldIt plugin configures repositories, dependencies, and Java toolchain automatically through the hytale {} block in settings.gradle.kts.

How the Build System Works

The template uses the dev.scaffoldit Gradle plugin (applied in settings.gradle.kts, not build.gradle.kts). It automatically:

• Adds the Hytale Maven repository (https://maven.hytale.com/release)
• Adds the server dependency (com.hypixel.hytale:Server:+)
• Configures the Java 25 toolchain
• Generates plugin manifests
• Sets up dev server tasks

You do not need to manually configure repositories or dependencies.

Hytale Server Path (Optional)

Setting hytale.home_path in gradle.properties is only needed for Assets.zip resolution (used by setupServer / devServer tasks). It is not required for compilation.

Linux

hytale.home_path=/home/<username>/.var/app/com.hypixel.HytaleLauncher/data/Hytale

Windows

hytale.home_path=C:\\Users\\<username>\\AppData\\Local\\Hypixel\\HytaleLauncher\\data\\Hytale

macOS

hytale.home_path=/Users/<username>/Library/Application Support/Hypixel/HytaleLauncher/data/Hytale

Available Gradle Tasks

Task	Description
build	Compiles and packages your plugin
runServer	Starts the local development server
devServer	Alias for runServer
setupServer	Creates the devserver directory
generateManifest	Regenerates manifest.json from settings
openIdea	Opens the project in IntelliJ IDEA

Running Your Plugin

1. Set your hytale.home_path in gradle.properties (see above)
2. Run ./gradlew setupServer to create the local dev server
3. Run ./gradlew runServer to start it (add -Ddebug to enable remote debugging with hot-swap support)
4. Your plugin is loaded automatically from build/libs/

Alternatively, copy the built JAR from build/libs/ to any Hytale server’s plugins/ directory.

Manual Setup (Without the Template)

If you prefer not to use the ScaffoldIt template, you can set up a plain Gradle or Maven project manually.

Gradle

build.gradle

plugins {
    id 'java'
}

group = 'com.example'
version = '1.0.0'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
    }
}

repositories {
    mavenCentral()
    maven {
        name = "hytale"
        url = uri("https://maven.hytale.com/release")
    }
}

dependencies {
    compileOnly("com.hypixel.hytale:Server:+")
}

Maven

pom.xml

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>my-plugin</artifactId>
    <version>1.0.0</version>

    <properties>
        <maven.compiler.source>25</maven.compiler.source>
        <maven.compiler.target>25</maven.compiler.target>
    </properties>

    <repositories>
        <repository>
            <id>hytale</id>
            <url>https://maven.hytale.com/release</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>com.hypixel.hytale</groupId>
            <artifactId>Server</artifactId>
            <version>LATEST</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</project>

The server dependency is compile-only/provided — do not bundle it with your plugin. ScaffoldIt uses implementation internally because it handles packaging automatically, but in a manual setup you should use compileOnly (Gradle) or provided (Maven) since the server is available at runtime.

New in Update 3

The server now bundles JOML 1.10.8 and RocksDB 10.4.2 as runtime dependencies. These are available without including them in your plugin. See the Update 3 changelog for details.

IDE Configuration

IntelliJ IDEA

1. File → Open → select your project directory
2. IntelliJ will detect Gradle automatically and import the project
3. If using the template, run ./gradlew openIdea for pre-configured project files

VS Code

Install the Java Extension Pack. Open the project folder — the extension will detect Gradle and configure the classpath.

Troubleshooting

“Class not found” errors — Verify the Main field in manifest.json matches your class’s fully qualified name.

Plugin doesn’t load — Check for JSON syntax errors in manifest.json. Verify it’s at the root of your JAR, not in a subdirectory. Check server logs.

Hot-reload doesn’t work — You need JetBrains Runtime, not a regular JDK. Standard JDKs compile fine but don’t support DCEVM hot-swap.

Next Steps

• Extracting the Server — Decompile the server source for reference
• First Plugin Tutorial — Complete walkthrough
• Plugin Manifest — Full manifest schema
• Plugin Lifecycle — Understanding lifecycle hooks