Hytale Gradle Plugin

A Gradle plugin for Hytale mod development that standardizes project setup, manifest generation, validation, local server runs, and IDE-friendly decompiled source attachment.

Why use this plugin?

This plugin replaces manual setup tasks such as:

manual manifest management
manual server setup
manual dependency decompilation
manual IDE source attachment setup

Quickstart

plugins {
    id 'java'
    id 'com.azuredoom.hytale-tools' version '1.0.26'
}

hytaleTools {
    hytaleVersion = '2026.+'
    manifestGroup = 'com.example.mods'
    modCredits = 'yourname'
    patchline = 'release'
    modId = 'examplemod'
    mainClass = 'com.example.mods.ExampleMod'
    
    // Optional: declare sub-plugins bundled with this mod
    subPlugin('MyFeature', 'com.example.mods.feature.MyFeaturePlugin')
}

Then run:

./gradlew setupHytaleDev
./gradlew runServer

Having issues? See Support & Issues.

Hot Swap Quickstart

To enable debugging and hot swap:

./gradlew runServer -Ddebug=true -Dhotswap=true

For best results:

Install JetBrains Runtime (JBR)
Let the plugin auto-detect it or set jbrHome

Verify your setup:

./gradlew hytaleJvmDoctor

Multi-Project Setup

This plugin supports a clean separation between workspace orchestration and individual mod projects.

com.azuredoom.hytale-workspace → applied to the root project
com.azuredoom.hytale-tools → applied to each mod project

Project Layout

root/
├── settings.gradle
├── build.gradle
├── common/
├── modA/
└── modB/

settings.gradle

rootProject.name = "my-hytale-workspace"
include("common", "modA", "modB")

Root Project (Workspace)

// root build.gradle
plugins {
    id 'com.azuredoom.hytale-workspace' version '1.0.26'
}

// If you are getting an issue with Task 'prepareKotlinBuildScriptModel' not found in project ':modX'. 
// Add this
subprojects {
    tasks.register('prepareKotlinBuildScriptModel') {
        dependsOn(rootProject.tasks.named('prepareKotlinBuildScriptModel'))
    }
}

hytaleWorkspace {
    modProjects = [':modA', ':modB']

    // Optional (recommended)
    hostProject = ':modA'

    // Optional shared defaults propagated to child `hytaleTools` projects
    // when those projects apply the plugin, unless overridden locally
    manifestGroup = 'com.example.mods'
    hytaleVersion = '2026.+'
    patchline = 'release'
}

Shared Module

// common/build.gradle
plugins {
    id 'java-library'
}

Mod Project

// modA/build.gradle
plugins {
    id 'com.azuredoom.hytale-tools'
}

dependencies {
    implementation project(':common')
}

hytaleTools {
    // hytaleVersion, patchline, and manifestGroup are inherited from the workspace
    // Override workspace default
    manifestGroup = 'com.example.custom'
    
    modCredits = 'yourname'
    modId = 'moda'
    mainClass = 'com.example.mods.moda.ModA'
}

Repeat for additional mod projects (e.g. modB).

**Note for Kotlin users, please ensure you are also adding:

repositories {
    mavenCentral()
}

to any build.gradle that is calling the kotlin plugin.

How It Works

The workspace plugin (hytale-workspace) only applies to the root project
Each mod project applies hytale-tools independently
Non-mod projects (e.g. common) remain standard Gradle modules
Workspace tasks operate only on projects listed in modProjects
The workspace plugin does not automatically apply the mod plugin

Workspace Tasks

Available only on the root project:

updateAllPluginManifests
validateAllManifests
stageAllModAssets
runAllMods

Example:

./gradlew updateAllPluginManifests
./gradlew validateAllManifests
./gradlew runAllMods

Running

Run a single mod:

./gradlew :modA:runServer

Run all mods together:

./gradlew runAllMods

Host Project

The workspace uses a host project to resolve:

Hytale assets
Server runtime configuration

You can explicitly configure it:

hytaleWorkspace {
    hostProject = ':modA'
}

If not set, the first project (by path) is used.

Notes

All mod projects must resolve to the same hytaleVersion and patchline (after applying workspace defaults and/or local overrides)
runAllMods fails early if versions mismatch
Asset packs are staged into run/mods/
Symlinks are used when possible, with copy fallback
common should not apply the plugin unless it is a real mod

Recommended Usage

This setup is ideal for:

