Included Tasks

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

Resolves the Hytale Assets.zip used by local development.

By default, this task authenticates with Hytale device auth, downloads the asset wrapper, extracts Assets.zip, and caches the extracted zip under Gradle user home.

If hytaleHomeOverride is configured, the plugin resolves an existing local Assets.zip from that path and uses it directly. In this mode, the assets zip is not copied into the Gradle cache.

You can point hytaleHomeOverride at either:

• a direct Assets.zip file
• a directory containing Assets.zip
• a Hytale launcher/install directory that contains the configured patchline assets

hytaleTools {
    hytaleHomeOverride = "/path/to/Hytale/install/release/package/game/latest/Assets.zip"
}

or

hytaleTools {
    hytaleHomeOverride = "/path/to/Hytale/install/release/package/game/latest/"
}

If no override is configured and remote download fails, the task attempts to locate a local Hytale installation as a fallback and caches the found Assets.zip.

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 = '0.+'

    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 external HotswapAgent jar.
    // If unset, the plugin will try bundled JBR HotswapAgent support when available.
    hotswapAgentPath = ''
    
    // 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

When hotSwapEnabled is true, the plugin checks the selected JVM for enhanced class redefinition support. If enhanced redefinition is available, it adds -XX:+AllowEnhancedClassRedefinition. If useHotswapAgent is also true, the plugin either uses the configured external hotswapAgentPath jar or falls back to bundled JBR HotswapAgent support when available.

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 HotswapAgent integration when hot swap is enabled
• hotswapAgentPath points to an external HotswapAgent jar; when set, it is used as -javaagent:<path>=autoHotswap=true
• If hotswapAgentPath is empty, the plugin attempts to use bundled JBR HotswapAgent support when available
• 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.

---

Home | Task Reference | Troubleshooting