Back to Details

gradle-hytale

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Gradle for Hytale Plugins

Gradle在Hytale插件开发中的应用

Build system configuration for Hytale plugin development.
为Hytale插件开发提供的构建系统配置指南。

Overview

概述

Hytale plugins use Gradle 9.2 with Kotlin DSL (
build.gradle.kts
).
Hytale插件使用Gradle 9.2搭配Kotlin DSL（
build.gradle.kts
）进行构建。

Project Setup

项目设置

Recommended Structure

推荐项目结构

MyPlugin/
├── build.gradle.kts       # Main build script
├── settings.gradle.kts    # Project settings
├── gradle.properties      # Build properties
├── gradle/
│   └── wrapper/
│       └── gradle-wrapper.properties
└── src/
    └── main/
        ├── java/          # Source code
        └── resources/     # Resources (plugin.json)
MyPlugin/
├── build.gradle.kts       # 主构建脚本
├── settings.gradle.kts    # 项目设置
├── gradle.properties      # 构建属性
├── gradle/
│   └── wrapper/
│       └── gradle-wrapper.properties
└── src/
    └── main/
        ├── java/          # 源代码
        └── resources/     # 资源文件（plugin.json）

settings.gradle.kts

settings.gradle.kts配置示例

kotlin
rootProject.name = "MyPlugin"
kotlin
rootProject.name = "MyPlugin"

gradle.properties

gradle.properties配置示例

properties
undefined
properties
undefined

Gradle settings

Gradle设置

org.gradle.jvmargs=-Xmx2g org.gradle.parallel=true org.gradle.caching=true
org.gradle.jvmargs=-Xmx2g org.gradle.parallel=true org.gradle.caching=true

Plugin info

插件信息

plugin.version=1.0.0 plugin.group=com.yourname
undefined
plugin.version=1.0.0 plugin.group=com.yourname
undefined

build.gradle.kts (Complete)

build.gradle.kts完整配置

kotlin
plugins {
    java
    id("com.hytale.plugin") version "1.0.0"  // Hytale plugin
}

group = property("plugin.group").toString()
version = property("plugin.version").toString()

// Java 25 toolchain
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(25))
    }
}

repositories {
    mavenCentral()
    maven("https://maven.hytale.com/releases")
}

dependencies {
    // Hytale Server API (compile-only, provided at runtime)
    compileOnly("com.hytale:server-api:1.0.0")
    
    // Optional: Common libraries
    implementation("com.google.code.gson:gson:2.10.1")
    
    // Testing
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
}

// Plugin metadata
hytalePlugin {
    pluginId = rootProject.name.lowercase()
    pluginName = rootProject.name
    author = "YourName"
    version = project.version.toString()
    description = "My awesome Hytale plugin"
}

// Test configuration
tasks.test {
    useJUnitPlatform()
}

// JAR configuration
tasks.jar {
    manifest {
        attributes(
            "Plugin-Id" to rootProject.name.lowercase(),
            "Plugin-Version" to project.version
        )
    }
}
kotlin
plugins {
    java
    id("com.hytale.plugin") version "1.0.0"  // Hytale插件插件
}

group = property("plugin.group").toString()
version = property("plugin.version").toString()

// Java 25工具链配置
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(25))
    }
}

repositories {
    mavenCentral()
    maven("https://maven.hytale.com/releases")
}

dependencies {
    // Hytale Server API（仅编译时依赖，运行时由服务器提供）
    compileOnly("com.hytale:server-api:1.0.0")
    
    // 可选：常用依赖库
    implementation("com.google.code.gson:gson:2.10.1")
    
    // 测试依赖
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
}

// 插件元数据配置
hytalePlugin {
    pluginId = rootProject.name.lowercase()
    pluginName = rootProject.name
    author = "YourName"
    version = project.version.toString()
    description = "My awesome Hytale plugin"
}

// 测试任务配置
tasks.test {
    useJUnitPlatform()
}

// JAR包配置
tasks.jar {
    manifest {
        attributes(
            "Plugin-Id" to rootProject.name.lowercase(),
            "Plugin-Version" to project.version
        )
    }
}

Common Tasks

常见任务

Build

构建插件

bash
undefined
bash
undefined

Build plugin JAR

构建插件JAR包

gradle build
gradle build

Output: build/libs/MyPlugin-1.0.0.jar

输出位置：build/libs/MyPlugin-1.0.0.jar

undefined
undefined

Clean Build

清理并重新构建

bash
undefined
bash
undefined

Remove build artifacts and rebuild

删除构建产物后重新构建

gradle clean build
undefined
gradle clean build
undefined

Run Development Server

启动开发服务器

bash
undefined
bash
undefined

If using Hytale dev server plugin

若已安装Hytale开发服务器插件

gradle runServer
undefined
gradle runServer
undefined

List All Tasks

查看所有任务

bash
gradle tasks
bash
gradle tasks

Dependency Tree

查看依赖树

bash
undefined
bash
undefined

View all dependencies

查看所有依赖

gradle dependencies
gradle dependencies

Specific configuration

查看特定配置的依赖

gradle dependencies --configuration compileClasspath

---
gradle dependencies --configuration compileClasspath

---

Dependency Management

依赖管理

Adding Dependencies

添加依赖

kotlin
dependencies {
    // Compile-only (provided by server)
    compileOnly("com.hytale:server-api:1.0.0")
    
    // Bundled in JAR
    implementation("org.yaml:snakeyaml:2.0")
    
    // Runtime only
    runtimeOnly("org.slf4j:slf4j-simple:2.0.9")
    
    // Test dependencies
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
}
kotlin
dependencies {
    // 仅编译时依赖（由服务器提供）
    compileOnly("com.hytale:server-api:1.0.0")
    
    打包进JAR包的依赖
    implementation("org.yaml:snakeyaml:2.0")
    
    // 仅运行时依赖
    runtimeOnly("org.slf4j:slf4j-simple:2.0.9")
    
    // 测试依赖
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
}

