RegionSpawnMobs

ByMATIASTGM
Mods

Take full control of how mobs spawn in your world. Define where they appear, how many, when, and under what conditions.

Description

RegionSpawnMobs – Admin Guide (BETA)

Project Status: BETA

Version: 1.1.3

This plugin is under active development and currently in BETA.

Core features are working and optimized
Bugs may occur — please report issues
Feedback and suggestions are welcome

Recommendation: Test on a development server before using in production.

What is RegionSpawnMobs?

RegionSpawnMobs is a plugin for Hytale servers that allows admins to create custom mob spawn regions with control over:

Where mobs appear (exact 3D area)
Which mobs appear (multiple types per region)
When they appear (configurable interval via presets)
How many appear (dynamic capacity based on region size)
Player proximity (spawn only when players are nearby — in chunks)
Chunk density (limits mobs per chunk to avoid overcrowding)
Spawn mode (CONTINUOUS, WAVE or THRESHOLD per region)
SpawnPoints (fixed positions inside the region where mobs appear)
Smart containment (keeps mobs in the region without breaking combat)
Folder organization (group regions into folders and sub-folders)

Use Cases

Combat Arenas: continuous PvE spawns within a fixed area
Dungeons/Raids: specific rooms with specific mobs and spawn rates
Farm Zones: predictable spawns for grinding
Natural Habitats: controlled spawns for themed areas
Special Events: temporary regions you can enable/disable
Content Hierarchy: organize regions in folders like dungeons/boss_room or world/forest/wolves

Quick Start

1) Select the area

/pos1
/pos2

2) Create the region

/rsmcreate <region_name>

Or with a folder:

/rsmcreate <folder> <region_name>
/rsmcreate <folder> <category> <region_name>

Example:

/rsmcreate wolf_arena
/rsmcreate dungeons wolf_arena
/rsmcreate dungeons bosses wolf_arena

3) Add mobs (with weights)

/rsmaddmob <region_name> <mob_type> <weight>

Example:

/rsmaddmob wolf_arena wolf_black 70
/rsmaddmob wolf_arena wolf_white 30

(70/30 weight split)

4) (Optional) Add SpawnPoints

Stand inside the region and run:

/rsmaddspawnpoint [name]

When SpawnPoints exist, mobs spawn exclusively at those positions.

Folder Organization

Regions can be grouped into folders to make managing large servers easier:

regions/
├── wolf_arena.json          ← root
├── dungeons/
│   ├── entrance.json
│   └── boss_room.json
└── world/
    ├── forest/
    │   └── wolves.json
    └── caves/
        └── skeletons.json

To reference a region with a folder, use the full path:

/rsminfo dungeons/boss_room
/rsmeditmenu world/forest/wolves

If the name is unique across all folders, it can be used without the path:

/rsminfo boss_room

Support

When reporting a bug, include:

Plugin version (currently 1.1.3)
Hytale server version
Commands used
Error messages (if any)
Server logs (with /rsmdebug enabled if possible)
Region configuration (/rsminfo <name>)
Global settings (/rsmglobal)

How the Spawn System Works

This system has its own way of working. Once you understand the core idea, everything else falls into place.

The Core Idea in One Sentence

Mobs appear inside regions. Players activate regions by being nearby. That's it.

There is no "spawn around the player". The player is the trigger, not the target.

The Three Controls

Everything in this system comes down to three numbers:

playerRangeSpawnChunks   How far a player needs to be to activate a region
maxPerChunk              How many mobs can exist per chunk inside the region
Region Size              How large the region is = how many mobs it can hold in total

That's it. Three controls. No hidden behavior.

Visual: How It Works Step by Step

Every second:

STEP 1 — Find active regions
┌─────────────────────────────────────────┐
│                                         │
│   [ Region A ]                          │
│                                         │
│              ★ Player                   │  ← Player is here
│                  └──────────────────┐   │
│                  playerRangeChunks  │   │
│                  = search radius    │   │
│                                     ▼   │
│                           [ Region B ] │  ← Inside radius, will be processed
│                                         │
│   [ Region C ]                          │  ← Outside radius, ignored
└─────────────────────────────────────────┘

STEP 2 — Validate each found region
  ✓ Region is active?
  ✓ Boundary is at least 4x4x4 blocks?
  ✓ Has mobs configured?
  ✓ Weather/time conditions met?
  ✓ Has available capacity?
  ✓ Spawn interval has passed?
  → All yes? Spawn happens.
  → Any no? Skip this cycle.

STEP 3 — Find a position inside the boundary
  Random (X, Z) inside the boundary
       ↓
  Scans downward for solid ground
       ↓
  Checks chunk density < maxPerChunk
       ↓
  Spawns mob here

Visual: Capacity — How Region Size Controls Mob Count

The maximum number of mobs a region can hold is calculated automatically:

Max mobs = Total chunks in boundary × maxPerChunk

Example A — Small region (4x4 blocks = 1 chunk):
  1 chunk × 3 maxPerChunk = 3 mobs maximum

Example B — Medium region (64x64 blocks = 4 chunks):
  4 chunks × 3 maxPerChunk = 12 mobs maximum

Example C — Large region (128x128 blocks = 16 chunks):
  16 chunks × 3 maxPerChunk = 48 mobs maximum

You never set a fixed mob count. You set the density. The region size does the rest.

Visual: Chunk Density — How Mobs Distribute

Region boundary (top view):
┌────────────────────────────┐
│  Chunk 1  │  Chunk 2       │
│  [mob]    │  [mob][mob]    │
│  [mob]    │                │
│  ─────────┼────────────    │
│  Chunk 3  │  Chunk 4       │
│           │  [mob]         │
│           │                │
└────────────────────────────┘

maxPerChunk = 3

Chunk 1: 2 mobs → can spawn 1 more ✓
Chunk 2: 2 mobs → can spawn 1 more ✓
Chunk 3: 0 mobs → can spawn 3 more ✓
Chunk 4: 1 mob  → can spawn 2 more ✓

Mobs distribute naturally across the region because full chunks are skipped. No configuration needed — this happens automatically.

What Happens with Multiple Players

