Init
This commit is contained in:
496
content/core-concepts/events/event-reference/world-events.en.md
Normal file
496
content/core-concepts/events/event-reference/world-events.en.md
Normal file
@@ -0,0 +1,496 @@
|
||||
---
|
||||
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 >}}
|
||||
Reference in New Issue
Block a user