VS Code Setup

VS Code Setup

The Hytale Gradle Plugin can generate a recommended Visual Studio Code configuration for building, running, and debugging a Hytale mod project.

Requirements

Before generating the VS Code configuration, make sure that:

• Java 25 or newer is installed
• the project can be opened as a Gradle project
• the Hytale Gradle Plugin is applied
• VS Code has permission to write to the project directory

A minimal project configuration looks like:

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

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

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

Generating the VS Code Configuration

Run:

./gradlew configureVSCodeHytaleRun

The task generates the recommended files under:

.vscode/

Generated files include:

.vscode/
├── extensions.json
├── launch.json
├── settings.json
└── tasks.json

These files configure recommended extensions, project settings, Hytale Gradle tasks, and the local server debugger.

You can rerun configureVSCodeHytaleRun when the generated configuration needs to be updated.

Generated Extensions

The generated file:

.vscode/extensions.json

contains the recommended extensions for the project.

After opening the project in VS Code, install the recommended extensions when prompted. Java and Gradle language support are required for the best experience.

Generated Settings

The generated file:

.vscode/settings.json

contains project-level settings used by VS Code's Java and Gradle integrations.

After generation, reload the VS Code window or reopen the project so the settings are applied.

Generated Gradle Tasks

The generated file:

.vscode/tasks.json

contains common Hytale development tasks.

These tasks provide convenient access to operations such as:

• setting up the development environment
• launching the local Hytale server
• preparing decompiled sources
• refreshing generated files
• cleaning generated Hytale outputs and caches

You can run them through:

1. Open the Command Palette.
2. Select Tasks: Run Task.
3. Select the desired Hytale or Gradle task.

You can also continue to run every task directly from the terminal:

./gradlew setupHytaleDev
./gradlew runServer
./gradlew prepareDecompiledSourcesForIde

First-Time Project Setup

For a new checkout or development environment, run:

./gradlew setupHytaleDev

This prepares the normal Hytale development dependencies, sources, and assets.

After it completes:

1. Refresh the Gradle project.
2. Reload the VS Code window.
3. Allow the Java language server to finish indexing.

Decompiled Source Attachment

The Hytale server is distributed as compiled bytecode. The plugin can generate readable sources and install them into local generated repositories for IDE attachment.

Run:

./gradlew prepareDecompiledSourcesForIde

This prepares sources for:

• the Hytale server
• vineImplementation dependencies
• vineCompileOnly dependencies
• requiredDependency dependencies
• optionalDependency dependencies
• additional vineDecompileTargets

Generated source repositories are placed under:

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

Generated source JARs are placed under:

build/generated-sources-jars/

After generation, refresh the Gradle project in VS Code.

The generated repositories are used for IDE source attachment. They are not replacements for the repositories used by the normal build.

Adding Additional Source Targets

Use vineDecompileTargets when you want IDE sources for a dependency that is not otherwise part of a supported Hytale dependency configuration:

dependencies {
    vineDecompileTargets 'com.example:some-api:1.0.0'
}

Then regenerate the sources:

./gradlew prepareDecompiledSourcesForIde

Browsing Hytale Assets

By default, the plugin generates a separate hytale-assets binary library from the resolved Assets.zip.

This keeps Hytale assets separate from the Hytale server library and allows the assets to appear independently in the IDE's external libraries.

The generated asset library:

• is intended for IDE browsing
• is not added to the final mod JAR
• does not modify the generated Hytale server library
• can be disabled when the large asset library is unnecessary

Disable it with:

hytaleTools {
    generateAssetsBinary = false
}

The plugin will still resolve Assets.zip for local server runs, but it will skip generating the IDE asset binary.

Running the Development Server

Start the local server from the integrated terminal:

./gradlew runServer

You can also use the generated task from Tasks: Run Task.

For a specific subproject:

./gradlew :modA:runServer

For a workspace containing multiple mods:

./gradlew runAllMods

See Running and Customizing the Development Server for server arguments, JVM options, debugging, and hot swap configuration.

Debugging the Server

The generated launch configuration is named:

Hytale: runServer

Open the Run and Debug panel in VS Code and select that configuration.

The generated configuration launches the Gradle server task with debugging enabled.

You can also enable debugging manually:

./gradlew runServer -Ddebug=true

The default debug port is:

5005

Configure another port through hytaleTools:

hytaleTools {
    debugEnabled = true
    debugPort = 5006
}

