Code Patterns

/add command using AbstractAsyncCommand

Create async commands that open custom GUIs. Use CompletableFuture.runAsync with world executor.

Pattern for async commands that need to access the world/ECS. Based on working AdminUI code.

/autosave command using AbstractCommand

/changeworld command using CommandBase

/admin command using AbstractAsyncCommand

Control who can use commands with setPermissionGroup() using GameMode enum.

Use various argument types: STRING, INTEGER, DOUBLE, BOOLEAN, PLAYER_REF, WORLD, ITEM_ASSET, BLOCK_TYPE_KEY, GAME_MODE, etc.

Create a command with required and optional arguments using ArgTypes.

Useful helper methods on CommandContext for player commands.

/config command using AbstractCommand

/debug command using AbstractCommand

/test command using CommandBase

/finish command using AbstractAsyncCommand

/hidepois command using AbstractCommand

/hidewarps command using AbstractCommand

/hideplayers command using AbstractCommand

/hideunexploredpoi command using AbstractCommand

/hideunexploredwarps command using AbstractCommand

/loot command using AbstractCommand

/show command using AbstractAsyncCommand

/spawn command using AbstractCommand

/map command using AbstractCommand

/radius command using AbstractCommand

/maxscale command using AbstractCommand

/minscale command using AbstractCommand

/quality command using AbstractCommand

/vote command using CommandBase

/markerteleport command using AbstractCommand

/maxchunks command using AbstractCommand

/memory command using CommandBase

/menu command using AbstractPlayerCommand

Create a command that requires a player context. Extends AbstractPlayerCommand for automatic ECS parameter injection.

/location command using AbstractCommand

/maxscale command using AbstractCommand

/minscale command using AbstractCommand

/radarrange command using AbstractCommand

/radar command using AbstractCommand

Register a command in the plugin setup() method.

/reload command using AbstractCommand

/shareallexploration command using AbstractCommand

/shop command using CommandBase

/adminshortcut command using AbstractAsyncCommand

/show command using AbstractAsyncCommand

Create a simple command using AbstractCommand. Best for server-wide commands or when you dont need ECS/player access. Supports async execution via CompletableFuture.

/spawn command using AbstractCommand

/spectator command using CommandBase

Create a synchronous command using CommandBase. Runs on main thread, good for simple commands that need immediate world access.

Enable/disable player flight using MovementManager and MovementSettings. Based on working Simple Fly mod by davidhenk.

/track command using AbstractCommand

/t command using AbstractAsyncCommand

/untrack command using AbstractCommand

/add command using AbstractPlayerCommand

/waypoint command using AbstractCommand

/remove command using AbstractPlayerCommand

/removeglobal command using AbstractPlayerCommand

/id command using AbstractPlayerCommand

/list command using AbstractPlayerCommand

/waypointteleport command using AbstractCommand

/update command using AbstractPlayerCommand

Listen for and modify damage events.

Make an entity immune to damage using Invulnerable component.

Archetypes group entities with the same component signature for cache-efficient iteration. Entities with components [A,B] are stored together, separate from [A,B,C]. This enables fast system processing.

EntityEventSystem implementation

Efficiently iterate over all entities with a specific component using forEachChunk for cache-friendly access.

ComponentType<T> provides type-safe access to components. Every component class has a static getComponentType() method that returns its ComponentType for Store operations.

Custom EntityStore component

Create custom ECS components with data and clone support.

Define custom ECS components with proper clone support and optional serialization.

Handle ECS events like crafting, block breaking, damage using EntityEventSystem.

Entity Component System (ECS) architecture overview for Hytale modding. ECS separates data (Components) from logic (Systems), with Entities being just IDs that group components together.

Understanding why Hytale uses ECS instead of traditional OOP. ECS avoids inheritance problems and enables better performance through data-oriented design.

Create new entities using Holder blueprint pattern. Collect all components first, then add to store.

EntityTickingSystem processes entities every tick (frame). It receives an index into an ArchetypeChunk for efficient iteration. Use for per-entity per-frame logic like movement, AI, or HUD updates.

Custom EntityStore component

RefSystem implementation

Holder<EntityStore> wraps an entity reference with convenient component access methods. Created from ArchetypeChunk index using EntityUtils.toHolder().

EntityTickingSystem implementation

EntityTickingSystem implementation

Custom EntityStore component

Create marker components (boolean flags) using singleton pattern for entities without data.

EntityEventSystem implementation

Custom EntityStore component

EntityTickingSystem implementation

Always validate entity references before use since entities can be deleted at any time.

React to entity creation and removal events.

The Store<EntityStore> and Ref<EntityStore> pattern is the core way to access entity components in Hytale ECS. Store is your accessor, Ref identifies which entity.

Create systems that run every game tick with query filtering.

Hytale world structure: Universe contains multiple Worlds, each World has an EntityStore. The Universe represents the entire game session, Worlds are individual dimensions/areas.

Apply a buff/debuff effect to an entity using EffectControllerComponent.

