Dungeon & Room Blueprints

Room components AstralDungeons reads

Each entry under components carries a RoomEditor primitive discriminator (component-type: position, typed-position, cuboid, orientation, or oriented-cuboid) plus a semantic type string that AstralDungeons matches on. Only a handful of types are meaningful to AstralDungeons:

Every position-family lookup above only checks instanceof PositionRoomComponent — typed-position (TypedPositionRoomComponent) is a subclass with an extra type-id field that AstralDungeons never reads, so either component-type works for spawn, boss, or mob markers.

generation

rooms

Every id here must resolve against a room's name loaded from rooms/. See Validation for exactly what happens — and what still loads — when one doesn't.

room-mobs

Map of room name → set of AstralMobs blueprint ids eligible to spawn in that room. The map key is a room's name — the same id used in rooms.rooms/rooms.caps — not a per-instance concept, so the same room-mobs entry applies to every occurrence of that room blueprint across a generated layout (a NORMAL room can be placed more than once if the generator reuses it while growing).

Spawn locations come from the room's mob markers, activated as participants move through the instance (mobs.detection-range/mobs.activation-range, see Configuration). For each activated location, MobListener picks one id from that room's room-mobs set uniformly at random (equal weight per id) and spawns it there via MobsAPI. A room with no room-mobs entry (or an empty set) simply never spawns an ambient mob at its markers. See Dungeon Instances: Mob activation.

boss & mob-experiences

boss is a single AstralMobs blueprint id, spawned once via MobsAPI.spawnMob at the end room's boss marker the first time any participant comes within mobs.activation-range blocks of it (MobListener#trySpawnBoss, gated so it fires at most once per instance). If boss is missing or blank, spawning is skipped and a warning is logged — the marker's location was already required at instance-creation time regardless (see Room components), so a blank boss only means nothing ever appears there. See Dungeon Instances: Boss.

mob-experiences maps an AstralMobs blueprint id to a double experience value. It applies to any dungeon mob a participant kills — MobListener#onMobDeath resolves the killed entity's blueprint id and looks it up here regardless of whether the mob was an ambient room-mobs spawn or the boss. A mob with no entry drops no XP (logged as a warning). Experience accumulates on the killer's DungeonPlayerData and is paid out on the lobby once they leave the instance. See Loot & Rewards: Mob loot & experience.

components-loot-tables & mobs-loot-tables

Both are maps of id → DungeonLootTable. mobs-loot-tables is keyed by AstralMobs blueprint id (checked against the same ids as mob-experiences) and rolled on a qualifying kill. components-loot-tables is a general map, but only the pots key is currently consumed, rolled once per click on a DecoratedPot block in a room schematic. The full entry shape (entries/minimum/maximum), roll rules, and reward carry-over to the lobby are covered in Loot & Rewards.

Footprints (computed at load)

When a dungeon blueprint loads, BlueprintService converts every room it references into a DungeonRoomBlueprint — its type (START/END/NORMAL/CAP), its extracted doors, and a footprint quantised to that dungeon's generation.cell-size:

1. The room's bounding box (inclusive block span) is divided by cell-size, rounded up, giving the footprint's width and length in cells (wCells/lCells).

2. Each door's local anchor — the center of its min/max box, in the room's own schematic-relative coordinates — is mapped to the local cell it falls in and kept alongside the wall edge (Cardinal) the door was derived to face.

This footprint — not the raw block geometry — is what the grid generator places and rotates.

A room whose block span isn't an exact multiple of cell-size, whose door anchor falls outside the footprint, or whose door isn't roughly centered on the cell edge it's assigned to, is not grid-conforming. This is logged as a [gen] room '<name>' not grid-conforming: ... warning at load time for every such room — it never blocks loading or changes generator behavior; it's a diagnostic for whoever is authoring rooms against that dungeon's cell size.

Generating a layout (instance creation)

At instance creation, DungeonGenerator retries up to generation.max-attempts times, each attempt using a fresh seed:

1. Topology. A pure, Bukkit-free grid engine (GridLayout) works entirely in integer cells: it seeds the START room's footprint at the origin, grows NORMAL rooms while the random room budget allows, then resolves — the END room claims the deepest still-open doorway it fits, and every remaining open doorway is closed with a CAP room. A placement is only valid under forced exact-edge matching: every footprint cell-edge that abuts a placed room must have a door meeting a door on the neighbour facing back — there are no sealed dead doors.

2. Realization. The accepted topology is converted to world space by chaining door anchors, not grid coordinates: walking the connection tree out from START, each room is positioned so its connector door's world anchor lands exactly on its already-placed parent's door anchor, so any two connected rooms meet flush at the doorway regardless of footprint size.

3. Collision check. Because door-anchored placement can in principle overlap, the realized layout is checked with a real bounding-box test (a 2-block horizontal inset lets a flush shared wall pass) — a colliding layout is discarded and the whole attempt retried with the next seed.

Exhausting max-attempts without a non-overlapping, fully-connected layout throws LayoutInfeasibleException, which fails the creation request (logged, and the requesting server replies success=false). See Dungeon Instances: Cross-server creation handshake.