Dungeons¶

HTSkyBlock includes a dungeon instance system with config-driven wave spawning. Create dungeon templates with trigger zones, spawn points, and waves of mobs. When a player enters a trigger radius, waves of mobs spawn using Hytale's built-in NPC role system.

Overview¶

The dungeon system consists of:

Dungeon Templates — Saved configurations that define a dungeon's spawn groups, waves, and trigger zones
Instance Worlds — Temporary worlds spawned from Hytale's instance system (Server/Instances/)
Spawn Groups — Areas within a dungeon with a proximity trigger, spawn points, and wave definitions
Waves — Ordered batches of mobs that spawn one after another as players clear them

Flow: Player enters instance → walks near a spawn group trigger → Wave 1 mobs spawn → all mobs killed → delay → Wave 2 spawns → ... → all waves complete → area cleared

Base Command¶

/dungeondev (alias: /ddev) — Dungeon development admin commands

Permission: htskyblock.admin.dungeondev

Concepts¶

Dungeon Templates¶

A template defines the configuration for a dungeon. It links to an instance asset (from Server/Instances/) and contains one or more spawn groups. Templates are saved to dungeons.json and persist across restarts.

Spawn Groups¶

A spawn group represents a combat encounter area. Each group has:

Trigger Point — A location + radius. When a player enters this radius, the group activates.
Spawn Points — Locations where mobs appear. Mobs cycle through spawn points if there are more mobs than points.
Waves — Ordered list of mob batches. Each wave has a mob type (NPC role name) and count.
Wave Delay — Seconds to wait after all mobs die before spawning the next wave.

Wave Progression¶

Player enters trigger radius → "Enemies approaching!"
Wave 1 spawns → "Wave 1 incoming!"
Player kills all mobs → "Wave 1 cleared!"
Configurable delay (default 3 seconds)
Wave 2 spawns → "Wave 2 incoming!"
Repeat until all waves complete → "Area cleared!"
When all groups in the dungeon are cleared → "Dungeon complete!"

Dungeon Setup Workflow¶

Create a dungeon template linked to an instance asset
Enter the dungeon instance with the test command
Walk to each combat area and add spawn groups
Walk to trigger points and set them
Walk to mob spawn locations and add them
Add waves defining mob types and counts
Test by re-entering the instance and walking to triggers

Template Management¶

create¶

Create a new dungeon template.

Usage: /ddev create <id> <instanceName> <displayName>

Permission: htskyblock.admin.dungeondev

Arguments:

<id> — Unique template ID (stored lowercase)
<instanceName> — Must match a folder name in Server/Instances/
<displayName> — Friendly name shown in messages

Example:

/ddev create skydungeon1 Skydungeon1 "Sky Dungeon 1"

Instance Assets

The instanceName must match an instance asset pack folder in Server/Instances/. This can be any custom dungeon world created by modders or map builders.

delete¶

Delete a dungeon template permanently.

Usage: /ddev delete <id>

Example:

/ddev delete skydungeon1

list¶

List all dungeon templates.

Usage: /ddev list

Displays:

Template ID
Instance name
Display name

info¶

Show detailed information about a dungeon template including all groups, spawn points, and waves.

Usage: /ddev info <id>

Example:

/ddev info skydungeon1

Displays:

Template ID, instance name, display name
Each spawn group with:
- Trigger position and radius
- Wave delay
- All spawn point coordinates
- All waves (mob type and count)

Spawn Group Management¶

addgroup¶

Add a new spawn group to a dungeon. The trigger point is set to your current position.

Usage: /ddev addgroup <dungeonId> <groupId>

Arguments:

<dungeonId> — Dungeon template ID
<groupId> — Unique name for this group (e.g., entrance, room1, boss_room)

Example:

# Stand at the center of the combat area
/ddev addgroup skydungeon1 entrance_guards

Naming Groups

Use descriptive names for groups so you can identify them later. Names like room1, hallway, boss_room are clear and easy to reference.

setpoint¶

Update the trigger point for a spawn group to your current position.

Usage: /ddev setpoint <dungeonId> <groupId>

Example:

# Stand where you want the trigger zone centered
/ddev setpoint skydungeon1 entrance_guards

setradius¶

Set the trigger radius for a spawn group. Default is 10 blocks.

Usage: /ddev setradius <dungeonId> <groupId> <radius>

Example:

/ddev setradius skydungeon1 entrance_guards 15

Trigger Radius

The radius is a sphere check from the trigger point. When the player's position is within this distance, the group activates. Larger radii trigger earlier, giving more dramatic "enemies incoming" moments.

setdelay¶

Set the delay (in seconds) between waves for a spawn group. Default is 3 seconds.

Usage: /ddev setdelay <dungeonId> <groupId> <seconds>

Example:

/ddev setdelay skydungeon1 entrance_guards 5

Spawn Point Management¶

addspawn¶

Add a spawn point at your current position. Mobs will appear at these locations.

Usage: /ddev addspawn <dungeonId> <groupId>

Example:

# Walk to where mobs should appear, then:
/ddev addspawn skydungeon1 entrance_guards
/ddev addspawn skydungeon1 entrance_guards
/ddev addspawn skydungeon1 entrance_guards

Multiple Spawn Points

Add several spawn points per group so mobs spread out. If a wave has more mobs than spawn points, mobs cycle through the points (mob 4 uses point 1 again, etc.). The spawn point also saves your facing direction (yaw), so mobs face the direction you were looking.

removespawn¶

Remove a spawn point by index.

Usage: /ddev removespawn <dungeonId> <groupId> <index>

Example:

