# Hytale Server API Reference (LLM-Optimized) This document is a comprehensive API reference for the Hytale Server modding system, optimized for LLM consumption. All class names, method signatures, and JSON structures are validated against the actual codebase. --- ## PLUGIN SYSTEM ### Core Classes | Class | Package | |-------|---------| | `JavaPlugin` | `com.hypixel.hytale.server.core.plugin.JavaPlugin` | | `PluginBase` | `com.hypixel.hytale.server.core.plugin.PluginBase` | | `PluginManifest` | `com.hypixel.hytale.common.plugin.PluginManifest` | | `JavaPluginInit` | `com.hypixel.hytale.server.core.plugin.JavaPluginInit` | | `PluginState` | `com.hypixel.hytale.server.core.plugin.PluginState` | ### Plugin Lifecycle ``` PluginState: NONE -> SETUP -> START -> ENABLED -> SHUTDOWN -> DISABLED ``` **Lifecycle Methods (exact names):** - `setup()` - Called during initialization, register components here - `start()` - Called after setup, plugin becomes active - `shutdown()` - Called during server stop/plugin disable ### Plugin Manifest JSON (exact field names, case-sensitive) ```json { "Group": "com.example", "Name": "MyPlugin", "Version": "1.0.0", "Description": "Plugin description", "Authors": [{"Name": "Dev", "Email": "dev@example.com", "Url": "https://example.com"}], "Website": "https://example.com", "Main": "com.example.MyPlugin", "ServerVersion": ">=1.0.0", "Dependencies": {"OtherGroup/OtherPlugin": ">=1.0.0"}, "OptionalDependencies": {}, "LoadBefore": {}, "DisabledByDefault": false, "IncludesAssetPack": false, "SubPlugins": [] } ``` ### Registry Methods on PluginBase | Method | Return Type | |--------|-------------| | `getClientFeatureRegistry()` | `ClientFeatureRegistry` | | `getCommandRegistry()` | `CommandRegistry` | | `getEventRegistry()` | `EventRegistry` | | `getBlockStateRegistry()` | `BlockStateRegistry` | | `getEntityRegistry()` | `EntityRegistry` | | `getTaskRegistry()` | `TaskRegistry` | | `getEntityStoreRegistry()` | `ComponentRegistryProxy` | | `getChunkStoreRegistry()` | `ComponentRegistryProxy` | | `getAssetRegistry()` | `AssetRegistry` | ### Configuration Pattern ```java // In constructor (BEFORE setup): Config config = withConfig(MyConfig.CODEC); Config config = withConfig("filename", MyConfig.CODEC); // Access in setup/start: MyConfig cfg = config.get(); ``` --- ## EVENT SYSTEM ### Core Interfaces (Package: `com.hypixel.hytale.event`) | Interface | Description | |-----------|-------------| | `IBaseEvent` | Base event interface | | `IEvent` | Synchronous event, extends IBaseEvent | | `IAsyncEvent` | Async event, extends IBaseEvent | | `ICancellable` | Mixin: `isCancelled()`, `setCancelled(boolean)` | | `IProcessedEvent` | Mixin: `processEvent(String)` | ### EventPriority (exact values) ```java FIRST = (short)-21844 // Runs first EARLY = (short)-10922 NORMAL = (short)0 // Default LATE = (short)10922 LAST = (short)21844 // Runs last ``` ### EventRegistry Methods (IEventRegistry interface) **Sync Registration:** ```java // Without key (Void key) EventRegistration register(Class eventClass, Consumer consumer) EventRegistration register(EventPriority priority, Class eventClass, Consumer consumer) // With key EventRegistration register(Class eventClass, KeyType key, Consumer consumer) EventRegistration register(EventPriority priority, Class eventClass, KeyType key, Consumer consumer) ``` **Global Registration (receives all keys):** ```java EventRegistration registerGlobal(Class eventClass, Consumer consumer) EventRegistration registerGlobal(EventPriority priority, Class eventClass, Consumer consumer) ``` **Unhandled Registration (when no other handler processed):** ```java EventRegistration registerUnhandled(Class eventClass, Consumer consumer) ``` **Async Registration:** ```java EventRegistration registerAsync(Class eventClass, Function, CompletableFuture> function) EventRegistration registerAsyncGlobal(...) EventRegistration registerAsyncUnhandled(...) ``` ### Key Event Classes **Server Events (`com.hypixel.hytale.server.core.event.events`):** - `BootEvent` - IEvent - `ShutdownEvent` - IEvent - `PrepareUniverseEvent` - IEvent **Player Events (`...event.events.player`):** - `PlayerConnectEvent` - IEvent - `PlayerSetupConnectEvent` - IEvent, ICancellable - `PlayerDisconnectEvent` - PlayerRefEvent - `PlayerChatEvent` - IAsyncEvent, ICancellable - `PlayerInteractEvent` - PlayerEvent, ICancellable - `PlayerMouseButtonEvent` - PlayerEvent, ICancellable - `AddPlayerToWorldEvent` - IEvent - `DrainPlayerFromWorldEvent` - IEvent **World Events (`...universe.world.events`):** - `AddWorldEvent` - WorldEvent, ICancellable - `RemoveWorldEvent` - WorldEvent, ICancellable - `StartWorldEvent` - WorldEvent - `AllWorldsLoadedEvent` - IEvent **ECS Events (`...event.events.ecs`):** - `BreakBlockEvent` - CancellableEcsEvent - `PlaceBlockEvent` - CancellableEcsEvent - `UseBlockEvent` - EcsEvent (with nested `Pre` implementing ICancellableEcsEvent) - `DamageBlockEvent` - CancellableEcsEvent - `DropItemEvent` - CancellableEcsEvent --- ## COMMAND SYSTEM ### Core Classes (Package: `com.hypixel.hytale.server.core.command.system`) | Class | Description | |-------|-------------| | `AbstractCommand` | Base command class | | `CommandRegistry` | Plugin command registration | | `CommandContext` | Execution context | | `CommandBase` | Sync command base (override `executeSync`) | | `AbstractAsyncCommand` | Async command base | | `AbstractPlayerCommand` | Player-required command | | `AbstractWorldCommand` | World context command | | `AbstractCommandCollection` | Parent with subcommands only | ### AbstractCommand Key Methods ```java // Constructor protected AbstractCommand(String name, String description) protected AbstractCommand(String name, String description, boolean requiresConfirmation) protected AbstractCommand(String description) // For variants (no name) // Abstract - must implement protected abstract CompletableFuture execute(CommandContext context) // Configuration void requirePermission(String permission) void addAliases(String... aliases) void addSubCommand(AbstractCommand command) void addUsageVariant(AbstractCommand command) // Arguments RequiredArg withRequiredArg(String name, String description, ArgumentType argType) OptionalArg withOptionalArg(String name, String description, ArgumentType argType) DefaultArg withDefaultArg(String name, String description, ArgumentType argType, D defaultValue, String defaultValueDescription) FlagArg withFlagArg(String name, String description) RequiredArg> withListRequiredArg(String name, String description, ArgumentType argType) ``` ### CommandContext Key Methods ```java DataType get(Argument argument) // Get argument value boolean provided(Argument argument) // Check if provided void sendMessage(Message message) // Send to sender boolean isPlayer() // Is sender a player CommandSender sender() // Get sender T senderAs(Class type) // Cast sender Ref senderAsPlayerRef() // Get as player ref ``` ### Built-in ArgTypes (`com.hypixel.hytale.server.core.command.system.arguments.types.ArgTypes`) ```java ArgTypes.BOOLEAN, ArgTypes.INTEGER, ArgTypes.FLOAT, ArgTypes.DOUBLE, ArgTypes.STRING ArgTypes.UUID, ArgTypes.PLAYER_UUID, ArgTypes.PLAYER_REF, ArgTypes.WORLD ArgTypes.RELATIVE_DOUBLE_COORD, ArgTypes.RELATIVE_INT_COORD ArgTypes.RELATIVE_BLOCK_POSITION, ArgTypes.RELATIVE_POSITION ArgTypes.VECTOR2I, ArgTypes.VECTOR3I, ArgTypes.ROTATION, ArgTypes.COLOR ArgTypes.GAME_MODE, ArgTypes.ITEM_ASSET, ArgTypes.BLOCK_TYPE_ASSET ArgTypes.WEATHER_ASSET, ArgTypes.SOUND_EVENT_ASSET, ArgTypes.PARTICLE_SYSTEM ArgTypes.forEnum(String name, Class enumClass) // Create enum type ``` --- ## ENTITY COMPONENT SYSTEM (ECS) ### Core Classes (Package: `com.hypixel.hytale.component`) | Class | Description | |-------|-------------| | `Component` | Base component interface | | `ComponentRegistry` | Component type registration | | `ComponentType` | Registered component type | | `Store` | ECS data storage | | `Ref` | Entity reference (ID) | | `Holder` | Component holder for entity construction | | `Query` | Entity filtering | ### Entity Hierarchy ``` Entity (com.hypixel.hytale.server.core.entity.Entity) └── LivingEntity (com.hypixel.hytale.server.core.entity.LivingEntity) ├── Player (com.hypixel.hytale.server.core.entity.entities.Player) └── NPCEntity (com.hypixel.hytale.server.npc.entities.NPCEntity) ``` ### EntityStore (Package: `com.hypixel.hytale.server.core.universe.world.storage`) ```java public static final ComponentRegistry REGISTRY = new ComponentRegistry<>(); // Registration ComponentType registerComponent(Class tClass, Supplier supplier) ComponentType registerComponent(Class tClass, String id, BuilderCodec codec) void registerSystem(ISystem system) ``` ### Key Built-in Components **Transform/Position:** - `TransformComponent` - Position (Vector3d) and rotation (Vector3f) - `HeadRotation` - Head rotation angles - `EntityScaleComponent` - Scale modifier **Physics:** - `Velocity` - Velocity vector - `BoundingBox` - Collision box - `CollisionResultComponent` - Collision results - `MovementStatesComponent` - Movement flags (onGround, swimming, etc.) **Identity:** - `UUIDComponent` - Unique identifier - `NetworkId` - Network sync ID - `DisplayNameComponent` - Display name **Visual:** - `ModelComponent` - 3D model reference - `ActiveAnimationComponent` - Current animations - `DynamicLight` - Dynamic lighting **State Flags:** - `Invulnerable` - Immune to damage - `Intangible` - Non-collidable - `Interactable` - Can be interacted with - `Frozen` - Frozen state **Player-specific:** - `Player` - Core player component - `PlayerRef` - Network connection reference - `ChunkTracker` - Loaded chunks tracking - `PlayerInput` - Input state ### Working with Components ```java Store store = world.getEntityStore().getStore(); // Get component TransformComponent transform = store.getComponent(entityRef, TransformComponent.getComponentType()); // Add/Put component store.addComponent(entityRef, ComponentType, component); store.putComponent(entityRef, ComponentType, component); // Add or replace // Remove component store.removeComponent(entityRef, ComponentType); // Create entity Holder holder = EntityStore.REGISTRY.newHolder(); holder.addComponent(TransformComponent.getComponentType(), new TransformComponent(pos, rot)); Ref ref = store.addEntity(holder, AddReason.SPAWN); ``` --- ## UI SYSTEM ### Page System Classes | Class | Package | |-------|---------| | `CustomUIPage` | `com.hypixel.hytale.server.core.entity.entities.player.pages.CustomUIPage` | | `BasicCustomUIPage` | Same package - no event data parsing | | `InteractiveCustomUIPage` | Same package - typed event handling | | `PageManager` | Same package - page lifecycle | | `UICommandBuilder` | `com.hypixel.hytale.server.core.ui.builder.UICommandBuilder` | | `UIEventBuilder` | `com.hypixel.hytale.server.core.ui.builder.UIEventBuilder` | ### CustomPageLifetime ```java CantClose(0) // Cannot be closed CanDismiss(1) // ESC to close CanDismissOrCloseThroughInteraction(2) // ESC or interaction ``` ### UICommandBuilder Methods ```java // Load documents void append(String documentPath) void append(String selector, String documentPath) void appendInline(String selector, String xmlContent) void insertBefore(String selector, String documentPath) // Manipulate DOM void clear(String selector) void remove(String selector) void set(String selector, String value) void set(String selector, int value) void set(String selector, float value) void set(String selector, boolean value) void set(String selector, Message value) void set(String selector, Value ref) void setObject(String selector, Object data) void set(String selector, T[] data) void set(String selector, List data) ``` ### CustomUIEventBindingType ```java Activating(0), RightClicking(1), DoubleClicking(2) MouseEntered(3), MouseExited(4), ValueChanged(5) ElementReordered(6), Validating(7), Dismissing(8) FocusGained(9), FocusLost(10), KeyDown(11) MouseButtonReleased(12), SlotClicking(13), SlotDoubleClicking(14) SlotMouseEntered(15), SlotMouseExited(16), DragCancelled(17) Dropped(18), SlotMouseDragCompleted(19), SlotMouseDragExited(20) SlotClickReleaseWhileDragging(21), SlotClickPressWhileDragging(22) SelectedTabChanged(23) ``` ### UIEventBuilder Methods ```java void addEventBinding(CustomUIEventBindingType type, String selector) void addEventBinding(CustomUIEventBindingType type, String selector, boolean locksInterface) void addEventBinding(CustomUIEventBindingType type, String selector, EventData data) void addEventBinding(CustomUIEventBindingType type, String selector, EventData data, boolean locksInterface) ``` ### EventData ```java EventData.of("Key", "Value") new EventData().append("Key", "Value").append("@ElementValue", "#Element.Property") // @ prefix = extract value from element ``` ### Value References ```java Value.of(directValue) // Direct value Value.ref("Document.ui", "ValueName") // Reference from UI document ``` ### Page Example ```java public class MyPage extends InteractiveCustomUIPage { public MyPage(PlayerRef playerRef) { super(playerRef, CustomPageLifetime.CanDismiss, Data.CODEC); } @Override public void build(Ref ref, UICommandBuilder cmd, UIEventBuilder events, Store store) { cmd.append("Pages/MyPage.ui"); cmd.set("#Title.Text", "Hello"); events.addEventBinding(CustomUIEventBindingType.Activating, "#Button", EventData.of("Action", "Click")); } @Override public void handleDataEvent(Ref ref, Store store, Data data) { if ("Click".equals(data.action)) { close(); } } public static class Data { public static final BuilderCodec CODEC = BuilderCodec.builder(Data.class, Data::new) .addField(new KeyedCodec<>("Action", Codec.STRING), (d,v) -> d.action = v, d -> d.action) .build(); String action; } } // Open page: player.getPageManager().openCustomPage(ref, store, new MyPage(playerRef)); ``` ### Window System | Class | Package | |-------|---------| | `Window` | `com.hypixel.hytale.server.core.entity.entities.player.windows.Window` | | `WindowManager` | Same package | | `ContainerWindow`, `CraftingWindow`, etc. | Same package | ### WindowType ```java Container(0), PocketCrafting(1), BasicCrafting(2) DiagramCrafting(3), StructuralCrafting(4), Processing(5), Memories(6) ``` --- ## CODEC SYSTEM ### Core Classes (Package: `com.hypixel.hytale.codec`) | Class | Description | |-------|-------------| | `Codec` | Base codec interface | | `BuilderCodec` | Builder-based codec | | `KeyedCodec` | Key-value codec | ### Primitive Codecs ```java Codec.STRING, Codec.BOOLEAN, Codec.INTEGER, Codec.LONG Codec.FLOAT, Codec.DOUBLE, Codec.BYTE_ARRAY ``` ### Collection Codecs ```java Codec.STRING.listOf() // List Codec.STRING.setOf() // Set Codec.mapOf(Codec.STRING, Codec.INTEGER) // Map Codec.arrayOf(Codec.STRING, String[]::new) // String[] ``` ### BuilderCodec Pattern ```java public static final BuilderCodec CODEC = BuilderCodec.of(MyClass::new) .with("fieldName", Codec.STRING, c -> c.field) // Required .with("fieldName", Codec.STRING, c -> c.field, "default") // With default .withOptional("fieldName", Codec.STRING, c -> c.field) // Optional .build(); ``` ### Codec Transformations ```java Codec UUID_CODEC = Codec.STRING.xmap(UUID::fromString, UUID::toString); Codec PORT = Codec.INTEGER.validate(p -> p > 0 && p < 65536, "Invalid port"); Codec VOLUME = Codec.FLOAT.clamp(0.0f, 1.0f); Codec ENUM = Codec.enumCodec(MyEnum.class); ``` --- ## ASSET SYSTEM ### Core Classes | Class | Package | |-------|---------| | `JsonAsset` | `com.hypixel.hytale.assetstore.JsonAsset` | | `AssetStore` | `com.hypixel.hytale.assetstore.AssetStore` | | `AssetRegistry` | `com.hypixel.hytale.server.core.plugin.AssetRegistry` | ### Key Asset Types (Package: `com.hypixel.hytale.server.core.asset.type`) **Blocks:** - `BlockType` - blocktype.config.BlockType - `BlockSet` - blockset.config.BlockSet - `BlockSoundSet` - blocksound.config.BlockSoundSet **Items:** - `Item` - item.config.Item - `ItemCategory` - item.config.ItemCategory - `CraftingRecipe` - item.config.CraftingRecipe **Visual:** - `ModelAsset` - model.config.ModelAsset - `ParticleSystem` - particle.config.ParticleSystem - `EntityEffect` - entityeffect.config.EntityEffect **Audio:** - `SoundEvent` - soundevent.config.SoundEvent - `SoundSet` - soundset.config.SoundSet **Environment:** - `Environment` - environment.config.Environment - `Weather` - weather.config.Weather - `Fluid` - fluid.Fluid **Gameplay:** - `Projectile` - projectile.config.Projectile - `GameplayConfig` - gameplay.GameplayConfig ### Asset JSON Structure Pattern ```json { "Id": "namespace:asset_id", "Parent": "namespace:parent_id", "Type": "ConcreteType", ...fields } ``` --- ## WORLD MANAGEMENT ### Core Classes | Class | Package | |-------|---------| | `Universe` | `com.hypixel.hytale.server.core.universe.Universe` | | `World` | `com.hypixel.hytale.server.core.universe.world.World` | | `EntityStore` | `com.hypixel.hytale.server.core.universe.world.storage.EntityStore` | | `ChunkStore` | `com.hypixel.hytale.server.core.universe.world.storage.ChunkStore` | ### Universe Access ```java Universe universe = Universe.get(); Collection worlds = universe.getWorlds(); World world = universe.getWorld("worldName"); Collection players = universe.getPlayers(); Player player = universe.getPlayer("name"); Player player = universe.getPlayer(uuid); ``` ### World Access ```java String name = world.getName(); EntityStore entityStore = world.getEntityStore(); Store store = entityStore.getStore(); long tick = world.getTick(); boolean paused = world.isPaused(); ``` --- ## NPC/AI SYSTEM ### Core Classes (Package: `com.hypixel.hytale.server.npc`) | Class | Description | |-------|-------------| | `NPCEntity` | entities.NPCEntity - NPC entity class | | `Role` | role.Role - Behavior definition | | `Instruction` | instructions.Instruction - Behavior action | | `PathManager` | navigation.PathManager - Pathfinding | ### NPCEntity Key Methods ```java Role getRole() void setRole(Role role) String getRoleName() void setRoleName(String name) PathManager getPathManager() void playAnimation(...) ``` ### Flock System (Package: `com.hypixel.hytale.server.flock`) | Component | Description | |-----------|-------------| | `Flock` | Flock leader/group | | `FlockMembership` | Entity's flock membership | --- ## NETWORKING ### Packet System (Package: `com.hypixel.hytale.protocol`) | Class | Description | |-------|-------------| | `Packet` | Base packet interface | | `PacketRegistry` | Packet type registration | ### Key Packet Categories (`protocol.packets.*`) - `connection/` - Connect, disconnect, ping - `auth/` - Authentication - `player/` - Player state - `entities/` - Entity sync - `world/` - Chunk/block data - `inventory/` - Inventory ops - `interface_/` - UI packets - `window/` - Window packets ### UI Packets | Packet | ID | Direction | |--------|-----|-----------| | `SetPage` | 216 | S->C | | `CustomHud` | 217 | S->C | | `CustomPage` | 218 | S->C | | `CustomPageEvent` | 219 | C->S | ### Window Packets | Packet | ID | Direction | |--------|-----|-----------| | `OpenWindow` | 200 | S->C | | `UpdateWindow` | 201 | S->C | | `CloseWindow` | 202 | S->C | | `ClientOpenWindow` | 203 | C->S | | `SendWindowAction` | 204 | C->S | --- ## MATH UTILITIES (Package: `com.hypixel.hytale.math`) ### Vector Types ```java Vector3d // 3D double precision Vector3f // 3D float precision Vector3i // 3D integer Vector2d // 2D double Vector2i // 2D integer ``` ### Vector Operations ```java Vector3d a = new Vector3d(x, y, z); a.add(b), a.subtract(b), a.multiply(scalar) a.dot(b), a.cross(b), a.length(), a.normalize() a.distance(b) ``` ### Shapes ```java Box, Ellipsoid, Cylinder Transform, Location ``` --- ## COMMON UTILITIES (Package: `com.hypixel.hytale.common`) ### Utility Classes ```java StringUtil, ArrayUtil, ListUtil, MapUtil TimeUtil, FormatUtil, MathUtil, TrigMathUtil Semver, SemverRange WeightedMap // Weighted random selection ``` --- ## EARLY PLUGIN SYSTEM ### ClassTransformer Interface (Package: `com.hypixel.hytale.plugin.early`) ```java public interface ClassTransformer { int priority(); // Higher = loaded first byte[] transform(String className, String transformedName, byte[] classBytes); } ``` ### Service Registration Create `META-INF/services/com.hypixel.hytale.plugin.early.ClassTransformer` containing transformer class name. Place JAR in `earlyplugins/` directory. --- ## COMPLETE COMPONENT LIST ### EntityStore Components (130+) **Transform:** TransformComponent, HeadRotation, PositionDataComponent, EntityScaleComponent, RotateObjectComponent, SnapshotBuffer **Physics:** Velocity, PhysicsValues, BoundingBox, CollisionResultComponent, KnockbackComponent, MovementStatesComponent, HitboxCollision, Repulsion **Player:** Player, MovementManager, CameraManager, ChunkTracker, PlayerInput, PlayerSettings, PlayerSkinComponent, PlayerRef **NPC:** NPCEntity, ValueStore, StateEvaluator, StepComponent, Timers, FailedSpawnComponent **Combat:** DamageDataComponent, DeathComponent, DeferredCorpseRemoval, CombatActionEvaluator, TargetMemory, DamageMemory **Visual:** ModelComponent, PersistentModel, PropComponent, DisplayNameComponent, ActiveAnimationComponent, DynamicLight, Nameplate **Audio:** AudioComponent, MovementAudioComponent **Identity:** UUIDComponent, NetworkId, EntityViewer, Visible, PersistentRefCount **State Flags:** Frozen, Intangible, Invulnerable, Interactable, RespondToHit, HiddenFromAdventurePlayers, NewSpawnComponent, FromPrefab, FromWorldGen, DespawnComponent **Teleport:** Teleport, PendingTeleport, TeleportHistory, WarpComponent **Projectile:** ProjectileComponent, Projectile, PredictedProjectile **Item:** ItemComponent, ItemPhysicsComponent, PickupItemComponent, PreventPickup, PreventItemMerging **Mount:** MountedComponent, MountedByComponent, NPCMountComponent, MinecartComponent **Deployable:** DeployableComponent, DeployableOwnerComponent, DeployableProjectileShooterComponent **Spawning:** SpawnMarkerEntity, LocalSpawnController, LocalSpawnBeacon, SpawnSuppressionComponent **Flock:** Flock, FlockMembership, PersistentFlockData **Effects:** EffectControllerComponent **Stats:** EntityStatMap ### ChunkStore Components (25+) **Structure:** BlockChunk, BlockComponentChunk, EntityChunk, ChunkColumn, ChunkSection, BlockSection, FluidSection, EnvironmentChunk **Block State:** BlockState, RespawnBlock, LaunchPad, BlockMapMarker **Physics:** BlockPhysics, BlockHealthChunk **Farming:** FarmingBlock, FarmingBlockState, TilledSoilBlock, CoopBlock **Instance:** InstanceBlock, ConfigurableInstanceBlock **Portal:** PortalDevice **Spawning:** BlockSpawner, ChunkSuppressionEntry, ChunkSpawnedNPCData, ChunkSpawnData