Player A ──→ finds Region X ──→ Region X is processed once
Player B ──→ finds Region X ──→ already processed this second, skipped
Player C ──→ finds Region Y ──→ Region Y is processed once

Each region is processed at most once per second, regardless of how many players are nearby. 10 players near the same region = same cost as 1 player.

FAQ

"I set playerRangeSpawnChunks = 3 but mobs are spawning far from me"

That is the correct behavior. The player activates the region, but mobs appear anywhere inside the boundary — not necessarily near you. If you want mobs near you, make the region smaller and position it around where players usually stand.

"My small region (4x4x4) never spawns mobs"

Check two things:

Are you within playerRangeSpawnChunks of the region?
Is the region already at max capacity? (/rsminfo <name> shows the current count)

A 4x4x4 region has 1 chunk. With maxPerChunk = 3, it holds 3 mobs maximum. If there are already 3 mobs there, nothing will spawn until one dies.

"I want more mobs in my region"

Three options:

Enlarge the region (more chunks = more capacity automatically)
Increase maxPerChunk globally with /rsmglobalmaxperchunk <value> (affects all regions)

"I want mobs to spawn faster"

Decrease the spawn interval in the preset assigned to the region:

/rsmpresetinterval <preset_name> <seconds>

"I disabled a region but the mobs are still there"

Disabling a region stops new spawns. Existing mobs remain until they die or you remove them manually with /rsmkill <region_name>.

Spawn Modes

Each region has a spawnMode that controls how it decides to spawn mobs. You configure it through the edit menu (/rsmeditmenu).

There are three modes:

CONTINUOUS

The default mode. The region replenishes mobs continuously as long as there is space and the configured interval has passed. This is the same behavior that existed before version 1.1.2.

Every cycle:
  adjustedCount < maxCapacity?
  Interval passed?
  → Yes to both? Spawn happens.

WAVE

The region spawns mobs gradually until it reaches maximum capacity. Once the wave is complete, no new mobs appear — even if some die. Only when all mobs from the wave die does the next wave begin.

Every cycle:
  Wave already complete?
  → Yes + adjustedCount == 0? Reset wave, next wave can start.
  → Yes + adjustedCount > 0? Wait. No spawn.
  → No? Spawn up to the remaining wave target.

Ideal for dungeons, catacombs and challenge areas where you want to control the flow of enemies.

SpawnPoints

When a region has SpawnPoints configured, the system uses exclusively those positions to spawn mobs instead of random positions inside the boundary.

Create a SpawnPoint by standing inside the region and running:

/rsmaddspawnpoint [name]

Each SpawnPoint can have:

an entity filter (allowedEntities)
maxSpawn

If the filter is empty, the SpawnPoint uses the full region mob pool. If it has mobs configured, only those mobs appear at that point.

maxSpawn limits how many living mobs originating from that point can exist at the same time. If it is empty, the SpawnPoint has no local limit.

SpawnPoints are managed through the region edit menu (/rsmeditmenu).

maxAlive per Entity

Each entity in the region can also have maxAlive.

maxAlive limits how many living mobs of that type can exist in the whole region, regardless of how many SpawnPoints accept that entity.

Example:

guard with maxAlive = 4
SpawnPoint gate_a with maxSpawn = 2
SpawnPoint gate_b with maxSpawn = 2

Result:

the system can distribute up to 4 guards in the region
never more than 2 at gate_a
never more than 2 at gate_b

THRESHOLD

The region only resumes spawning when the mob population drops below 40% of maximum capacity. Does not require a full clear like WAVE, but does not replenish continuously like CONTINUOUS.

threshold = floor(maxCapacity * 0.4)

Every cycle:
  adjustedCount > threshold? → Blocked. No spawn.
  adjustedCount <= threshold? → Spawn normally.

Ideal for strong areas where you want constant pressure without excessive spam.

Note: If a region using THRESHOLD has a very low maximum capacity, the server will log a one-time warning informing that the behavior will be close to WAVE.

Parent System — Configuration Inheritance

A region can inherit configurations from another region through the parentRegionPath field.

When an inheritable field is empty in the child region, the system automatically uses the parent's value. If there is a local value, the local value is used.

Inheritable fields: entities, presetId, spawnMode, spawnConditions, ignoreChunkDensity

Always local fields: boundary, spawnPoints, isActive, regionName, folderPath, maxPerChunk

This allows creating a "template" region with all mobs configured and linking multiple regions to it, each with its own boundary and SpawnPoints.

Configured through the region edit menu — Parent field in the REGION section.

Preset and Mode — Required Fields

When creating a region, preset and spawnMode start as (none) — no silent default value.

Without parent: preset and mode are required. The system blocks the save in the menu if they are (none) and logs a warning in the console every 15 seconds while the region is incomplete
With parent: can leave as (none) — the values will be inherited from the parent

This ensures no region operates in an undefined state without the admin noticing.

What Does NOT Exist in This System

Some features admins commonly ask about are intentionally not included:

Feature	Status
Spawn mobs at a fixed distance from the player	❌ Does not exist in this system
Spawn mobs only in front of the player	❌ Does not exist in this system
Mobs disappear when the player leaves	❌ Mobs persist — use containment
Sub-regions	❌ Removed in 1.1.2 — use folders for organization or the parent system to inherit configurations

What now exists as additional fine control:

maxSpawn per SpawnPoint
maxAlive per entity

These features sit on top of the current system without replacing the core region/chunk/capacity logic.

Configuration Menu

RegionSpawnMobs has a built-in GUI for Hytale to configure everything without editing JSON files or using commands. All menus are accessible directly in-game.

Menu Overview

There are 4 menus in total:

Menu	Command	What it does
Region	`/rsmeditmenu [name]`	Configure a region: mobs, SpawnPoints, spawn mode
Preset	`/rsmpresetmenu`	Create, edit and remove presets
Global Config	`/rsmglobalmenu`	Configure global options
Terrain Type	`/rsmterrainmenu`	Manage terrain types

Note: The sub-region menu was removed in version 1.1.2. All region configuration is done through the single /rsmeditmenu.

Region Menu

