hytale-events-api

Hytale Events API

Complete guide for handling server events and creating custom event systems.

When to use this skill

Use this skill when:

• Listening for player actions (connect, chat, interact)
• Reacting to world changes (blocks, chunks)
• Handling entity events (damage, death, spawn)
• Creating custom events
• Managing event priorities and cancellation
• Implementing async event handlers

Event System Architecture

Hytale has two event systems:

1. General Event Bus - Server-wide events (players, worlds, assets)
2. ECS Event System - Entity-specific events (damage, interactions)

General Event Bus

Event Registration

Register in plugin setup():

@Override
protected void setup() {
    // Global listener - receives ALL events of this type
    getEventRegistry().registerGlobal(
        PlayerConnectEvent.class, 
        this::onPlayerConnect
    );
    
    // Keyed listener - receives events with specific key
    getEventRegistry().register(
        AddPlayerToWorldEvent.class, 
        "world_name", 
        this::onPlayerAddToWorld
    );
    
    // Priority listener
    getEventRegistry().registerGlobal(
        EventPriority.FIRST, 
        SomeEvent.class, 
        this::onSomeEvent
    );
    
    // Unhandled listener - only if no keyed handler processed
    getEventRegistry().registerUnhandled(
        SomeEvent.class, 
        this::onUnhandledEvent
    );
}

Event Priorities

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

Handlers execute in priority order. Use custom short values for fine-grained control.

Event Cancellation

For cancellable events:

private void onPlayerInteract(PlayerInteractEvent event) {
    if (shouldBlock(event)) {
        event.setCancelled(true);
    }
}

Check cancellation:

private void onEvent(SomeEvent event) {
    if (event instanceof ICancellable cancellable && cancellable.isCancelled()) {
        return; // Already cancelled by earlier handler
    }
    // Process event
}