Init

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

@@ -0,0 +1,212 @@
+---
+title: Local Spawning
+type: docs
+weight: 3
+---
+
+Local spawning manages NPC spawning around players, ensuring active gameplay areas have appropriate creature density.
+
+**Package:** `com.hypixel.hytale.server.spawning.local`
+
+## Architecture
+
+```
+Local Spawning
+├── Components
+│   ├── LocalSpawnController - Player spawn controller
+│   ├── LocalSpawnBeacon - Local spawn point
+│   └── LocalSpawnState - Spawn state tracking
+└── Systems
+    ├── LocalSpawnSetupSystem - Initialize local spawning
+    ├── LocalSpawnControllerSystem - Process controllers
+    ├── LocalSpawnBeaconSystem - Process beacons
+    └── LocalSpawnForceTriggerSystem - Manual triggers
+```
+
+## LocalSpawnController
+
+Controls local spawning around a player:
+
+```java
+public class LocalSpawnController implements Component<EntityStore> {
+    private double timeToNextRunSeconds;
+
+    public void setTimeToNextRunSeconds(double seconds);
+    public boolean tickTimeToNextRunSeconds(float dt);
+}
+```
+
+### Component Access
+
+```java
+// Get component type
+ComponentType<EntityStore, LocalSpawnController> type =
+    SpawningPlugin.get().getLocalSpawnControllerComponentType();
+
+// Access on player entity
+LocalSpawnController controller = store.getComponent(playerRef, type);
+```
+
+### Spawn Timing
+
+The controller uses a configurable delay before spawning:
+
+```java
+// Initial delay configured in SpawningPlugin
+double joinDelay = SpawningPlugin.get().getLocalSpawnControllerJoinDelay();
+```
+
+This prevents immediate spawning when a player joins, allowing time for world loading.
+
+## LocalSpawnBeacon
+
+Defines local spawn points around players:
+
+```java
+public class LocalSpawnBeacon {
+    // Position and configuration for local spawns
+    // Dynamically created based on player position
+}
+```
+
+### Beacon Usage
+
+Local spawn beacons are automatically managed:
+1. Created around active players
+2. Updated as players move
+3. Removed when players leave area
+
+## LocalSpawnState
+
+Tracks local spawn state:
+
+```java
+public class LocalSpawnState {
+    // Current spawn state for a local spawn controller
+    // Tracks active spawns and cooldowns
+}
+```
+
+## Systems
+
+### LocalSpawnSetupSystem
+
+Initializes local spawning for players:
+
+```java
+getEntityStoreRegistry().registerSystem(new LocalSpawnSetupSystem());
+```
+
+This system:
+- Attaches `LocalSpawnController` to new players
+- Configures initial spawn parameters
+- Sets up spawn beacons
+
+### LocalSpawnControllerSystem
+
+Processes spawn controllers each tick:
+
+```java
+getEntityStoreRegistry().registerSystem(new LocalSpawnControllerSystem());
+```
+
+This system:
+- Decrements spawn timers
+- Checks spawn conditions
+- Triggers spawn jobs when ready
+
+### LocalSpawnBeaconSystem
+
+Manages local spawn beacons:
+
+```java
+getEntityStoreRegistry().registerSystem(new LocalSpawnBeaconSystem());
+```
+
+This system:
+- Updates beacon positions
+- Processes beacon spawn logic
+- Handles beacon lifecycle
+
+### LocalSpawnForceTriggerSystem
+
+Handles forced spawn triggers:
+
+```java
+getEntityStoreRegistry().registerSystem(new LocalSpawnForceTriggerSystem());
+```
+
+Used for:
+- Debug commands
+- Event-triggered spawning
+- Manual population
+
+## API Usage
+
+### Get Local Spawn Controller
+
+```java
+ComponentType<EntityStore, LocalSpawnController> type =
+    LocalSpawnController.getComponentType();
+
+LocalSpawnController controller = store.getComponent(playerRef, type);
+if (controller != null) {
+    // Player has local spawning enabled
+}
+```
+
+### Force Spawn Update
+
+```java
+// Reset spawn timer to trigger immediate check
+LocalSpawnController controller = store.getComponent(playerRef, type);
+controller.setTimeToNextRunSeconds(0);
+```
+
+### Check Spawn Ready
+
+```java
+// Check if spawn timer has elapsed
+boolean ready = controller.tickTimeToNextRunSeconds(deltaTime);
+if (ready) {
+    // Time to attempt spawning
+}
+```
+
+## Configuration
+
+### Join Delay
+
+Configure the delay before local spawning starts for new players:
+
+```java
+double delay = SpawningPlugin.get().getLocalSpawnControllerJoinDelay();
+```
+
+This prevents:
+- Immediate spawn-in ambushes
+- Overwhelming new players
+- Spawning before world is loaded
+
+### Spawn Radius
+
+Local spawning uses a configured radius around players:
+
+```java
+// Spawn radius determines how far from player NPCs can spawn
+// Configured per spawn definition
+```
+
+## Integration with World Spawning
+
+Local spawning works alongside world spawning:
+
+| System | Scope | Trigger |
+|--------|-------|---------|
+| World Spawning | Chunk-based | Chunk loading |
+| Local Spawning | Player-centric | Player proximity |
+
+Both systems:
+- Respect spawn suppression
+- Use same NPC pool
+- Share spawn limits