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

title, type, weight

title	type	weight
Spawner Assets	docs	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/

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

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
}

{
  "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)

{
  "RealtimeRespawn": true,
  "NPCs": [{ "RealtimeRespawnTime": 120.0 }]
}

Game Time: Uses SpawnAfterGameTime (ISO 8601 duration)

{
  "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:

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

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

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

Beacon Systems

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

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

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

Light Level Filtering

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

Light types: Any, Day, Night

Spawn Marker Entity

SpawnMarkerEntity Component

Entity representing a spawn marker in the world:

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

Marker Block State

Spawn markers can be placed as blocks:

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

public class SpawnMarkerBlockReference {
    // Reference to marker block
}

Interactions

TriggerSpawnMarkersInteraction

Manually trigger spawn markers via interaction:

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

Registered as:

getCodecRegistry(Interaction.CODEC).register(
    "TriggerSpawnMarkers",
    TriggerSpawnMarkersInteraction.class,
    TriggerSpawnMarkersInteraction.CODEC
);

API Usage

Access Spawn Marker Assets

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

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

Validate Marker Asset

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

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