Hytale Mob Spawning System: Beacons, Markers, and Spawn Suppression

Hytale's mob spawning system is fully data-driven and surprisingly sophisticated. Rather than scattering spawn logic across entity classes, Hytale centralizes everything into a dedicated spawning package with three distinct spawn mechanisms, a spatial validation pipeline, and a suppression system for controlling spawn density. This reference is based on Hytale server version 2026.03.26-89796e57b.

Architecture Overview

The spawning system is managed by SpawningPlugin, which registers all spawn-related components, systems, and asset types. It coordinates three independent spawn mechanisms:

1. World Spawns — environment-driven ambient spawning (passive mobs, wildlife)
2. Spawn Beacons — player-proximity spawning with cooldowns and radius control (hostile encounters)
3. Spawn Markers — fixed-position spawning with respawn timers (dungeon guards, quest NPCs)

Each mechanism shares a common NPCSpawn base configuration and uses SpawningContext to validate candidate positions before placing entities.

NPCSpawn: The Shared Configuration Base

All three spawn types extend NPCSpawn, which defines the conditions under which NPCs can appear:

public abstract class NPCSpawn {
    protected RoleSpawnParameters[] npcs;       // Weighted list of NPC roles
    protected DespawnParameters despawnParameters;
    protected String[] environments;             // e.g. "Forest", "Desert"
    protected double[] dayTimeRange;             // Hour range [0-24]
    protected int[] moonPhaseRange;              // Moon phase filter
    protected Map<LightType, double[]> lightTypeMap; // Light level constraints
    protected boolean scaleDayTimeRange;         // Scale relative to day/night cycle
}

The RoleSpawnParameters class defines each NPC that can spawn, along with a weight for weighted random selection:

public class RoleSpawnParameters implements IWeightedElement {
    protected String id;              // NPC Role ID (e.g. "Kweebec_Villager")
    protected double weight;          // Relative spawn chance
    protected String spawnBlockSet;   // Optional: blocks this NPC can spawn on
    protected String spawnFluidTag;   // Optional: fluids this NPC can spawn on
    protected String flockDefinitionId; // Optional: spawn as a flock/group
}

Light Types

Hytale supports six light channels for spawn control, going well beyond the typical “light level” check:

• Light — total combined light level
• SkyLight — how exposed the position is to open sky (low in caves)
• Sunlight — time-of-day based light (peaks at noon, zero at night)
• RedLight, GreenLight, BlueLight — colored light channels

Each channel accepts a range from 0 to 100, allowing fine-grained control like “only spawn in caves with no sky exposure” or “only spawn under red torchlight.”

World Spawns

WorldNPCSpawn handles ambient spawning tied to environments (biomes). These are the mobs that appear naturally as you explore.

public class WorldNPCSpawn extends NPCSpawn {
    protected double[] moonPhaseWeightModifiers;
}

The moonPhaseWeightModifiers array lets you scale spawn rates per moon phase. Hytale has 5 moon phases (day 0 = full moon, day 4 = new moon), and each modifier multiplies the NPC's weight:

{
    "Id": "NightCreatures",
    "Environments": ["Dark_Forest"],
    "DayTimeRange": [20, 6],
    "NPCs": [
        { "Id": "Shadow_Wolf", "Weight": 2.0 }
    ],
    "MoonPhaseWeightModifiers": [0, 0, 0.5, 1, 2]
}

This configuration spawns Shadow Wolves only at night in Dark Forests, with zero spawns during the full moon but double spawns during the new moon.

The WorldSpawnManager processes world spawns per chunk, using EnvironmentSpawnParameters to track how many NPCs of each type exist in each environment and enforce population caps. An overpopulation ratio of 25% prevents any single NPC group from dominating.

Spawn Beacons

BeaconNPCSpawn creates invisible entities near players that periodically spawn hostile NPCs. This is how Hytale generates combat encounters that feel dynamic rather than pre-placed.

Key configuration fields:

public class BeaconNPCSpawn extends NPCSpawn {
    protected double targetDistanceFromPlayer = 15.0;  // Ideal spawn distance
    protected double minDistanceFromPlayer = 5.0;      // Hard minimum distance
    protected double beaconRadius = 20.0;              // NPC influence radius
    protected double spawnRadius = 15.0;               // Physical spawn area
    protected int maxSpawnedNpcs = 1;                  // Population cap
    protected int[] concurrentSpawnsRange = {1, 1};    // NPCs per spawn wave
    protected Duration[] spawnAfterGameTime;            // Cooldown (game time)
    protected Duration[] spawnAfterRealTime;            // Cooldown (real time)
    protected String npcSpawnState;                     // Initial AI state
    protected String targetSlot = "LockedTarget";       // Target assignment
}

When a beacon spawns an NPC, it calls postSpawn to immediately assign the triggering player as the NPC's locked target and optionally force an AI state:

protected static void postSpawn(NPCEntity npc, Ref<EntityStore> selfRef,
        BeaconNPCSpawn spawn, Ref<EntityStore> targetRef,
        ComponentAccessor<EntityStore> componentAccessor) {
    Role role = npc.getRole();
    role.getMarkedEntitySupport().setMarkedEntity(spawn.getTargetSlot(), targetRef);
    String spawnState = spawn.getNpcSpawnState();
    if (spawnState != null) {
        role.getStateSupport().setState(selfRef, spawnState,
            spawn.getNpcSpawnSubState(), componentAccessor);
    }
}

Setting NPCSpawnState to "Chase" makes spawned mobs immediately aggro the nearest player. Without it, NPCs spawn idle and rely on their sensors to detect threats.