You can also configure the matching Gradle property:

hytools.debug.port=5006

Waiting for the Debugger

To make the server wait for the debugger before continuing startup:

hytaleTools {
    debugEnabled = true
    debugSuspend = true
}

This is useful when debugging code that executes very early in the server or plugin startup process.

Hot Swap

Enable debugging and hot swap with:

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

For enhanced class redefinition, use JetBrains Runtime:

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

Check the selected runtime with:

./gradlew hytaleJvmDoctor

The diagnostic report shows:

• the Java executable used by runServer
• whether JetBrains Runtime was detected
• whether enhanced class redefinition is supported
• whether HotswapAgent support is available

Optional Dev Container

The plugin can generate a development container for contributors who want a reproducible Java and Gradle environment.

Run:

./gradlew generateHytaleDevContainer

This creates:

.devcontainer/
├── devcontainer.json
└── Dockerfile

The Dev Container is optional. A local Java 25 installation is sufficient for normal development.

Opening the Dev Container

After generating the files:

1. Install the VS Code Dev Containers extension.
2. Open the Command Palette.
3. Select Dev Containers: Reopen in Container.
4. Allow the container to build.
5. Run the normal Gradle setup task inside the container.

./gradlew setupHytaleDev

Hytale authentication data, local installation paths, and other host-specific resources may need to be mounted or configured separately for the container.

Customizing Generated Files

The generated .vscode files provide a starting configuration. You can add project-specific tasks or launch configurations after generation.

When rerunning configureVSCodeHytaleRun, review local customizations to ensure they are not replaced by regenerated content.

For substantial project-specific settings, consider keeping custom tasks or launch configurations clearly separated from generated entries.

Cleaning Generated Outputs

Remove project-local generated Hytale outputs with:

./gradlew cleanHytaleGenerated

Remove the cached Hytale assets with:

./gradlew cleanHytaleAssetsCache

Clear global decompiled-source and Javadoc caches with:

./gradlew cleanHytaleGlobalCache

The global cleanup affects all Hytale projects using the same Gradle user home and requires confirmation.

For a non-interactive environment:

./gradlew cleanHytaleGlobalCache \
    -PconfirmCleanHytaleGlobalCache=true

After cleaning generated sources, run:

./gradlew prepareDecompiledSourcesForIde

Then refresh the Gradle project in VS Code.

Troubleshooting

VS Code does not show the generated configuration

Confirm that these files exist:

.vscode/launch.json
.vscode/tasks.json

Regenerate them:

./gradlew configureVSCodeHytaleRun

Then reload the window through the Command Palette:

Developer: Reload Window

Decompiled sources are not attached

Run:

./gradlew prepareDecompiledSourcesForIde

Then refresh the Gradle project and restart the Java language server.

If the dependency is not declared through one of the supported dependency configurations, add it to vineDecompileTargets.

Dependency source generation appears stale

Run:

./gradlew cleanHytaleGenerated
./gradlew prepareDecompiledSourcesForIde --rerun-tasks

If the global decompilation cache itself must be recreated, use:

./gradlew cleanHytaleGlobalCache

Be aware that this affects other projects using the same Gradle user home.

Hytale API comments are missing

Confirm that Javadoc injection is enabled:

hytaleTools {
    injectServerJavadocsIntoSources = true
}

Make sure the configured patchline is correct and regenerate the sources.

The default hosted documentation URL is selected from the active patchline. It can be overridden with:

hytaleTools {
    serverJavadocsUrl =
        'https://release.server.docs.hytale.com/'
}

The debugger cannot connect

Check that:

• the server was launched with debugging enabled
• the configured debug port matches the launch configuration
• another process is not using the port
• debugSuspend has not left the server waiting unexpectedly

Run:

./gradlew hytaleJvmDoctor

Hot swap only supports method-body changes

The selected JVM probably does not support enhanced class redefinition.

Use JetBrains Runtime and confirm it was selected:

./gradlew hytaleJvmDoctor

Gradle changes are not recognized

Refresh the Gradle project after changing:

• dependencies
• hytaleTools
• source sets
• the Java toolchain
• workspace configuration

When needed, reload the VS Code window after the Gradle refresh completes.

Related Pages

• Running and Customizing the Development Server
• IDE Source Attachment
• Runtime Dependency Staging
• Development Workflow
• Task Reference
• Troubleshooting