Info Screen

Opened with /rsminfomenu [name] or the Info button inside the editor.

[ IMAGE: menu-region-info.png ]

Displays:

Full region path (folder/name) and world
Status (active/inactive)
Assigned preset
Region MaxPerChunk
Total chunks and dimensions (e.g. 4 (2x2))
Current mob count vs max capacity (e.g. 7/12)
List of configured mobs with weight, time, weather, terrain and maxAlive for each
List of SpawnPoints with position, maxSpawn and entity filter

Edit Screen

Opened with /rsmeditmenu [name] or the Edit button on the info screen.

If the name is omitted, the menu automatically detects the region by player position.

[ IMAGE: menu-region-edit.png ]

The menu is now visually organized in 3 columns:

Region
SpawnPoints
Mobs

REGION Section

Name — rename the region (cannot contain / or \)
Folder — folder path (read-only on this screen)
Parent — dropdown to select a parent region (see Parent System)
World — region world (read-only)
Chunks — total chunks and dimensions (read-only)
Mob Count — current mobs vs max capacity (read-only)
Active — checkbox to enable or disable the region
Ignore Chunk — checkbox to ignore chunk density when you want stronger manual control through SpawnPoints
Preset — dropdown to select the assigned preset ((none) if not configured)
Max / Chunk — mob limit per chunk for this region

SPAWN MODE Section

Mode — dropdown with four options:
- (none) — not configured (must configure or have a parent)
- Continuous — replenishes mobs continuously (default)
- Wave — waits for all mobs to die before the next wave
- Threshold — only spawns when population drops below 40% of capacity

Important: Preset and Mode are required for the region to function. If the region has no parent configured, the system blocks the save and displays an error message. If it has a parent, (none) is valid — the values will be inherited.

SPAWN POINTS Section

Selected — dropdown to select the active SpawnPoint
Count — total SpawnPoints in the region
Point ID — short identifier of the selected SpawnPoint
Name — editable name for the selected SpawnPoint
Max Spawn — dropdown with Unlimited or 1..50
Position — SpawnPoint position (read-only)
Allow Mob — dropdown to add a mob to the SpawnPoint filter
Remove Mob — dropdown to remove a mob from the SpawnPoint filter
Save SpawnPoint button — saves the name, maxSpawn and applies the Allow/Remove selections
Delete SpawnPoint button — removes the selected SpawnPoint

SpawnPoints are created with the /rsmaddspawnpoint [name] command while standing inside the region.

MOBS Section

Mob ID — text field for the mob type
Spawn Weight — spawn weight
Max Alive — dropdown with Unlimited or 1..200
Time of Day — dropdown (ALL, Dawn, Midday, Dusk, Midnight, Day, Night)
Weather — weather dropdown
Terrain Type — terrain type dropdown
Add / Update Mob button — adds or updates the mob with the given values
Remove Mob — dropdown to select the mob to remove
Remove Mob button — removes the selected mob
Mob List — list of all configured mobs with their parameters

Clicking Save Region, Save SpawnPoint or Add / Update Mob saves the corresponding section immediately.

Parent System

Any region can inherit configurations from another region through the Parent field.

What it's for

Avoids reconfiguring the same mobs, preset and conditions across multiple regions. Create one region with everything configured and use it as the parent for the others.

Practical example:

Region "animals" (parent)
  → entities: cow, pig, chicken
  → preset: fast
  → mode: CONTINUOUS

Region "forest-north" (parent = animals)
  → own boundary
  → inherits everything from "animals"

Region "forest-south" (parent = animals)
  → own boundary
  → inherits everything from "animals"

Inheritable fields

Field	Inheritable
`entities` (mob list)	✅
`presetId`	✅
`spawnMode`	✅
`spawnConditions` (time/weather/terrain)	✅
`ignoreChunkDensity`	✅
`boundary`	❌ always local
`spawnPoints`	❌ always local
`isActive`	❌ always local
`regionName` / `folderPath`	❌ always local
`maxPerChunk`	❌ always local

Rules

1 level maximum — a parent cannot have a parent
Cannot be itself — the dropdown does not list the region being edited
Deletion blocked — a region with children linked to it cannot be deleted
Automatic rename — when renaming the parent through the menu, the parentRegionPath of all children is updated automatically
Moving files manually — the admin's responsibility; the system attempts to resolve by name as a fallback

How to configure

Open the child region menu with /rsmeditmenu <name>
In the Parent field, select the parent region from the dropdown
Click Save Region
Empty inheritable fields will now use the parent's values

To remove the link, select (none) in the Parent dropdown and save.

Note: The parent is stored as a full path string (folderPath/regionName) in the JSON. If the parent file is moved manually outside the mod, the system attempts to resolve by name. If not found, the region operates as independent and logs a warning in the console.

Preset Menu

Info Screen

Opened with /rsmpresetinfomenu.

[ IMAGE: menu-preset-info.png ]

Displays:

Total registered presets
For each preset: name, interval in seconds and quantity range (min-max)

Edit Screen

Opened with /rsmpresetmenu or the Edit button on the info screen.

[ IMAGE: menu-preset-edit.png ]

Allows in a single screen:

Add preset — enter name, interval, minimum and maximum quantity
Edit existing preset — enter name and new values
Remove preset — enter the name to remove

Global Config Menu

Opened with /rsmglobalmenu.

[ IMAGE: menu-global-config.png ]

Displays current values and allows editing:

Field	Description
`playerRangeSpawnChunks`	Player distance to activate regions (in chunks)
`minSpawnDistanceChunks`	Minimum player distance for spawn
`maxSpawnDistanceChunks`	Maximum player distance for spawn
`maxPerChunkDefault`	Default mob limit per chunk (for all regions)
`containMobs`	Enable or disable the containment system (checkbox)
`containmentMode`	Containment mode: `OFF`, `RETURN` or `TELEPORT`
`containmentMarginChunks`	Containment safety margin in chunks

Clicking Apply saves the configuration immediately without restarting the server.

Navigation Between Screens

Info and edit menus are connected by buttons:

Info Screen  ──[ Edit ]──→  Edit Screen
Edit Screen  ──[ Info ]──→  Info Screen