shared code (common)
multiple independent mods
a single combined development server

The design keeps:

mod configuration isolated per project
workspace behavior centralized at the root

VS Code Usage

If you are using VS Code, run:

./gradlew prepareDecompiledSourcesForIde

Then reload the workspace to enable source attachment.

Dependency Flow

The following diagram shows how plugin configurations feed into compilation and decompilation:

vineServerJar ─┐
               ├──> compileOnly ───> compileClasspath
vineCompileOnly┘

vineImplementation ─────┐
vineCompileOnly   ──────┼──> vineDependencyJars ───> decompilation
vineDecompileTargets ───┘

At a high level:

vineServerJar provides the Hytale server API
vineCompileOnly and vineImplementation define your dependencies
vineDecompileTargets controls which dependencies get source attachment
Hytale Assets.zip (for IDE asset browsing)

Assets in IDEs

The plugin merges the resolved Hytale Assets.zip directly into a generated server jar used for IDE dependency resolution.

Unlike previous versions (which exposed assets as a separate dependency), this approach ensures a more stable and consistent IDE experience.

This means:

assets appear directly under the Hytale server library in IntelliJ (External Libraries)
you can browse game assets alongside server classes in the same library tree
assets are no longer exposed as a separate dependency or external library
assets are not included in your final mod jar

Version Compatibility

Plugin Version	Java Version	Hytale Support
1.0.x	25+	Release/Pre-Release

Gradle Compatibility

This plugin is designed to work with modern Gradle features:

✅ Configuration cache compatible
✅ Passes Gradle 9.x plugin validation
⚠️ Selective build cache support

Build Cache Behavior

Tasks are categorized as follows:

Cacheable:

DecompileDependencyJarTask
DecompileServerJarTask

Not cacheable (by design):

downloadAssetsZip (network + auth dependent)
runServer (executes an external process)
prepareRunServer (filesystem links/junctions)
manifest tasks (low-cost file operations)

This ensures correctness while still benefiting from caching where it matters.

CI Usage

The plugin is compatible with:

Gradle configuration cache
Gradle plugin validation (Gradle 9+)

Recommended CI flags:

./gradlew build --configuration-cache

Features

Automatically adds required repositories
Creates Hytale-specific and source vine* configurations
Generates, updates, and validates manifest.json
Downloads authenticated Hytale assets
Runs a local Hytale server for development
Supports debug mode and hot swap capable JVM runtime setup
Generates decompiled sources and attaches them in IDEs

Included Tasks

`createManifestIfMissing`

Creates src/main/resources/manifest.json with a default structure if it does not already exist.

This task is safe to run repeatedly and will not overwrite an existing manifest.

`updatePluginManifest`

Updates (or rewrites) src/main/resources/manifest.json from Gradle configuration.

`downloadAssetsZip`

Authenticates with Hytale device auth, downloads the asset wrapper, extracts Assets.zip, and caches the result.

Fallback behavior: If remote download fails, the task will attempt to locate a local Hytale installation and reuse an existing Assets.zip.

You can override this location via:

hytaleTools {
    hytaleHomeOverride = "/path/to/Hytale"
}

`runServer`

Launches a local Hytale server using:

your project output
your runtime classpath
the resolved Hytale server jar

Customizing `runServer`

You can customize the server launch arguments, JVM arguments, debug mode, and hot swap behavior through the extension:

hytaleTools {
    hytaleVersion = '2026.+'

    serverArgs = [
        '--allow-op',
        '--disable-sentry',
        '--disable-file-watcher'
    ]

    serverJvmArgs = [
        '-Xms1G',
        '-Xmx2G'
    ]

    preRunTask = 'generateDevResources'

    // Optional debug / hot swap support
    debugEnabled = false
    debugPort = 5005
    debugSuspend = false

    hotSwapEnabled = false
    requireDcevm = false
    useHotswapAgent = true

    // Optional explicit JetBrains Runtime location
    // jbrHome = '/path/to/jbr'
}

tasks.register('generateDevResources') {
    doLast {
        println 'Preparing additional dev resources...'
    }
}

You can also enable debug and hot swap from the command line:

./gradlew runServer -Ddebug=true
./gradlew runServer -Ddebug=true -Dhotswap=true

Hot swap support depends on the selected JVM:

Standard JVM: limited to method body changes
JetBrains Runtime (JBR): supports enhanced class redefinition
HotswapAgent (if available): improves runtime reload behavior

