Hytale 服务器 API 参考：事件、消息与插件开发指南

理解 Hytale 服务器架构 Hytale 服务器 API 基于强大的 Java 架构构建，对于有 Minecraft 服务器插件开发经验的人来说会非常熟悉。随着回归 Legacy Engine，开发者现在可以访问一个成熟、经过充分测试的代码库，该代码库优先考虑模组开发的便利性而非跨平台复杂性。 服务器的核心是 com.hypixel.hytale.server.core 包，它为所有服务器端操作提供了基础。这包括玩家管理、世界处理、事件调度和命令处理。 玩家连接事件：处理加入和离开 任何服务器插件最常见的需求之一是响应玩家的加入或离开。Hytale API 为此提供了两个基本事件。 PlayerConnectEvent 当玩家成功连接到服务器时触发，此事件在玩家完全生成到世界之前就提供了对玩家引用的访问。主要属性包括： playerRef — 包含 UUID、用户名和网络信息的 PlayerRef 实例 player — 代表玩家在世界中的 Player 实体 world — 玩家正在加入的 World 实例 holder — 用于组件访问的实体存储持有者 与某些其他事件不同，PlayerConnectEvent 不可取消。如果你需要阻止玩家加入，应在身份验证层进行处理。 eventRegistry.register(PlayerConnectEvent::class.java) { event -> val player = event.playerRef logger.info("Player connected: ${player.username}") // Send welcome message player.sendMessage(Message.raw("Welcome to the server!")) } PlayerDisconnectEvent 当玩家离开服务器时触发，此事件包含关于断开原因的重要上下文： playerRef — 离开玩家的引用 disconnectReason — 指示超时、踢出、退出或服务器关闭的枚举 此事件也不可取消，因为断开连接已在网络层发生。 Message 类：富文本格式化 希望创建精美聊天体验的服务器所有者将花费大量时间使用 Message 类。它位于核心消息包中，提供了用于构建格式化文本的流式 API。 基本消息创建 // Simple text message val msg = Message.raw("Hello, world!") // With color formatting val styled = Message.raw("Important!") .color("red") .bold(true) .italic(false) .monospace(true) 参数替换 对于动态内容，使用参数占位符： val welcome = Message.raw("Welcome, {name}! You have {coins} coins.") .param("name", player.username) .param("coins", playerData.coinBalance.toString()) 可点击链接 消息可以包含可点击的超链接： val linked = Message.raw("Click here to visit our website") .link("https://example.com") 事件注册模式 Hytale 事件系统支持同步和异步事件处理，为开发者提供了基于性能需求的灵活性。 同步注册 对于需要在服务器线程上立即处理的事件： eventRegistry.register(PlayerInteractEvent::class.java) { event -> if (event.actionType == ActionType.RIGHT_CLICK) { // Process the interaction event.setCancelled(true) } } 异步注册 对于可以在主线程之外处理的事件（如聊天审核）： eventRegistry.registerAsync(PlayerChatEvent::class.java) { future -> future.thenApply { event -> // Perform async chat filtering if (containsBannedWords(event.content)) { event.setCancelled(true) } event } } 常用事件参考表 以下是服务器开发中最常用事件的快速参考： 事件名称可取消主要属性 PlayerConnectEvent否playerRef, player, world, holder PlayerDisconnectEvent否playerRef, disconnectReason PlayerChatEvent是（异步）sender, targets, content, formatter PlayerInteractEvent是player, actionType, itemInHand, targetBlock, targetEntity PlayerDeathEvent否player PlayerRespawnEvent否player BreakBlockEvent是itemInHand, targetBlock, blockType PlaceBlockEvent是itemInHand, targetBlock, rotation DamageBlockEvent是itemInHand, targetBlock, currentDamage, damage DropItemEvent是item, location CraftRecipeEvent是craftedRecipe, quantity 构建自定义命令 命令系统允许你注册玩家可以在聊天中执行的斜杠命令。 基本命令实现 class MyCommand : Command { override fun getName(): String = "mycommand" override fun execute(sender: CommandSender, args: Array<String>) { sender.sendMessage(Message.raw("Hello from my custom command!")) } } // Register in your plugin's setup phase commandRegistry.registerCommand(MyCommand()) 使用 CommandManager 你也可以通过编程方式执行命令： val commandManager = CommandManager.get() commandManager.handleCommand(sender, "time day") 插件生命周期和结构 每个 Hytale 服务器插件都继承 JavaPlugin 基类，该类提供了基本的注册表和生命周期钩子。 插件生命周期阶段 Construction — 插件类实例化 PreLoad — 服务器启动前的异步初始化 Setup — 注册组件、事件和命令 Start — 服务器准备好接受玩家 Shutdown — 服务器停止前的清理 关键插件属性 // Available in your plugin class logger: HytaleLogger // Logging capability manifest: PluginManifest? // Plugin metadata from manifest file eventRegistry: EventRegistry // Register event listeners commandRegistry: CommandRegistry // Register commands dataDirectory: Path // Plugin storage location taskRegistry: TaskRegistry // Scheduled task management 配置辅助工具 插件可以轻松加载 JSON 配置文件： // Using default config.json val config: Config<MyConfigClass> = withConfig(MyConfigClass.CODEC) // Using custom filename val config: Config<MyConfigClass> = withConfig("custom-name.json", MyConfigClass.CODEC) 与玩家交互 PlayerRef 类是与已连接玩家交互的主要接口。 玩家身份和位置 val player: PlayerRef = event.playerRef // Identity val uuid: UUID = player.uuid val name: String = player.username val language: String = player.language // Position val transform: Transform = player.transform val worldUuid: UUID = player.worldUuid val headRotation: Vector3f = player.headRotation 玩家实体访问 对于更深层的交互（如背包管理），访问 Player 实体： val playerEntity: Player = player.entity // Inventory operations val inventory: Inventory = playerEntity.inventory playerEntity.sendInventory() // UI managers val hotbar = playerEntity.hotbarManager val windows = playerEntity.windowManager val pages = playerEntity.pageManager val hud = playerEntity.hudManager // Permissions val canBuild: Boolean = playerEntity.hasPermission("server.build") 世界和宇宙管理 Universe 单例提供对所有世界和已连接玩家的访问。 val universe = Universe.get() // Player access val allPlayers: List<PlayerRef> = universe.players val playerCount: Int = universe.playerCount val specificPlayer: PlayerRef? = universe.getPlayer(uuid) // World access val worlds: Map<String, World> = universe.worlds val defaultWorld: World? = universe.defaultWorld val specificWorld: World? = universe.getWorld("my-world") // World management val newWorld: CompletableFuture<World> = universe.addWorld("new-world") val loaded: CompletableFuture<World> = universe.loadWorld("existing-world") 线程安全警告 组件访问必须在世界线程上进行。始终将操作包装在 execute 块中： world.execute { // Safe component access here val entities = world.getEntities() } 服务器开发者的下一步 有了这份 API 参考作为基础，你已经准备好开始构建 Hytale 服务器插件了。接下来值得探索的关键资源： 实体组件系统（ECS）用于高级实体操控 内置模块，如 NPC、传送门和任务系统 用于游戏行为的可视化脚本系统 用于自定义数据包处理的网络协议 请记住，随着 Hytale 在抢先体验阶段的推进，API 可能会发生变化。请保持与社区的联系，并关注官方文档的更新。