You can close any menu at any time without saving — changes are only applied when clicking the save button for the corresponding section.

Commands

Basic Management

/rsmcreate <region> – Create a spawn region from pos1/pos2 selection (at root)
/rsmcreate <folder> <region> – Create a region inside a folder
/rsmcreate <folder> <category> <region> – Create a region inside a nested folder
/rsmdelete <region> – Delete a region (accepts full path: folder/name)
/rsminfo <region> – Display region information in chat
/rsmkill [region] – Remove all mobs from the region (or all regions if not specified), including orphaned mobs

Mob Configuration

/rsmaddmob <region> <mob> <weight> – Add a mob type to the region (default conditions: ALL)
/rsmremovemob <region> <mob> – Remove a mob type from the region

maxAlive, weather, time and terrain type can also be configured through /rsmeditmenu.

SpawnPoints

/rsmaddspawnpoint [name] – Create a SpawnPoint at your current position, inside the region you are standing in. Name is optional

maxSpawn, entity filters and SpawnPoint rename are configured through /rsmeditmenu.

Menus (GUI)

/rsminfomenu [region] – Open region info screen in the menu. If name is omitted, detects region by player position
/rsmeditmenu [region] – Open region edit screen in the menu. If name is omitted, detects region by player position
/rsmpresetinfomenu – Open preset info screen in the menu
/rsmpresetmenu – Open preset edit screen in the menu
/rsmglobalmenu – Open global config menu

Presets

/rsmpresetlist – List all spawn presets
/rsmpresetinfo <name> – Display preset details in chat
/rsmpresetcreate <name> <interval> <minQty> <maxQty> – Create a new preset
/rsmpresetdelete <name> – Delete a preset
/rsmpresetinterval <name> <seconds> – Change preset spawn interval
/rsmpresetminqty <name> <quantity> – Change preset minimum quantity
/rsmpresetmaxqty <name> <quantity> – Change preset maximum quantity

Visualization

/rsmshow true – Show all regions with colored boxes
/rsmshow false – Hide all visualizations
/rsmshowchunks true – Show regions aligned to chunk boundaries
/rsmshowchunks false – Hide chunk visualization
/rsmselect <region> – Load region into BuilderTools selection (for adjustment with pos1/pos2)

Relocation

/rsmrelocate <region> – Move region to current pos1/pos2 selection

Global Settings

/rsmglobal – Display current global settings in chat
/rsmglobalmaxperchunk <number> – Set global max mobs per chunk (0 = unlimited)
/rsmglobalspawnrange <chunks> – Set player distance to activate regions (in chunks)
/rsmcontainment <mode> – Set containment mode: OFF, RETURN or TELEPORT

Other

/rsmreload – Reload regions, global config and presets from disk
/rsmdebug <type> <true/false> – Enable or disable a debug type

Available debug types: spawn, spawn_verbose, containment, containment_verbose, region, player, tracker, policy, initialization, capacity, validation, all

Deprecated Commands

The commands below still exist but return a warning message. Use presets or the menu instead:

/rsmenable <name> – ⚠️ Deprecated. Use the region edit menu
/rsmdisable <name> – ⚠️ Deprecated. Use the region edit menu
/rsmsetinterval <name> <seconds> – ⚠️ Deprecated. Use presets
/rsmsetquantity <name> <min> <max> – ⚠️ Deprecated. Use presets

Commands Removed in 1.1.2

The following commands were removed along with the sub-region system:

/rsmcreatesub – Removed. Use /rsmcreate <folder> <region> to organize regions
/rsmdeletesub – Removed. Use /rsmdelete <path/name>
/rsminfosub – Removed. Use /rsminfo <path/name>
/rsmaddmobsub – Removed. Use /rsmaddmob <path/name> <mob> <weight>
/rsmsubinfomenu – Removed. Use /rsminfomenu <path/name>
/rsmsubeditmenu – Removed. Use /rsmeditmenu <path/name>
/rsmrelocatesub – Removed. Use /rsmrelocate <path/name>

Visualization System

Overview

RegionSpawnMobs offers two visualization tools to help you understand your regions and the chunk-based spawn system.

`/rsmshow` - Region Boundaries

Purpose: Visualize ALL spawn regions with colored 3D boxes

Commands:

/rsmshow true   # Show all regions
/rsmshow false  # Hide all regions

Features:

Shows all regions at once with colored bounding boxes
Each region gets a unique color for easy identification
Displays main regions and sub-regions separately
Visualization lasts 10 minutes and is then removed automatically
Helps identify overlapping regions
Useful for planning new regions

Use Cases:

Check if regions overlap
Confirm region size and position
Plan placement of new regions
Debug region boundaries
Show regions to other admins

Example Visual:

What You See:

Colored wireframe boxes around each region
Different colors for each region
Sub-regions shown inside parent regions
Clear boundaries of spawn areas

`/rsmshowchunks` - Chunk Grid

Purpose: Visualize the chunk grid system used for spawning

Commands:

/rsmshowchunks true   # Show chunk grid
/rsmshowchunks false  # Hide chunk grid

Features:

Shows chunk boundaries as a grid overlay
Each chunk is 32x32 blocks with a height of 320 blocks (Hytale standard)
Helps understand the chunk-based spawn system
Visualizes maxPerChunk limits
Shows where chunk density is calculated
Useful for optimizing spawn distribution

Use Cases:

Understand chunk-based spawning
Optimize maxPerChunk settings
See why mobs aren't spawning (chunk full)
Plan region size in chunks
Debug chunk density issues

Example Visual:

What You See:

Colored wireframe boxes aligned to chunk boundaries (32x32 blocks)
Box height covers the entire world (320 blocks)
Colors match the corresponding regions
Helps count chunks in your region

Comparison: `/rsmshow` vs `/rsmshowchunks`

Feature	`/rsmshow`	`/rsmshowchunks`
Shows	Region boundaries	Chunk grid
Purpose	See spawn regions	Understand chunk system
Duration	10 minutes	10 minutes
Use for	Region planning	Spawn optimization
Displays	Colored boxes	Grid lines
Best for	Admins setting up regions	Debugging spawn issues

