7.2 KiB
7.2 KiB
Dungeon Build System Review (Admin/DungeonBuilder)
Goal
Document the current dungeon build/generation system, explain why it works today, and define a practical plan to make it more reliable and easier to operate from /admin/dungeonbuilder.
Current Architecture
Runtime generation entry points
- Active dungeon creation uses fallback chain:
Game/Dungeon/DungeonHandler.Dungeons.cstriesDungeonGeneratorV3first.- If V3 produces no tiles or throws, it falls back to
DungeonGeneratorV2. - If V2 fails, it falls back to
DungeonGenerator(V1).
DungeonHandlerhas a duplicated create/join flow inGame/Dungeon/DungeonHandler.cswith the same fallback behavior.
Layout models
DungeonLayout(Game/Dungeon/DungeonLayout.cs):- Core grid + walkability + spawn lists.
- Supports RLE serialization for transport.
DungeonLayoutV2(Game/Dungeon/DungeonLayoutV2.cs):- Adds
TileDetails,TileMapSheets, and placed objects for visual rendering. - Keeps compatibility with
DungeonLayout.
- Adds
Generator versions
- V1:
Game/Dungeon/DungeonGenerator.cs- Pure procedural rooms + L-corridors.
- No DungeonBuilder template pipeline.
- V2:
Game/Dungeon/DungeonGeneratorV2.cs- Uses legacy
RoomTemplate+ tile definitions + socket/tag logic. - Includes strict socket support and tag-driven fallback (
Game/Dungeon/TagDrivenTiles.cs).
- Uses legacy
- V3:
Game/Dungeon/DungeonGeneratorV3.cs- Uses DungeonBuilder entities (
BuilderRoomTemplate,TileTemplate,ObjectTemplate,DungeonPalette, buckets/rules). - Pipeline:
- Uses DungeonBuilder entities (
- Load palette and template sets.
- Load tile definitions/sheets and bucket rules.
- Place rooms (template stamp or procedural fallback).
- Connect rooms (MST-like nearest linking + L corridors).
- Fill floor tiles.
- Place wall tiles.
- Place objects.
- Build spawn points.
Admin DungeonBuilder data model
- Main entities are defined in:
Data/entities/DungeonBuilder.csData/entities/TileMap.csData/entities/TileBuckets.cs
- Editing pages:
- Rooms:
Services/Admin/Pages/DungeonBuilder/Rooms.cshtml.cs,RoomEdit.cshtml.cs - Tiles:
Services/Admin/Pages/DungeonBuilder/Tiles.cshtml.cs,TileEdit.cshtml.cs - Palettes:
Services/Admin/Pages/DungeonBuilder/PaletteEdit.cshtml.cs - Buckets:
Services/Admin/Pages/DungeonBuilder/Buckets/Edit.cshtml.cs - Stamps:
Services/Admin/Pages/DungeonBuilder/Stamps/Edit.cshtml.cs
- Rooms:
Why the system works today
1) Defensive fallback chain prevents total outage
- Even if V3 content is misconfigured, dungeon creation still succeeds via V2/V1 fallback.
2) Deterministic seed-based generation
- All generators initialize
Randomwith seed, so reproducing map behavior is possible when using the same pipeline and data.
3) Separation between logic grid and render tiles
Walkable+ tile ids drive simulation;TileDetails+TileMapSheetsdrive rendering.- This supports live gameplay without requiring renderer-specific assumptions in sim code.
4) Content-first generation in V3
- V3 consumes palette and template assets from admin-managed DB content, enabling non-code content iteration.
Main issues (current gaps)
A) Generator fragmentation and duplicate orchestration
- V1/V2/V3 coexist with overlapping responsibilities.
- Dungeon creation logic is duplicated in both
DungeonHandler.Dungeons.csandDungeonHandler.cs. - This increases drift risk and makes fixes easy to miss.
B) Restore path drops V2/V3 visual fidelity
RestoreDungeonFromPersistenceAsyncrebuilds with V1 (DungeonGenerator.Generate(...)) inGame/Dungeon/DungeonHandler.Dungeons.cs.- Result: restored dungeons do not preserve V2/V3 visual layout/object output.
C) Test tool does not test real runtime generator
/admin/dungeonbuilder/testgen(TestGen.cshtml.cs) uses an internal simplified generator, not V3.- This makes admin preview results diverge from real dungeon runtime behavior.
D) Heavy silent-failure behavior in V3 parsing
- Multiple broad
catch { }paths inDungeonGeneratorV3suppress parse/content errors. - Invalid JSON or bad references degrade quality silently instead of failing fast with diagnostics.
E) Runtime DB access inside stamp/object loops
DungeonGeneratorV3calls DB lookups inside generation loops (example: object template lookup during room stamping).- This increases generation latency and variability under load.
F) Live tile edit broadcasting can become expensive
- Tile updates in
DungeonHandlercan fall back to full tile payload broadcast when diff data is missing. HasPendingTileUpdatesand_changedTilescoordination is workable but fragile under concurrent edits.
G) Inconsistent template lineage
- V2 relies on
RoomTemplatewhile V3 usesBuilderRoomTemplate. - Admin UX is centered on Builder entities, but runtime still keeps legacy paths active.
Viable solution to improve system
Direction
Keep V3 as the primary pipeline and make admin tools validate against the same runtime code path. Retain V2/V1 only as controlled feature-flagged emergency fallback, not normal operation.
Phase 1: Stabilize and align tooling
- Make
/admin/dungeonbuilder/testgencallDungeonGeneratorV3.GenerateAsyncdirectly. - Add a structured generation report object (rooms placed, fallbacks used, parse errors, missing refs, timing).
- Surface this report in the TestGen UI and store last N reports for troubleshooting.
Phase 2: Add content validation/compile step
- Add “Validate Palette” action in admin:
- checks JSON parse for room/tile/object blobs,
- verifies referenced IDs exist and are enabled,
- checks connection points and spawn points are in-bounds,
- checks sockets/buckets consistency.
- Add “Compile Palette Snapshot”:
- pre-resolve template references into normalized DTOs,
- cache by palette id + updated timestamp.
- Generator consumes compiled snapshot (single load) instead of many ad-hoc DB lookups.
Phase 3: Runtime consistency and persistence
- Persist enough V2/V3 layout data to restore exact walkability + visual state (or persisted layout seed+palette+version with deterministic replay).
- Remove V1 restore path for dungeons created with V2/V3.
- Keep one generator orchestration path in
DungeonHandler(single method used by both partial files).
Phase 4: Live editing robustness
- Replace boolean
HasPendingTileUpdateswith monotonic change version. - Store tile delta batches (position/layer/op/version) per dungeon for replay-safe client sync.
- Keep “full snapshot” path only for explicit resync, not as implicit fallback.
Concrete acceptance criteria
- TestGen output matches runtime generation for same
seed/tier/palette. - Invalid Builder content produces actionable validation errors before runtime.
- Restored dungeons preserve V3 visual/walkability integrity.
- Generation no longer does N+1 DB fetches in stamp/object loops.
- Tile edit sync remains differential under normal operation.
Recommended immediate next steps
- Implement TestGen -> V3 integration first (highest ROI for admin trust).
- Add validation endpoint + UI report next (prevents silent bad content).
- Refactor dungeon creation into one shared internal method in
DungeonHandler.