Documentation/content/core-concepts/events/event-reference/world-events.en.md

title, type, weight

title	type	weight
World Events	docs	5

Events related to world management, chunks, and environmental changes.

World Lifecycle Events

AddWorldEvent

{{< badge "Cancellable" >}}

Fired when a world is being added to the server.

Package: com.hypixel.hytale.server.core.event.events.world

{{< tabs items="Fields,Methods,Example" >}} {{< tab >}}

Field	Type	Description
world	World	The world being added
universe	Universe	The parent universe
{{< /tab >}}
{{< tab >}}

• getWorld() - Returns the world
• getUniverse() - Returns the parent universe
• isCancelled() - Check if cancelled
• setCancelled(boolean) - Cancel world addition {{< /tab >}} {{< tab >}}

getEventRegistry().register(AddWorldEvent.class, event -> {
    World world = event.getWorld();
    Universe universe = event.getUniverse();

    getLogger().at(Level.INFO).log("World added: " + world.getName() + " to " + universe.getName());

    // Prevent certain world types from loading
    if (world.getName().contains("test") && !isDevMode()) {
        event.setCancelled(true);
    }
});

{{< /tab >}} {{< /tabs >}}

---

RemoveWorldEvent

{{< badge "Cancellable" >}}

Fired when a world is being removed from the server.

Package: com.hypixel.hytale.server.core.event.events.world

{{< tabs items="Fields,Methods,Example" >}} {{< tab >}}

Field	Type	Description
world	World	The world being removed
reason	RemovalReason	Why the world is being removed
{{< /tab >}}
{{< tab >}}

• getWorld() - Returns the world
• getReason() - Returns removal reason
• isCancelled() - Check if cancelled
• setCancelled(boolean) - Cancel world removal {{< /tab >}} {{< tab >}}

getEventRegistry().register(RemoveWorldEvent.class, event -> {
    World world = event.getWorld();

    // Prevent removal of main world
    if (world.getName().equals("main")) {
        event.setCancelled(true);
        getLogger().warning("Cannot remove main world!");
        return;
    }

    // Save data before world is removed
    saveWorldData(world);
    notifyPlayersInWorld(world, "World is being unloaded!");
});

{{< /tab >}} {{< /tabs >}}

---

StartWorldEvent

Fired when a world starts (finishes initialization).

Package: com.hypixel.hytale.server.core.event.events.world

{{< tabs items="Fields,Methods,Example" >}} {{< tab >}}

Field	Type	Description
world	World	The world that started
{{< /tab >}}
{{< tab >}}

• getWorld() - Returns the world {{< /tab >}} {{< tab >}}

getEventRegistry().register(StartWorldEvent.class, event -> {
    World world = event.getWorld();

    getLogger().at(Level.INFO).log("World started: " + world.getName());

    // Initialize world-specific features
    initializeWorldBorders(world);
    spawnWorldBoss(world);
    startWeatherCycle(world);
});

{{< /tab >}} {{< /tabs >}}

---

AllWorldsLoadedEvent

Fired when all worlds have finished loading on server startup.

Package: com.hypixel.hytale.server.core.event.events.world

{{< tabs items="Fields,Methods,Example" >}} {{< tab >}}

Field	Type	Description
worlds	List<World>	All loaded worlds
{{< /tab >}}
{{< tab >}}

• getWorlds() - Returns list of all loaded worlds {{< /tab >}} {{< tab >}}

getEventRegistry().register(AllWorldsLoadedEvent.class, event -> {
    List<World> worlds = event.getWorlds();

    getLogger().at(Level.INFO).log("All " + worlds.size() + " worlds loaded!");

    // Initialize cross-world features
    initializePortalNetwork(worlds);
    syncWorldTimes(worlds);
});

{{< /tab >}} {{< /tabs >}}

---

Chunk Events

ChunkPreLoadProcessEvent

Fired before a chunk begins loading.

Package: com.hypixel.hytale.server.core.event.events.world

{{< tabs items="Fields,Methods,Example" >}} {{< tab >}}

Field	Type	Description
world	World	The world
chunkX	int	Chunk X coordinate
chunkZ	int	Chunk Z coordinate
{{< /tab >}}
{{< tab >}}

