Довідник API сервера Hytale: події, повідомлення та посібник з розробки плагінів

Розуміння архітектури сервера Hytale API сервера Hytale побудовано на надійній Java-архітектурі, яка буде знайома кожному, хто працював із плагінами для серверів Minecraft. З поверненням до Legacy Engine розробники тепер мають доступ до зрілої, добре протестованої кодової бази, яка надає пріоритет доступності модифікацій над кросплатформною складністю. В основі сервера лежить пакет com.hypixel.hytale.server.core, який забезпечує фундамент для всіх серверних операцій. Це включає управління гравцями, обробку світів, диспетчеризацію подій та обробку команд. Події підключення гравців: обробка входу та виходу Одна з найпоширеніших вимог для будь-якого серверного плагіна — реагування на підключення та відключення гравців. API Hytale надає дві основні події для цієї мети. PlayerConnectEvent Спрацьовує при успішному підключенні гравця до сервера. Ця подія надає доступ до посилання на гравця до його повного появи у світі. Основні властивості: playerRef — екземпляр PlayerRef, що містить UUID, ім'я користувача та мережеву інформацію 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. Розташований у пакеті core messaging, він надає fluent 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. Основні ресурси для подальшого вивчення: Система Entity Component System (ECS) для просунутого управління сутностями Вбудовані модулі: NPC, портали та системи квестів Система візуального скриптингу для ігрової поведінки Мережевий протокол для обробки користувацьких пакетів Пам'ятайте, що в міру просування Hytale через ранній доступ API може розвиватися. Залишайтеся на зв'язку зі спільнотою та стежте за офіційною документацією.