Beacons also support scaling curves (MaxSpawnsScalingCurve and ConcurrentSpawnsScalingCurve) that increase spawn intensity based on the number of nearby players, enabling multiplayer-aware difficulty scaling.

Beacons use a FloodFillPositionSelector to pre-calculate valid spawn positions within their radius, caching positions per NPC role. When a beacon can't find valid positions for any of its NPC types, it removes itself and logs a warning.

Spawn Markers

SpawnMarker assets define fixed-position spawns with respawn timers. Unlike beacons, markers spawn NPCs at their exact location and rotation, making them ideal for guarding specific points:

{
    "Id": "DungeonGuard",
    "ExclusionRadius": 10.0,
    "MaxDropHeight": 4.0,
    "DeactivationDistance": 40.0,
    "RealtimeRespawn": true,
    "NPCs": [
        {
            "Name": "Skeleton_Guard",
            "Weight": 1.0,
            "RealtimeRespawnTime": 120.0
        },
        {
            "Name": "Skeleton_Archer",
            "Weight": 0.5,
            "RealtimeRespawnTime": 180.0
        }
    ]
}

Key features of spawn markers:

• ExclusionRadius — prevents spawning if an adventure-mode player is within range (so mobs don't pop into existence in front of you)
• MaxDropHeight — if the terrain below the marker has been destroyed, mobs won't spawn if the ground is too far below
• DeactivationDistance — when no players are nearby, the marker deactivates and stores its NPCs
• ManualTrigger — markers can be set to only spawn when triggered by an interaction or game event
• Flock support — each spawn configuration can reference a FlockAsset to spawn groups

Respawn timing can use either real time (RealtimeRespawnTime in seconds) or game time (SpawnAfterGameTime as an ISO 8601 duration like "PT2H" for 2 in-game hours).

SpawningContext: Position Validation

Before any NPC is placed in the world, SpawningContext validates the candidate position through a multi-step pipeline:

1. Spawn Span Detection — scans the block column to find vertical spans of non-solid blocks tall enough for the NPC's model bounding box
2. Ground Level Resolution — identifies the solid ground block and calculates the exact Y spawn position based on block height
3. Water Level Detection — tracks fluid blocks to determine if the NPC would be underwater
4. Breathability Check — verifies the NPC can breathe at the spawn position (air-breathers need their eye height above water, water-breathers need submersion)
5. Collision Validation — uses CollisionModule to verify the NPC's bounding box doesn't intersect any solid blocks
6. Entity Overlap — checks for intersection with existing entities

The SpawnTestResult enum captures exactly why a spawn attempt failed:

public enum SpawnTestResult {
    TEST_OK,
    FAIL_NO_POSITION,
    FAIL_INVALID_POSITION,
    FAIL_INTERSECT_ENTITY,
    FAIL_NO_MOTION_CONTROLLERS,
    FAIL_NOT_SPAWNABLE,
    FAIL_NOT_BREATHABLE
}

SpawningContext also supports three placement modes via helper methods:

• isOnSolidGround() — standard ground placement
• isInWater(float minDepth) — underwater placement at a minimum depth
• isInAir(double height) — aerial placement at a specific height above ground

Spawn Suppression

The suppression system lets you carve out spawn-free zones. SpawnSuppression assets define a radius and a list of NPC groups to suppress:

public class SpawnSuppression {
    protected double radius = 10.0;
    protected String[] suppressedGroups;    // NPCGroup IDs to block
    protected boolean suppressSpawnMarkers; // Also suppress markers?
}

Suppression works on a per-chunk basis for horizontal distance (for efficiency) but uses exact Y-axis distance. This means NPCs can still spawn in caves beneath a suppression zone or in the sky above, which keeps the world feeling alive while preventing specific areas from being overrun.

Beacons can opt out of suppression entirely using the OverrideSpawnSuppressors flag, which is useful for scripted encounters or boss fights that must spawn regardless of nearby suppression zones.

Practical Examples for Modders

Custom Night Spawn with Light Constraints

{
    "Id": "CaveBats",
    "Environments": ["Underground"],
    "LightRanges": {
        "SkyLight": [0, 10],
        "Light": [0, 30]
    },
    "NPCs": [
        { "Id": "Cave_Bat", "Weight": 1.0, "SpawnBlockSet": "StoneBlocks" }
    ]
}

Encounter Beacon with Multiplayer Scaling

{
    "Id": "ForestAmbush",
    "Environments": ["Forest"],
    "DayTimeRange": [20, 5],
    "TargetDistanceFromPlayer": 20.0,
    "MinDistanceFromPlayer": 8.0,
    "BeaconRadius": 30.0,
    "SpawnRadius": 20.0,
    "MaxSpawnedNPCs": 3,
    "ConcurrentSpawnsRange": [1, 2],
    "SpawnAfterRealTimeRange": ["PT30S", "PT60S"],
    "NPCSpawnState": "Chase",
    "TargetSlot": "LockedTarget",
    "NPCs": [
        { "Id": "Forest_Bandit", "Weight": 2.0 },
        { "Id": "Forest_Bandit_Archer", "Weight": 1.0 }
    ],
    "MaxSpawnsScalingCurve": {
        "Points": [[1, 0], [4, 3]]
    }
}

This beacon spawns bandits near players at night in forests, immediately putting them in chase mode. With 4 players nearby, the max NPC count scales from 3 to 6.

Summary

Hytale's spawning system is one of its most modder-friendly subsystems. The entire pipeline — from spawn conditions to position validation to population control — is configured through JSON assets rather than code. World spawns handle ambient life, beacons create dynamic encounters, and markers control fixed positions. Combined with light-channel filtering, moon phase modifiers, and spawn suppression, modders have precise control over when, where, and how many NPCs appear in their worlds.