Hytale Server API Reference: Events, Messages, and Plugin Development Guide

Understanding the Hytale Server Architecture The Hytale server API is built on a robust Java-based architecture that will feel familiar to anyone who has worked with Minecraft server plugins. With the return to the Legacy Engine, developers now have access to a mature, well-tested codebase that prioritizes modding accessibility over cross-platform complexity. At the heart of the server sits the com.hypixel.hytale.server.core package, which provides the foundation for all server-side operations. This includes player management, world handling, event dispatching, and command processing. Player Connection Events: Handling Join and Leave One of the most common requirements for any server plugin is responding to players joining or leaving. The Hytale API provides two essential events for this purpose. PlayerConnectEvent Fired when a player successfully connects to the server, this event gives you access to the player reference before they fully spawn into the world. Key properties include: playerRef - The PlayerRef instance containing UUID, username, and network info player - The Player entity that will represent them in the world world - The World instance they are joining holder - The entity store holder for component access Unlike some other events, PlayerConnectEvent is not cancellable. If you need to prevent a player from joining, you should handle this at the authentication layer instead. 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 Triggered when a player leaves the server, this event includes important context about why they disconnected: playerRef - The departing player's reference disconnectReason - Enum indicating timeout, kick, quit, or server shutdown This event is also non-cancellable since the disconnection has already occurred at the network level. The Message Class: Rich Text Formatting Server owners looking to create polished chat experiences will spend significant time with the Message class. Located in the core messaging package, it provides a fluent API for building formatted text. Basic Message Creation // 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) Parameter Substitution For dynamic content, use parameter placeholders: val welcome = Message.raw("Welcome, {name}! You have {coins} coins.") .param("name", player.username) .param("coins", playerData.coinBalance.toString()) Clickable Links Messages can include clickable hyperlinks: val linked = Message.raw("Click here to visit our website") .link("https://example.com") Event Registration Patterns The Hytale event system supports both synchronous and asynchronous event handling, giving developers flexibility based on their performance requirements. Synchronous Registration For events that need immediate processing on the server thread: eventRegistry.register(PlayerInteractEvent::class.java) { event -> if (event.actionType == ActionType.RIGHT_CLICK) { // Process the interaction event.setCancelled(true) } } Asynchronous Registration For events that can be processed off the main thread (like chat moderation): eventRegistry.registerAsync(PlayerChatEvent::class.java) { future -> future.thenApply { event -> // Perform async chat filtering if (containsBannedWords(event.content)) { event.setCancelled(true) } event } } Common Event Reference Table Here's a quick reference for the most frequently used events in server development: Event NameCancellableKey Properties PlayerConnectEventNoplayerRef, player, world, holder PlayerDisconnectEventNoplayerRef, disconnectReason PlayerChatEventYes (Async)sender, targets, content, formatter PlayerInteractEventYesplayer, actionType, itemInHand, targetBlock, targetEntity PlayerDeathEventNoplayer PlayerRespawnEventNoplayer BreakBlockEventYesitemInHand, targetBlock, blockType PlaceBlockEventYesitemInHand, targetBlock, rotation DamageBlockEventYesitemInHand, targetBlock, currentDamage, damage DropItemEventYesitem, location CraftRecipeEventYescraftedRecipe, quantity Building Custom Commands The command system allows you to register slash commands that players can execute in chat. Basic Command Implementation 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()) Using the CommandManager You can also programmatically execute commands: val commandManager = CommandManager.get() commandManager.handleCommand(sender, "time day") Plugin Lifecycle and Structure Every Hytale server plugin extends the JavaPlugin base class, which provides essential registries and lifecycle hooks. Plugin Lifecycle Phases Construction - Plugin class instantiation PreLoad - Async initialization before server start Setup - Register components, events, and commands Start - Server is ready to accept players Shutdown - Cleanup before server stops Key Plugin Properties // 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 Configuration Helper Plugins can easily load JSON configuration files: // Using default config.json val config: Config<MyConfigClass> = withConfig(MyConfigClass.CODEC) // Using custom filename val config: Config<MyConfigClass> = withConfig("custom-name.json", MyConfigClass.CODEC) Working with Players The PlayerRef class is your primary interface for interacting with connected players. Player Identity and Location 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 Entity Access For deeper interactions like inventory management, access the Player entity: 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") World and Universe Management The Universe singleton provides access to all worlds and connected players. 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") Thread Safety Warning Component access must occur on the world thread. Always wrap operations in the execute block: world.execute { // Safe component access here val entities = world.getEntities() } Next Steps for Server Developers With this API reference as your foundation, you're ready to start building Hytale server plugins. Key resources to explore next: The Entity Component System (ECS) for advanced entity manipulation Built-in modules like NPCs, Portals, and Quest systems The visual scripting system for game behaviors Network protocol for custom packet handling Remember that as Hytale moves through Early Access, the API may evolve. Stay connected with the community and official documentation as it develops.