For best results, use JetBrains Runtime with hot swap enabled.

Notes:

serverArgs are appended to the default --assets=... argument automatically added by the plugin
serverJvmArgs are added in addition to the plugin’s default JVM launch settings
preRunTask lets you run a custom preparation task before runServer
debugEnabled enables JDWP debugging for IDE attach
hotSwapEnabled enables runtime probing for enhanced class redefinition support
requireDcevm fails early if enhanced class redefinition is not available
useHotswapAgent enables bundled HotswapAgent support when available in the selected runtime
jbrHome can be used to point the plugin at a specific JetBrains Runtime installation

`hytaleJvmDoctor`

Prints JVM diagnostics relevant to debugging and hot swap, including:

resolved Java executable
JetBrains Runtime detection
enhanced class redefinition support
HotswapAgent mode support
bundled HotswapAgent availability

This is useful when validating a local JetBrains Runtime setup before using hot swap.

Runtime resolution uses jbrHome first, then known JetBrains Runtime environment variables (JBR_HOME, etc.), and finally falls back to the current JVM.

The plugin can automatically detect JetBrains Runtime installations from common locations, including JetBrains Toolbox installs, when jbrHome is not explicitly configured.

`prepareDecompiledSourcesForIde`

Decompiles the server jar and all dependencies declared in vineImplementation, vineCompileOnly, or vineDecompileTargets into build/generated-sources-m2 and build/generated-sources-ivy.

This is useful for IDE source attachment.

Development Workflow

For first-time setup, you can run:

./gradlew setupHytaleDev

During development:

./gradlew runServer

What happens during normal development:

updatePluginManifest writes manifest values from Gradle configuration, if missing createManifestIfMissing creates a default.
validateManifest runs before processResources, ensuring the manifest is generated and checked as part of the build.
runServer prepares the run directory, downloads assets if needed, and launches the server.

Because manifest generation and validation are wired into the build, most projects do not need to invoke those tasks manually.

Extension Reference

Property	Type	Default	Required	Purpose
`javaVersion`	`Integer`	`25`	No	Java version used for decompilation/tooling
`hytaleVersion`	`String`	'2026.+'	Yes	Hytale server version to resolve. Accepts dynamic selectors (e.g. `2026.+`)
`patchline`	`String`	`release`	No	Asset/server patchline
`oauthBaseUrl`	`String`	Hytale OAuth URL	No	Override auth endpoint
`accountBaseUrl`	`String`	Hytale account-data URL	No	Override account endpoint
`manifestGroup`	`String`	`project.group`	Yes	Manifest group / namespace
`modId`	`String`	`project.name`	Yes	Manifest mod id
`modDescription`	`String`	empty	No	Manifest description
`modUrl`	`String`	empty	No	Manifest project URL
`mainClass`	`String`	empty	Yes	Plugin entrypoint
`modCredits`	`String`	'replace_me'	No	Manifest credits
`manifestDependencies`	`String`	empty	No	Required manifest deps
`manifestOptionalDependencies`	`String`	empty	No	Optional manifest deps
`curseforgeId`	`String`	empty	No	CurseForge project id
`disabledByDefault`	`Boolean`	`false`	No	Manifest flag
`includesPack`	`Boolean`	`false`	No	Manifest flag
`manifestFile`	`RegularFile`	`src/main/resources/manifest.json`	No	Manifest location
`runDirectory`	`Directory`	`run/`	No	Local server run dir
`assetPackSourceDirectory`	`Directory`	`src/main/resources`	No	Source asset directory used by `runServer` and `stageAllModAssets`
`assetPackRunDirectory`	`Directory`	computed under `run/mods/...`	No	Assets target dir
`bundleAssetEditorRuntime`	`Boolean`	`true`	No	Controls whether AssetBridge is bundled into the final jar
`serverArgs`	`List<String>`	`['--allow-op', '--disable-sentry']`	No	Additional Hytale server arguments appended after the required `--assets=...` argument
`serverJvmArgs`	`List<String>`	`[]`	No	Extra JVM arguments for `runServer`
`preRunTask`	`String`	empty	No	Task name to run before `runServer`
`debugEnabled`	`Boolean`	`false`	No	Enables JDWP debugging for `runServer`
`debugPort`	`Integer`	`5005`	No	Debug port used when `debugEnabled` is true
`debugSuspend`	`Boolean`	`false`	No	Whether the JVM waits for a debugger before starting
`hotSwapEnabled`	`Boolean`	`false`	No	Enables hot swap capability detection and runtime setup
`requireDcevm`	`Boolean`	`false`	No	Fails launch if enhanced class redefinition support is unavailable
`useHotswapAgent`	`Boolean`	`true`	No	Enables bundled HotswapAgent integration when available
`jbrHome`	`String`	empty	No	Optional path to a JetBrains Runtime installation
`subPlugins`	`List<Map>`	`[]`	No	Sub-plugins bundled with this mod (see SubPlugins)

