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 可能會發生變化。請保持與社群的聯繫，並關注官方文件的更新。