Dungeon data and authoring

A native dungeon combines a server definition, Jigsaw templates and a configured entrance in the world. Scripts control encounters, gates and completion; selecting a mode alone does not build those encounters.

Where the files live

Definitions live at data/<namespace>/dungeons/**/*.json. A file normally uses its resource ID, unless id overrides it. Jigsaw pools and templates remain ordinary world-generation resources; titles and messages use client language files.

The shipped definitions are isekaiexpansion:dark_delves (Dark Delves), isekaiexpansion:sunken_sanctum (Sunken Sanctum) and isekaiexpansion:verdant_temple (Verdant Temple). The built-in isekaiexpansion:dungeon_instance dimension has an empty flat generator: templates must supply the floors and all playable blocks.

Minimal example

Save this reduced form of the shipped Dark Delves encounter at data/example/dungeons/trial.json, then configure a gateway for example:trial. It uses the mod’s existing starting pool, spawns one zombie after 100 ticks (5 seconds), and begins a 600-tick (30-second) extraction after its hazard is cleared.

{
  "difficulty": "uncommon",
  "modes": [
    "hazard"
  ],
  "structure": {
    "start_pool": "isekaiexpansion:dark_dungeon/dungeon_spawn",
    "start_jigsaw": "isekaiexpansion:spawn",
    "base_y": 80,
    "jigsaw_depth": 64
  },
  "scripts": [
    {
      "id": "example:opening",
      "trigger": "session_started",
      "actions": [
        {
          "type": "spawn_hazard",
          "offset": [
            7,
            0,
            0
          ],
          "waves": [
            {
              "entries": [
                {
                  "entity": "minecraft:zombie",
                  "count": 1,
                  "delay_ticks": 100
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "example:finish",
      "trigger": "hazard_cleared",
      "actions": [
        {
          "type": "complete",
          "completion_delay_ticks": 600
        }
      ]
    }
  ]
}

Fields

Unknown fields reject the definition at every parser-owned object level. Arrays and objects must have the expected container type. Enum strings are trimmed and case-insensitive; blank values use that enum’s default, unknown values reject. Numeric fields below describe the post-parse clamps; syntactically invalid numbers still fail parsing.

Root

Structure

Scripts and actions

Hazard waves

Powerup pool

The nbt value uses the same typed JSON NBT rules as quest spawning: a compound object, homogeneous lists and explicit numeric wrappers where needed. It is not an SNBT string. Arbitrary entity NBT remains the entity’s own schema; the dungeon parser validates its NBT representation, not every entity-specific key.

When scripts run

Replay memory is per session and script ID. Actions execute before the replay state is recorded, without a transaction or per-action rollback. repeatable allows every qualifying dispatch; cooldown stores the next eligible game tick.

spawn_hazard creates ordered waves. Within a wave, batches follow their own delays; the next wave waits until every emitted, tracked entity is gone. Unloaded entity UUIDs remain tracked rather than counting as kills. Failed spawn searches are not retried as the same batch. After all hazards clear, rogue-like offers are also generated for eligible participants, independently of an explicit offer_powerup action.

spawn_return_portal creates an exit without completing the session; must_complete prevents its use. complete starts extraction rather than immediately awarding completion. During extraction, new area scripts and hazard/tick processing stop; the original timed deadline is checked first and can still fail the run. Finishing waits for an online participant in the dungeon.

unlock_gate targets a controller at the integer origin offset; a missing controller or empty link set logs a warning and does not unlock a substitute location. message sends the translated message to online participants. offer_powerup needs rogue_like and a nonempty pool.

Mode and membership boundaries

timed creates the initial deadline; must_complete blocks voluntary return portals and selects the native dungeon death-respawn path. rogue_like enables temporary upgrade offers. common and hazard do not automatically create enemies or completion rules.

A physical gateway reuses an active session matching its entrance and dungeon definition. The current entry path does not compare the entrant’s party with that session’s recorded party key. Thus solo, party and open must not be used as an access-control or private-party isolation guarantee. A player already bound to an active session cannot start another.

Placed authoring blocks

Editing requires creative mode and permission level 2. Use the main hand to open the gateway, trigger or controller editor. The four block/item IDs are isekaiexpansion:dungeon_gateway, isekaiexpansion:dungeon_script_trigger, isekaiexpansion:dungeon_unlock_controller and isekaiexpansion:dungeon_unlockable.

1. Place the gateway in the world-entry structure and set its dungeon ID. A nonspectator standing in its bounds charges for 40 ticks (2 seconds); leaving clears the charge. Portal cooldown also resets charging.
2. Place trigger blocks inside the dungeon template and bind area_entered script IDs. The scan uses a sphere, optional line of sight and on_enter or while_present activation. Replay mode still governs the script itself.
3. Use the unlockable item on an existing block to capture its block state as a gate facade. This preserves the block state, not the original block entity’s inventory or other NBT. A facade’s appearance does not replace the gate’s full-cube locked collision.
4. Sneak-use a controller while holding its controller item to select it. Use that selected item on gate cells to toggle relative links, in the same dimension.
5. Configure controller timings and point an unlock_gate action at it. A fresh session resets controllers referenced by its definition. Unlocking orders cells outward and clockwise in the two axes with the widest spans; cells remain collision-blocking until their own animation ends.

Trigger scans dispatch at most one player per scan. Their occupant cache is transient and updated only through the scanned prefix before that dispatch; on_enter is therefore not a durable once-per-player guarantee. Use script replay rules for durable once/cooldown behaviour.

The following fields are placed-block or controller-item NBT, separate from the dungeon definition JSON. Editors write them for you; runtime fields are included so a saved structure can be inspected accurately.

Gateway and trigger/controller geometry is invisible to ordinary players. Unlockable cells retain their facade while locked, then become non-colliding when unlocked. Trigger/controller editor updates require the player within 8 blocks; gateway configuration checks creative/operator permission and the block type without that distance check.

Built-in temporary upgrades

All IDs below use isekaiexpansion:. A draft offers up to 3 distinct eligible choices and stores the pending choices per participant. An unpicked offer is reused; choosing requires the active session, participant membership and an offered ID. Levels and pending choices survive reconnects, and levels are cleared on departure or resolution.

These event effects require an active participant in the session dimension. Clearing levels stops future hooks; existing timed status effects expire by their own durations.

Completion advancement

The advancement trigger isekaiexpansion:dungeon_completed fires for online participants on successful native dungeon completion. Its custom condition fields are below; the ordinary advancement player predicate is handled by Minecraft. This condition object is separate from the strict dungeon definition schema.

Validation

The loader catches errors per file and publishes the valid subset, even if other files failed. Duplicate explicit dungeon IDs retain the first successfully inserted definition in loader iteration order and report the later duplicate. This is not an atomic rollback to the old catalogue.

Definition parsing does not resolve every pool, connector, dimension, script reference, entity type or powerup. Entry later plans the Jigsaw graph and rejects missing/empty pools, missing starting connectors, unsupported pieces or a layout not containing its anchor. The layout may cover at most 256 chunks; guarded preloading adds a 1-chunk border and has a 1024-chunk limit.

The initial entry search checks up to 8 blocks horizontally and 8 vertically for empty, fluid-free feet/head space and a supporting collision shape below. It stores the chosen feet position before participants bind. Once populated, the session keeps that exact spawn; restoring a damaged layout does not silently relocate it.

In a test world, verify successful entry and return, every script replay mode, restart during a wave and gate animation, missing references, failed spawn positions and completion near the timed deadline. Test actual party admission rather than inferring it from team_policy.

Reloading

Definitions use server data reload. Valid entries replace the previous catalogue; malformed entries can disappear on /reload. Active sessions look up the current definition during ticking: removing or invalidating their definition fails them. Stored session origin, spawn, slot and deadline are not recalculated from edited structure/time fields.

Editing a gateway or trigger updates its placed configuration; it does not rewrite the JSON definition. Full layout replacement is not guaranteed by a definition reload: an existing placed session with a safe arrival can continue using its current blocks.

Related

• Dungeon runtime — lifecycle, save schema, hooks and commands.
• Progression data — progression graph definitions.
• Quest objectives — native dungeon completion objectives and typed NBT.