gradle-build
Gradle Kotlin DSL build standards for Java game mod projects. Use when editing build.gradle.kts, settings.gradle.kts, gradle.properties, or when adding dependencies, configuring tasks, or troubleshoot
SKILL.mdskills/gradle-build/SKILL.md
GitHubGradle Build Standards
Project Context
- Build system: Gradle with Kotlin DSL (
build.gradle.kts) - Java version: 25 (configured via
java.toolchain) - Plugin:
hytale-mod(providesrunServer, asset management) - Dependency sources: Maven Central +
maven.hytale-modding.info
Key Rules
Dependencies
// ✅ compileOnly for API jars (provided at runtime by the game)
compileOnly(libs.jetbrains.annotations)
// ✅ implementation for bundled libs (included in mod jar)
implementation(files("libs/HyUI-0.9.5-all.jar"))
// ❌ NEVER use implementation for game API classes
// They are already on the classpath at runtime
Version Catalog
- Use
libs.<alias>references fromgradle/libs.versions.toml - Never hardcode version strings in
build.gradle.kts - Exception: local file jars (
files("libs/..."))
Task Configuration
// ✅ Use typed task configuration
tasks.named<ProcessResources>("processResources") { ... }
tasks.withType<Jar> { ... }
// ❌ Don't use string-only task references
tasks.getByName("processResources")
Resource Processing
manifest.jsonuses template expansion → protect withexclude("manifest.json")in sync tasks- Assets sync from
build/resources/main→src/main/resourcesafter server stop - JSON spell/config files go in
src/main/resources/Server/
Common Issues
| Symptom | Cause | Fix |
|---|---|---|
ClassNotFoundException at runtime |
Wrong dependency scope | compileOnly → game provides it |
| Assets not loading | Wrong resource path | Check Server/Spells/ structure |
| Template not expanded | Missing filesMatching |
Add to processResources block |
| Build cache stale | Incremental build issue | ./gradlew clean build |
Build Commands
# Full build
./gradlew build
# Run dev server (if hytale-mod plugin provides it)
./gradlew runServer
# Clean + rebuild
./gradlew clean build
# Check dependencies
./gradlew dependencies --configuration compileClasspath
File Structure
project/
├── build.gradle.kts # Main build config
├── settings.gradle.kts # Project settings
├── gradle.properties # Plugin properties (version, author, etc.)
├── gradle/
│ └── libs.versions.toml # Version catalog
├── libs/ # Local jar dependencies
└── src/main/
├── java/ # Java source
└── resources/
├── manifest.json # Plugin manifest (templated)
├── Server/ # Server-side assets
│ ├── Spells/ # Spell JSON configs
│ └── Languages/ # i18n files
└── Common/ # Shared assets