---
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<World>` | All loaded worlds |
{{< /tab >}}
{{< tab >}}
- `getWorlds()` - Returns list of all loaded worlds
{{< /tab >}}
{{< tab >}}
```java
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 >}}
```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<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

```java
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

```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 >}}
