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

title, type, weight

title	type	weight
Spawn Suppression	docs	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

# 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

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

public class SpawnSuppressionComponent implements Component<EntityStore> {
    private String spawnSuppression;  // Asset ID reference

    public String getSpawnSuppression();
    public void setSpawnSuppression(String spawnSuppression);
}

Component Usage

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

public static final BuilderCodec<SpawnSuppressionComponent> CODEC = BuilderCodec.builder(...)
    .append(new KeyedCodec<>("SpawnSuppression", Codec.STRING), ...)
    .build();

Suppression Controller

SpawnSuppressionController

Manages active suppression zones:

// Controller tracks active suppressions
// Calculates affected chunks
// Updates suppression state

Chunk Suppression

ChunkSuppressionEntry

Tracks suppression state per chunk:

// Records which suppressions affect each chunk
// Cached for efficient spawn checks

ChunkSuppressionQueue

Queue of pending suppression updates:

// Handles async suppression calculations
// Processes additions and removals

ChunkSuppressionSystems

Processes chunk-level suppression:

getEntityStoreRegistry().registerSystem(new ChunkSuppressionSystems());

Suppression Systems

SpawnSuppressionSystems

Main suppression logic:

// Processes SpawnSuppressionComponent entities
// Updates affected chunk data
// Triggers suppression state changes

SpawnMarkerSuppressionSystem

Handles spawn marker suppression:

// Disables markers within suppression radius
// Re-enables when suppression removed

Suppression Utilities

SuppressionSpanHelper

Calculates suppression spans:

SuppressionSpanHelper helper = new SuppressionSpanHelper();
// Computes which chunks fall within suppression radius
// Handles edge cases at chunk boundaries

SpawnSuppressorEntry

Tracks individual suppressor entities:

// Links entity reference to suppression config
// Enables efficient lookup and cleanup

API Usage

Create Suppression Zone

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

// Suppression is checked automatically during spawn attempts
// The spawning system queries suppression state per chunk

Remove Suppression

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

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