Combined Usage

Recommended workflow:

# 1. Show regions to see boundaries
/rsmshow true

# 2. Show chunks to understand density
/rsmshowchunks true

# 3. Analyze your region
# - Count how many chunks are in the region
# - Calculate capacity: chunks × maxPerChunk
# - Adjust settings if needed

# 4. Hide visualizations
/rsmshow false
/rsmshowchunks false

Practical Examples

Example 1: Planning a New Region

# Step 1: Show existing regions
/rsmshow true

# Step 2: Find empty space
# (Look for areas without colored boxes)

# Step 3: Select new area
/pos1
/pos2

# Step 4: Create region
/rsmcreate new_arena

Example 2: Optimizing Chunk Density

# Step 1: Show chunks
/rsmshowchunks true

# Step 2: Count chunks in your region
# Example: 10 chunks wide × 10 chunks deep = 100 chunks

# Step 3: Calculate capacity
# 100 chunks × 3 maxPerChunk = 300 mobs maximum

# Step 4: Adjust if needed
/rsmglobalmaxperchunk 5  # Increase to 500 mobs maximum

Example 3: Debugging Spawn Issues

# Problem: Mobs are not spawning

# Step 1: Show region
/rsmshow true
# Check: Is the region where you think it is?

# Step 2: Show chunks
/rsmshowchunks true
# Check: Are chunks full? (maxPerChunk reached)

# Step 3: Check info
/rsminfo <region_name>
# Check: Current mobs vs capacity

# Step 4: Enable debug
/rsmdebug spawn true
# Check: Spawn attempt logs

Containment System Explained

How Chunk-Based Containment Works

The containment system uses chunk coordinates instead of exact block positions for performance reasons. This creates an important behavior you need to understand:

Containment Margin

Key Concept: The system checks mobs using containmentMarginChunks (default: 3 chunks = 96 blocks)

Region Boundary (exact blocks)
┌─────────────────────────┐
│                         │  ← Your defined region
│    Actual Region        │
│                         │
└─────────────────────────┘

Containment Check Area (chunks)
╔═══════════════════════════╗
║  ┌─────────────────────┐  ║
║  │                     │  ║  ← Margin: 3 chunks
║  │  Actual Region      │  ║     (96 blocks)
║  │                     │  ║
║  └─────────────────────┘  ║
╚═══════════════════════════╝
     ↑
  Mobs can walk here before being teleported!

Important: Small Region Behavior

If your region is smaller than 1 chunk (32 blocks):

Mobs will have free space to walk outside the region boundary before being teleported back!

Why? The system checks containment by chunks, not exact blocks.

Example Visual:

[IMAGE: containment_small_region.png]
(Screenshot showing small region with mob walking outside)

Example:

Region size: 20x20 blocks (smaller than 1 chunk)
Containment margin: 3 chunks (96 blocks)
Result: Mobs can walk up to ~96 blocks before teleport

Configuration

In global_config.json:

{
  "containMobs": true,
  "containmentMode": "TELEPORT",
  "containmentMarginChunks": 3
}

Modes:

OFF - No containment (mobs roam freely). Sets containMobs to false automatically
RETURN - Pushes mobs back with velocity
TELEPORT - Instant teleport back (recommended)

Command to change mode:

/rsmcontainment OFF
/rsmcontainment RETURN
/rsmcontainment TELEPORT

Recommendations

For Small Regions (< 32 blocks):

# Reduce margin for more precise containment
# Edit global_config.json:
"containmentMarginChunks": 1    # 32-block margin

For Large Regions (> 100 blocks):

# Keep the default margin
"containmentMarginChunks": 3    # 96-block margin (default)

For Boss Arenas:

# Precise containment
"containmentMarginChunks": 0    # No margin (exact chunk boundary)
"containmentMode": "TELEPORT"   # Instant teleport

How It Works

Every 5 seconds, the system checks mob positions (only if there are players in the world)
Converts mob position to chunk coordinates
Checks if the mob is outside the region + margin
If outside:
- Skips if mob is in combat and still within the margin
- Waits for cooldown (3 seconds between teleports per mob)
- Finds a safe position inside the region
- Teleports the mob back
Maximum of 5 teleports per tick to avoid lag
Every 10 minutes, cleans up cooldown records for inactive mobs

How the Safe Position is Found

When teleporting a mob, the system follows this priority order:

Priority 1 — Mob's original SpawnPoint:

If the mob was spawned from a SpawnPoint, it returns to that exact position
The spawnPointId is saved in the RegionTrackerComponent at spawn time and persists across server restarts
The lookup is done by unique UUID — no ambiguity even if multiple SpawnPoints share the same name
If the SpawnPoint was deleted since the mob spawned, falls through to Phase 1

Phase 1 — 12 random attempts (fallback):

Used when the mob has no origin SpawnPoint
Picks random positions distributed across the boundary (with 2-block internal margin)
Scans downward for solid ground
Checks for 2 empty blocks above the ground

Phase 2 — Fixed anchor fallback:

If no random attempt works, tries: center + 4 corners of the region
If no anchor works, the teleport is cancelled and logged in debug

Combat Protection

Important: The containment system has smart combat detection!

How it works:

Mobs in combat (with LockedTarget) can move freely through the containment margin
Only teleports when the mob reaches or exceeds the last chunk of the margin (distance ≥ containmentMarginChunks)
Mobs not in combat are teleported as soon as they leave the region (any distance > 0 chunks)

Example with containmentMarginChunks = 3:

Region: [====REGION====]
Margin: [1][2][3][====REGION====][3][2][1]

Mob NOT in combat:
  → Teleports immediately upon leaving the region

Mob IN combat:
  → Can fight in margin chunks 1 and 2
  → Teleports only upon reaching margin chunk 3 (border)

Benefits:

Players can chase mobs near borders without constant teleports
Combat feels natural and fluid
Mobs still cannot fully escape (safety limit applied)

Performance Notes

Checks only border mobs (via ChunkIterator.scanRegions)
Maximum of 5 teleports per tick (avoids lag)
3-second cooldown per mob (avoids spam)
Skips check if no players are in the world
Automatic cooldown cleanup every 10 minutes

