Event System

Package: com.hypixel.hytale.event (infrastructure) + com.hypixel.hytale.server.core.event.events (concrete events)

Hytale has a dual event system with two parallel hierarchies that use completely separate dispatch mechanisms.

Standard Events (EventBus)

Standard events implement IEvent<KeyType> (synchronous) or IAsyncEvent<KeyType> (asynchronous) and are dispatched through the EventBus. Registration uses Consumer-based callbacks — no annotations.

Listener Registration

// In a plugin's setup() or start() method:
getEventRegistry().register(BreakBlockEvent.class, event -> {
    BlockType blockType = event.getBlockType();
    if (event.isCancelled()) return;
    // handle event
});

// With priority:
getEventRegistry().register(EventPriority.EARLY, PlayerChatEvent.class, event -> {
    // runs before NORMAL priority listeners
});

// Async event (PlayerChatEvent implements IAsyncEvent):
getEventRegistry().registerAsync(PlayerChatEvent.class, future -> {
    return future.thenApply(event -> {
        event.setContent(event.getContent().toUpperCase());
        return event;
    });
});

Registration Families

Method	Dispatch	Scope
register(Class, Consumer)	Sync	Keyed (specific key)
registerGlobal(Class, Consumer)	Sync	All keys
registerUnhandled(Class, Consumer)	Sync	Fallback (no specific listeners)
registerAsync(Class, Function)	Async	Keyed
registerAsyncGlobal(Class, Function)	Async	All keys
registerAsyncUnhandled(Class, Function)	Async	Fallback

Each family has 3 overloads: default priority, EventPriority enum, raw short priority.

Event Priority

Priority	Value	Description
FIRST	-21844	Highest priority, runs earliest
EARLY	-10922	Before normal
NORMAL	0	Default
LATE	10922	After normal
LAST	21844	Lowest priority, runs last

Raw short values allow custom priorities between enum values.

Keyed Dispatch

Events have a KeyType generic parameter:

• KeyType=Void — Unkeyed (global dispatch). Example: BootEvent, ShutdownEvent.
• KeyType=String — Can be dispatched for specific string keys. Example: PlayerReadyEvent, AddPlayerToWorldEvent. Listeners can register for a specific key or use registerGlobal() to receive all keys.

ECS Events

ECS events extend EcsEvent (or CancellableEcsEvent) and are dispatched through the ECS system pipeline using store.invoke(). They do not use the EventBus — this is a completely separate dispatch mechanism.

ECS events are handled by EntityEventSystem subclasses that declare a Query to filter which entities receive the event. Only entities whose archetype matches the system’s query will trigger the handler.

ECS Event Dispatch

// Entity-level dispatch (most common):
store.invoke(ref, event);
componentAccessor.invoke(ref, event);

// Store-level dispatch:
store.invoke(event);

Cancellation

There are two separate cancellation interfaces with identical method signatures:

Interface	Hierarchy	Methods
ICancellable	Standard events (IEvent)	isCancelled(), setCancelled(boolean)
ICancellableEcsEvent	ECS events (EcsEvent)	isCancelled(), setCancelled(boolean)

Type Hierarchy

Standard Events

IBaseEvent<KeyType>
├── IEvent<KeyType>                    (synchronous)
│   ├── EntityEvent<EntityType, KeyType>
│   │   ├── EntityRemoveEvent
│   │   ├── LivingEntityInventoryChangeEvent
│   │   └── LivingEntityUseBlockEvent (deprecated)
│   ├── PlayerEvent<KeyType>
│   │   ├── PlayerReadyEvent
│   │   ├── PlayerCraftEvent (deprecated)
│   │   ├── PlayerInteractEvent (deprecated)
│   │   ├── PlayerMouseButtonEvent
│   │   └── PlayerMouseMotionEvent
│   ├── PlayerRefEvent<KeyType>
│   │   └── PlayerDisconnectEvent
│   ├── PlayerPermissionChangeEvent
│   │   ├── .GroupAdded
│   │   ├── .GroupRemoved
│   │   ├── .PermissionsAdded
│   │   └── .PermissionsRemoved
│   ├── PlayerGroupEvent
│   │   ├── .Added
│   │   └── .Removed
│   ├── GroupPermissionChangeEvent
│   │   ├── .Added
│   │   └── .Removed
│   ├── BootEvent
│   ├── ShutdownEvent
│   ├── PrepareUniverseEvent (deprecated)
│   ├── PlayerConnectEvent
│   ├── PlayerSetupConnectEvent (+ ICancellable)
│   ├── PlayerSetupDisconnectEvent
│   ├── PlayerChatEvent (IAsyncEvent + ICancellable)
│   ├── AddPlayerToWorldEvent
│   ├── DrainPlayerFromWorldEvent
│   ├── AllWorldsLoadedEvent
│   ├── AllNPCsLoadedEvent
│   ├── LoadedNPCEvent
│   ├── AssetPackRegisterEvent
│   ├── AssetPackUnregisterEvent
│   ├── LoadAssetEvent
│   ├── GenerateSchemaEvent
│   ├── GenerateDefaultLanguageEvent
│   ├── MessagesUpdated
│   ├── WorldPathChangedEvent
│   └── SingleplayerRequestAccessEvent
└── IAsyncEvent<KeyType>               (asynchronous)
    ├── PlayerChatEvent
    └── SendCommonAssetsEvent

ECS Events

