hytale-plugin-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hytale Plugin Development

Hytale 插件开发

Create server-side plugins for Hytale using Java 25 and Gradle.

使用Java 25和Gradle为Hytale创建服务器端插件。

Overview

概述

Hytale uses a server-side first modding approach. All plugins run on the server - players don't need to install anything to join modded servers.

Tech Stack:

Java 25 - Required JDK version
Gradle 9.2 - Build system
Antigravity - Recommended IDE (AI-assisted development!)

Hytale采用服务器优先的模组开发方式。所有插件都在服务器端运行——玩家无需安装任何内容即可加入模组化服务器。

技术栈:

Java 25 - 所需的JDK版本
Gradle 9.2 - 构建系统
Antigravity - 推荐使用的IDE（支持AI辅助开发！）

First-Time Setup Flow

首次设置流程

When a user asks to create a plugin, guide them through this:

当用户请求创建插件时，按照以下步骤引导他们：

Step 1: Prerequisites Check

步骤1：前置条件检查

I'll help you create that plugin! First, let me verify your setup:

Prerequisites:
1. Java 25 (download from Adoptium or Oracle)
2. Gradle (I can run commands for you in Antigravity!)

If you're using Antigravity, you're all set - I can handle builds directly!

我会帮你创建这个插件！首先，让我确认你的环境是否满足要求：

前置条件：
1. Java 25（可从Adoptium或Oracle下载）
2. Gradle（我可以在Antigravity中帮你运行命令！）

如果你正在使用Antigravity，那一切准备就绪——我可以直接处理构建操作！

Step 2: Install Java 25

步骤2：安装Java 25

Windows:

powershell

undefined

Windows系统:

powershell

undefined

Download from Adoptium

从Adoptium下载

winget install EclipseAdoptium.Temurin.25.JDK


**Or download manually** from: https://adoptium.net/

winget install EclipseAdoptium.Temurin.25.JDK


**或手动下载**：https://adoptium.net/

Step 3: Create Project from Template

步骤3：从模板创建项目

The easiest way to start - use the community template:

bash

undefined

最简单的入门方式——使用社区模板：

bash

undefined

Clone the official template (Darkhax/Jared)

克隆官方模板（Darkhax/Jared）

git clone https://github.com/Darkhax-Hytale/HytalePluginTemplate.git MyPlugin cd MyPlugin


Or create manually with this structure:

MyPlugin/ ├── build.gradle.kts ├── settings.gradle.kts ├── gradle.properties └── src/ └── main/ └── java/ └── com/ └── yourname/ └── myplugin/ └── MyPlugin.java

undefined

git clone https://github.com/Darkhax-Hytale/HytalePluginTemplate.git MyPlugin cd MyPlugin


或手动创建如下结构的项目：

undefined

Step 4: Open in Antigravity

步骤4：在Antigravity中打开项目

Open the project folder in Antigravity
I'll automatically detect the Gradle project
Use
```
gradle build
```
via run_command to build
I can help you write, debug, and test code!

Alternative: IntelliJ IDEA

Open IntelliJ IDEA
File → Open → Select project folder
File → Project Structure → Project → SDK → Select Java 25
Let Gradle sync complete

在Antigravity中打开项目文件夹
我会自动检测Gradle项目
通过run_command执行
```
gradle build
```
命令进行构建
我可以帮你编写、调试和测试代码！

替代方案：IntelliJ IDEA

打开IntelliJ IDEA
文件 → 打开 → 选择项目文件夹
文件 → 项目结构 → 项目 → SDK → 选择Java 25
等待Gradle同步完成

Plugin Lifecycle

插件生命周期

Every plugin extends

JavaPlugin

with these lifecycle methods:

java

package com.yourname.myplugin;

import com.hytale.server.plugin.JavaPlugin;

public class MyPlugin extends JavaPlugin {
    
    @Override
    public void setup() {
        // Called during server setup phase
        // Register commands, events, configs here
        getLogger().info("MyPlugin setting up...");
    }
    
