--- title: World Events type: docs weight: 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 >}} ```java 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 >}} ```java 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 >}} ```java 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` | All loaded worlds | {{< /tab >}} {{< tab >}} - `getWorlds()` - Returns list of all loaded worlds {{< /tab >}} {{< tab >}} ```java getEventRegistry().register(AllWorldsLoadedEvent.class, event -> { List 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 >}} ```java 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 >}} ```java 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 >}} ```java 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 >}} ```java 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 >}} ```java 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 ```java public class WorldManagerPlugin extends JavaPlugin { private final Map 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 ```java public class ChunkProtectionPlugin extends JavaPlugin { private final Set 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 ```java 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 >}}