Troubleshooting

Problem: Mobs escape too far

# Solution: Reduce the margin
# Edit global_config.json:
"containmentMarginChunks": 1

Problem: Mobs teleport during combat

# This should NOT happen — it's a bug!
# Enable debug and report:
/rsmdebug containment true

Problem: Mobs are not being contained

# Check if containment is enabled:
/rsmglobal

# Enable via command:
/rsmcontainment TELEPORT

# Or edit global_config.json manually:
"containMobs": true,
"containmentMode": "TELEPORT"

Problem: Mob cannot find a safe position for teleport

# The system tries 12 random positions + 5 fixed anchors
# If all fail, the teleport is cancelled
# Enable debug to see logs:
/rsmdebug containment true
# Look for: "[SKIP] <mob_uuid> — sem posição segura" (or similar in debug output)

Data Saving

Regions are saved automatically as JSON
Base path: mods/RegionSpawnMobs/regions/
Global config: mods/RegionSpawnMobs/global_config.json
Each region is saved at regions/<folderPath>/<name>.json
Regions at root (no folder) are saved at regions/<name>/<name>.json
Automatic backup: on every save, the system creates <name>.json.bak automatically
Manual backup: copy the RegionSpawnMobs/ folder

Folder Structure

mods/RegionSpawnMobs/
├── regions/
│   ├── wolf_arena/
│   │   ├── wolf_arena.json          # Root region
│   │   └── wolf_arena.json.bak      # Automatic backup
│   ├── dungeons/
│   │   ├── entrance/
│   │   │   ├── entrance.json        # Region in folder
│   │   │   └── entrance.json.bak
│   │   └── boss_room/
│   │       ├── boss_room.json
│   │       └── boss_room.json.bak
│   └── world/
│       └── forest/
│           └── wolves/
│               └── wolves.json      # Region in nested folder
├── global_config.json
├── presets.json
└── terrain-types.json

Empty folders are removed automatically when all regions inside them are deleted.

JSON Format Examples

Region JSON (`wolf_arena.json`)

{
  "regionId": "425d0f39-0098-4d00-bcb2-27af5bd59589",
  "regionName": "wolf_arena",
  "folderPath": "",
  "presetId": "default",
  "isActive": true,
  "maxPerChunk": 5,
  "spawnMode": "CONTINUOUS",
  "boundary": {
    "worldName": "default",
    "firstPosition": {
      "x": -256.0,
      "y": 119.0,
      "z": -96.0
    },
    "secondPosition": {
      "x": -225.0,
      "y": 135.0,
      "z": -65.0
    }
  },
  "entities": {
    "wolf_black": {
      "spawnWeight": 40,
      "spawnConditions": {
        "timeOfDay": ["ALL"],
        "weather": ["ALL"],
        "terrainType": "ALL"
      }
    },
    "skeleton": {
      "spawnWeight": 30,
      "spawnConditions": {
        "timeOfDay": ["NIGHT", "DUSK"],
        "weather": ["ALL"],
        "terrainType": "ALL"
      }
    }
  },
  "spawnPoints": [
    {
      "spawnPointId": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "entrance",
      "x": -240.0,
      "y": 120.0,
      "z": -80.0,
      "allowedEntities": []
    }
  ]
}

Region with Folder JSON (`dungeons/boss_room.json`)

{
  "regionId": "7a3c1f20-1234-4b00-aaaa-000000000001",
  "regionName": "boss_room",
  "folderPath": "dungeons",
  "presetId": "dungeon_hard",
  "isActive": true,
  "maxPerChunk": 3,
  "spawnMode": "WAVE",
  "boundary": { ... },
  "entities": { ... },
  "spawnPoints": []
}

Global Config JSON (`global_config.json`)

{
  "playerRangeSpawnChunks": 2,
  "maxPerChunkDefault": 3,
  "containMobs": true,
  "containmentMode": "TELEPORT",
  "containmentMarginChunks": 3
}

JSON Field Reference

Region Fields:

regionId - Unique region UUID (generated automatically)
regionName - Region name (must match the file name)
folderPath - Folder path where the region is organized (empty = root)
presetId - Preset template ID (default: "default")
isActive - Whether the region is enabled (true/false)
maxPerChunk - Max mobs per chunk in this region
spawnMode - Spawn mode: CONTINUOUS, WAVE or THRESHOLD
boundary - 3D area definition with world name and two corner positions
entities - Map of mob types with spawn weights and conditions
spawnPoints - List of fixed spawn positions (can be empty)

SpawnPoint Fields:

spawnPointId - Unique SpawnPoint UUID (generated automatically)
name - Optional name for identification
x, y, z - Exact position in the world
allowedEntities - List of allowed mobs at this point. If empty, uses the full region mob pool

Entity Fields (EntitySpawnConfig):