    @Override
    public void start() {
        // Called when server starts
        // Initialize runtime features
        getLogger().info("MyPlugin started!");
    }
    
    @Override
    public void shutdown() {
        // Called during server shutdown
        // Clean up resources, save data
        getLogger().info("MyPlugin shutting down...");
    }
}

每个插件都需要继承

JavaPlugin

并实现以下生命周期方法：

java

package com.yourname.myplugin;

import com.hytale.server.plugin.JavaPlugin;

public class MyPlugin extends JavaPlugin {
    
    @Override
    public void setup() {
        // 服务器初始化阶段调用
        // 在此注册命令、事件、配置
        getLogger().info("MyPlugin setting up...");
    }
    
    @Override
    public void start() {
        // 服务器启动时调用
        // 初始化运行时功能
        getLogger().info("MyPlugin started!");
    }
    
    @Override
    public void shutdown() {
        // 服务器关闭时调用
        // 清理资源、保存数据
        getLogger().info("MyPlugin shutting down...");
    }
}

Lifecycle Order

生命周期顺序

Server Boot → setup() → start() → [Running] → shutdown() → Server Stop

服务器启动 → setup() → start() → [运行中] → shutdown() → 服务器停止

Command Registration

命令注册

setup()

java

@Override
public void setup() {
    registerCommand("hello", (sender, args) -> {
        sender.sendMessage("Hello from MyPlugin!");
        return true;
    });
    
    registerCommand("spawn", (sender, args) -> {
        if (sender instanceof Player player) {
            player.teleportToSpawn();
            player.sendMessage("Teleported to spawn!");
        }
        return true;
    });
}

在

setup()

方法中注册自定义命令：

java

@Override
public void setup() {
    registerCommand("hello", (sender, args) -> {
        sender.sendMessage("Hello from MyPlugin!");
        return true;
    });
    
    registerCommand("spawn", (sender, args) -> {
        if (sender instanceof Player player) {
            player.teleportToSpawn();
            player.sendMessage("Teleported to spawn!");
        }
        return true;
    });
}

Command with Arguments

带参数的命令

java

registerCommand("give", (sender, args) -> {
    if (args.length < 2) {
        sender.sendMessage("Usage: /give <player> <item>");
        return false;
    }
    String playerName = args[0];
    String itemId = args[1];
    // Implementation...
    return true;
});

java

registerCommand("give", (sender, args) -> {
    if (args.length < 2) {
        sender.sendMessage("Usage: /give <player> <item>");
        return false;
    }
    String playerName = args[0];
    String itemId = args[1];
    // 实现逻辑...
    return true;
});

Event System

事件系统

Event Types

事件类型

Category	Examples
Server Lifecycle	`BootEvent` , `ShutdownEvent` , `PluginSetupEvent`
Player Events	`PlayerJoinEvent` , `PlayerQuitEvent` , `PlayerChatEvent`
World Events	`WorldLoadEvent` , `ChunkLoadEvent`
Entity Events	`EntitySpawnEvent` , `EntityDamageEvent`
Block Events	`BlockBreakEvent` , `BlockPlaceEvent`

分类	示例
服务器生命周期	`BootEvent` , `ShutdownEvent` , `PluginSetupEvent`
玩家事件	`PlayerJoinEvent` , `PlayerQuitEvent` , `PlayerChatEvent`
世界事件	`WorldLoadEvent` , `ChunkLoadEvent`
实体事件	`EntitySpawnEvent` , `EntityDamageEvent`
方块事件	`BlockBreakEvent` , `BlockPlaceEvent`

Registering Event Listeners

注册事件监听器

java

@Override
public void setup() {
    registerEventListener(PlayerJoinEvent.class, event -> {
        Player player = event.getPlayer();
        getServer().broadcastMessage(player.getName() + " joined!");
    });
    
    registerEventListener(BlockBreakEvent.class, event -> {
        if (event.getBlock().getType().equals("diamond_ore")) {
            event.getPlayer().sendMessage("You found diamonds!");
        }
    });
}

java

