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 frommain.ts, so the listener is attached as soon as the core's script starts.- The core broadcasts
dungeon:readyonce immediately, then every 20 ticks for 30 seconds, so a late-starting external pack never misses it. - Every
dungeon:pingthe core receives triggers an additionaldungeon:readyresponse.
External-side behaviour
- Subscribe to
dungeon:readyat module load (before any world data loads). - On
worldLoad, begin sendingdungeon:pingevery 20 ticks. - On the first
dungeon:ready, stop pinging and send the payload after a 1-tick grace period. - If no
dungeon:readyarrives 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:
- Confirm the core pack is loaded (its “Plugin Discovered” line appears).
- Confirm your addon's script module is
"type": "script"inmanifest.jsonand points to an existing entry. - Check that
/scriptevent dungeon:ping 1works manually. If not, cheats or command permissions are blocking/scriptevent.