Init

content/world/entities/spawning/spawn-suppression.en.md

@@ -0,0 +1,249 @@
+---
+title: Spawn Suppression
+type: docs
+weight: 2
+---
+
+Spawn suppression allows preventing NPC spawning within defined areas, useful for safe zones, player bases, and controlled environments.
+
+**Package:** `com.hypixel.hytale.server.spawning.suppression`
+
+## Architecture
+
+```
+Spawn Suppression
+├── Assets
+│   └── SpawnSuppression - Suppression zone definitions
+├── Components
+│   ├── SpawnSuppressionComponent - Entity-attached suppression
+│   ├── SpawnSuppressionController - Suppression logic
+│   ├── ChunkSuppressionEntry - Chunk suppression data
+│   └── ChunkSuppressionQueue - Pending suppressions
+├── Systems
+│   ├── SpawnSuppressionSystems - Main suppression logic
+│   ├── ChunkSuppressionSystems - Chunk-level processing
+│   └── SpawnMarkerSuppressionSystem - Marker suppression
+└── Utilities
+    ├── SuppressionSpanHelper - Span calculations
+    └── SpawnSuppressorEntry - Suppressor tracking
+```
+
+## SpawnSuppression Asset
+
+### Asset Configuration
+
+```yaml
+# NPC/Spawn/Suppression/safe_zone.json
+{
+  "Id": "safe_zone",
+  "SuppressionRadius": 50.0,
+  "SuppressedGroups": ["hostile", "neutral_aggressive"],
+  "SuppressSpawnMarkers": true
+}
+```
+
+### Asset Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `Id` | String | Unique suppression identifier |
+| `SuppressionRadius` | Double | Radius of suppression effect |
+| `SuppressedGroups` | String[] | NPCGroup IDs to suppress |
+| `SuppressSpawnMarkers` | Boolean | Also suppress spawn markers |
+
+### Asset Access
+
+```java
+// Get suppression asset
+SpawnSuppression suppression = SpawnSuppression.getAssetMap().getAsset("safe_zone");
+
+// Get properties
+double radius = suppression.getRadius();
+int[] suppressedGroups = suppression.getSuppressedGroupIds();
+boolean suppressMarkers = suppression.isSuppressSpawnMarkers();
+```
+
+## SpawnSuppressionComponent
+
+Attaches suppression behavior to entities:
+
+```java
+public class SpawnSuppressionComponent implements Component<EntityStore> {
+    private String spawnSuppression;  // Asset ID reference
+
+    public String getSpawnSuppression();
+    public void setSpawnSuppression(String spawnSuppression);
+}
+```
+
+### Component Usage
+
+```java
+// Get component type
+ComponentType<EntityStore, SpawnSuppressionComponent> type =
+    SpawningPlugin.get().getSpawnSuppressorComponentType();
+
+// Attach to entity
+SpawnSuppressionComponent comp = new SpawnSuppressionComponent("safe_zone");
+store.setComponent(entityRef, type, comp);
+
+// Read from entity
+SpawnSuppressionComponent existing = store.getComponent(entityRef, type);
+String suppressionId = existing.getSpawnSuppression();
+```
+
+### Component Codec
+
+```java
+public static final BuilderCodec<SpawnSuppressionComponent> CODEC = BuilderCodec.builder(...)
+    .append(new KeyedCodec<>("SpawnSuppression", Codec.STRING), ...)
+    .build();
+```
+
+## Suppression Controller
+
+### SpawnSuppressionController
+
+Manages active suppression zones:
+
+```java
+// Controller tracks active suppressions
+// Calculates affected chunks
+// Updates suppression state
+```
+
+## Chunk Suppression
+
+### ChunkSuppressionEntry
+
+Tracks suppression state per chunk:
+
+```java
+// Records which suppressions affect each chunk
+// Cached for efficient spawn checks
+```
+
+### ChunkSuppressionQueue
+
+Queue of pending suppression updates:
+
+```java
+// Handles async suppression calculations
+// Processes additions and removals
+```
+
+### ChunkSuppressionSystems
+
+Processes chunk-level suppression:
+
+```java
+getEntityStoreRegistry().registerSystem(new ChunkSuppressionSystems());
+```
+
+## Suppression Systems
+
+### SpawnSuppressionSystems
+
+Main suppression logic:
+
+```java
+// Processes SpawnSuppressionComponent entities
+// Updates affected chunk data
+// Triggers suppression state changes
+```
+
+### SpawnMarkerSuppressionSystem
+
+Handles spawn marker suppression:
+
+```java
+// Disables markers within suppression radius
+// Re-enables when suppression removed
+```
+
+## Suppression Utilities
+
+### SuppressionSpanHelper
+
+Calculates suppression spans:
+
+```java
+SuppressionSpanHelper helper = new SuppressionSpanHelper();
+// Computes which chunks fall within suppression radius
+// Handles edge cases at chunk boundaries
+```
+
+### SpawnSuppressorEntry
+
+Tracks individual suppressor entities:
+
+```java
+// Links entity reference to suppression config
+// Enables efficient lookup and cleanup
+```
+
+## API Usage
+
+### Create Suppression Zone
+
+```java
+// 1. Define asset in JSON
+// NPC/Spawn/Suppression/player_base.json
+
+// 2. Attach component to entity
+SpawnSuppressionComponent comp = new SpawnSuppressionComponent("player_base");
+store.setComponent(entityRef, SpawnSuppressionComponent.getComponentType(), comp);
+```
+
+### Check If Position Suppressed
+
+```java
+// Suppression is checked automatically during spawn attempts
+// The spawning system queries suppression state per chunk
+```
+
+### Remove Suppression
+
+```java
+// Remove component to disable suppression
+store.removeComponent(entityRef, SpawnSuppressionComponent.getComponentType());
+```
+
+## Suppression Behavior
+
+### Radius Calculation
+
+Suppression uses 3D distance with optimization:
+- X/Z: Affects entire chunks within radius
+- Y: Uses exact distance calculation
+
+This allows NPCs to spawn in caves below or sky above a suppression zone.
+
+### Group Filtering
+
+Only specified NPC groups are suppressed:
+
+```yaml
+{
+  "SuppressedGroups": ["hostile"]
+  // Hostile NPCs blocked
+  // Friendly/neutral NPCs can still spawn
+}
+```
+
+### Marker Suppression
+
+When `SuppressSpawnMarkers` is true:
+- Spawn markers within radius stop functioning
+- They resume when suppression is removed
+- Does not permanently delete markers
+
+## Commands
+
+Access via `/spawning suppression`:
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List active suppressions |
+| `info <id>` | Show suppression details |
+| `clear <id>` | Remove suppression |