@Override
public void setup() {
    registerEventListener(PlayerJoinEvent.class, event -> {
        Player player = event.getPlayer();
        getServer().broadcastMessage(player.getName() + " joined!");
    });
    
    registerEventListener(BlockBreakEvent.class, event -> {
        if (event.getBlock().getType().equals("diamond_ore")) {
            event.getPlayer().sendMessage("You found diamonds!");
        }
    });
}

Cancellable Events

可取消的事件

java

registerEventListener(BlockBreakEvent.class, event -> {
    if (isProtectedArea(event.getBlock().getPosition())) {
        event.setCancelled(true);
        event.getPlayer().sendMessage("This area is protected!");
    }
});

java

registerEventListener(BlockBreakEvent.class, event -> {
    if (isProtectedArea(event.getBlock().getPosition())) {
        event.setCancelled(true);
        event.getPlayer().sendMessage("This area is protected!");
    }
});

Entity Component System (ECS)

实体组件系统（ECS）

Hytale uses ECS architecture for entities:

Hytale采用ECS架构来管理实体：

Core Concepts

核心概念

Entity: Unique ID, no data or behavior
Component: Data container (health, position, inventory)
System: Logic that operates on components

实体：唯一ID，无数据或行为
组件：数据容器（生命值、位置、背包）
系统：操作组件的逻辑

Working with Components

组件操作

java

// Get a component from an entity
HealthComponent health = entity.getComponent(HealthComponent.class);
if (health != null) {
    health.setHealth(health.getHealth() + 10);
}

// Check if entity has component
if (entity.hasComponent(FlyingComponent.class)) {
    // Handle flying entity
}

java

// 从实体获取组件
HealthComponent health = entity.getComponent(HealthComponent.class);
if (health != null) {
    health.setHealth(health.getHealth() + 10);
}

// 检查实体是否拥有组件
if (entity.hasComponent(FlyingComponent.class)) {
    // 处理飞行实体
}

Gradle Build Configuration

Gradle构建配置

Setting Up Dependencies (Critical!)

依赖设置（至关重要！）

The official maven repo has been unstable. Use this local-first strategy:

Step 1: Extract API from HytaleServer.jar

bash

undefined

官方Maven仓库不稳定，建议采用本地优先策略：

步骤1：从HytaleServer.jar提取API

bash

undefined

Windows - find the server JAR:

Windows系统 - 找到服务器JAR文件：

%appdata%\Hytale\Hytale\install\release\package\game\latest\Server\HytaleServer.jar

Install to local Maven cache:

安装到本地Maven仓库：

mvn install:install-file
-Dfile="PATH_TO_JAR/HytaleServer.jar"
-DgroupId=com.hypixel.hytale
-DartifactId=Server
-Dversion=1.0-SNAPSHOT
-Dpackaging=jar

undefined

mvn install:install-file
-Dfile="PATH_TO_JAR/HytaleServer.jar"
-DgroupId=com.hypixel.hytale
-DartifactId=Server
-Dversion=1.0-SNAPSHOT
-Dpackaging=jar

undefined

build.gradle.kts

kotlin

plugins {
    `java-library`
    id("hytale-mod") version "0.+" // Community tooling
}

group = "com.yourname"
version = "1.0.0"

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

repositories {
    mavenLocal() // Priority 1: Local cache (from extracted JAR)
    mavenCentral()
    
    // Priority 2: Community mirror (more stable than official)
    maven("https://maven.hytale-modding.info/releases") {
        content {
            includeGroup("com.hypixel.hytale")
        }
    }
    
    // JitPack for GitHub-hosted community libs
    maven("https://jitpack.io")
}

dependencies {
    // MUST be compileOnly - server provides at runtime
    compileOnly("com.hypixel.hytale:Server:1.0-SNAPSHOT")
}

Important: Use

compileOnly

for the server dependency. Bundling it causes ClassCastExceptions.

kotlin

plugins {
    `java-library`
    id("hytale-mod") version "0.+" // 社区工具
}

group = "com.yourname"
version = "1.0.0"

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(25)) // 必须配置！
    }
}

