Init

content/world/entities/spawning/world-spawning.en.md

@@ -0,0 +1,260 @@
+---
+title: World Spawning
+type: docs
+weight: 1
+---
+
+World spawning manages ambient NPC spawning based on environment, biome, and chunk conditions.
+
+**Package:** `com.hypixel.hytale.server.spawning.world`
+
+## Architecture
+
+```
+World Spawning
+├── Manager
+│   └── WorldSpawnManager - Central spawn coordination
+├── Components
+│   ├── WorldSpawnData - World-level spawn state
+│   ├── ChunkSpawnData - Per-chunk spawn tracking
+│   ├── ChunkSpawnedNPCData - Spawned NPC records
+│   └── SpawnJobData - Active spawn jobs
+├── Systems
+│   ├── WorldSpawningSystem - Main spawning logic
+│   ├── WorldSpawnTrackingSystem - Track spawned entities
+│   ├── WorldSpawnJobSystems - Job processing
+│   ├── ChunkSpawningSystems - Chunk-level spawning
+│   └── MoonPhaseChangeEventSystem - Lunar spawn modifiers
+└── Config
+    ├── WorldNPCSpawn - Spawn definitions
+    ├── NPCSpawn - Base spawn config
+    └── RoleSpawnParameters - Role-specific params
+```
+
+## WorldSpawnManager
+
+Central manager for world-level NPC spawning:
+
+```java
+WorldSpawnManager manager = SpawningPlugin.get().getWorldSpawnManager();
+```
+
+The manager coordinates spawning across chunks based on:
+- Environment type
+- Biome conditions
+- Light levels
+- Moon phase
+- Player proximity
+
+## World Spawn Configuration
+
+### WorldNPCSpawn Asset
+
+```yaml
+# NPC/Spawn/World/forest_creatures.json
+{
+  "Id": "forest_creatures",
+  "NPCRole": "deer",
+  "SpawnWeight": 10,
+  "MinGroupSize": 1,
+  "MaxGroupSize": 3,
+  "Environments": ["forest", "plains"],
+  "LightType": "Day",
+  "MinLightLevel": 8,
+  "MaxLightLevel": 15
+}
+```
+
+### NPCSpawn Base Configuration
+
+```java
+public class NPCSpawn {
+    protected String npcRole;          // NPC role to spawn
+    protected int spawnWeight;         // Spawn probability weight
+    protected int minGroupSize;        // Minimum group size
+    protected int maxGroupSize;        // Maximum group size
+}
+```
+
+### RoleSpawnParameters
+
+Per-role spawn parameters:
+
+```java
+public class RoleSpawnParameters {
+    // Role-specific spawn configuration
+    // Defines constraints and behaviors per NPC type
+}
+```
+
+## Environment-Based Spawning
+
+### EnvironmentSpawnParameters
+
+```java
+EnvironmentSpawnParameters params = new EnvironmentSpawnParameters();
+// Parameters specific to environment type
+```
+
+### Light Type Filtering
+
+```java
+public enum LightType {
+    Any,        // Spawn at any light level
+    Day,        // Only spawn during day
+    Night       // Only spawn at night
+}
+```
+
+Used with `LightRangePredicate` to filter spawn positions:
+
+```java
+LightRangePredicate predicate = new LightRangePredicate(minLight, maxLight, lightType);
+boolean canSpawn = predicate.test(world, position);
+```
+
+## Chunk-Level Management
+
+### ChunkSpawnData
+
+Tracks spawn state per chunk:
+
+```java
+ComponentType<ChunkStore, ChunkSpawnData> type =
+    SpawningPlugin.get().getChunkSpawnDataComponentType();
+ChunkSpawnData data = chunkStore.getComponent(chunkRef, type);
+```
+
+### ChunkSpawnedNPCData
+
+Records which NPCs were spawned in a chunk:
+
+```java
+// Tracks spawned entities for cleanup and respawning
+```
+
+### ChunkEnvironmentSpawnData
+
+Environment-specific spawn data per chunk:
+
+```java
+// Caches environment conditions for spawn decisions
+```
+
+## Spawn Job System
+
+### SpawnJob
+
+Base class for spawn operations:
+
+```java
+public class SpawnJob {
+    // Asynchronous spawn operation
+}
+```
+
+### SpawnJobData Component
+
+Tracks active spawn jobs:
+
+```java
+SpawnJobData jobData = store.getComponent(worldRef, SpawnJobData.getComponentType());
+```
+
+### WorldSpawnJobSystems
+
+Processes spawn jobs:
+
+```java
+// System that executes pending spawn jobs
+// Handles spawn position validation
+// Creates NPCs when conditions are met
+```
+
+## World Spawn Systems
+
+### WorldSpawningSystem
+
+Main system for world spawning logic:
+
+```java
+getEntityStoreRegistry().registerSystem(new WorldSpawningSystem());
+```
+
+This system:
+1. Checks spawn conditions per chunk
+2. Selects appropriate NPC types
+3. Validates spawn positions
+4. Creates spawn jobs
+
+### WorldSpawnTrackingSystem
+
+Tracks spawned entities for management:
+
+```java
+// Monitors spawned NPCs
+// Handles despawn when conditions change
+// Updates spawn counts
+```
+
+### MoonPhaseChangeEventSystem
+
+Adjusts spawning based on moon phase:
+
+```java
+// Modifies spawn rates during different moon phases
+// Enables special night spawns during full moon
+```
+
+## Position Selection
+
+### FloodFillPositionSelector
+
+Finds valid spawn positions using flood fill:
+
+```java
+FloodFillPositionSelector selector = new FloodFillPositionSelector();
+// Searches for suitable spawn locations
+```
+
+### RandomChunkColumnIterator
+
+Iterates through random positions in a chunk column:
+
+```java
+RandomChunkColumnIterator iterator = new RandomChunkColumnIterator();
+// Provides random positions for spawn attempts
+```
+
+### ChunkColumnMask
+
+Masks specific areas within a chunk:
+
+```java
+ChunkColumnMask mask = new ChunkColumnMask();
+// Excludes certain positions from spawning
+```
+
+## API Usage
+
+### Check World Spawn State
+
+```java
+WorldSpawnData worldData = store.getComponent(worldRef, WorldSpawnData.getComponentType());
+```
+
+### Get Spawn Wrapper
+
+```java
+WorldSpawnWrapper wrapper = manager.getSpawnWrapper(spawnIndex);
+WorldNPCSpawn spawn = wrapper.getSpawn();
+```
+
+## Spawn Statistics
+
+Track spawning metrics with `WorldNPCSpawnStat`:
+
+```java
+// Records spawn attempts, successes, and failures
+// Used by /spawning stats command
+```