World Events

Packages:

com.hypixel.hytale.server.core.universe.world.events
com.hypixel.hytale.server.core.universe.world.events.ecs

Events related to world and chunk lifecycle.

AddWorldEvent

Fired when a world is added to the universe. This event is cancellable.

Class: com.hypixel.hytale.server.core.universe.world.events.AddWorldEvent

Property	Value
Extends	`WorldEvent`, `ICancellable`
KeyType	`String` (world name)
Cancellable	Yes

Methods

Method	Return Type	Description
`getWorld()`	`@Nonnull World`	Returns the world being added (inherited from `WorldEvent`)

Example (from TeleportPlugin, PortalsPlugin, BlockModule)

The primary use case is registering map marker providers:

events.registerGlobal(AddWorldEvent.class, event -> {
    event.getWorld().getWorldMapManager()
        .addMarkerProvider("warps", WarpMarkerProvider.INSTANCE);
});

RemoveWorldEvent

Fired when a world is removed. This event is cancellable (unless removal reason is EXCEPTIONAL).

Class: com.hypixel.hytale.server.core.universe.world.events.RemoveWorldEvent

Property	Value
Extends	`WorldEvent`, `ICancellable`
KeyType	`String` (world name)

Methods

Method	Return Type	Description
`getWorld()`	`@Nonnull World`	Returns the world being removed (inherited from `WorldEvent`)
`getRemovalReason()`	`@Nonnull RemovalReason`	Returns the reason for removal (`GENERAL` or `EXCEPTIONAL`)

RemovalReason Enum

Value	Description
`GENERAL`	Normal world removal (cancellable)
`EXCEPTIONAL`	Forced removal due to error (not cancellable)

Example (from PortalsPlugin)

events.registerGlobal(RemoveWorldEvent.class, event -> {
    // disable portals pointing to this world
    for (World otherWorld : Universe.get().getWorlds().values()) {
        if (otherWorld == event.getWorld()) continue;
        otherWorld.execute(() ->
            PortalInvalidDestinationSystem.turnOffPortalsInWorld(otherWorld, event.getWorld())
        );
    }
});

StartWorldEvent

Fired when a world starts its tick loop. This is the earliest point where the world is fully initialized — ECS stores, chunk loader/saver, and lighting are all ready.

Class: com.hypixel.hytale.server.core.universe.world.events.StartWorldEvent

Property	Value
Extends	`WorldEvent`
KeyType	`String` (world name)

Methods

Method	Return Type	Description
`getWorld()`	`@Nonnull World`	Returns the world that started (inherited from `WorldEvent`)

World initialization order

Phase	What happens	What’s available
World constructor	`ChunkStore` and `EntityStore` objects created	World object, `WorldConfig`
`World.init()`	World generator loaded asynchronously	World generator (`IWorldGen`)
Plugin `start()`	All mods finished setup	Assets, config, event registration — not world contents
`World.onStart()`	`chunkStore.start()`, `entityStore.start()`, lighting started	Everything
`StartWorldEvent`	Dispatched right after `onStart()`	Everything — safe to access stores, loader, entities

Use this event to defer initialization that needs world contents:

getEventRegistry().registerGlobal(StartWorldEvent.class, event -> {
    World world = event.getWorld();
    // stores, loader, entities, lighting — all ready
    initializeRenderer(world);
});

AllWorldsLoadedEvent

Fired once after all configured worlds have loaded during startup.

Class: com.hypixel.hytale.server.core.universe.world.events.AllWorldsLoadedEvent

Property	Value
Implements	`IEvent<Void>`
KeyType	`Void`

Methods

This event has no public methods besides toString().

Example (from TeleportPlugin)

events.registerGlobal(AllWorldsLoadedEvent.class, event -> {
    loadWarps(); // load warps.json after all worlds are ready
});

ChunkPreLoadProcessEvent

Fired during chunk loading/generation. Implements IProcessedEvent.

Class: com.hypixel.hytale.server.core.universe.world.events.ChunkPreLoadProcessEvent

Property	Value
Extends	`ChunkEvent`, `IProcessedEvent`
KeyType	`String` (world name)

Methods

Method	Return Type	Description
`getChunk()`	`WorldChunk`	Returns the chunk being loaded (inherited from `ChunkEvent`)
`isNewlyGenerated()`	`boolean`	Returns `true` if the chunk was newly generated, `false` if loaded from disk
`getHolder()`	`Holder<ChunkStore>`	Returns the chunk storage holder
`didLog()`	`boolean`	Returns whether a performance warning was logged for this event
`processEvent(String hookName)`	`void`	Internal method called after each handler to track timing

Example (from TeleportPlugin)

// spawn warp entities when their chunk loads
events.registerGlobal(ChunkPreLoadProcessEvent.class, event -> {
    WorldChunk chunk = event.getChunk();
    for (Warp warp : getWarpsInChunk(chunk)) {
        spawnWarpEntity(warp, chunk);
    }
});

Example (from FluidPlugin, BlockTickPlugin)

// use priority to control processing order
events.registerGlobal(EventPriority.FIRST, ChunkPreLoadProcessEvent.class, event -> {
    if (!event.isNewlyGenerated()) return; // only for new chunks
    setupFluidTicking(event.getChunk());
});

WorldPathChangedEvent

Fired when a world’s file path changes (rare).

Class: com.hypixel.hytale.server.core.universe.world.path.WorldPathChangedEvent

Property	Value
Implements	`IEvent<Void>`
KeyType	`Void`

Methods

Method	Return Type	Description
`getWorldPath()`	`WorldPath`	Returns the new world path

ChunkUnloadEvent

Fired when a chunk is unloaded. This event is cancellable.

Class: com.hypixel.hytale.server.core.universe.world.events.ecs.ChunkUnloadEvent

Property	Value
Extends	`CancellableEcsEvent`
Cancellable	Yes

Methods

Method	Return Type	Description
`getChunk()`	`@Nonnull WorldChunk`	Returns the chunk being unloaded
`willResetKeepAlive()`	`boolean`	Returns whether the keep-alive timer will be reset after unload (default: `true`)
`setResetKeepAlive(boolean willResetKeepAlive)`	`void`	Sets whether to reset the keep-alive timer

ChunkSaveEvent

Fired when a chunk is saved. This event is cancellable.

Class: com.hypixel.hytale.server.core.universe.world.events.ecs.ChunkSaveEvent

Property	Value
Extends	`CancellableEcsEvent`
Cancellable	Yes

Methods

Method	Return Type	Description
`getChunk()`	`@Nonnull WorldChunk`	Returns the chunk being saved

MoonPhaseChangeEvent

Fired when the moon phase changes.

Class: com.hypixel.hytale.server.core.universe.world.events.ecs.MoonPhaseChangeEvent

Property	Value
Extends	`EcsEvent`

Methods

Method	Return Type	Description
`getNewMoonPhase()`	`int`	Returns the new moon phase value