Generated dungeons

A generated dungeon has no template world. You build small rooms once, describe how they connect, and a generator assembles a new layout for each run: from a start room, through normal, treasure and secret rooms, to a boss room.

Fixed and generated dungeons share the same runs, menus, chests, NPCs, mobs, events and facts. What changes is where the rooms come from.

The pieces

Piece	Entry	What it is
Door kind	Dungeon Connector Type	The size of a door opening, the block that seals an unused door, and which kinds can be joined.
Room	Dungeon Room Template	A saved structure (a Paper structure .nbt kept as an artifact) with its category, doors and markers.
Pool	Dungeon Room Pool	A weighted list of room templates.
Generator	Dungeon Generator	The rules: which pools, how many rooms, how deep the boss is, how often a path branches.
Affix	Dungeon Affix	A modifier of the run drawn at random, such as "fast mobs".
Dungeon	Dungeon Instance	Its generator field turns it into a generated dungeon.

Build one, step by step

1. Door kinds. Add at least one Dungeon Connector Type. Set its width and height (3 by 3 by default), the sealBlock that closes an unused door (minecraft:stone_bricks by default) and, if you have several kinds, compatibleWith. A kind can always be joined to itself.
2. Rooms. For each room, add a Dungeon Room Template and use the in-game editor to capture its blocks and place its doors and markers. Pick its category.
3. Pools. Add a Dungeon Room Pool for the start rooms, one for the boss rooms, one (or more) for the other rooms, and optionally one for corridors. A start, boss or corridor pool holds templates of that category only. A normal pool may mix NORMAL, TREASURE and SECRET templates.
4. Generator. Add a Dungeon Generator and set startPool, bossPool, optionally corridorPool, and normalPools with a weight each.
5. Dungeon. On your Dungeon Instance, set generator. Leave templateWorld empty: a generated dungeon has no template world. Isolation must be AUTO or WORLD_PER_RUN.
6. Game logic. Use the onEnter and onClear triggers of the room templates, the TRIGGER markers, the room events, Dungeon Mob Spawn entries on MOB markers, and finish the run with Dungeon Complete.

If the pools and templates cannot make a dungeon, the launch is refused and the server log says why (for example a pool without any start room, or a template without a readable capture). The messages field of the generator holds the reasons reported to you, the author. The player sees only a short text taken from the snippets content.dungeon_generated.refusal.setup (the pools and templates cannot make a dungeon) and content.dungeon_generated.refusal.paste (the rooms could not be pasted), which you can edit in the web panel. Nothing is taken from them. The line announcing the affixes of a run is the snippet content.dungeon_generated.affix.announcement.

Room categories

The category of a room template says what role it can play.

Category	Role
START	The run begins here. One per dungeon. It must hold a SPAWN marker.
NORMAL	An ordinary room.
TREASURE	Always on a branch, never on the path to the boss.
CORRIDOR	Inserted between two rooms that cannot touch directly.
SECRET	Always a dead end.
BOSS	The last room. One per dungeon.

Rooms are joined door to door, so a room without doors can only be a dead-end START. A door with required on must be joined to another room: a template that cannot fill all its required doors is never used. A door nobody went through is closed with the sealBlock of its kind.

Markers

A marker is a point of interest inside a room. Each one has a kind:

Kind	What it does	Field to fill
SPAWN	Where players appear when the run begins. Only the first SPAWN of the start room is used.	none
CHEST	A loot chest is placed here. Its position and yaw replace the location of the entry. A chest named by a marker is always placed, even if its entry is in manualMode.	chest: a Dungeon Loot Chest
TRIGGER	The triggers are fired for the player who reaches the room.	triggers
NPC	A Dungeon NPC Instance stands here, shown to the members of the run.	npc
MOB	A Dungeon Mob Spawn makes its mobs appear here, the first time a member of the run enters the room.	mob

The yaw of a marker turns a chest (it faces back toward the yaw) and an NPC (it looks toward it). The marker is linked to its entry by its place in the markers list.

Rooms in play

When a player enters a room of a generated dungeon, the onEnter triggers of its template fire, then the triggers of its TRIGGER markers and the mobs of its MOB markers. With enterOnce on (the default for templates), they fire only the first time each player enters the room in a run.

The onClear triggers fire once per run when a Dungeon Clear Room action runs while the player stands in the room. The platform never decides alone that a room is cleared: you do, for instance from the mob death event when the last monster dies.