Heal a player to full health and stamina using EntityStatsModule. Based on working AdminUI code.

Kill a player using the damage system.

Spawn custom entities in the world with model and components.

Stop entity movement instantly when collision is detected using ApplyForce interaction. Use Force: 0.01 with ChangeVelocityType: Set to zero out velocity.

Create custom styled buttons in native .ui files with different colors for default, hovered, and pressed states.

Create custom UI pages by extending InteractiveCustomUIPage. Define data codec for event handling.

InteractiveCustomUIPage implementation

Official Hytale UI: ArgumentTypeItem with text elements

Official Hytale UI: BarterGridSpacer

Official Hytale UI: BarterPage - Container layout with buttons with text elements

Official Hytale UI: BarterTradeRow - Container layout with buttons with text elements

Official Hytale UI: BasicTextButton with buttons with text elements

Official Hytale UI: BulletPoint with text elements

Official Hytale UI: ChangeModelPage - Container layout with buttons with text elements

Official Hytale UI: ChestMarker - Container layout with text elements

Official Hytale UI: CommandListPage - Container layout with buttons with text elements

Official Hytale UI: ConfigureInstanceBlockPage - Container layout with buttons with text elements

Official Hytale UI: DroppedItemSlot with text elements

Official Hytale UI: EntitySpawnPage - Container layout with buttons with text elements with item grid

Official Hytale UI: ImageImportPage - Container layout with buttons with text elements

Official Hytale UI: InstanceListPage - Container layout with buttons with text elements

Official Hytale UI: ItemRepairElement with buttons with text elements

Official Hytale UI: ItemRepairPage - Container layout with buttons with text elements

Official Hytale UI: LaunchPadSettingsPage - Container layout with buttons with text elements

Official Hytale UI: MemoriesCategory with buttons with text elements

Official Hytale UI: MemoriesCategoryPanel - Container layout with buttons with text elements

Official Hytale UI: MemoriesPanel - Container layout with buttons with text elements

Official Hytale UI: MemoriesUnlocked with buttons with text elements

Official Hytale UI: Memory with buttons with text elements

Official Hytale UI: NameRespawnPointPage - Container layout with buttons with text elements

Official Hytale UI: ObjImportPage - Container layout with buttons with text elements

Official Hytale UI: OverrideNearbyRespawnPointPage - Container layout with buttons with text elements

Official Hytale UI: OverrideRespawnPointButton with buttons with text elements

Official Hytale UI: ParameterItem with text elements

Official Hytale UI: ParticleSpawnPage - Container layout with buttons with text elements

Official Hytale UI: Pill with text elements

Official Hytale UI: PlaySoundPage - Container layout with buttons with text elements

Official Hytale UI: PluginListButton with buttons with text elements

Official Hytale UI: PluginListPage - Container layout with buttons with text elements

Official Hytale UI: PortalDeviceActive - Container layout with buttons with text elements

Official Hytale UI: PortalDeviceError - Container layout with buttons with text elements

Official Hytale UI: PortalDeviceSummon - Container layout with buttons with text elements

Official Hytale UI: Portals with text elements

Official Hytale UI: PrefabBrowser with text elements

Official Hytale UI: PrefabEditorExitConfirm - Container layout with buttons with text elements

Official Hytale UI: PrefabEditorSaveSettings - Container layout with buttons with text elements

Official Hytale UI: PrefabEditorSettings - Container layout with buttons with text elements

Official Hytale UI: PrefabListPage - Container layout with buttons with text elements

Official Hytale UI: PrefabSavePage - Container layout with buttons with text elements

Official Hytale UI: PrefabSpawnerSettingsPage - Container layout with buttons with text elements

Official Hytale UI: PrefabTeleportPage - Container layout with buttons with text elements

Official Hytale UI: RespawnPage - Container layout with buttons with text elements

Official Hytale UI: ScriptedBrushListPage - Container layout with buttons with text elements

Official Hytale UI: SelectOverrideRespawnPointPage - Container layout with buttons with text elements

Official Hytale UI: ShopElementButton with buttons

Official Hytale UI: ShopPage - Container layout with buttons with text elements

Official Hytale UI: SubcommandCard with buttons with text elements

Official Hytale UI: Teleporter - Container layout with buttons with text elements

Official Hytale UI: TintChunkPage - Container layout with buttons with text elements

Official Hytale UI: VariantCard with buttons with text elements

Official Hytale UI: WarpEntryButton with buttons with text elements

Official Hytale UI: WarpListPage - Container layout with buttons with text elements

InteractiveCustomUIPage implementation

CustomUIHud implementation

InteractiveCustomUIPage implementation

InteractiveCustomUIPage implementation

Set up native .ui files for custom UI pages. Files must be in Common/UI/Custom/Pages/ in JAR but referenced as Pages/ in Java code. Requires IncludesAssetPack in manifest.

CustomUIHud implementation

InteractiveCustomUIPage implementation

