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

title, type, weight

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

public class LocalSpawnController implements Component<EntityStore> {
    private double timeToNextRunSeconds;

    public void setTimeToNextRunSeconds(double seconds);
    public boolean tickTimeToNextRunSeconds(float dt);
}

Component Access

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

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

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:

public class LocalSpawnState {
    // Current spawn state for a local spawn controller
    // Tracks active spawns and cooldowns
}

Systems

LocalSpawnSetupSystem

Initializes local spawning for players:

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:

getEntityStoreRegistry().registerSystem(new LocalSpawnControllerSystem());

This system:

• Decrements spawn timers
• Checks spawn conditions
• Triggers spawn jobs when ready

LocalSpawnBeaconSystem

Manages local spawn beacons:

getEntityStoreRegistry().registerSystem(new LocalSpawnBeaconSystem());

This system:

• Updates beacon positions
• Processes beacon spawn logic
• Handles beacon lifecycle

LocalSpawnForceTriggerSystem

Handles forced spawn triggers:

getEntityStoreRegistry().registerSystem(new LocalSpawnForceTriggerSystem());

Used for:

• Debug commands
• Event-triggered spawning
• Manual population

API Usage

Get Local Spawn Controller

ComponentType<EntityStore, LocalSpawnController> type =
    LocalSpawnController.getComponentType();

LocalSpawnController controller = store.getComponent(playerRef, type);
if (controller != null) {
    // Player has local spawning enabled
}

Force Spawn Update

// Reset spawn timer to trigger immediate check
LocalSpawnController controller = store.getComponent(playerRef, type);
controller.setTimeToNextRunSeconds(0);

Check Spawn Ready

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

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:

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