spawnWeight - Relative spawn weight (default: 100)
presetId - Entity-specific preset (optional, overrides the region's preset)
spawnConditions - Spawn conditions (time, weather and terrain)

Spawn Conditions:

timeOfDay - When to spawn:
- Specific periods: Dawn (0-4.8h), Midday (4.8-12h), Dusk (12-19.2h), Midnight (19.2-24h)
- Aliases: Day (Midday + Dusk), Night (Dawn + Midnight)
- Special: ALL (any time)
weather - Weather conditions (see Weather System)
terrainType - Terrain type (see Terrain Type System)

Global Config Fields:

playerRangeSpawnChunks - Player distance for spawn (in chunks, default: 2)
maxPerChunkDefault - Default max mobs per chunk (default: 3)
containMobs - Enable/disable containment system (default: true)
containmentMode - How to contain mobs: OFF, RETURN, TELEPORT (default: TELEPORT)
containmentMarginChunks - Containment safety margin in chunks (default: 3)

Legacy Sub-Region Migration

If you had sub-regions from versions prior to 1.1.2, the system migrates them automatically:

Files with subRegionName are detected as legacy format
Each sub-region becomes an independent region with folderPath equal to the parent region name
Example: sub-region boss of region wolf_arena becomes region boss in folder wolf_arena
The legacy file is replaced with the new format and a warning is logged

No manual action is required.

Spawn Preset System

Presets are reusable spawn configuration templates. Apply a preset to multiple regions to maintain consistency and simplify updates.

Commands

/rsmpresetlist                                   # List all presets
/rsmpresetinfo <name>                            # View preset details
/rsmpresetcreate <name> <interval> <min> <max>   # Create preset
/rsmpresetinterval <name> <seconds>              # Change interval
/rsmpresetminqty <name> <quantity>               # Change minimum quantity
/rsmpresetmaxqty <name> <quantity>               # Change maximum quantity
/rsmpresetdelete <name>                          # Delete preset

Default Presets

The plugin automatically creates 4 presets on first startup:

Preset	Interval	Min	Max
`default`	30s	1	3
`dungeon_easy`	10s	1	2
`dungeon_hard`	3s	2	5
`boss_spawner`	120s	1	1

File Format (`presets.json`)

{
  "default": {
    "spawnIntervalSeconds": 30,
    "minimumSpawnQuantity": 1,
    "maximumSpawnQuantity": 3
  },
  "dungeon_easy": {
    "spawnIntervalSeconds": 10,
    "minimumSpawnQuantity": 1,
    "maximumSpawnQuantity": 2
  },
  "dungeon_hard": {
    "spawnIntervalSeconds": 3,
    "minimumSpawnQuantity": 2,
    "maximumSpawnQuantity": 5
  },
  "boss_spawner": {
    "spawnIntervalSeconds": 120,
    "minimumSpawnQuantity": 1,
    "maximumSpawnQuantity": 1
  }
}

Preset Fields

spawnIntervalSeconds — time between spawn attempts (default: 30)
minimumSpawnQuantity — minimum mobs per attempt (default: 1)
maximumSpawnQuantity — maximum mobs per attempt (default: 3)

How to Apply to a Region

The presetId field in the region JSON references the preset by name:

{
  "regionName": "wolf_arena",
  "presetId": "dungeon_hard",
  ...
}

Troubleshooting

Preset not applied: check that the name is exact (case-sensitive) and use /rsmreload after editing the file.

Region using wrong preset: edit the presetId in the region JSON and reload with /rsmreload.

Time of Day System

Time is divided into 4 periods based on a 24-hour Hytale cycle:

Period	Hours	Alias
`Dawn`	0 – 4.8h	part of `Night`
`Midday`	4.8 – 12h	part of `Day`
`Dusk`	12 – 19.2h	part of `Day`
`Midnight`	19.2 – 24h	part of `Night`

Accepted values in JSON:

Periods: Dawn, Midday, Dusk, Midnight
Aliases: Day (Midday + Dusk), Night (Dawn + Midnight)
Special: ALL (any time)
Case-insensitive: night, NIGHT, Night all work the same

Examples

"timeOfDay": ["Night"]           // Dawn + Midnight
"timeOfDay": ["Day"]             // Midday + Dusk
"timeOfDay": ["Dawn", "Dusk"]    // transitions only
"timeOfDay": ["Midnight"]        // midnight only
"timeOfDay": ["ALL"]             // no restriction

Troubleshooting

Mobs not spawning at expected time:

Enable debug with /rsmdebug spawn true and look for [TIME] Current: in the logs to see the current period
If timeOfDay is null or empty, the system allows spawning at any time

Weather System

How Weather Works in Spawn Conditions

You can control when mobs appear based on the current Hytale weather. The weather field in spawnConditions accepts an array of weather names.

Special Weather Values

ALL - Spawn in any weather (ignores the weather condition)

Examples

Example 1: Spawn only during rain

"skeleton": {
  "spawnWeight": 50,
  "spawnConditions": {
    "timeOfDay": ["ALL"],
    "weather": ["Zone1_Rain", "Zone1_Rain_Light"]
  }
}

Example 2: Spawn during storms

"wolf_black": {
  "spawnWeight": 30,
  "spawnConditions": {
    "timeOfDay": ["Night"],
    "weather": ["Zone1_Storm", "Zone2_Thunder_Storm"]
  }
}

Example 3: Spawn in any weather

"wolf_white": {
  "spawnWeight": 40,
  "spawnConditions": {
    "timeOfDay": ["ALL"],
    "weather": ["ALL"]
  }
}

Example 4: Multiple weather conditions

"ice_creature": {
  "spawnWeight": 60,
  "spawnConditions": {
    "timeOfDay": ["ALL"],
    "weather": [
      "Zone3_Snow",
      "Zone3_Snow_Heavy",
      "Zone3_Snow_Storm",
      "Zone3_Northern_Lights"
    ]
  }
}

Available Weather Types

Note: Weather names are case-sensitive and must match exactly!

Global/Special

Blood_Moon
Creative_Hub
Forgotten_Temple
Void

Zone 1 (Plains/Forest)

Zone1_Sunny
Zone1_Sunny_Fireflies
Zone1_Cloudy_Medium
Zone1_Foggy_Light
Zone1_Rain
Zone1_Rain_Light
Zone1_Storm
Zone1_Autumn_Forest_Windy
Zone1_Oak_Forest_Windy
Zone1_Azurewood_Fireflies
Zone1_Swamp
Zone1_Swamp_Foggy
Zone1_Swamp_Rain
Zone1_Gully

Zone 2 (Desert)

Zone2_Sunny
Zone2_Blazing_Light
Zone2_Cloudy_Light
Zone2_Cloudy_Heavy
Zone2_Desert_Haze
Zone2_Sand_Storm
Zone2_Thunder_Storm
Zone2_Corrupted_Oasis
Zone2_Corrupted_Oasis_Night
Zone2_Story_Dungeon_Exterior
Zone2_Story_Dungeon_Interior1
Zone2_Story_Dungeon_Interior_Corrupted

Zone 3 (Taiga/Snow)

Zone3_Cloudy_Light
Zone3_Cloudy_Medium
Zone3_Cloudy_Boreal
Zone3_Rain
Zone3_Snow
Zone3_Snow_Heavy
Zone3_Snow_Storm
Zone3_Northern_Lights
Zone3_Hedera
Hedera_Forest
Zone3_Cave_Shallow
Zone3_Cave_Deep
Zone3_Cave_Volcanic

Zone 4 (Volcanic/Void)

Zone4_Light
Zone4_Storm
Zone4_Spooky
Zone4_AshWastes
Zone4_AshWastes_Storm
Zone4_Wastes
Zone4_Wastes_Rain
Zone4_Wastes_Rain_Heavy
Zone4_Lava_Fields
Zone4_Geyser
Zone4_GhostForest
Zone4_GhostForest_Rain
Zone4_Forest_Burnt
Zone4_Forest_Root
Zone4_Ruined_City
Zone4_Swamp_Gloomy
Zone4_Swamp_Storm
Zone4_Underground_Jungle
Zone4_Underground_Jungle_Pink
Zone4_Underground_Jungle_Red
Zone4_Caves_Jungles

Cave

Cave_Shallow
Cave_Deep
Cave_Fog
Cave_Goblin
Cave_Volcanic

Skylands

Skylands_Sunny
Skylands_Light
Skylands_Mushroom_Forest_Cloudy
Skylands_Mystic_Forest_Cloudy
Skylands_Rapid_Marsh_Cloudy_Medium
Skylands_Rapids_Marsh_Cloudy_Medium
Skylands_Rapid_Marsh_Stormy

Poisonlands

Poisonlands_Heavy
Poisonlands_PurpleTwirl
Poisonlands_Red
Poison_Test

Dungeon

Dungeon_Cursed_Crypt
Dungeon_Cursed_Crypt_Graveyard

Portal

Portals_Void_Event_Light
Portals_Void_Event_Intense

Minigame

Terror_Weather
Default_Flat
Default_Void

Tips

Use ALL for simplicity: If you don't care about weather, use ["ALL"]
Match your zone: Use Zone1 weather for plains, Zone2 for desert, etc.
Test in-game: Weather names must match exactly (case-sensitive)
Combine conditions: Mix weather + time for specific spawns (e.g. skeletons during night storms)
Multiple weathers: You can list multiple weather types in the arrays

Settings and Troubleshooting

Global Parameters

/rsmglobalmaxperchunk <number>   # Max mobs per chunk (default: 3, 0 = unlimited)
/rsmglobalspawnrange <chunks>    # Player distance to activate regions (default: 2 chunks)
/rsmcontainment <mode>           # Containment mode: OFF, RETURN, TELEPORT (default: TELEPORT)

/rsmsetinterval and /rsmsetquantity exist but are deprecated — use presets to configure interval and quantity.

Debug Mode

The /rsmdebug command requires a type and a state:

/rsmdebug <type> true    # Enable
/rsmdebug <type> false   # Disable

Available types:

Type	What it logs
`spawn`	Spawn attempts and results
`spawn_verbose`	Detailed spawn info (very spammy)
`containment`	Teleports and boundary checks
`containment_verbose`	Detailed containment info (very spammy)
`region`	Region management
`player`	Player detection
`tracker`	Mob tracking
`policy`	Spawn throttle and cooldown
`initialization`	Region initialization
`capacity`	Capacity calculations
`validation`	Position validation
`all`	All types above

Common Issues

Mobs not spawning:

Check if the region is active: /rsminfo <name>
Confirm mobs have been added to the region
Check if there are players in the world (spawn only occurs with players present)
Enable debug: /rsmdebug spawn true

Mobs escaping the region:

Check if containment is active: /rsmglobal
Adjust the margin: edit containmentMarginChunks in global_config.json
See the containment guide for details

Too many mobs in an area:

Reduce the chunk limit: /rsmglobalmaxperchunk 3
Adjust the region's preset with a smaller interval/quantity

Region won't create:

Make sure /pos1 and /pos2 have been set
Minimum size: 4x4x4 blocks
Check if the name already exists: /rsminfo <name>

RegionSpawnMobs

Description

RegionSpawnMobs – Admin Guide (BETA)

Project Status: BETA

What is RegionSpawnMobs?

Use Cases

Quick Start

1) Select the area