• getWorld() - Returns the world
• getChunkX() - Returns chunk X coordinate
• getChunkZ() - Returns chunk Z coordinate {{< /tab >}} {{< tab >}}

getEventRegistry().register(ChunkPreLoadProcessEvent.class, event -> {
    int x = event.getChunkX();
    int z = event.getChunkZ();

    // Pre-load adjacent chunk data for seamless loading
    prepareAdjacentChunkData(event.getWorld(), x, z);
});

{{< /tab >}} {{< /tabs >}}

---

ChunkLoadEvent

Fired when a chunk finishes loading.

Package: com.hypixel.hytale.server.core.event.events.world

{{< tabs items="Fields,Methods,Example" >}} {{< tab >}}

Field	Type	Description
world	World	The world
chunk	Chunk	The loaded chunk
isNewChunk	boolean	Whether this is a newly generated chunk
{{< /tab >}}
{{< tab >}}

• getWorld() - Returns the world
• getChunk() - Returns the chunk
• isNewChunk() - Returns true if newly generated {{< /tab >}} {{< tab >}}

getEventRegistry().register(ChunkLoadEvent.class, event -> {
    Chunk chunk = event.getChunk();
    World world = event.getWorld();

    if (event.isNewChunk()) {
        // Add custom structures to new chunks
        generateCustomStructures(chunk);
        populateCustomOres(chunk);
    }

    // Restore entities from storage
    loadChunkEntities(world, chunk);
});

{{< /tab >}} {{< /tabs >}}

---

ChunkUnloadEvent

Fired when a chunk is about to be unloaded.

Package: com.hypixel.hytale.server.core.event.events.world

{{< tabs items="Fields,Methods,Example" >}} {{< tab >}}

Field	Type	Description
world	World	The world
chunk	Chunk	The chunk being unloaded
{{< /tab >}}
{{< tab >}}

• getWorld() - Returns the world
• getChunk() - Returns the chunk {{< /tab >}} {{< tab >}}

getEventRegistry().register(ChunkUnloadEvent.class, event -> {
    Chunk chunk = event.getChunk();
    World world = event.getWorld();

    // Save custom chunk data
    saveChunkEntities(world, chunk);
    saveChunkMetadata(chunk);

    // Clean up chunk-specific resources
    cleanupChunkParticles(chunk);
});

{{< /tab >}} {{< /tabs >}}

---

ChunkSaveEvent

Fired when a chunk is being saved.

Package: com.hypixel.hytale.server.core.event.events.world

{{< tabs items="Fields,Methods,Example" >}} {{< tab >}}

Field	Type	Description
world	World	The world
chunk	Chunk	The chunk being saved
{{< /tab >}}
{{< tab >}}

• getWorld() - Returns the world
• getChunk() - Returns the chunk {{< /tab >}} {{< tab >}}

getEventRegistry().register(ChunkSaveEvent.class, event -> {
    Chunk chunk = event.getChunk();

    // Save additional custom data alongside chunk
    saveCustomChunkData(chunk);

    getLogger().debug("Chunk saved: " + chunk.getX() + ", " + chunk.getZ());
});

{{< /tab >}} {{< /tabs >}}

---

Environmental Events

MoonPhaseChangeEvent

Fired when the moon phase changes.

Package: com.hypixel.hytale.server.core.event.events.world

{{< tabs items="Fields,Methods,Example" >}} {{< tab >}}

Field	Type	Description
world	World	The world
previousPhase	MoonPhase	Previous moon phase
newPhase	MoonPhase	New moon phase
{{< /tab >}}
{{< tab >}}

• getWorld() - Returns the world
• getPreviousPhase() - Returns previous phase
• getNewPhase() - Returns new phase {{< /tab >}} {{< tab >}}

getEventRegistry().register(MoonPhaseChangeEvent.class, event -> {
    World world = event.getWorld();
    MoonPhase phase = event.getNewPhase();

    getLogger().at(Level.INFO).log("Moon phase changed to: " + phase);

    // Full moon special events
    if (phase == MoonPhase.FULL) {
        increaseHostileMobSpawns(world);
        enableWerewolfTransformations(world);
    }

    // New moon darkness events
    if (phase == MoonPhase.NEW) {
        spawnDarkCreatures(world);
    }
});