SubPlugins

The plugin supports declaring sub-plugins that are bundled within your main mod. Sub-plugins appear in manifest.json as a SubPlugins array and are loaded by the server alongside the parent mod.

Use the subPlugin(...) DSL method in your hytaleTools block:

hytaleTools {
    modId = 'mymod'
    mainClass = 'com.example.mods.MyMod'
 
    subPlugin('Forestry', 'com.example.mods.forestry.ForestryPlugin')
    subPlugin('Economy', 'com.example.mods.economy.EconomyPlugin', true, false)
    // Pin a specific server version for this sub-plugin instead of inheriting the parent's:
    subPlugin('Legacy', 'com.example.mods.legacy.LegacyPlugin', false, false, '2026.03.15-aabbccdd1')
}

`subPlugin` parameters

Parameter	Type	Default	Description
`name`	`String`	—	Sub-plugin name (maps to `Name` in the manifest)
`main`	`String`	—	Fully-qualified entry point class (maps to `Main`)
`disabledByDefault`	`boolean`	`false`	Whether this sub-plugin is disabled by default
`includesAssetPack`	`boolean`	`false`	Whether this sub-plugin includes an asset pack
`serverVersion`	`String`	`null`	Optional server version override. When omitted, the parent mod's resolved server version is used

Each declared sub-plugin is written into manifest.json with the resolved server version automatically applied:

"SubPlugins": [
  {
    "Name": "Forestry",
    "Main": "com.example.mods.forestry.ForestryPlugin",
    "ServerVersion": "2026.04.30-b4f6a911e",
    "DisabledByDefault": false,
    "IncludesAssetPack": false
  },
  {
    "Name": "Economy",
    "Main": "com.example.mods.economy.EconomyPlugin",
    "ServerVersion": "2026.03.15-aabbccdd1",
    "DisabledByDefault": true,
    "IncludesAssetPack": false
  }
]

If no sub-plugins are declared, the SubPlugins key is omitted from the manifest entirely.

Task Reference

Task	Group	Purpose	Typical Use
`createManifestIfMissing`	`hytale`	Creates a starter manifest if missing	First setup
`updatePluginManifest`	`hytale`	Rewrites manifest from Gradle config	Normal dev/build
`updateAllPluginManifests`	`hytale`	Rewrites manifests for all Hytale subprojects	Multi-project manifest sync
`downloadAssetsZip`	`hytale`	Authenticates and fetches assets	Before first run / troubleshooting
`hytaleDoctor`	`hytale`	Prints plugin, manifest, asset, and dependency diagnostics	Troubleshooting
`runServer`	`hytale`	Launches local Hytale server	Single-project dev loop
`runAllMods`	`hytale`	Launches one shared server with all mod subprojects	Multi-project dev loop
`stageAllModAssets`	`hytale`	Stages each mod's asset pack into the root `run/mods` directory	Multi-project run preparation
`prepareDecompiledSourcesForIde`	`hytale`	Generates source jars for IDE attachment	IDE setup
`validateManifest`	internal	Verifies generated manifest values	Runs automatically
`validateAllManifests`	`hytale`	Verifies manifests for all Hytale subprojects	Multi-project validation
`prepareRunServer`	internal	Sets up run directory and mod assets	Runs automatically
`decompileServerJar`	internal	Decompiles Hytale server sources	Internal source pipeline
`setupHytaleDev`	`hytale`	Prepares IDE sources and downloads assets	First-time setup
`hytaleJvmDoctor`	`hytale`	Prints JVM debug / hot swap diagnostics	Debugging hot swap setup

IDE Source Attachment

The plugin can prepare decompiled sources for IDE use.

It decompiles:

the Hytale server jar
every dependency declared in vineImplementation, vineCompileOnly, or vineDecompileTargets

How it works

Generated decompiled sources are packaged as -sources.jar files and installed into local generated repositories under:

build/generated-sources-m2/
build/generated-sources-ivy/