2) Create the region

3) Add mobs (with weights)

4) (Optional) Add SpawnPoints

Folder Organization

Support

How the Spawn System Works

The Core Idea in One Sentence

The Three Controls

Visual: How It Works Step by Step

Visual: Capacity — How Region Size Controls Mob Count

Visual: Chunk Density — How Mobs Distribute

What Happens with Multiple Players

FAQ

Spawn Modes

CONTINUOUS

WAVE

SpawnPoints

maxAlive per Entity

THRESHOLD

Parent System — Configuration Inheritance

Preset and Mode — Required Fields

What Does NOT Exist in This System

Configuration Menu

Menu Overview

Region Menu

Info Screen

Edit Screen

REGION Section

SPAWN MODE Section

SPAWN POINTS Section

MOBS Section

Parent System

What it's for

Inheritable fields

Rules

How to configure

Preset Menu

Info Screen

Edit Screen

Global Config Menu

Navigation Between Screens

Commands

Basic Management

Mob Configuration

SpawnPoints

Menus (GUI)

Presets

Visualization

Relocation

Global Settings

Other

Deprecated Commands

Commands Removed in 1.1.2

Visualization System

Overview

/rsmshow - Region Boundaries

/rsmshowchunks - Chunk Grid

Comparison: /rsmshow vs /rsmshowchunks

Combined Usage

Practical Examples

Example 1: Planning a New Region

Example 2: Optimizing Chunk Density

Example 3: Debugging Spawn Issues

Containment System Explained

How Chunk-Based Containment Works

Containment Margin

Important: Small Region Behavior

Configuration

Recommendations

How It Works

How the Safe Position is Found

Combat Protection

`/rsmshow` - Region Boundaries

`/rsmshowchunks` - Chunk Grid

Comparison: `/rsmshow` vs `/rsmshowchunks`

Region JSON (`wolf_arena.json`)

Region with Folder JSON (`dungeons/boss_room.json`)

Global Config JSON (`global_config.json`)

File Format (`presets.json`)