{{< /tab >}} {{< /tabs >}}

---

Practical Examples

World Manager Plugin

public class WorldManagerPlugin extends JavaPlugin {

    private final Map<String, WorldConfig> worldConfigs = new HashMap<>();

    @Override
    public void start() {
        // Track world additions
        getEventRegistry().register(AddWorldEvent.class, event -> {
            World world = event.getWorld();
            WorldConfig config = loadWorldConfig(world.getName());
            worldConfigs.put(world.getName(), config);

            // Apply world-specific settings
            applyWorldConfig(world, config);
        });

        // Handle world removal
        getEventRegistry().register(RemoveWorldEvent.class, event -> {
            World world = event.getWorld();
            WorldConfig config = worldConfigs.remove(world.getName());

            if (config != null) {
                saveWorldConfig(world.getName(), config);
            }
        });

        // Initialize when all worlds ready
        getEventRegistry().register(AllWorldsLoadedEvent.class, event -> {
            getLogger().at(Level.INFO).log("Initializing world manager with " +
                event.getWorlds().size() + " worlds");
            initializeCrossWorldFeatures();
        });
    }
}

Chunk Protection System

public class ChunkProtectionPlugin extends JavaPlugin {

    private final Set<ChunkCoord> protectedChunks = new HashSet<>();

    @Override
    public void start() {
        // Load protected chunks when chunk loads
        getEventRegistry().register(ChunkLoadEvent.class, event -> {
            Chunk chunk = event.getChunk();
            ChunkCoord coord = new ChunkCoord(
                event.getWorld().getName(),
                chunk.getX(),
                chunk.getZ()
            );

            if (isChunkProtected(coord)) {
                protectedChunks.add(coord);
                // Apply chunk-level protection
                markChunkAsProtected(chunk);
            }
        });

        // Save protection status on unload
        getEventRegistry().register(ChunkUnloadEvent.class, event -> {
            Chunk chunk = event.getChunk();
            ChunkCoord coord = new ChunkCoord(
                event.getWorld().getName(),
                chunk.getX(),
                chunk.getZ()
            );

            if (protectedChunks.contains(coord)) {
                saveProtectionStatus(coord);
            }
        });
    }

    public void protectChunk(World world, int chunkX, int chunkZ) {
        ChunkCoord coord = new ChunkCoord(world.getName(), chunkX, chunkZ);
        protectedChunks.add(coord);
        saveProtectionStatus(coord);
    }
}

Dynamic World Events

public class DynamicWorldPlugin extends JavaPlugin {

    @Override
    public void start() {
        // Moon phase effects
        getEventRegistry().register(MoonPhaseChangeEvent.class, event -> {
            World world = event.getWorld();
            MoonPhase phase = event.getNewPhase();

            switch (phase) {
                case FULL:
                    broadcastToWorld(world, "The full moon rises...");
                    applyMoonEffect(world, "mob_spawn_increase", 2.0);
                    break;
                case NEW:
                    broadcastToWorld(world, "Darkness falls...");
                    applyMoonEffect(world, "visibility_decrease", 0.5);
                    break;
                default:
                    clearMoonEffects(world);
            }
        });

        // Custom chunk generation
        getEventRegistry().register(ChunkLoadEvent.class, event -> {
            if (event.isNewChunk()) {
                Chunk chunk = event.getChunk();

                // Add mystery locations
                if (random.nextFloat() < 0.01) {  // 1% chance
                    generateMysteryStructure(chunk);
                }

                // Add resource nodes
                populateResourceNodes(chunk, event.getWorld());
            }
        });
    }
}

Best Practices

{{< callout type="info" >}} World Event Guidelines:

• Use AllWorldsLoadedEvent for cross-world initialization
• Save important data in ChunkUnloadEvent and RemoveWorldEvent
• Use isNewChunk() to avoid regenerating content in existing chunks
• Be careful with cancelling AddWorldEvent and RemoveWorldEvent
• Consider memory usage when storing per-chunk data {{< /callout >}}

{{< callout type="warning" >}} Performance Note: Chunk events can fire frequently during player movement. Keep handlers lightweight and avoid blocking operations. {{< /callout >}}