The plugin installs both:

the original binary jar
the generated sources jar

IDEs use these for source attachment after generation.

Note: These generated repositories are not used for normal dependency resolution during the build. They exist only to support IDE source attachment after sources have been generated.

This avoids Gradle task dependency conflicts and ensures consistent builds.

When it runs

If the idea plugin is applied, decompiled sources are prepared automatically when you run:

./gradlew idea

You can also run it directly:

./gradlew prepareDecompiledSourcesForIde

Generated output

Decompiled source jars are written under:

build/generated-sources-jars/

Recommended dependency setup

Use vineDecompileTargets for any dependency whose decompiled sources you want available in your IDE:

dependencies {
    vineDecompileTargets 'com.buuz135:MultipleHUD:1.0.6'
}

Repositories

The plugin automatically adds these repositories:

Maven Central
Hytale Server Release
Hytale Server Pre-Release
Hytale Modding Maven
Hytale-Mods.info Maven
PlaceholderAPI
CurseMaven
AzureDoom Maven
Modtale (exclusive Ivy content for group modtale)

You do not need to declare them manually.

Note on patchlines: Both Hytale server repos are registered, but com.hypixel.hytale artifacts are only served by the repo matching the configured patchline. The other repo is restricted with excludeGroup('com.hypixel.hytale') so dynamic selectors like 2026.+ never cross patchlines. Other artifacts that happen to live in either repo are unaffected.

Configurations

The plugin automatically creates:

vineDecompileTargets
vineDecompileClasspath
vineServerJar
vineDependencyJars
vineflowerTool

Configuration Overview

Configuration	Purpose
vineServerJar	Hytale server binary (auto-injected)
vineImplementation	Runtime dependencies
vineCompileOnly	Compile-time only dependencies
vineDecompileTargets	Extra dependencies to decompile for IDE sources
hytaleBundledRuntime	Runtime dependency automatically added and optionally bundled

compileOnly automatically includes:

vineCompileOnly
vineServerJar
hytaleAssets (Assets.zip for IDE browsing)

This lets you write mods against the Hytale server API without manually declaring the server dependency.

Usage

`settings.gradle`

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

`build.gradle`

plugins {
    id 'java'
    id 'com.azuredoom.hytale-tools' version '1.0.26'
}

Dependencies

dependencies {
    // Dependencies declared in `vineImplementation`, `vineCompileOnly`, and `vineDecompileTargets` 
    // are included in the decompilation classpath (`vineDependencyJars`).
    vineImplementation 'com.buuz135:MultipleHUD:1.0.6'
    vineCompileOnly 'curse.maven:partyinfo-1429469:7526614'
    
    // Optional decompile targets for IDE source attachment
    vineDecompileTargets 'com.buuz135:MultipleHUD:1.0.6'
}

Hytale Server Dependency

The plugin automatically adds the Hytale server dependency based on:

hytaleTools {
    hytaleVersion = '2026.+'
}

This injects:

vineServerJar "com.hypixel.hytale:Server:${hytaleVersion}"

and makes it available on compileOnly. You do not need to declare this manually.

Dynamic versions

hytaleVersion accepts Gradle's dynamic version selectors, which is the easiest way to track the latest server build for a patchline:

hytaleTools {
    hytaleVersion = '2026.+'   // latest 2026.x build on the configured patchline
    patchline     = 'release'
}

Supported selectors:

2026.+ — latest version starting with 2026.
2026.1.+ — latest version starting with 2026.1.
latest.release — same as +

The generated manifest.json always contains the resolved concrete version (e.g. 2026.1.22-6f8bdbdc4), not the selector, so your built mod jar remains reproducible and pins to a specific server version.

Patchline scoping

When using a dynamic selector, the plugin scopes resolution to the configured patchline:

patchline = 'release' resolves only against the Hytale Server Release repo
patchline = 'pre-release' resolves only against the Hytale Server Pre-Release repo

This prevents 2026.+ from accidentally selecting a pre-release build when you're targeting release, or vice versa. Static versions are unaffected and continue to resolve from whichever repo serves them.

Cache behavior

Gradle caches dynamic version resolutions. The plugin configures the vineServerJar configuration with a 10-minute cache window, so a freshly published server build is picked up within that interval. To force an immediate refetch:

./gradlew runServer --refresh-dependencies

The Hytale server dependency is also marked as changing = true, so the same flag will refetch the artifact bytes if Hytale ever republishes a coordinate.

