hytale/hytale-server
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
49a80ebf771a0048591ba01f4719fc912df44e4b
hytale-server/docs/00-llm-reference.md

26 KiB
Raw Blame History

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)

{
    "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<EntityStore>
getChunkStoreRegistry() ComponentRegistryProxy<ChunkStore>
getAssetRegistry() AssetRegistry

Configuration Pattern

// In constructor (BEFORE setup):
Config<MyConfig> config = withConfig(MyConfig.CODEC);
Config<MyConfig> 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<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)

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:

// Without key (Void key)
EventRegistration register(Class<? super EventType> eventClass, Consumer<EventType> consumer)
EventRegistration register(EventPriority priority, Class<? super EventType> eventClass, Consumer<EventType> consumer)

// With key
EventRegistration register(Class<? super EventType> eventClass, KeyType key, Consumer<EventType> consumer)
EventRegistration register(EventPriority priority, Class<? super EventType> eventClass, KeyType key, Consumer<EventType> consumer)

Global Registration (receives all keys):

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):

EventRegistration registerUnhandled(Class<? super EventType> eventClass, Consumer<EventType> consumer)

Async Registration:

EventRegistration registerAsync(Class<? super EventType> eventClass, Function<CompletableFuture<EventType>, CompletableFuture<EventType>> 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

// 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<Void> execute(CommandContext context)

// Configuration
void requirePermission(String permission)
void addAliases(String... aliases)
void addSubCommand(AbstractCommand command)
void addUsageVariant(AbstractCommand command)

// Arguments
RequiredArg<D> withRequiredArg(String name, String description, ArgumentType<D> argType)
OptionalArg<D> withOptionalArg(String name, String description, ArgumentType<D> argType)
DefaultArg<D> withDefaultArg(String name, String description, ArgumentType<D> argType, D defaultValue, String defaultValueDescription)
FlagArg withFlagArg(String name, String description)
RequiredArg<List<D>> withListRequiredArg(String name, String description, ArgumentType<D> argType)

CommandContext Key Methods

<DataType> DataType get(Argument<?, DataType> 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 extends CommandSender> T senderAs(Class<T> type)      // Cast sender
Ref<EntityStore> senderAsPlayerRef()                     // Get as player ref

Built-in ArgTypes (com.hypixel.hytale.server.core.command.system.arguments.types.ArgTypes)

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<E> enumClass)  // Create enum type

ENTITY COMPONENT SYSTEM (ECS)

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

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)

public static final ComponentRegistry<EntityStore> REGISTRY = new ComponentRegistry<>();

// Registration
ComponentType<EntityStore, T> registerComponent(Class<? super T> tClass, Supplier<T> supplier)
ComponentType<EntityStore, T> registerComponent(Class<? super T> tClass, String id, BuilderCodec<T> codec)
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
  • PlayerInput - Input state

Working with Components

Store<EntityStore> 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<EntityStore> holder = EntityStore.REGISTRY.newHolder();
holder.addComponent(TransformComponent.getComponentType(), new TransformComponent(pos, rot));
Ref<EntityStore> 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<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

CantClose(0)                           // Cannot be closed
CanDismiss(1)                          // ESC to close
CanDismissOrCloseThroughInteraction(2) // ESC or interaction

UICommandBuilder Methods

// 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<T> ref)
void setObject(String selector, Object data)
void set(String selector, T[] data)
void set(String selector, List<T> data)

CustomUIEventBindingType

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

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

EventData.of("Key", "Value")
new EventData().append("Key", "Value").append("@ElementValue", "#Element.Property")
// @ prefix = extract value from element

Value References

Value.of(directValue)                    // Direct value
Value.ref("Document.ui", "ValueName")    // Reference from UI document

Page Example

public class MyPage extends InteractiveCustomUIPage<MyPage.Data> {
    public MyPage(PlayerRef playerRef) {
        super(playerRef, CustomPageLifetime.CanDismiss, Data.CODEC);
    }
    
    @Override
    public void build(Ref<EntityStore> ref, UICommandBuilder cmd, 
                     UIEventBuilder events, Store<EntityStore> 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<EntityStore> ref, Store<EntityStore> store, Data data) {
        if ("Click".equals(data.action)) { close(); }
    }
    
    public static class Data {
        public static final BuilderCodec<Data> 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

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<T> Base codec interface
BuilderCodec<T> Builder-based codec
KeyedCodec<T> Key-value codec

Primitive Codecs

Codec.STRING, Codec.BOOLEAN, Codec.INTEGER, Codec.LONG
Codec.FLOAT, Codec.DOUBLE, Codec.BYTE_ARRAY

Collection Codecs

Codec.STRING.listOf()                      // List<String>
Codec.STRING.setOf()                       // Set<String>
Codec.mapOf(Codec.STRING, Codec.INTEGER)   // Map<String, Integer>
Codec.arrayOf(Codec.STRING, String[]::new) // String[]

BuilderCodec Pattern

public static final BuilderCodec<MyClass> 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

Codec<UUID> UUID_CODEC = Codec.STRING.xmap(UUID::fromString, UUID::toString);
Codec<Integer> PORT = Codec.INTEGER.validate(p -> p > 0 && p < 65536, "Invalid port");
Codec<Float> VOLUME = Codec.FLOAT.clamp(0.0f, 1.0f);
Codec<MyEnum> ENUM = Codec.enumCodec(MyEnum.class);

ASSET SYSTEM

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

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

{
    "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

Universe universe = Universe.get();
Collection<World> worlds = universe.getWorlds();
World world = universe.getWorld("worldName");
Collection<Player> players = universe.getPlayers();
Player player = universe.getPlayer("name");
Player player = universe.getPlayer(uuid);

World Access

String name = world.getName();
EntityStore entityStore = world.getEntityStore();
Store<EntityStore> 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

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

Vector3d  // 3D double precision
Vector3f  // 3D float precision
Vector3i  // 3D integer
Vector2d  // 2D double
Vector2i  // 2D integer

Vector Operations

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

Box, Ellipsoid, Cylinder
Transform, Location

COMMON UTILITIES (Package: com.hypixel.hytale.common)

Utility Classes

StringUtil, ArrayUtil, ListUtil, MapUtil
TimeUtil, FormatUtil, MathUtil, TrigMathUtil
Semver, SemverRange
WeightedMap<T>  // Weighted random selection

EARLY PLUGIN SYSTEM

ClassTransformer Interface (Package: com.hypixel.hytale.plugin.early)

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

Reference in New Issue View Git Blame Copy Permalink