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