Init

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

@@ -0,0 +1,304 @@
+---
+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();
+```