EpicQuestDungeoning

EpicQuest Dungeoning — author documentation for NeoForge 1.21.1.

Build jigsaw dungeon packs, register them in config, and let players open them through keyed portals. Layouts generate in a shared void dimension on keystone activate, then wipe on extract until the next activation.

Strongly recommended: use EventMaker alongside this mod. EventMaker helps authors configure events (invisible triggers + datapack/KubeJS command polls) inside dungeon jigsaw pieces — doors, corridors, boss rooms, loot gates, cutscenes, and more. Pair it with /dungeon complete / the completion API when a trigger should extract the party.

How it works

1. Author a pack: structure pieces (.nbt) + vanilla-style template pools under config/epicquest_dungeoning/dungeons/<id>/.
2. Register the dungeon in dungeons.json with a required jigsaw object.
3. Player attunes a dungeon key (anvil: unbound key + attunement_item) and inserts it into a Dungeon Keystone.
4. The mod generates the jigsaw instance, fills leftover connectors with dead-ends, and ensures unique_templates (e.g. boss) once in a late depth band.
5. Portal entry teleports to a Dungeon Player Spawn block placed in your pieces.
6. Completion / return starts a 10s group extract, then wipes that dungeon (no regen until next activation).

Pack layout

config/epicquest_dungeoning/
  dungeons.json
  images/                          optional preview PNGs
  dungeons/<dungeon_id>/
    structures/<namespace>/.../*.nbt
    worldgen/template_pool/<namespace>/*.json

Use one namespace per pack (often the same as dungeon_id). Pool file .../quartz_corridors/halls.json → id quartz_corridors:halls. Structure file .../hall_1.nbt → quartz_corridors:hall_1.

Building pieces

• Structure Block SAVE mirrors into the pack under config/.../structures/ and creates the pack folder if needed.
• Put a Dungeon Player Spawn in the start/anchor piece (entry pose).
• Put a Dungeon End Pad only if you use reach_end completion.
• Wire jigsaws with matching name/target pairs (vanilla rules). Dead-end pieces should be terminal (minecraft:empty target/pool); the filler can adapt their name to seal leftover openings.
• Keep at least one small dead-end in fallback_pool. If nothing fits collision checks, the smallest attachable dead-end is force-placed.

Registering (dungeons.json)

{
  "id": "quartz_corridors",
  "name": "Quartz Corridors",
  "description": "A labyrinth of smooth quartz halls.",
  "attunement_item": "minecraft:quartz",
  "jigsaw": {
    "start_pool": "quartz_corridors:anchor",
    "start_jigsaw_name": "quartz_corridors:anchor",
    "size": 12,
    "max_distance_from_center": 160,
    "fallback_pool": "quartz_corridors:dead_ends",
    "unique_templates": ["quartz_corridors:boss"],
    "unique_depth_min_ratio": 0.75,
    "unique_depth_max_ratio": 1.0
  },
  "completion": { "type": "reach_end", "stand_seconds": 3 }
}

Required jigsaw fields

Global options: return_button_item, cooldowns, protect_structures, teleport_charge_seconds, portal_activation_radius.

Completion

• kill_entity — "entity": "minecraft:warden"
• collect_items — "items": [{ "id", "count" }] (detect only; does not consume)
• reach_end — stand on a Dungeon End Pad for stand_seconds

Omit completion to disable auto-triggers; return button / API / /dungeon complete still extract.

Author checklist

1. Choose namespace / dungeon id.
2. Build start piece (spawn block + start jigsaw) plus halls, rooms, and dead-ends.
3. Write template pools; SAVE or drop NBT under structures/.
4. Add the dungeons.json entry with jigsaw.
5. Optional: unique_templates, completion, preview image.
6. Recommended: author in-piece events with EventMaker.
7. /dungeon reload, then /dungeon generate <id> or activate a keyed portal.
8. Verify spawn, connectivity, uniques, sealed openings, and events; tune size / pools.

Useful commands (op)

• /dungeon generate <id> · /dungeon wipe <id>
• /dungeon piece <id> <piece> · /dungeon pieces <id>
• /dungeon reload · /dungeon list · /dungeon givekey <id> · /dungeon placeportal
• /dungeon complete <id> · /dungeon return

Also included

• Attunable keys, rich tooltips, optional JEI recipes
• Structure protection, teleport charge, reload / Reset All progress UI
• Public completion API + NeoForge events for other mods

Requirements: Java 21 · NeoForge 1.21.1