The triggers of a room read these values from the context (with an interaction_context_variable):

Key	Value
RUN_ID	Id of the run.
SEED	Seed of the dungeon, in decimal.
ROOM	Number of the room: 0 is the start room, then in the order the generator placed them.
ROOM_TEMPLATE	Id of the room template entry.
DIFFICULTY	The difficulty of the generator.
POSITION	The block of the marker for a TRIGGER marker, otherwise the position of the player.

The triggers of an affix read RUN_ID, SEED and DIFFICULTY only. A fixed dungeon provides none of these keys.

Seeds, affixes and difficulty

The same seed always gives the same dungeon, so a layout can be replayed. A new seed is drawn for each run. The seed is saved with the run, so a reload rebuilds the same dungeon in memory. If it cannot be rebuilt, the run is closed at start-up instead of being adopted with rooms nobody knows.

Affixes are drawn after the layout, from the affixes of the generator by their weight, affixCount of them without repeating. The draw follows the seed but never changes the layout. Their modifiers and triggers apply to each member when the run starts.

difficulty is just a number handed to your triggers through the context: it does not change the layout by itself.

Generator settings that matter

Field	Default	Notes
minRooms, maxRooms	6, 10	Total rooms including start and boss, corridors excluded. Allowed range: 2 to 256.
minBossDepth	3	The boss is at least this many steps from the start.
branchRatePercent	40	Chance, in percent, that a room beyond the main path opens a side branch.
quotas	none	Bounds on the number of NORMAL, TREASURE and SECRET rooms. A category without a bound is unlimited.
trialBudget, replans	20000, 5	How hard the search tries before it fails. The trial budget times (replans + 1) must stay within 5 000 000.
baseY	64	Height of the floor of the start room in the world of the run.
roomsPerTick	4	Rooms pasted per server tick. Lower keeps ticks short; higher is faster.
pasteTimeoutSeconds	120	After this, the launch is cancelled, the cost refunded and the world thrown away.
naturalSpawning	off	Monsters and animals spawn by themselves in the run world. Off by default.
verticalMargin	1.0	Blocks added above the ceiling and below the floor of every room when deciding whether a player is inside.
paster	STRUCTURE	Uses the Paper structure API: no other plugin needed.

A room template is at most 256 blocks along each side, with at most 64 doors and 1024 markers.

The in-game editor

Open a Dungeon Room Template in the web panel and click the content editor of the artifactId field. You get a set of tools in your hotbar:

Tool	Use
Corner wand	Left click a block for corner A, right click a block for corner B.
Capture	Saves the blocks of the box as the structure of the template.
Door tool	Right click a block of a wall to add a door (the block is the bottom centre of the opening). Left click to remove the doors there.
Door type	Right click for the next connector type, left click for the previous.
Required toggle	Toggles whether the next doors are required.
Marker tool	Right click a block to add a marker in front of it. Left click to remove the markers there.
Marker kind	Right click for the next kind, left click for the previous.
Save	Writes the doors and markers into the entry.

A boss bar shows the box size, the number of doors and markers, and whether you have unsaved work. The size of the room is read from the saved structure, never typed. You must create and publish at least one connector type before you can add a door.

The captures skip entities by default, because a living entity changes the room at every capture and comes back as a loose mob in every copy. These behaviours and all the texts of the editor are Typewriter snippets under content.dungeon_room_template., so you can change or translate them in the web panel:

Snippet	Default	Meaning
capture.include_entities	false	Whether a capture saves the entities of the box.
capture.max_volume	262144	Most blocks one capture reads. It is read in one server tick: a very large box holds that tick.
capture.timeout_seconds	30	Seconds to wait for a capture before giving up.
sound.confirm	entity.experience_orb.pickup	Sound after a capture or a save. Empty: none.

Limits and good practice

• Generated dungeons use WORLD_PER_RUN only: each run creates a world and deletes it afterwards.
• The editor of fixed rooms (nodes) has its own snippets under content.dungeon_room. (messages node.*, save.*, editor.*, tools tool.add, tool.remove, tool.save).
• Build rooms so that two joined doors of the same kind line up. An even opening width has its extra block on the higher x or z of the template. The generator slides a room by one block when an even opening needs it.
• The whole dungeon must fit between the lowest and highest block of the world, counted from baseY.
• Do not rely on a fixed number of rooms: use markers and events instead of room numbers.

Related

• Runs and world isolation
• Entities in dungeons