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

title, type, weight

title	type	weight
World Spawning	docs	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:

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

# 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

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:

public class RoleSpawnParameters {
    // Role-specific spawn configuration
    // Defines constraints and behaviors per NPC type
}

Environment-Based Spawning

EnvironmentSpawnParameters

EnvironmentSpawnParameters params = new EnvironmentSpawnParameters();
// Parameters specific to environment type

Light Type Filtering

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:

LightRangePredicate predicate = new LightRangePredicate(minLight, maxLight, lightType);
boolean canSpawn = predicate.test(world, position);

Chunk-Level Management

ChunkSpawnData

Tracks spawn state per chunk:

ComponentType<ChunkStore, ChunkSpawnData> type =
    SpawningPlugin.get().getChunkSpawnDataComponentType();
ChunkSpawnData data = chunkStore.getComponent(chunkRef, type);

ChunkSpawnedNPCData

Records which NPCs were spawned in a chunk:

// Tracks spawned entities for cleanup and respawning

ChunkEnvironmentSpawnData

Environment-specific spawn data per chunk:

// Caches environment conditions for spawn decisions

Spawn Job System

SpawnJob

Base class for spawn operations:

public class SpawnJob {
    // Asynchronous spawn operation
}

SpawnJobData Component

Tracks active spawn jobs:

SpawnJobData jobData = store.getComponent(worldRef, SpawnJobData.getComponentType());

WorldSpawnJobSystems

Processes spawn jobs:

// 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:

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:

// Monitors spawned NPCs
// Handles despawn when conditions change
// Updates spawn counts

MoonPhaseChangeEventSystem

Adjusts spawning based on moon phase:

// Modifies spawn rates during different moon phases
// Enables special night spawns during full moon

Position Selection

FloodFillPositionSelector

Finds valid spawn positions using flood fill:

FloodFillPositionSelector selector = new FloodFillPositionSelector();
// Searches for suitable spawn locations

RandomChunkColumnIterator

Iterates through random positions in a chunk column:

RandomChunkColumnIterator iterator = new RandomChunkColumnIterator();
// Provides random positions for spawn attempts

ChunkColumnMask

Masks specific areas within a chunk:

ChunkColumnMask mask = new ChunkColumnMask();
// Excludes certain positions from spawning

API Usage

Check World Spawn State

WorldSpawnData worldData = store.getComponent(worldRef, WorldSpawnData.getComponentType());

Get Spawn Wrapper

WorldSpawnWrapper wrapper = manager.getSpawnWrapper(spawnIndex);
WorldNPCSpawn spawn = wrapper.getSpawn();

Spawn Statistics

Track spawning metrics with WorldNPCSpawnStat:

// Records spawn attempts, successes, and failures
// Used by /spawning stats command