Custom Dungeon

The mod is the engine: worldgen, instanced dimensions, portals, keys, waves, bosses, rules, and rewards. You add your own dungeons as JSON (and optional SNBT rooms) without writing Java.

The jar ships three example dungeons so you can test the engine and copy the format. They are optional. Delete or disable them and ship only your content.

• Minecraft: 1.16.5
• Loader: Forge 36.1+
• Mod id: customdungeon
• License: MIT

Features

• JSON dungeons — one folder per dungeon under data/<namespace>/dungeons/<name>/
• Two worldgen modes — surface shrine + portal into an instance, or a full dungeon embedded in the Overworld / Nether / End
• ASCII layouts — draw rooms with letters, - and |; stack floors for 3D maps
• Procedural or SNBT rooms — palettes, shapes, loot chests, or structure-block exports
• Waves and bosses — equipment, health, custom loot tables
• Portal activation — catalyst, bound key, both, or always open
• Run rules — break/place protection, PvP, timers, keep inventory, room constraints (mining fatigue, slowness, …)
• Rewards — loot tables, XP, commands, messages
• Server overrides — tweak dungeons from config/customdungeon/dungeons/ without repacking

Example dungeons (optional)

Three examples are included so you can play, copy, or delete them. The mod works with zero of them. Put your own folders under data/<namespace>/dungeons/ (or disable the examples below).

To remove the examples from a pack:

1. Disable — in a datapack or config/customdungeon/dungeons/<name>/dungeon.json, set "enabled": false for example_crypt, example_nether, and example_end.
2. Override — ship a datapack that replaces those folders with your own dungeons (or empty stubs).

Already-generated chunks will not grow new shrines or embeds. Explore new terrain, start a new world, or use /cd place <id>.

Playing

Crypt shrine

1. Craft a Dungeon Key (gold ingots + ender pearl).
2. Find a shrine (/cd locate example_crypt if you are op) or /cd place example_crypt.
3. Right-click the portal with the key to bind it.
4. Hold stone and the bound key, then use the portal.
5. Clear rooms. On victory you get a title countdown, then extract. Use a Dungeon Exit Token to leave early.

Embedded dungeons (Nether / End)

Walk into the structure. Rooms are protected, encounters spawn, and leaving unbinds you in place (you stay in that dimension).

Items

/give @p customdungeon:dungeon_key{Dungeon:"customdungeon:example_crypt"} 1

Commands

Alias: /cd. Ids can be example_crypt or customdungeon:example_crypt.

/customdungeon list
/customdungeon info <id>
/customdungeon start <id>
/customdungeon leave
/customdungeon locate [id]     # op — clickable coords in front of the shrine
/customdungeon place <id>      # op — shrine or embed at your feet
/customdungeon reload          # op — config overlay only (use /reload for datapacks)
/customdungeon complete        # op — force-clear the current run

Vanilla:

/locate customdungeon:dungeon_shrine

For datapack authors

Each dungeon is one folder:

data/<namespace>/dungeons/<name>/
  dungeon.json              required
  portal.json               optional — merged into dungeon.portal
  rooms/<room>.json         procedural (or SNBT) room templates
  rooms/<room>.snbt         structure-block export as a room
  encounters/<id>.json      waves / boss

Dungeon id is <namespace>:<name> unless dungeon.json sets "id".

Relative refs ("encounters": ["skeletons"]) resolve to <namespace>:<name>/skeletons.

Omitted keys use defaults. Only write what you change.

Vanilla /reload reloads datapacks. /cd reload reloads config/customdungeon/dungeons/ only.

The mod provides empty dimension customdungeon:dungeon for instanced runs. Point portal.dimension at it, or at your own datapack dimension.

Minimal shrine dungeon

{
  "display": { "name": "My Crypt" },
  "natural_spawn": {
    "enabled": true,
    "dimensions": ["minecraft:overworld"],
    "biomes": ["#is_forest"],
    "rarity": 48
  },
  "layout": {
    "shape": ["E-H-B"],
    "rooms": [
      { "id": "entrance", "encounters": ["skels"] },
      { "id": "hall", "encounters": ["skels"] },
      { "id": "boss", "encounters": ["boss"] }
    ]
  }
}

{
  "activation": "both",
  "frame": "minecraft:stone_bricks",
  "catalyst": "minecraft:stone"
}

Put the portal object in portal.json or under "portal" in dungeon.json.

Embedded dungeon (no shrine)

"natural_spawn": {
  "enabled": true,
  "embed": true,
  "dimensions": ["minecraft:the_nether"],
  "layer": "nether",
  "min_y": 40,
  "max_y": 90,
  "rarity": 24
}

ASCII shape

Letters are rooms. - | + link them. A 2D list is one floor; a list of lists stacks floors on Y.

"shape": [
  ["  G  ", "  |  ", "E-H-B"],
  ["  A  ", "  |  ", "  T  "]
],
"cells": { "E": "entrance", "H": "hall", "B": "boss", "G": "graves", "A": "chapel", "T": "treasury" }

If cells is omitted, the letter matches the room id prefix. start_room defaults to the first room.

Procedural rooms get a corridor of gap blocks. SNBT rooms sit wall-to-wall (doors punched).

Other layouts: omit shape for a linear row; "type": "grid" with grid_x / grid_z; or set x / z / next for exact offsets.

JSON reference

Defaults apply when a key is missing.

dungeon.json

natural_spawn

portal / portal.json

Unbound portal: sneak-use a key with NBT Dungeon to bind it.

entry

instance

layout

rooms/<id>.json

features: pillars, torches, windows, chest_count, carpet, fountain, cobwebs, skulls, bones, bookshelves, braziers, altar, hanging_lights, cages, vines, lava_moat, water_moat, floor_pattern (spots, checker, mosaic, path, rings, cracked, bones).

Constraints

On rules (whole run) or a room. Reapplied while inside, cleared on leave. Room effects stack.

Booleans: slowness, mining_fatigue, weakness, hunger, wither, poison, glowing, nausea, darkness (blindness on 1.16). Amplifiers: slowness_level, mining_level, wither_level. Extra list: "effects": [{ "id": "minecraft:wither", "amplifier": 0, "duration": 80, "particles": true }].

encounters/<id>.json

Mob spec: entity, count (number or {min,max}), name, health, damage, nbt, glowing, loot_table, equipment.helmet / chestplate / leggings / boots / mainhand.

rules

rewards

on_complete / on_fail / on_room_clear: loot_table, xp, commands, broadcast, message, item_count.

Config

config/customdungeon-common.toml

Quick test

/cd start example_crypt
/cd start example_nether
/cd start example_end
/cd place example_crypt

Crypt portal: bound key + stone. Nether / End: explore new chunks in that dimension.