Running and Customizing the Development Server

Running and Customizing the Development Server

The Hytale Gradle Plugin can launch a local Hytale server directly from Gradle. It prepares the development environment, stages the current mod and its dependencies, resolves the required assets, and starts the server with your configured runtime options.

Running a Single Mod

Run the current project with:

./gradlew runServer

In a multi-project build, target a specific mod project:

./gradlew :modA:runServer

Before launching the server, the plugin automatically runs the required preparation work through prepareRunServer.

This includes:

• validating the project manifest
• resolving the Hytale server
• resolving Assets.zip
• staging runtime plugin dependencies
• expanding runtime libraries
• linking the current project's classes and resources into the run environment

You normally do not need to invoke prepareRunServer manually.

Running a Multi-Project Workspace

When the root project applies com.azuredoom.hytale-workspace, run all configured mods together with:

./gradlew runAllMods

The workspace starts one Hytale server containing every project configured through modProjects.

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

The host project provides the shared server runtime configuration and Hytale assets used by runAllMods.

See Multi-Project Setup for the complete workspace configuration.

Basic Run Configuration

Development server options are configured inside hytaleTools:

hytaleTools {
    hytaleVersion = '0.+'

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

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

The plugin automatically adds the required --assets=... argument. Values from serverArgs are appended to the Hytale server arguments.

Values from serverJvmArgs are added to the JVM arguments used to start the server.

Server Arguments

Use serverArgs to pass options to the Hytale server:

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

Combined argument entries containing spaces are also supported:

hytaleTools {
    serverArgs = ['--transport QUICHE']
}

You can combine both styles:

hytaleTools {
    serverArgs = [
        '--allow-op',
        '--transport QUICHE',
        '--disable-sentry'
    ]
}

The default value is:

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

Setting serverArgs replaces that configured list, so include any default options that you want to retain.

JVM Arguments

Use serverJvmArgs for memory settings, garbage collector options, system properties, or other JVM-level configuration:

hytaleTools {
    serverJvmArgs = [
        '-Xms2G',
        '-Xmx4G',
        '-XX:+UseG1GC'
    ]
}

These options are added in addition to the JVM settings managed internally by the plugin.

Do not place Hytale server options such as --allow-op in serverJvmArgs. Likewise, JVM options such as -Xmx4G belong in serverJvmArgs, not serverArgs.

Running a Preparation Task

Use preRunTask when another Gradle task must complete before the server starts:

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

hytaleTools {
    preRunTask = 'generateDevResources'
}

The named task must:

• exist in the same project as runServer
• be registered before Gradle finishes configuring the project
• be specified using its task name as a string

For a multi-project build, configure the task on the individual mod project whose runServer task uses it.

Run Directory

By default, the development server uses:

run/

You can change it through runDirectory:

hytaleTools {
    runDirectory = layout.projectDirectory.dir('dev-server')
}

Generated and staged files inside the run environment are managed by the plugin. Avoid manually modifying plugin-managed staging directories because they may be recreated or cleaned during later runs.

Assets

The server requires Hytale's Assets.zip. By default, the plugin authenticates with Hytale, resolves the appropriate asset bundle, and caches the extracted assets under the Gradle user home.

To resolve assets before launching the server, run:

./gradlew downloadAssetsZip

You can use a local installation instead:

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

The override may point to:

• an Assets.zip file
• a directory containing Assets.zip
• a Hytale launcher or installation directory containing the configured patchline

When no override is configured and the remote lookup fails, the plugin attempts to locate a local Hytale installation as a fallback.

For runAllMods, configure hytaleHomeOverride on the selected workspace host project:

hytaleWorkspace {
    hostProject = ':modA'
}

project(':modA') {
    hytaleTools {
        hytaleHomeOverride =
            '/path/to/Hytale/install/release/package/game/latest/Assets.zip'
    }
}

Debugging

Enable JDWP debugging in the extension:

hytaleTools {
    debugEnabled = true
    debugPort = 5005
    debugSuspend = false
}

You can also enable it for an individual command:

./gradlew runServer -Ddebug=true

The debug options are:

Property	Default	Purpose
debugEnabled	false	Enables JDWP debugging
debugPort	5005	Port used by the debugger
debugSuspend	false	Waits for a debugger before starting when enabled

Set debugSuspend to true when you need the JVM to wait before loading the server:

hytaleTools {
    debugEnabled = true
    debugSuspend = true
}

You can then attach your IDE debugger to the configured port.

When an IDE such as IntelliJ already injects a JDWP debugger agent, the plugin detects it and avoids adding a duplicate agent.

Hot Swap

Hot swap allows supported code changes to be applied while the development server is running.

Enable debugging and hot swap from the command line:

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

Or configure it in the project:

hytaleTools {
    debugEnabled = true
    hotSwapEnabled = true
}

The available options are:

hytaleTools {
    debugEnabled = true
    debugPort = 5005
    debugSuspend = false

    hotSwapEnabled = true
    requireDcevm = false
    useHotswapAgent = true

    // Optional external HotswapAgent jar
    hotswapAgentPath = ''

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

JVM Support

Hot swap capabilities depend on the selected JVM:

• A standard JVM generally supports method-body changes.
• JetBrains Runtime supports enhanced class redefinition.
• HotswapAgent can improve automatic runtime reload behavior.

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

When enhanced class redefinition is available, the plugin adds:

-XX:+AllowEnhancedClassRedefinition

Requiring Enhanced Redefinition

Set requireDcevm when the server should fail instead of starting with limited hot swap support:

hytaleTools {
    hotSwapEnabled = true
    requireDcevm = true
}

When enhanced class redefinition is unavailable, runServer stops with an error.

HotswapAgent

Enable HotswapAgent integration with:

hytaleTools {
    hotSwapEnabled = true
    useHotswapAgent = true
}

If hotswapAgentPath is empty, the plugin attempts to use the HotswapAgent support bundled with a compatible JetBrains Runtime.

To use an external agent:

hytaleTools {
    hotSwapEnabled = true
    useHotswapAgent = true
    hotswapAgentPath = '/absolute/path/to/hotswap-agent.jar'
}

The configured file must exist and point directly to a HotswapAgent JAR.

Selecting JetBrains Runtime

The plugin resolves the JVM in the following order:

1. jbrHome
2. known JetBrains Runtime environment variables, including JBR_HOME
3. automatically detected JetBrains Runtime installations
4. the current JVM

Set an explicit installation when needed:

hytaleTools {
    jbrHome = '/path/to/jbr'
}

The matching Gradle property is:

hytools.jbr.home=/path/to/jbr

Checking the Runtime

Use hytaleJvmDoctor to inspect the runtime selected for development:

./gradlew hytaleJvmDoctor

The report includes:

• the resolved Java executable
• whether JetBrains Runtime was detected
• enhanced class-redefinition support
• HotswapAgent mode support
• bundled HotswapAgent availability

Run this first when debugging or hot swap does not behave as expected.

For broader project diagnostics, run:

./gradlew hytaleDoctor

This reports the configured Hytale version, patchline, manifest, assets, server dependency, run directory, and declared Hytale dependencies.

Complete Example

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

tasks.register('generateDevResources') {
    doLast {
        println 'Generating development resources...'
    }
}

hytaleTools {
    hytaleVersion = '0.+'
    patchline = 'release'

    manifestGroup = 'com.example.mods'
    modId = 'examplemod'
    mainClass = 'com.example.mods.ExampleMod'

    serverArgs = [
        '--allow-op',
        '--disable-sentry',
        '--transport QUICHE'
    ]

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

    preRunTask = 'generateDevResources'

    debugEnabled = false
    debugPort = 5005
    debugSuspend = false

    hotSwapEnabled = false
    requireDcevm = false
    useHotswapAgent = true
}

Run normally:

./gradlew runServer

Run with debugging:

./gradlew runServer -Ddebug=true

Run with debugging and hot swap:

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

Troubleshooting

The server does not receive an argument

Run the task with additional Gradle logging:

./gradlew runServer --info

Check the reported launch command and confirm the option is in serverArgs, not serverJvmArgs.

Both of these forms are supported:

serverArgs = ['--transport QUICHE']

serverArgs = ['--transport', 'QUICHE']

preRunTask does not run

Verify that:

• the task exists in the same project as runServer
• the task name matches exactly
• preRunTask contains a string task name

Assets cannot be resolved

Run:

./gradlew hytaleDoctor
./gradlew downloadAssetsZip --info

Verify:

• hytaleVersion
• patchline
• hytaleHomeOverride, when configured
• the local Hytale installation path
• the cached authentication state

To clear the assets cache:

./gradlew cleanHytaleAssetsCache

Then retry:

./gradlew downloadAssetsZip

Hot swap is unavailable

Run:

./gradlew hytaleJvmDoctor

Confirm that the expected JetBrains Runtime was selected and that enhanced class redefinition is supported.

The external HotswapAgent cannot be found

Make sure hotswapAgentPath is an absolute path to an existing JAR:

hytaleTools {
    hotswapAgentPath = '/absolute/path/to/hotswap-agent.jar'
}

Duplicate JDWP agent error

Do not manually add another -agentlib:jdwp=... entry to serverJvmArgs when your IDE already starts Gradle in debug mode.

For command-line debugging, use:

./gradlew runServer -Ddebug=true

Related Pages

• Development Workflow
• Multi-Project Setup
• VS Code Setup
• Runtime Dependency Staging
• Troubleshooting
• Task Reference