Skip to content

02-event-system.md

Latest commit

 

History

History
187 lines (145 loc) · 6.83 KB

02-event-system.md

File metadata and controls

187 lines (145 loc) · 6.83 KB

Event System

Architecture

IEventBus (server-wide event bus)
  └── EventBusRegistry (manages consumers per event class)
        ├── SyncEventBusRegistry (synchronous dispatch)
        └── AsyncEventBusRegistry (async dispatch via CompletableFuture)

EventRegistry (per-plugin wrapper, auto-cleanup on shutdown)
  └── delegates to IEventRegistry (parent bus)

EventRegistry (Plugin API)

Package: com.hypixel.hytale.event

Each plugin gets its own EventRegistry via getEventRegistry(). All registrations are auto-cleaned on plugin shutdown.

Registration Methods

// Simple event listener (no key, default priority)
<EventType extends IBaseEvent<Void>> EventRegistration<Void, EventType>
    register(Class<? super EventType> eventClass, Consumer<EventType> consumer);

// With priority
<EventType extends IBaseEvent<Void>> EventRegistration<Void, EventType>
    register(EventPriority priority, Class<? super EventType> eventClass, Consumer<EventType> consumer);

// With custom priority value
<EventType extends IBaseEvent<Void>> EventRegistration<Void, EventType>
    register(short priority, Class<? super EventType> eventClass, Consumer<EventType> consumer);

// Keyed event (entity-scoped)
<KeyType, EventType extends IBaseEvent<KeyType>> EventRegistration<KeyType, EventType>
    register(Class<? super EventType> eventClass, KeyType key, Consumer<EventType> consumer);

// Global listener for keyed events (receives all keys)
<KeyType, EventType extends IBaseEvent<KeyType>> EventRegistration<KeyType, EventType>
    registerGlobal(Class<? super EventType> eventClass, Consumer<EventType> consumer);

// Async event listener
<EventType extends IAsyncEvent<Void>> EventRegistration<Void, EventType>
    registerAsync(Class<? super EventType> eventClass,
                  Function<CompletableFuture<EventType>, CompletableFuture<EventType>> function);

// Unhandled event listener (fires only if no keyed handler matched)
<KeyType, EventType extends IBaseEvent<KeyType>> EventRegistration<KeyType, EventType>
    registerUnhandled(Class<? super EventType> eventClass, Consumer<EventType> consumer);

EventPriority

public enum EventPriority {
    FIRST(-21844),   // Runs first
    EARLY(-10922),
    NORMAL(0),       // Default
    LATE(10922),
    LAST(21844);     // Runs last
}

Custom priority values (short) also supported for fine-grained ordering.

Event Interfaces

public interface IBaseEvent<KeyType> { }           // Base for all events
public interface IEvent<KeyType> extends IBaseEvent<KeyType> { }  // Sync events
public interface IAsyncEvent<KeyType> extends IBaseEvent<KeyType> { }  // Async events
public interface ICancellable { boolean isCancelled(); void setCancelled(boolean cancelled); }
public interface IProcessedEvent { boolean isProcessed(); void setProcessed(boolean processed); }

Server Events

Player Events (server.core.event.events.player)

Event Key Type Description
PlayerConnectEvent Void Player connected to server
PlayerDisconnectEvent Void Player disconnected
PlayerReadyEvent Void Player fully loaded and ready
PlayerSetupConnectEvent Void Pre-connection setup
PlayerSetupDisconnectEvent Void Pre-disconnect cleanup
AddPlayerToWorldEvent keyed Player added to a world
DrainPlayerFromWorldEvent keyed Player removed from world
PlayerChatEvent Void Player sent chat message
PlayerInteractEvent keyed Player interacted with entity/block
PlayerMouseButtonEvent keyed Mouse button pressed
PlayerMouseMotionEvent keyed Mouse moved
PlayerCraftEvent keyed Player crafted item

PlayerConnectEvent Key Methods

PlayerRef getPlayerRef();
World getWorld();          // Initial world (may be null)

PlayerDisconnectEvent Key Methods

PlayerRef getPlayerRef();

PlayerChatEvent Key Methods

PlayerRef getPlayerRef();
String getMessage();
void setMessage(String message);
Formatter getFormatter();  // Interface for formatting

ECS Events (server.core.event.events.ecs)

Event Description
BreakBlockEvent Block broken
PlaceBlockEvent Block placed
DamageBlockEvent Block damaged
UseBlockEvent.Pre / .Post Block used (interaction)
ChangeGameModeEvent Game mode changed
CraftRecipeEvent.Pre / .Post Recipe crafted
DropItemEvent Item dropped
InteractivelyPickupItemEvent Item picked up
SwitchActiveSlotEvent Hotbar slot changed
DiscoverZoneEvent Zone discovered

Permission Events (server.core.event.events.permissions)

Event Description
PlayerPermissionChangeEvent.PermissionsAdded Permissions added to player
PlayerPermissionChangeEvent.PermissionsRemoved Permissions removed from player
PlayerPermissionChangeEvent.GroupAdded Player added to group
PlayerPermissionChangeEvent.GroupRemoved Player removed from group
PlayerGroupEvent.Added Player-group association added
PlayerGroupEvent.Removed Player-group association removed
GroupPermissionChangeEvent.Added Permissions added to group
GroupPermissionChangeEvent.Removed Permissions removed from group

Entity Events (server.core.event.events.entity)

Event Description
EntityEvent Base entity event
EntityRemoveEvent Entity removed from world
LivingEntityInventoryChangeEvent Inventory changed
LivingEntityUseBlockEvent Entity used a block

Server Lifecycle Events

Event Description
BootEvent Server boot complete
ShutdownEvent Server shutting down
PrepareUniverseEvent Universe initialization

Plugin Events (server.core.plugin.event)

Event Description
PluginEvent Base plugin event
PluginSetupEvent Plugin setup phase complete

Keyed vs Non-keyed Events

  • Non-keyed (IBaseEvent<Void>): Use register() — all listeners receive the event
  • Keyed (IBaseEvent<KeyType>): Use register(eventClass, key, consumer) — only listeners matching the key receive the event. Use registerGlobal() to receive all keys.

HyperPerms Usage Patterns

// Non-keyed: all player connects
getEventRegistry().register(PlayerConnectEvent.class, this::onPlayerConnect);

// Non-keyed: all player disconnects
getEventRegistry().register(PlayerDisconnectEvent.class, this::onPlayerDisconnect);

// Global for keyed events: all world additions
getEventRegistry().registerGlobal(AddPlayerToWorldEvent.class, this::onPlayerAddedToWorld);

// Global for keyed events: all game mode changes
getEventRegistry().registerGlobal(ChangeGameModeEvent.class, this::onGameModeChange);