DungeonExpanse External Addon

External addon for adding rooms to the Dungeon Expanse Addon

Cross-Pack Room Registry — Usage Guide

Version: 2.0.0 · Core pack: Dungeon Expanse · Transport: chunked system.sendScriptEvent()


1. Overview

The Dungeon Expanse core pack exposes a cross-pack room registry so that separate behaviour packs can contribute additional room templates to dungeon generation. This guide documents the wire protocol, the RoomTemplate schema, and a complete example addon you can copy to add your own rooms.


2. Architecture

External behaviour pack                Core: Dungeon Expanse
└─ DungeonAddon.ts                     └─ RoomRegistry.ts
   ├─ Ping every 20 ticks                 ├─ Beacons ready
   ├─ Wait for ready          ◀───────────┤
   ├─ Send chunked rooms      ───────────▶├─ Receives chunks
   │                                       ├─ Reassembles payload
   └─ Await send complete ◀───────────────└─ Registers templates

           Communication: /scriptevent

Both sides communicate exclusively through these script events:

Event ID Direction Purpose
dungeon:ping external → core Sender announces it is ready
dungeon:ready core → external Core confirms it is listening
dungeon:room_chunk external → core One chunk of a JSON payload
dungeon:room_final external → core Signals the last chunk of a transaction

3. Handshake

The handshake guarantees the receiver's listener is attached before chunks arrive. Events sent before the core subscribes are silently lost.

External                              Core
   │                                    │
   ├── dungeon:ping ──────────────────▶ │
   │                                    │ Listener attached at module load
   │ ◀──────────────── dungeon:ready ───┤
   │                                    │
   ├── dungeon:room_chunk (0) ────────▶ │
   ├── dungeon:room_chunk (1) ────────▶ │
   ├── dungeon:room_chunk (2) ────────▶ │
   ├── dungeon:room_final ────────────▶ │
   │                                    │ Reassemble, validate, register

Core-side behaviour

  • RoomRegistry.registerCrossPackListener() is called at module load from main.ts, so the listener is attached as soon as the core's script starts.
  • The core broadcasts dungeon:ready once immediately, then every 20 ticks for 30 seconds, so a late-starting external pack never misses it.
  • Every dungeon:ping the core receives triggers an additional dungeon:ready response.

External-side behaviour

  • Subscribe to dungeon:ready at module load (before any world data loads).
  • On worldLoad, begin sending dungeon:ping every 20 ticks.
  • On the first dungeon:ready, stop pinging and send the payload after a 1-tick grace period.
  • If no dungeon:ready arrives after 600 ticks (30 s), send the payload anyway — this keeps the addon functional against older core versions.

4. Chunking protocol

Script-event messages are limited to 2048 characters. Each payload is JSON-serialised, split into ≤200-character chunks, then wrapped in an envelope:

// dungeon:room_chunk payload
{
  "id": "exxxxx",       // transaction id, unique per send
  "i": 0,               // chunk index (0-based)
  "n": 3,               // total chunk count
  "d": "{\"rooms\":[…]}" // ≤200-character slice of the JSON payload
}

// dungeon:room_final payload
"exxxxx"                // the transaction id as a plain string

Receiver guarantees

Property Guarantee
Duplicate chunks Ignored; a chunk is only counted when its slot is empty.
Out-of-order chunks Handled; chunks are placed by index into a slot array.
Missing chunks dungeon:room_final rejects the transaction and logs.
Inconsistent chunk totals Chunks claiming a different n than the first are discarded.
Abandoned transactions Removed after 200 ticks without a final.
Concurrent senders Transactions are keyed by originKey::id, so multiple packs never collide.

5. Payload schema

The reassembled JSON must be one of:

// Form A: single batch
{ tier_1: [{ ... }] }

// Form B: multiple batches (the form the example addon uses)
{
  tier_1: [
    { ... },
    { ... },
  ],
  tier_2: [
    { ... }
  ]
}

Each entry in templates must be a valid RoomTemplate:

Field Type Required Notes
id string ✅ Unique within the tier; used for dedup
weight number > 0 ✅ Relative selection weight
size { x, y, z } ✅ Unrotated structure size (all > 0)
offset { x, y, z } ✅ Doorway alignment offset for your .mcstructure
roomType string ✅ features, goals, single_use_goals, hallways, traps, intersections
biome string ✅ default, forest, desert, frozen, swamp
path string ✅ Namespaced structure ID, e.g. mypack:tier_1/goals/hall
integrity number 0–1 ❌ Overrides tier decay profile
exits integer ❌ Doorways besides the entry (used for branching bias)
decayProcessor string ❌ Reserved for future jigsaw processor IDs

Templates missing required fields or containing invalid types are silently skipped and counted in the receiver's result.

Reserved room types

  • staircase_room | reserved; the generator places at most one per tier.
  • deadends, entrance, stairs, base | reserved for the generator.

6. Verifying registration