# Use /ddev info to see spawn point indices
/ddev removespawn skydungeon1 entrance_guards 2

Wave Management¶

addwave¶

Add a wave to a spawn group. Waves are executed in the order they are added.

Usage: /ddev addwave <dungeonId> <groupId> <mobType> <count>

Arguments:

<mobType> — Hytale NPC role name (e.g., Trork_Warrior, Trork_Grunt)
<count> — Number of mobs to spawn in this wave

Example:

# Add 3 waves to a group - increasing difficulty
/ddev addwave skydungeon1 entrance_guards Trork_Warrior 3
/ddev addwave skydungeon1 entrance_guards Trork_Warrior 5
/ddev addwave skydungeon1 entrance_guards Trork_Grunt 8

Mob Types

The mob type is the NPC role name from Hytale's built-in NPC system. Mobs spawn with their full default AI, animations, and behavior. Common roles include Trork_Warrior, Trork_Grunt, Trork_Archer, and other role names defined in the game or mod packs.

removewave¶

Remove a wave by index.

Usage: /ddev removewave <dungeonId> <groupId> <index>

Example:

# Use /ddev info to see wave indices
/ddev removewave skydungeon1 entrance_guards 1

Testing¶

test¶

Spawn a dungeon instance and teleport into it. This registers the instance with the wave system so triggers become active.

Usage: /ddev test <dungeonId>

Example:

/ddev test skydungeon1

What Happens:

The instance asset is spawned as a new temporary world
You are teleported into the instance
The instance is registered with the wave system
Walking near trigger points will start wave spawning
Use the instance's return system to leave

Standalone Test Command

There is also a /dungeontest command that spawns the default skydungeon1 template. For full control, use /ddev test instead.

Configuration¶

The dungeon system is toggled in config.json:

{
  "dungeon": {
    "enabled": true
  }
}

Set enabled to false to disable the entire dungeon system (wave scheduler, commands, etc.).

Complete Example¶

Here's a full workflow for setting up a dungeon with two combat rooms:

# 1. Create the dungeon template
/ddev create skydungeon1 Skydungeon1 "Sky Dungeon 1"

# 2. Enter the dungeon instance
/ddev test skydungeon1

# 3. Walk to the first combat room, add a group
/ddev addgroup skydungeon1 room1

# 4. Walk to where mobs should spawn, add spawn points
/ddev addspawn skydungeon1 room1
/ddev addspawn skydungeon1 room1
/ddev addspawn skydungeon1 room1

# 5. Add waves (3 waves of increasing difficulty)
/ddev addwave skydungeon1 room1 Trork_Warrior 3
/ddev addwave skydungeon1 room1 Trork_Warrior 5
/ddev addwave skydungeon1 room1 Trork_Grunt 8

# 6. Set trigger radius and wave delay
/ddev setradius skydungeon1 room1 12
/ddev setdelay skydungeon1 room1 4

# 7. Walk to the second combat room, repeat
/ddev addgroup skydungeon1 room2
/ddev addspawn skydungeon1 room2
/ddev addspawn skydungeon1 room2

# 8. Add a boss wave
/ddev addwave skydungeon1 room2 Trork_Warrior 4
/ddev addwave skydungeon1 room2 Trork_Grunt 2

# 9. Verify configuration
/ddev info skydungeon1

# 10. Re-enter to test the full dungeon
/ddev test skydungeon1

Instance Compatibility¶

The dungeon system works with any instance asset pack. The wave configuration is separate from the dungeon world itself — server owners or modders can create custom instance worlds in Server/Instances/ and link them to dungeon templates. The spawn groups, trigger points, and waves are configured independently via commands.

Troubleshooting¶

Mobs Not Spawning¶

Check that the dungeon system is enabled in config.json
Verify spawn groups have spawn points: /ddev info <id>
Verify spawn groups have waves: /ddev info <id>
Look for [DungeonManager] errors in the console
Ensure the NPC role name is correct (e.g., Trork_Warrior not trork_warrior)

Waves Not Progressing¶

Each group needs multiple waves for progression. One addwave = one wave.
Use /ddev info <id> to check the wave count per group
Check the console for [DungeonWave] messages showing state transitions

Trigger Not Activating¶

Verify you entered via /ddev test (which registers the instance with the wave system)
Check trigger position: /ddev info <id> shows coordinates
Try increasing the trigger radius: /ddev setradius <id> <group> 20
The trigger is a sphere — check that the Y coordinate is close to your walking level

Instance Not Found¶

The instanceName must exactly match a folder in Server/Instances/
Check capitalization — Skydungeon1 is not the same as skydungeon1

Player Access¶

Players enter dungeons with the /dungeon command. Each dungeon can be locked behind a per-dungeon permission.

Player Commands¶

Command	Description
`/dungeon list`	Show available dungeons (with locked/unlocked status)
`/dungeon <name>`	Enter a dungeon by template ID

Player Permissions¶

Permission	Description
`htskyblock.dungeon`	Base `/dungeon` command access
`htskyblock.dungeon.<id>`	Access to a specific dungeon
`htskyblock.dungeon.all`	Access to all dungeons

Grant htskyblock.dungeon to all players so they can use /dungeon list, then grant specific dungeon permissions (e.g., htskyblock.dungeon.skydungeon1) to control access. Staff can use htskyblock.dungeon.all to bypass per-dungeon checks.

Admin Permission Summary¶

Command	Permission
Base `/dungeondev`	`htskyblock.admin.dungeondev`
`/dungeontest`	`htskyblock.admin.dungeontest`

All /dungeondev subcommands inherit from the base htskyblock.admin.dungeondev permission.