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.

biomes

The biome is what carries the ambience — fog, sky and water tint, ambient sound and music — so the boss room reads as a different place before its door is opened. Its effect on mob spawn lists is moot here: dungeon worlds run with SPAWN_MOBS off and every mob is placed from a marker.

The boss biome covers the full column over the boss room's X/Z footprint — the whole world height above and below it, not just up to its ceiling. The room it applies to is whichever room carries a boss marker (the same marker the boss spawns from, so the biome cannot land anywhere but the fight); a boss room authored without one falls back to the room named by rooms.end.

Behaviour when a key is absent or wrong:

• Block or key omitted → minecraft:plains, for that key alone. A blueprint may set only one of the two.

• Both keys equal → the world is painted with one biome and the boss room does not stand out.

• Key present but unknown → instance creation fails. This is deliberate: a typo silently painting the wrong ambience is harder to notice than a dungeon that refuses to open.

Because a BiomeProvider is fixed at world creation and needs to know where the boss room landed, the layout is grown before the world is created — see Generating a layout.

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).

Which id is spawned is not random. Each placed room keeps its own set of already-spawned types and the listener takes the first id in the room's room-mobs set that is not in it, so a room cycles through its whole roster before repeating: once every type has been placed the set is cleared and the cycle restarts. Ordering follows the YAML set's iteration order, which is not guaranteed to be the order you wrote.

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).

The experience is credited to every alive participant, not just the killer; only the killer's killedMobs counter is incremented. It accumulates on each player's DungeonPlayerData and is paid out on the lobby once they leave the instance. See Loot & Rewards: Mob loot & experience.

components-loot-tables

A map of id → DungeonLootTable. The map is general, but only the pots key is currently consumed, rolled once per right-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.

Mob drops are not configured here — they come from the AstralMobs blueprint, tagged with the mobs.loot-persistent-data-key payload. See Mob loot.

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 — choosing which open doorway to expand from according to branchiness, and which room to try there according to weights — then resolves: the END room claims the still-open doorway farthest from START by hop distance that 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.

4. Loop-edge check. A layout that survives collision is checked for misaligned loop edges — a cycle-closing connection whose two doors do not actually line up in world space. A clean layout is returned immediately; the first layout whose only flaw is misaligned loops is held as a fallback.

If no seed produces a clean layout but a fallback exists, that fallback is used and a warning naming every dead doorway is logged. Connectivity is unaffected — the spanning tree always stitches, so every room is reachable — but those doors open into a wall. Shipping a dungeon with a dead shortcut beats refusing to open it.

Exhausting max-attempts with no fallback at all throws LayoutInfeasibleException, which fails the creation request (logged with the seed, budget and pool size so the run can be replayed; the requesting server replies success=false). See Dungeon Instances: Cross-server creation handshake.

The layout is grown before the world is created, not after: the world's BiomeProvider needs to know where the boss room landed, and a provider is fixed at world creation. The topology search and the marker precompute are pure CPU with no world access, so they run off the main thread; only world creation itself is scheduled onto it.