BasicCustomUIPage implementation

InteractiveCustomUIPage implementation

InteractiveCustomUIPage implementation

InteractiveCustomUIPage implementation

Reference built-in Hytale UI components from Common.ui in your custom .ui files.

Create dropdown menus in custom UI with selectable options.

Style labels in native .ui files with custom fonts, colors, and alignment.

InteractiveCustomUIPage implementation

InteractiveCustomUIPage implementation

InteractiveCustomUIPage implementation

Per-player configurable actions for custom item interactions

Create custom item interactions by extending SimpleInteraction. Register with codec registry.

Give an item to a player inventory.

Add, remove, and manage items in player inventory using ItemStack and ItemContainer.

Open different inventory pages/UIs for players using PageManager.

Open another player's inventory for viewing/editing.

Server backup management with configuration and manual trigger

Timed mute system with JSON persistence. Automatically cleans up expired mutes.

Manage server whitelist via HytaleWhitelistProvider with GUI controls

Define permissions as an enum for type-safe permission management.

Check, grant, and revoke permissions using PermissionsModule.

Ban a player using the built-in ban provider.

Format chat messages using PlayerChatEvent and Message builder.

Get a player's network latency/ping.

Get the current position of a player using the TransformComponent.

Disconnect a player from the server.

Correct way to create and combine messages using Message.raw(), .color(), .bold() and Message.join().

Look up player profile by username, checking online players first then auth service

Send colored messages to players using Hytale Message API. Use .color() with Color constants or hex strings like "#RRGGBB". Do NOT use Minecraft § color codes - they do not work in Hytale!

Change a player's game mode.

Configure manifest.json to include custom UI files and other assets from the plugin JAR.

Use HytaleLogger for structured logging with levels (info, warn, error).

Main plugin class extending JavaPlugin with constructor and setup method.

Schedule repeating tasks using HytaleServer.SCHEDULED_EXECUTOR.

Persist data to JSON files using BlockingDiskFile. Thread-safe with built-in file locking.

Simple single-object JSON configuration storage (not array-based)

Teleport a player to specific coordinates using the ECS Teleport component.

Teleport a player to specific coordinates using TransformComponent.

Use the built-in warp system to create and teleport to warps.

Use java.awt.Color for message colors. Available constants: RED, GREEN, BLUE, YELLOW, CYAN (not AQUA!), MAGENTA, WHITE, BLACK, GRAY, DARK_GRAY, LIGHT_GRAY, ORANGE, PINK.

Official Hytale UI: ActionButton - Container layout with buttons with text elements

Official Hytale UI: Common - Container layout with buttons with text elements

Official Hytale UI: Sounds with buttons

Official Hytale UI: TextButton with buttons with text elements

Official Hytale UI: TimeLeft

Helper for setting up navigation bar in custom UI pages with permission-filtered entries

Play sounds to players using SoundUtil.

Send item pickup-style notifications to players.

Display server statistics (CPU, RAM, uptime) in custom UI with auto-refresh

Searchable list UI with delete confirmation on hover pattern

Singleton registry for registering UI pages with navigation bar and command shortcuts

Simplest Custom UI Page pattern using BasicCustomUIPage. Use this for static, non-interactive UI displays that just show information without any buttons or inputs.

Define reusable button styles with hover and pressed states using TextButtonStyle. Styles are defined at the top of .ui files with @ prefix and referenced in TextButton elements.

Color formats and common styling properties for Hytale UI elements. Colors use hex format with optional alpha. Style properties control text appearance, alignment, and formatting.

Two-panel layout with sidebar navigation and main content area. Uses LayoutMode: Left for horizontal arrangement and FlexWeight for flexible sizing. Great for settings pages, dashboards, or info panels.

Pattern for passing dynamic data from Java to UI elements using cmd.set(). Pass data through constructor, store as fields, then use cmd.set("#ElementId.Property", value) in build() method.

Different event binding types for UI interactions. Activating is most common (button clicks), but other types exist for hover, focus changes, and value changes.

Form pattern with TextField, NumberField, and CheckBox inputs. Shows how to read input values using the @-prefix in EventData codec and binding input values to events.

Dialog pattern using InteractiveCustomUIPage with button click event handling. Demonstrates event binding, dynamic text setting with cmd.set(), and closing the page programmatically.

Understanding LayoutMode options for arranging child elements. Top = vertical stack, Left = horizontal row, Center = centered, Right = right-aligned. Combine with FlexWeight for responsive layouts.

CustomPageLifetime options control when and how a UI page can be closed. Choose based on whether the UI should be dismissible by ESC key, clicking outside, or only through explicit code.

Common API mistakes and their corrections. Read this before writing Hytale plugins!

Thread-safe singleton pattern for managing player data with ConcurrentHashMap.

Parse human-readable duration strings like "1d 2h 30m 15s" into milliseconds

Define crafting recipes as JSON data assets. Place in src/main/resources/Server/Item/Recipes/

Access private fields via reflection