Overriding the server dependency

If you want to use a different version of the Hytale server:

dependencies {
    vineServerJar 'com.example:custom-server:1.0.0'
}

Auto-injection is skipped when a dependency is already declared.

AssetBridge

The plugin automatically adds the AssetBridge library dependency:

dependencies {
  implementation 'com.azuredoom.hytale:hytale-asset-editor-runtime:0.2.0'
}

This dependency is:

added automatically via the hytaleBundledRuntime configuration
available on implementation

Bundling into the final jar

By default, the runtime is bundled into your mod jar (similar to a lightweight shading step without requiring an external plugin).

You can disable this behavior:

hytaleTools {
    bundleAssetEditorRuntime = false
}

When disabled:

the dependency is still available at compile/runtime
it is not included inside the final jar

Overriding the runtime version

You can override the default version:

dependencies {
  hytaleBundledRuntime 'com.azuredoom.hytale:hytale-asset-editor-runtime:0.x.0'
}

Declaring a dependency manually will replace the plugin’s default.

Configuration

Example extension usage:

hytaleTools {
    javaVersion = project.java_version as Integer
    hytaleVersion = project.hytale_version.toString()
    patchline = project.hytale_patchline.toString()

    manifestGroup = project.manifest_group.toString()
    modId = project.mod_id.toString()
    modDescription = project.mod_description.toString()
    modUrl = project.mod_url.toString()
    mainClass = project.main_class.toString()
    modCredits = project.mod_credits.toString()

    manifestDependencies = project.manifest_dependencies.toString()
    manifestOptionalDependencies = project.manifest_opt_dependencies.toString()
    curseforgeId = project.curseforgeID.toString()

    disabledByDefault = project.disabled_by_default.toString().toBoolean()
    includesPack = project.includes_pack.toString().toBoolean()
    
    // Optional: declare sub-plugins
    subPlugin('Forestry', 'com.example.mods.forestry.ForestryPlugin')
    // subPlugin(name, main, disabledByDefault, includesAssetPack, serverVersion)
    
    serverArgs = ['--allow-op', '--disable-sentry']
    serverJvmArgs = ['-Xms1G', '-Xmx2G']
    preRunTask = 'generateDevResources'
    
    debugEnabled = false
    debugPort = 5005
    debugSuspend = false

    hotSwapEnabled = false
    requireDcevm = false
    useHotswapAgent = true

    // Optional
    // jbrHome = '/path/to/jbr'
}

Backing Gradle properties

The plugin also reads these Gradle properties automatically:

java_version
hytale_version
hytale_patchline
hytools.hytale.oauth.base
hytools.hytale.accounts.base
manifest_group
mod_id
mod_description
mod_url
main_class
mod_credits
manifest_dependencies
manifest_opt_dependencies
curseforgeID
disabled_by_default
includes_pack
hytools.debug.port
hytools.debug.suspend
hytools.jbr.home

The plugin also recognizes these system properties for dev runtime features:

debug → enables debug mode
hotswap → enables hot swap support

Support & Issues

If you encounter a bug, unexpected behavior, or have a feature request:

🐛 Open an issue: https://github.com/AzureDoom/Hytale-Gradle-Plugin/issues
💬 Join the Discord: https://discord.gg/f2NJGA8ey8

Issue templates are provided for bug reports and feature requests.

Please include:

Gradle version
Plugin version
Full stacktrace (--stacktrace)
Relevant build configuration

For general questions or help getting started, Discord is usually the fastest way to get support.

Troubleshooting

Start here first:

./gradlew hytaleDoctor

hytaleDoctor prints a summary of:

configured hytaleVersion and patchline
manifest path and run directory
resolved asset wrapper / Assets.zip cache paths
auth token cache path
resolved vineServerJar files
declared vineImplementation, vineCompileOnly, and vineDecompileTargets dependencies

Use it when:

runServer fails
assets are missing
manifest values look wrong
expected dependency sources are not showing up

Missing `hytaleVersion`

If hytaleVersion is not set and no vineServerJar is declared, tasks that require the server jar may fail.

Always configure:

hytaleTools {
    hytaleVersion = '...'
}

Dynamic version not resolving the expected build

If you're using a dynamic selector like 2026.+ and Gradle is picking the wrong version (or claims it can't find any matching version), check the following:

