hytale/hytale-server
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update documentation; patch ChangeActiveSlotInteraction

Browse Source
This commit is contained in:
luk
2026-02-03 16:44:06 +00:00
parent f8d7b9a781
commit 49a80ebf77
16 changed files with 531 additions and 472 deletions
Download Patch File Download Diff File Expand all files Collapse all files

237
docs/00-llm-reference.md
View File

@@ -1,6 +1,7 @@
# 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.
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.
---
@@ -8,13 +9,13 @@ This document is a comprehensive API reference for the Hytale Server modding sys
### 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` |
| 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` |
| `PluginState` | `com.hypixel.hytale.server.core.plugin.PluginState` |
### Plugin Lifecycle
@@ -23,8 +24,9 @@ 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
- `start()` - Called after setup, plugin becomes active
- `shutdown()` - Called during server stop/plugin disable
### Plugin Manifest JSON (exact field names, case-sensitive)
@@ -50,17 +52,17 @@ PluginState: NONE -> SETUP -> START -> ENABLED -> SHUTDOWN -> DISABLED
### Registry Methods on PluginBase
| Method | Return Type |
|--------|-------------|
| `getClientFeatureRegistry()` | `ClientFeatureRegistry` |
| `getCommandRegistry()` | `CommandRegistry` |
| `getEventRegistry()` | `EventRegistry` |
| `getBlockStateRegistry()` | `BlockStateRegistry` |
| `getEntityRegistry()` | `EntityRegistry` |
| `getTaskRegistry()` | `TaskRegistry` |
| `getEntityStoreRegistry()` | `ComponentRegistryProxy<EntityStore>` |
| `getChunkStoreRegistry()` | `ComponentRegistryProxy<ChunkStore>` |
| `getAssetRegistry()` | `AssetRegistry` |
| Method | Return Type |
|------------------------------|---------------------------------------|
| `getClientFeatureRegistry()` | `ClientFeatureRegistry` |
| `getCommandRegistry()` | `CommandRegistry` |
| `getEventRegistry()` | `EventRegistry` |
| `getBlockStateRegistry()` | `BlockStateRegistry` |
| `getEntityRegistry()` | `EntityRegistry` |
| `getTaskRegistry()` | `TaskRegistry` |
| `getEntityStoreRegistry()` | `ComponentRegistryProxy<EntityStore>` |
| `getChunkStoreRegistry()` | `ComponentRegistryProxy<ChunkStore>` |
| `getAssetRegistry()` | `AssetRegistry` |
### Configuration Pattern
@@ -79,13 +81,13 @@ MyConfig cfg = config.get();
### Core Interfaces (Package: `com.hypixel.hytale.event`)
| Interface | Description |
|-----------|-------------|
| `IBaseEvent<KeyType>` | Base event interface |
| `IEvent<KeyType>` | Synchronous event, extends IBaseEvent |
| `IAsyncEvent<KeyType>` | Async event, extends IBaseEvent |
| `ICancellable` | Mixin: `isCancelled()`, `setCancelled(boolean)` |
| `IProcessedEvent` | Mixin: `processEvent(String)` |
| Interface | Description |
|------------------------|-------------------------------------------------|
| `IBaseEvent<KeyType>` | Base event interface |
| `IEvent<KeyType>` | Synchronous event, extends IBaseEvent |
| `IAsyncEvent<KeyType>` | Async event, extends IBaseEvent |
| `ICancellable` | Mixin: `isCancelled()`, `setCancelled(boolean)` |
| `IProcessedEvent` | Mixin: `processEvent(String)` |
### EventPriority (exact values)
@@ -100,6 +102,7 @@ LAST = (short)21844 // Runs last
### EventRegistry Methods (IEventRegistry interface)
**Sync Registration:**
```java
// Without key (Void key)
EventRegistration register(Class<? super EventType> eventClass, Consumer<EventType> consumer)
@@ -111,17 +114,20 @@ EventRegistration register(EventPriority priority, Class<? super EventType> even
```
**Global Registration (receives all keys):**
```java
EventRegistration registerGlobal(Class<? super EventType> eventClass, Consumer<EventType> consumer)
EventRegistration registerGlobal(EventPriority priority, Class<? super EventType> eventClass, Consumer<EventType> consumer)
```
**Unhandled Registration (when no other handler processed):**
```java
EventRegistration registerUnhandled(Class<? super EventType> eventClass, Consumer<EventType> consumer)
```
**Async Registration:**
```java
EventRegistration registerAsync(Class<? super EventType> eventClass, Function<CompletableFuture<EventType>, CompletableFuture<EventType>> function)
EventRegistration registerAsyncGlobal(...)
@@ -131,11 +137,13 @@ EventRegistration registerAsyncUnhandled(...)
### Key Event Classes
**Server Events (`com.hypixel.hytale.server.core.event.events`):**
- `BootEvent` - IEvent<Void>
- `ShutdownEvent` - IEvent<Void>
- `PrepareUniverseEvent` - IEvent<Void>
**Player Events (`...event.events.player`):**
- `PlayerConnectEvent` - IEvent<Void>
- `PlayerSetupConnectEvent` - IEvent<Void>, ICancellable
- `PlayerDisconnectEvent` - PlayerRefEvent<Void>
@@ -146,12 +154,14 @@ EventRegistration registerAsyncUnhandled(...)
- `DrainPlayerFromWorldEvent` - IEvent<String>
**World Events (`...universe.world.events`):**
- `AddWorldEvent` - WorldEvent, ICancellable
- `RemoveWorldEvent` - WorldEvent, ICancellable
- `StartWorldEvent` - WorldEvent
- `AllWorldsLoadedEvent` - IEvent<Void>
**ECS Events (`...event.events.ecs`):**
- `BreakBlockEvent` - CancellableEcsEvent
- `PlaceBlockEvent` - CancellableEcsEvent
- `UseBlockEvent` - EcsEvent (with nested `Pre` implementing ICancellableEcsEvent)
@@ -164,16 +174,16 @@ EventRegistration registerAsyncUnhandled(...)
### 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 |
| 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
@@ -231,15 +241,15 @@ ArgTypes.forEnum(String name, Class<E> enumClass) // Create enum type
### Core Classes (Package: `com.hypixel.hytale.component`)
| Class | Description |
|-------|-------------|
| `Component<ECS_TYPE>` | Base component interface |
| `ComponentRegistry` | Component type registration |
| `ComponentType<ECS_TYPE, T>` | Registered component type |
| `Store` | ECS data storage |
| `Ref` | Entity reference (ID) |
| `Holder` | Component holder for entity construction |
| `Query` | Entity filtering |
| Class | Description |
|------------------------------|------------------------------------------|
| `Component<ECS_TYPE>` | Base component interface |
| `ComponentRegistry` | Component type registration |
| `ComponentType<ECS_TYPE, T>` | Registered component type |
| `Store` | ECS data storage |
| `Ref` | Entity reference (ID) |
| `Holder` | Component holder for entity construction |
| `Query` | Entity filtering |
### Entity Hierarchy
@@ -264,33 +274,39 @@ void registerSystem(ISystem<EntityStore> 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
@@ -323,14 +339,14 @@ Ref<EntityStore> ref = store.addEntity(holder, AddReason.SPAWN);
### Page System Classes
| Class | Package |
|-------|---------|
| `CustomUIPage` | `com.hypixel.hytale.server.core.entity.entities.player.pages.CustomUIPage` |
| `BasicCustomUIPage` | Same package - no event data parsing |
| `InteractiveCustomUIPage<T>` | 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` |
| Class | Package |
|------------------------------|----------------------------------------------------------------------------|
| `CustomUIPage` | `com.hypixel.hytale.server.core.entity.entities.player.pages.CustomUIPage` |
| `BasicCustomUIPage` | Same package - no event data parsing |
| `InteractiveCustomUIPage<T>` | 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
@@ -437,11 +453,11 @@ 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 |
| Class | Package |
|-------------------------------------------|------------------------------------------------------------------------|
| `Window` | `com.hypixel.hytale.server.core.entity.entities.player.windows.Window` |
| `WindowManager` | Same package |
| `ContainerWindow`, `CraftingWindow`, etc. | Same package |
### WindowType
@@ -456,11 +472,11 @@ DiagramCrafting(3), StructuralCrafting(4), Processing(5), Memories(6)
### Core Classes (Package: `com.hypixel.hytale.codec`)
| Class | Description |
|-------|-------------|
| `Codec<T>` | Base codec interface |
| `BuilderCodec<T>` | Builder-based codec |
| `KeyedCodec<T>` | Key-value codec |
| Class | Description |
|-------------------|----------------------|
| `Codec<T>` | Base codec interface |
| `BuilderCodec<T>` | Builder-based codec |
| `KeyedCodec<T>` | Key-value codec |
### Primitive Codecs
@@ -503,39 +519,45 @@ Codec<MyEnum> ENUM = Codec.enumCodec(MyEnum.class);
### Core Classes
| Class | Package |
|-------|---------|
| `JsonAsset<K>` | `com.hypixel.hytale.assetstore.JsonAsset` |
| `AssetStore<K,T,M>` | `com.hypixel.hytale.assetstore.AssetStore` |
| `AssetRegistry` | `com.hypixel.hytale.server.core.plugin.AssetRegistry` |
| Class | Package |
|---------------------|-------------------------------------------------------|
| `JsonAsset<K>` | `com.hypixel.hytale.assetstore.JsonAsset` |
| `AssetStore<K,T,M>` | `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
@@ -556,12 +578,12 @@ Codec<MyEnum> ENUM = Codec.enumCodec(MyEnum.class);
### Core Classes
| Class | Package |
|-------|---------|
| `Universe` | `com.hypixel.hytale.server.core.universe.Universe` |
| `World` | `com.hypixel.hytale.server.core.universe.world.World` |
| 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` |
| `ChunkStore` | `com.hypixel.hytale.server.core.universe.world.storage.ChunkStore` |
### Universe Access
@@ -590,12 +612,12 @@ boolean paused = world.isPaused();
### Core Classes (Package: `com.hypixel.hytale.server.npc`)
| Class | Description |
|-------|-------------|
| `NPCEntity` | entities.NPCEntity - NPC entity class |
| `Role` | role.Role - Behavior definition |
| Class | Description |
|---------------|--------------------------------------------|
| `NPCEntity` | entities.NPCEntity - NPC entity class |
| `Role` | role.Role - Behavior definition |
| `Instruction` | instructions.Instruction - Behavior action |
| `PathManager` | navigation.PathManager - Pathfinding |
| `PathManager` | navigation.PathManager - Pathfinding |
### NPCEntity Key Methods
@@ -610,9 +632,9 @@ void playAnimation(...)
### Flock System (Package: `com.hypixel.hytale.server.flock`)
| Component | Description |
|-----------|-------------|
| `Flock` | Flock leader/group |
| Component | Description |
|-------------------|---------------------------|
| `Flock` | Flock leader/group |
| `FlockMembership` | Entity's flock membership |
---
@@ -621,9 +643,9 @@ void playAnimation(...)
### Packet System (Package: `com.hypixel.hytale.protocol`)
| Class | Description |
|-------|-------------|
| `Packet` | Base packet interface |
| Class | Description |
|------------------|--------------------------|
| `Packet` | Base packet interface |
| `PacketRegistry` | Packet type registration |
### Key Packet Categories (`protocol.packets.*`)
@@ -639,22 +661,22 @@ void playAnimation(...)
### UI Packets
| Packet | ID | Direction |
|--------|-----|-----------|
| `SetPage` | 216 | S->C |
| `CustomHud` | 217 | S->C |
| `CustomPage` | 218 | S->C |
| `CustomPageEvent` | 219 | C->S |
| 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 |
| Packet | ID | Direction |
|--------------------|-----|-----------|
| `OpenWindow` | 200 | S->C |
| `UpdateWindow` | 201 | S->C |
| `CloseWindow` | 202 | S->C |
| `ClientOpenWindow` | 203 | C->S |
| `SendWindowAction` | 204 | C->S |
---
@@ -724,23 +746,29 @@ Place JAR in `earlyplugins/` directory.
### EntityStore Components (130+)
**Transform:** TransformComponent, HeadRotation, PositionDataComponent, EntityScaleComponent, RotateObjectComponent, SnapshotBuffer
**Transform:** TransformComponent, HeadRotation, PositionDataComponent, EntityScaleComponent, RotateObjectComponent,
SnapshotBuffer
**Physics:** Velocity, PhysicsValues, BoundingBox, CollisionResultComponent, KnockbackComponent, MovementStatesComponent, HitboxCollision, Repulsion
**Physics:** Velocity, PhysicsValues, BoundingBox, CollisionResultComponent, KnockbackComponent,
MovementStatesComponent, HitboxCollision, Repulsion
**Player:** Player, MovementManager, CameraManager, ChunkTracker, PlayerInput, PlayerSettings, PlayerSkinComponent, PlayerRef
**Player:** Player, MovementManager, CameraManager, ChunkTracker, PlayerInput, PlayerSettings, PlayerSkinComponent,
PlayerRef
**NPC:** NPCEntity, ValueStore, StateEvaluator, StepComponent, Timers, FailedSpawnComponent
**Combat:** DamageDataComponent, DeathComponent, DeferredCorpseRemoval, CombatActionEvaluator, TargetMemory, DamageMemory
**Combat:** DamageDataComponent, DeathComponent, DeferredCorpseRemoval, CombatActionEvaluator, TargetMemory,
DamageMemory
**Visual:** ModelComponent, PersistentModel, PropComponent, DisplayNameComponent, ActiveAnimationComponent, DynamicLight, Nameplate
**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
**State Flags:** Frozen, Intangible, Invulnerable, Interactable, RespondToHit, HiddenFromAdventurePlayers,
NewSpawnComponent, FromPrefab, FromWorldGen, DespawnComponent
**Teleport:** Teleport, PendingTeleport, TeleportHistory, WarpComponent
@@ -762,7 +790,8 @@ Place JAR in `earlyplugins/` directory.
### ChunkStore Components (25+)
**Structure:** BlockChunk, BlockComponentChunk, EntityChunk, ChunkColumn, ChunkSection, BlockSection, FluidSection, EnvironmentChunk
**Structure:** BlockChunk, BlockComponentChunk, EntityChunk, ChunkColumn, ChunkSection, BlockSection, FluidSection,
EnvironmentChunk
**Block State:** BlockState, RespawnBlock, LaunchPad, BlockMapMarker