Справочник по 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 может развиваться. Оставайтесь на связи с сообществом и следите за официальной документацией по мере её обновления.