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

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