Use +, not *. Gradle's dynamic version syntax is 2026.+, not 2026.*. The * form is treated as a literal version string and will fail to resolve.
Confirm patchline is set correctly. Dynamic resolution is scoped to the active patchline. If you're tracking pre-release builds, set patchline = 'pre-release' (or hytale_patchline=pre-release in gradle.properties).
Force a refresh. Dynamic versions are cached for 10 minutes. Run ./gradlew --refresh-dependencies to bypass the cache and refetch the latest version listing.
Check hytaleDoctor. The diagnostic task prints the configured patchline and the resolved server jar files so you can confirm what was actually picked.

Sources are not attached in the IDE

Run:

./gradlew prepareDecompiledSourcesForIde

This allows IDEs to attach readable generated source code instead of showing only compiled classes.

Then refresh or reimport the Gradle project in your IDE.

Also verify the dependency is listed in vineDecompileTargets if you expect decompiled dependency sources.

`runServer` fails because assets are missing

Run:

./gradlew downloadAssetsZip

Also verify:

hytale_version is set correctly
hytale_patchline matches the artifact you expect
authentication cache under Gradle user home is valid

`manifest.json` is out of date

Run:

./gradlew updatePluginManifest

The build also wires manifest validation automatically, so this usually indicates missing configuration values.

Manifest validation fails during build

Verify the configured values for:

manifestGroup
modId
mainClass
hytaleVersion

Also review:

manifest_dependencies
manifest_opt_dependencies
includes_pack

Dependency sources are not being generated

Make sure the dependency is declared in:

vineDecompileTargets "group:module:version"

Only dependencies in that configuration are decompiled for IDE attachment.

`preRunTask` does not run

Verify that:

the task name matches exactly
the task is registered in the same project as runServer
preRunTask is set to the task name as a string

Validate your debug / hot swap runtime

Run:

./gradlew hytaleJvmDoctor

Use it to verify:

which Java executable runServer will use
whether JetBrains Runtime was detected
whether enhanced class redefinition is supported
whether bundled HotswapAgent support is available

If hot swap is not working as expected, this should be the first check.

Notes

Requires Java 25+
release is the default patchline
The plugin applies the java plugin automatically
The plugin does not apply the idea plugin automatically
If the idea plugin is present, IDEA integration is wired automatically
You can always run prepareDecompiledSourcesForIde directly for source generation

Name		Name	Last commit message	Last commit date
Latest commit History 106 Commits
.github		.github
gradle/wrapper		gradle/wrapper
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
build.gradle		build.gradle
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle

Folders and files

Latest commit

History

Repository files navigation

Hytale Gradle Plugin

Why use this plugin?

Quickstart

Hot Swap Quickstart

Multi-Project Setup

Project Layout

settings.gradle

Root Project (Workspace)

Shared Module

Mod Project

How It Works

Workspace Tasks

Running

Host Project

Notes

Recommended Usage

VS Code Usage

Dependency Flow

Assets in IDEs

Version Compatibility

Gradle Compatibility

Build Cache Behavior

CI Usage

Features

Included Tasks

createManifestIfMissing

updatePluginManifest

downloadAssetsZip

runServer

Customizing runServer

hytaleJvmDoctor

prepareDecompiledSourcesForIde

Development Workflow

Extension Reference

SubPlugins

subPlugin parameters

Task Reference

IDE Source Attachment

How it works

When it runs

Generated output

Recommended dependency setup

Repositories

Configurations

Configuration Overview

Usage

settings.gradle

build.gradle

Dependencies

Hytale Server Dependency

Dynamic versions

Patchline scoping

Cache behavior

Overriding the server dependency

AssetBridge

Bundling into the final jar

Overriding the runtime version

Configuration

Backing Gradle properties

Support & Issues

Troubleshooting

Missing hytaleVersion

Dynamic version not resolving the expected build

Sources are not attached in the IDE

runServer fails because assets are missing

manifest.json is out of date

Manifest validation fails during build

Dependency sources are not being generated

preRunTask does not run

Validate your debug / hot swap runtime

Notes

About

Topics

Resources

License

Uh oh!

`createManifestIfMissing`

`updatePluginManifest`

`downloadAssetsZip`

`runServer`

Customizing `runServer`

`hytaleJvmDoctor`

`prepareDecompiledSourcesForIde`

`subPlugin` parameters

`settings.gradle`

`build.gradle`

Missing `hytaleVersion`

`runServer` fails because assets are missing

`manifest.json` is out of date

`preRunTask` does not run