EcsEvent
├── CancellableEcsEvent (+ ICancellableEcsEvent)
│   ├── BreakBlockEvent
│   ├── PlaceBlockEvent
│   ├── DamageBlockEvent
│   ├── ChangeGameModeEvent
│   ├── SwitchActiveSlotEvent
│   ├── InteractivelyPickupItemEvent
│   ├── DropItemEvent
│   │   ├── .Drop
│   │   └── .PlayerRequest
│   ├── CraftRecipeEvent
│   │   ├── .Pre
│   │   └── .Post
│   ├── ChunkSaveEvent
│   ├── ChunkUnloadEvent
│   └── PrefabPasteEvent
├── UseBlockEvent
│   ├── .Pre (+ ICancellableEcsEvent)
│   └── .Post
├── DiscoverZoneEvent
│   └── .Display (+ ICancellableEcsEvent)
├── MoonPhaseChangeEvent
├── PrefabPlaceEntityEvent
├── DiscoverInstanceEvent
│   └── .Display (+ ICancellableEcsEvent)
└── KillFeedEvent
    ├── .DecedentMessage (+ CancellableEcsEvent)
    ├── .Display (+ CancellableEcsEvent)
    └── .KillerMessage (+ CancellableEcsEvent)

Concrete Events

Lifecycle Events

Event	Type	Cancellable	Description
BootEvent	Standard	No	Server boot lifecycle
ShutdownEvent	Standard	No	Server shutdown lifecycle
PrepareUniverseEvent	Standard	No	Universe initialization (deprecated)

Player Events

Event	Type	Cancellable	Description
PlayerSetupConnectEvent	Standard	Yes	Early connection (before player entity)
PlayerConnectEvent	Standard	No	Player entity created and connected
PlayerDisconnectEvent	Standard	No	Player disconnects
PlayerSetupDisconnectEvent	Standard	No	Setup-phase disconnect
AddPlayerToWorldEvent	Standard	No	Player enters a world
DrainPlayerFromWorldEvent	Standard	No	Player leaves a world
PlayerReadyEvent	Standard	No	Player signals readiness
PlayerChatEvent	Async	Yes	Player sends chat message
PlayerMouseButtonEvent	Standard	Yes	Mouse button press/release
PlayerMouseMotionEvent	Standard	Yes	Mouse drag events
PlayerCraftEvent	Standard	No	Crafting (deprecated)
PlayerInteractEvent	Standard	Yes	Interaction (deprecated)

ECS / Block Events

Event	Type	Cancellable	Description
BreakBlockEvent	ECS	Yes	Player finishes mining a block
PlaceBlockEvent	ECS	Yes	Player places a block
DamageBlockEvent	ECS	Yes	Mining progress tick
UseBlockEvent	ECS	Pre: Yes	Block interaction (Pre/Post)
ChangeGameModeEvent	ECS	Yes	Game mode change
SwitchActiveSlotEvent	ECS	Yes	Hotbar slot change
InteractivelyPickupItemEvent	ECS	Yes	Item pickup
DropItemEvent	ECS	Yes	Item drop (PlayerRequest/Drop)
CraftRecipeEvent	ECS	Yes	Crafting (Pre/Post)
DiscoverZoneEvent	ECS	Display: Yes	Zone discovery

ECS / World Events

Event	Type	Cancellable	Description
MoonPhaseChangeEvent	ECS	No	Moon phase changes during time progression
ChunkSaveEvent	ECS	Yes	Chunk is being saved to storage
ChunkUnloadEvent	ECS	Yes	Chunk is being unloaded from memory
PrefabPasteEvent	ECS	Yes	Prefab is being pasted into the world
PrefabPlaceEntityEvent	ECS	No	Prefab places an entity into the world
DiscoverInstanceEvent	ECS	Display: Yes	Instance discovery
KillFeedEvent	ECS	Inner: Yes	Kill feed notifications (DecedentMessage/Display/KillerMessage)

Entity Events

Event	Type	Cancellable	Description
EntityRemoveEvent	Standard	No	Entity removed from world
LivingEntityInventoryChangeEvent	Standard	No	Inventory contents changed
LivingEntityUseBlockEvent	Standard	No	Block use (deprecated)

Permission Events

Event	Type	Cancellable	Description
GroupPermissionChangeEvent	Standard	No	Group permissions changed (Added/Removed)
PlayerGroupEvent	Standard	No	Player group membership changed (Added/Removed)
PlayerPermissionChangeEvent	Standard	No	Player permissions changed (GroupAdded/GroupRemoved/PermissionsAdded/PermissionsRemoved)

Server Infrastructure Events

These events are primarily used by internal server infrastructure. They are part of the API surface and plugins can listen for them, but they are most relevant for advanced use cases such as asset management, localization, and server lifecycle orchestration.

Event	Type	Cancellable	Description
AllWorldsLoadedEvent	Standard	No	All worlds have completed loading
AllNPCsLoadedEvent	Standard	No	All NPC builders have been loaded
LoadedNPCEvent	Standard	No	A single NPC builder has been loaded
AssetPackRegisterEvent	Standard	No	An asset pack is registered with the server
AssetPackUnregisterEvent	Standard	No	An asset pack is unregistered from the server
LoadAssetEvent	Standard	No	Dispatched during asset loading phase at boot
GenerateSchemaEvent	Standard	No	Fired during schema generation for editor toolchain
GenerateDefaultLanguageEvent	Standard	No	Fired during default language generation for i18n
MessagesUpdated	Standard	No	Translation messages changed or removed
WorldPathChangedEvent	Standard	No	World path configuration changed
SingleplayerRequestAccessEvent	Standard	No	Singleplayer mode requests access control
SendCommonAssetsEvent	Async	No	Common assets being sent to a connecting client

Related

• EventRegistry — Plugin-scoped event registration API
• IEventBus — Core dispatch interface
• EventPriority — Priority enum
• EventRegistration — Registration handle