---
title: Spawner Assets
type: docs
weight: 4
---

Spawner assets define how and where NPCs spawn, including markers for static spawn points and beacons for dynamic spawning.

**Package:** `com.hypixel.hytale.server.spawning.assets`

## Spawn Markers

### SpawnMarker Asset

Markers are static spawn points that spawn NPCs with configurable respawn timing.

**Asset Location:** `NPC/Spawn/Markers/`

```yaml
# NPC/Spawn/Markers/village_guard.json
{
  "Id": "village_guard",
  "Model": "spawn_marker_hostile",
  "ExclusionRadius": 15.0,
  "MaxDropHeight": 2.0,
  "RealtimeRespawn": true,
  "ManualTrigger": false,
  "DeactivationDistance": 40.0,
  "DeactivationTime": 5.0,
  "NPCs": [
    {
      "Name": "guard_soldier",
      "Weight": 70.0,
      "RealtimeRespawnTime": 120.0
    },
    {
      "Name": "guard_captain",
      "Weight": 30.0,
      "RealtimeRespawnTime": 300.0
    }
  ]
}
```

### SpawnMarker Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `Id` | String | Required | Unique marker identifier |
| `Model` | String | Config default | Visual model in creative mode |
| `NPCs` | SpawnConfiguration[] | Required | Weighted NPC list |
| `ExclusionRadius` | Double | 0 | Player exclusion radius |
| `MaxDropHeight` | Double | 2.0 | Max spawn height offset |
| `RealtimeRespawn` | Boolean | false | Use real vs game time |
| `ManualTrigger` | Boolean | false | Require manual activation |
| `DeactivationDistance` | Double | 40.0 | Distance to deactivate |
| `DeactivationTime` | Double | 5.0 | Seconds before deactivation |

### SpawnConfiguration

Individual NPC spawn entry in weighted pool:

```java
public class SpawnConfiguration implements IWeightedElement {
    protected String npc;                    // NPC role name
    protected double weight;                 // Spawn weight
    protected double realtimeRespawnTime;    // Seconds (realtime)
    protected Duration spawnAfterGameTime;   // Duration (game time)
    protected String flockDefinitionId;      // Optional flock
}
```

```yaml
{
  "Name": "forest_deer",
  "Weight": 50.0,
  "RealtimeRespawnTime": 60.0,
  "SpawnAfterGameTime": "PT1H",
  "Flock": "deer_herd"
}
```

### Respawn Timing

Choose between realtime or game time respawning:

**Realtime:** Uses `RealtimeRespawnTime` (seconds)
```yaml
{
  "RealtimeRespawn": true,
  "NPCs": [{ "RealtimeRespawnTime": 120.0 }]
}
```

**Game Time:** Uses `SpawnAfterGameTime` (ISO 8601 duration)
```yaml
{
  "RealtimeRespawn": false,
  "NPCs": [{ "SpawnAfterGameTime": "P1DT6H" }]
}
```

Duration format: `P[days]DT[hours]H[minutes]M[seconds]S`

### Flock Spawning

Spawn a group of NPCs around the main spawn:

```yaml
{
  "Name": "wolf_alpha",
  "Flock": "wolf_pack"
}
```

The flock definition specifies additional NPCs to spawn around the main one.

## Spawn Beacons

### BeaconNPCSpawn

Dynamic spawn points that spawn NPCs within a radius.

**Asset Location:** `NPC/Spawn/Beacons/`

```yaml
# NPC/Spawn/Beacons/dungeon_spawner.json
{
  "Id": "dungeon_spawner",
  "NPCRole": "skeleton_warrior",
  "SpawnWeight": 10,
  "MinGroupSize": 2,
  "MaxGroupSize": 5,
  "Environments": ["dungeon_dark"]
}
```

### SpawnBeacon Component

Entities with spawn beacon behavior:

```java
public class SpawnBeacon {
    // Configuration for beacon spawning
    // Triggers spawning within radius
}
```

### Beacon Systems

```java
// SpawnBeaconSystems processes active beacons
getEntityStoreRegistry().registerSystem(new SpawnBeaconSystems());

// BeaconSpatialSystem handles spatial queries
getEntityStoreRegistry().registerSystem(new BeaconSpatialSystem());
```

## World Spawn Configuration

### WorldNPCSpawn

Environment-based ambient spawning.

**Asset Location:** `NPC/Spawn/World/`

```yaml
# NPC/Spawn/World/forest_fauna.json
{
  "Id": "forest_fauna",
  "NPCRole": "rabbit",
  "SpawnWeight": 20,
  "MinGroupSize": 1,
  "MaxGroupSize": 3,
  "Environments": ["forest", "grassland"],
  "LightType": "Day",
  "MinLightLevel": 8
}
```

### NPCSpawn Base Fields

| Field | Type | Description |
|-------|------|-------------|
| `NPCRole` | String | NPC role to spawn |
| `SpawnWeight` | Integer | Spawn probability weight |
| `MinGroupSize` | Integer | Minimum NPCs to spawn |
| `MaxGroupSize` | Integer | Maximum NPCs to spawn |

### Environment Filtering

Restrict spawning to specific environments:

```yaml
{
  "Environments": ["cave_dark", "dungeon"]
}
```

### Light Level Filtering

```yaml
{
  "LightType": "Night",
  "MinLightLevel": 0,
  "MaxLightLevel": 7
}
```

Light types: `Any`, `Day`, `Night`

## Spawn Marker Entity

### SpawnMarkerEntity Component

Entity representing a spawn marker in the world:

```java
ComponentType<EntityStore, SpawnMarkerEntity> type =
    SpawningPlugin.get().getSpawnMarkerEntityComponentType();
```

### Marker Block State

Spawn markers can be placed as blocks:

```java
public class SpawnMarkerBlockState {
    // Block-based spawn marker
}

public class SpawnMarkerBlockReference {
    // Reference to marker block
}
```

## Interactions

### TriggerSpawnMarkersInteraction

Manually trigger spawn markers via interaction:

```yaml
# Item or block interaction
{
  "Type": "TriggerSpawnMarkers",
  "MarkerIds": ["ambush_1", "ambush_2"],
  "Radius": 50.0
}
```

Registered as:
```java
getCodecRegistry(Interaction.CODEC).register(
    "TriggerSpawnMarkers",
    TriggerSpawnMarkersInteraction.class,
    TriggerSpawnMarkersInteraction.CODEC
);
```

## API Usage

### Access Spawn Marker Assets

```java
// Get marker asset
SpawnMarker marker = SpawnMarker.getAssetMap().getAsset("village_guard");

// Get weighted configurations
IWeightedMap<SpawnConfiguration> npcs = marker.getWeightedConfigurations();

// Get random NPC from pool
SpawnConfiguration selected = npcs.getRandom(random);
String npcRole = selected.getNpc();
```

### Access Spawn Suppression

```java
SpawnSuppression suppression = SpawnSuppression.getAssetMap().getAsset("safe_zone");
double radius = suppression.getRadius();
```

### Validate Marker Asset

```java
// Validation happens on plugin start
// Warns about:
// - Missing respawn times
// - Conflicting realtime/game time settings
// - Invalid NPC roles
```

## Asset Loading Order

Spawn assets have dependencies:

```java
// Markers load after models and NPC roles
HytaleAssetStore.builder(...)
    .loadsAfter(ModelAsset.class)
    .loadsAfter(NPCRole.class)
    .build();
```