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

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