repositories {
    mavenLocal() // 优先级1：本地缓存（来自提取的JAR）
    mavenCentral()
    
    // 优先级2：社区镜像（比官方更稳定）
    maven("https://maven.hytale-modding.info/releases") {
        content {
            includeGroup("com.hypixel.hytale")
        }
    }
    
    // JitPack用于托管在GitHub的社区库
    maven("https://jitpack.io")
}

dependencies {
    // 必须使用compileOnly - 服务器在运行时提供该依赖
    compileOnly("com.hypixel.hytale:Server:1.0-SNAPSHOT")
}

重要提示：对服务器依赖使用

compileOnly

。打包该依赖会导致ClassCastExceptions错误。

Building

构建插件

bash

undefined

bash

undefined

Build the plugin JAR

构建插件JAR文件

gradle build

Output: build/libs/MyPlugin-1.0.0.jar

输出路径：build/libs/MyPlugin-1.0.0.jar

undefined

undefined

Installing

安装插件

For client mods:

%APPDATA%/Hytale/UserData/Mods/

For server plugins: Copy to

server/mods/

folder (NOT

plugins/

)

客户端模组：

%APPDATA%/Hytale/UserData/Mods/

服务器插件：复制到

server/mods/

文件夹（注意：不是

plugins/

）

Project Structure

项目结构

MyPlugin/
├── build.gradle.kts          # Gradle build script
├── settings.gradle.kts       # Gradle settings
├── gradle.properties         # Gradle properties
├── src/
│   └── main/
│       ├── java/
│       │   └── com/yourname/myplugin/
│       │       ├── MyPlugin.java        # Main plugin class
│       │       ├── commands/            # Command handlers
│       │       ├── events/              # Event listeners
│       │       └── systems/             # ECS systems
│       └── resources/
│           └── plugin.json              # Plugin metadata
└── build/
    └── libs/
        └── MyPlugin-1.0.0.jar           # Built plugin

MyPlugin/
├── build.gradle.kts          # Gradle构建脚本
├── settings.gradle.kts       # Gradle设置
├── gradle.properties         # Gradle属性
├── src/
│   └── main/
│       ├── java/
│       │   └── com/yourname/myplugin/
│       │       ├── MyPlugin.java        # 主插件类
│       │       ├── commands/            # 命令处理器
│       │       ├── events/              # 事件监听器
│       │       └── systems/             # ECS系统
│       └── resources/
│           └── plugin.json              # 插件元数据
└── build/
    └── libs/
        └── MyPlugin-1.0.0.jar           # 构建完成的插件

Quick Reference

快速参考

Task	How
Build plugin	`gradle build`
Install plugin	Copy JAR to `%APPDATA%/Hytale/UserData/Mods/`
Reload plugins	`/plugin reload` in-game
View plugins	`/plugin list` in-game
Debug	Use Antigravity terminal + logging

任务	操作方式
构建插件	`gradle build`
安装插件	将JAR复制到 `%APPDATA%/Hytale/UserData/Mods/`
重载插件	在游戏内执行 `/plugin reload`
查看插件列表	在游戏内执行 `/plugin list`
调试	使用Antigravity终端 + 日志

Resources

资源

Community Mirror Maven:

https://maven.hytale-modding.info/releases

Example Plugin (Kaupenjoe): GitHub
SimpleClaims (Buuz135): GitHub
Hytale Modding Bible: Community API reference on Reddit
Kytale Framework: CurseForge
Imperat Command Framework: Multi-platform command lib
Java 25 Reference: See
```
java-25-hytale
```
skill
Gradle Reference: See
```
gradle-hytale
```
skill

社区镜像Maven:

https://maven.hytale-modding.info/releases

示例插件（Kaupenjoe）: GitHub
SimpleClaims（Buuz135）: GitHub
Hytale模组开发宝典: Reddit上的社区API参考
Kytale框架: CurseForge
Imperat命令框架: 跨平台命令库
Java 25参考: 查看
```
java-25-hytale
```
技能文档
Gradle参考: 查看
```
gradle-hytale
```
技能文档