From the world (operator required):

  • /dungeon:registry

Expected output once the handshake succeeds:

Tier 1: 40 template(s)   ← 39 built-in + your 1
Tier 2: 34 template(s)
Tier 3: 22 template(s)

7. Writing a template

A template is metadata for a .mcstructure file your pack ships in its resource pack. The generator places the structure using world.structureManager.place(path, dimension, origin, { rotation }).

Aspect Guidance
Structure namespace The resource pack must ship the structure at structures/<path>.mcstructure with a matching namespace. For example, path: "mypack:tier_1/hallways/myhall" requires structures/mypack/tier_1/hallways/myhall.mcstructure in the resource pack.
Size Measure the structure's bounding box. size.x, size.y, and size.z must match the .mcstructure dimensions exactly.
Offset The doorway placement anchor. In almost every built-in room, the offset is { x: 0, y: -5, z: 0 }—a 15×15×15 room whose floor is 5 blocks below the placement point. Confirm against your structure by placing it once in build mode and comparing it to a known room.
Connectors Author dungeon:gen_tier_N_room or dungeon:gen_tier_N_stairs blocks inside the structure at every doorway. The generator finds them after placement and expands from each one. Rooms without connectors act as dead ends, even if their roomType is not "deadends".
Room type: hallways, features, traps, intersections Common room types.
Room type: goals Biased deeper; the cap is enforced by maxGoals.
Room type: single_use_goals Used at most once per dungeon per template ID.
Room type: deadends Used only when sealing a doorway.
Exits Leave this unset if unsure; it is inferred from roomType and id.

8. Failure modes and diagnostics

All warnings are prefixed [DungeonRegistry] (core). Check the content log (/reload or a fresh world load) for:

Log message Meaning
Broadcast dungeon:room_chunk returned successCount=0 /scriptevent command was rejected (permission / world state)
Chunk parse failed: … URL decoding or JSON parsing failed on one chunk
Chunk shape invalid A chunk envelope is missing id/i/n/d
Transaction … chunk count mismatch A chunk declared a different n than the first
Incomplete transaction … (m/n) dungeon:room_final arrived before every chunk
Payload JSON invalid for … Reassembled payload is not valid JSON
Cross-pack: N added, M skipped Success: N templates registered, M rejected as invalid or duplicate
Cross-pack rejected: … Every template was rejected; the message lists why

If the core never sees your dungeon:ping:

  1. Confirm the core pack is loaded (its “Plugin Discovered” line appears).
  2. Confirm your addon's script module is "type": "script" in manifest.json and points to an existing entry.
  3. Check that /scriptevent dungeon:ping 1 works manually. If not, cheats or command permissions are blocking /scriptevent.

DungeonExpanse External Addon Team

profile avatar
  • 23
    Followers
  • 10
    Projects
  • 207.5K
    Downloads
Donate

More from SyKoSoFiView all

  • Dungeon Expanse! project image

    Dungeon Expanse!

    This add-on brings an experience like never before to MCBE! Completely randomized NEW dungeons in your world! No dungeon is ever the same! Be prepared for a dangerous, dark, and an intense plundering experience.

    • 174.9K
    • November 16, 2026
  • GraveDesire project image

    GraveDesire

    The Grave Desire addon adds a gravestone that is created when a player dies.

    • 46
    • November 15, 2026
  • Return Anchors (Multiplayer Home Teleport) project image

    Return Anchors (Multiplayer Home Teleport)

    Tired of leaving for an adventure only to have to walk all the way home, the you want Return Anchors! Return Anchors is a survival vanilla style home teleport system! No need for "/home", you make the block yourself!

    • 966
    • November 15, 2026
  • Natural Trees project image

    Natural Trees

    The Natural Trees Addon modifies the vanilla trees to have a more Real World appearance! Give your world a new look with The Natural Trees Addon. This addon does not add new trees!

    • 4.1K
    • November 14, 2026
  • Dungeon Expanse! project image

    Dungeon Expanse!

    This add-on brings an experience like never before to MCBE! Completely randomized NEW dungeons in your world! No dungeon is ever the same! Be prepared for a dangerous, dark, and an intense plundering experience.

    • 174.9K
    • November 16, 2026
  • GraveDesire project image

    GraveDesire

    The Grave Desire addon adds a gravestone that is created when a player dies.

    • 46
    • November 15, 2026
  • Return Anchors (Multiplayer Home Teleport) project image

    Return Anchors (Multiplayer Home Teleport)

    Tired of leaving for an adventure only to have to walk all the way home, the you want Return Anchors! Return Anchors is a survival vanilla style home teleport system! No need for "/home", you make the block yourself!

    • 966
    • November 15, 2026
  • Natural Trees project image

    Natural Trees

    The Natural Trees Addon modifies the vanilla trees to have a more Real World appearance! Give your world a new look with The Natural Trees Addon. This addon does not add new trees!

    • 4.1K
    • November 14, 2026