Shadow/Fat JAR (Bundle Dependencies)

Shadow/Fat JAR（打包依赖到JAR）

kotlin
plugins {
    java
    id("com.github.johnrengelman.shadow") version "8.1.1"
}

tasks.shadowJar {
    archiveClassifier.set("")
    
    // Relocate to avoid conflicts
    relocate("com.google.gson", "com.yourname.libs.gson")
}

// Use shadowJar as default JAR
tasks.build {
    dependsOn(tasks.shadowJar)
}
kotlin
plugins {
    java
    id("com.github.johnrengelman.shadow") version "8.1.1"
}

tasks.shadowJar {
    archiveClassifier.set("")
    
    // 重定位包路径避免冲突
    relocate("com.google.gson", "com.yourname.libs.gson")
}

// 将shadowJar设为默认JAR构建任务
tasks.build {
    dependsOn(tasks.shadowJar)
}

Version Catalogs (Optional)

版本目录（可选）

For larger projects, use version catalogs:
针对大型项目，推荐使用版本目录管理依赖版本：

gradle/libs.versions.toml

gradle/libs.versions.toml

toml
[versions]
hytale = "1.0.0"
gson = "2.10.1"
junit = "5.10.0"

[libraries]
hytale-api = { module = "com.hytale:server-api", version.ref = "hytale" }
gson = { module = "com.google.code.gson:gson", version.ref = "gson" }
junit = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
toml
[versions]
hytale = "1.0.0"
gson = "2.10.1"
junit = "5.10.0"

[libraries]
hytale-api = { module = "com.hytale:server-api", version.ref = "hytale" }
gson = { module = "com.google.code.gson:gson", version.ref = "gson" }
junit = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }

Using in build.gradle.kts

在build.gradle.kts中使用

kotlin
dependencies {
    compileOnly(libs.hytale.api)
    implementation(libs.gson)
    testImplementation(libs.junit)
}
kotlin
dependencies {
    compileOnly(libs.hytale.api)
    implementation(libs.gson)
    testImplementation(libs.junit)
}

Multi-Module Projects

多模块项目

For plugins with multiple modules:
针对包含多个模块的插件项目：

settings.gradle.kts

settings.gradle.kts

kotlin
rootProject.name = "MyPluginSuite"

include("core")
include("addon-pvp")
include("addon-economy")
kotlin
rootProject.name = "MyPluginSuite"

include("core")
include("addon-pvp")
include("addon-economy")

Structure

项目结构

MyPluginSuite/
├── build.gradle.kts          # Root build
├── settings.gradle.kts
├── core/
│   └── build.gradle.kts
├── addon-pvp/
│   └── build.gradle.kts
└── addon-economy/
    └── build.gradle.kts
MyPluginSuite/
├── build.gradle.kts          # 根项目构建脚本
├── settings.gradle.kts
├── core/
│   └── build.gradle.kts
├── addon-pvp/
│   └── build.gradle.kts
└── addon-economy/
    └── build.gradle.kts

Performance Tips

性能优化技巧

Enable Build Cache

启用构建缓存

properties
undefined
properties
undefined

gradle.properties

gradle.properties

org.gradle.caching=true
undefined
org.gradle.caching=true
undefined

Parallel Execution

并行执行构建

properties
undefined
properties
undefined

gradle.properties

gradle.properties

org.gradle.parallel=true
undefined
org.gradle.parallel=true
undefined

Daemon (Keep Gradle Running)

启用守护进程（保持Gradle后台运行）

properties
undefined
properties
undefined

gradle.properties

gradle.properties

org.gradle.daemon=true
undefined
org.gradle.daemon=true
undefined

Configuration Cache (Experimental)

配置缓存（实验性）

properties
undefined
properties
undefined

gradle.properties

gradle.properties

org.gradle.configuration-cache=true

---
org.gradle.configuration-cache=true

---

Troubleshooting

问题排查

IssueSolution
Gradle sync failsCheck Java 25 is installed and set
Could not resolve dependencyAdd correct Maven repository
Out of memoryIncrease 
-Xmx
in gradle.properties
Slow buildsEnable caching and parallel execution
Wrong JAR locationCheck 
build/libs/
folder
问题解决方案
Gradle同步失败检查是否已安装并配置Java 25
无法解析依赖添加正确的Maven仓库地址
内存不足增大gradle.properties中的
-Xmx
参数值
构建速度慢启用缓存与并行执行
JAR包位置错误检查
build/libs/
目录

Force Refresh Dependencies

强制刷新依赖

bash
gradle build --refresh-dependencies
bash
gradle build --refresh-dependencies

Debug Build Issues

调试构建问题

bash
gradle build --info
gradle build --debug
gradle build --stacktrace
bash
gradle build --info
gradle build --debug
gradle build --stacktrace

Quick Reference

快速参考

TaskCommand
Build
gradle build
Clean
gradle clean
Test
gradle test
Run server
gradle runServer
List tasks
gradle tasks
Dependencies
gradle dependencies
Refresh deps
gradle build --refresh-dependencies
任务命令
构建插件
gradle build
清理构建产物
gradle clean
运行测试
gradle test
启动开发服务器
gradle runServer
查看所有任务
gradle tasks
查看依赖树
gradle dependencies
刷新依赖后构建
gradle build --refresh-dependencies