# Dungeon Builder Execution Plan (Draft) ## Objective Deliver a stable, content-driven dungeon builder pipeline that: 1. Uses VNext generation rules (BSP + Random Walk + bucket constraints). 2. Produces deterministic results for a given seed/content snapshot. 3. Keeps admin tooling (`/admin/dungeonbuilder`) aligned with runtime output. 4. Scales to higher-tier larger dungeons with multi-boss support. 5. Uses palette-scoped tile selection only (no cross-palette wall/floor picks). ## Non-Goals (for this phase) 1. Final art polish for room shapes and micro-layout aesthetics. 2. Replacing every legacy generator immediately. 3. Full client-side editor redesign. ## Guardrails 1. No production cutover without side-by-side validation. 2. Keep V3/V2/V1 fallback available until VNext passes acceptance metrics. 3. Persist and log generator decisions for reproducibility/debugging. ## Workstreams ## 1) Runtime Generator Core (VNext) ### Scope 1. Implement/complete `DungeonGeneratorVNext` stages: - BSP macro partitioning. - Random walk connectivity overlay. - Corridor width enforcement (2-4). - Bucket-constrained floor placement. - Wall placement via ordered two-pass masking: 1) cardinal-first wall bucket fill, 2) diagonal/8-neighbor completion only for unfilled cells. 2. Tier scaling: - Increase map size/room budget for tier 6+. - Allow multi-boss placement tier 6+. 3. Hard constraints: - At least one boss per dungeon. - Dungeon clear requires all bosses defeated. 4. Wall placement rules: - Every wall tile must resolve to exactly one wall bucket. - Cardinal bucket matches are evaluated and applied first. - Remaining unresolved wall slots are resolved from 8-direction buckets. - Tile candidate selection is limited to buckets available in the active palette. ### Deliverables 1. Deterministic VNext map output for fixed seed + snapshot. 2. Generation report object (counts, fallbacks, violations, timings). 3. Validation/repair pass summary included in report. ## 2) Data + Rules Compilation Layer ### Scope 1. Add precompiled runtime snapshot for: - floor buckets, - wall buckets/masks, - adjacency matrix, - template pools, - palette bucket-to-tile indexes (for fast palette-only sampling). 2. Ensure no DB reads in inner generation loops. 3. Add snapshot key/versioning (palette id + updated timestamp). ### Deliverables 1. In-memory immutable generator input model. 2. Cache invalidation hooks on admin content updates. ## 3) Admin Builder Validation ### Scope 1. Add `Validate Palette` flow in admin: - missing refs, - invalid JSON, - out-of-bounds points, - bucket incompatibilities, - empty mask mappings. 2. Add readable validation report in UI. 3. Add `Compile Snapshot` action (or compile-on-save). ### Deliverables 1. Actionable error list (not silent catches). 2. Pass/fail status required before TestGen runtime execution. ## 4) TestGen Parity ### Scope 1. Make `/admin/dungeonbuilder/testgen` execute real runtime generator path. 2. Add options: - seed, - tier, - palette, - generator mode (`VNext`, `V3`, `Auto`). 3. Add side-by-side diff summary: - rooms/corridors/boss count/connectivity. ### Deliverables 1. TestGen output parity with runtime for same inputs. 2. Exportable generation report JSON. ## 5) Runtime Integration + Feature Flag Rollout ### Scope 1. Keep existing fallback chain but add explicit order: - `VNext -> V3 -> V2 -> V1`. 2. Add config controls: - global enable, - per-tier enable, - forced fallback mode. 3. Add operational metrics: - gen time, - failure reason, - fallback frequency. ### Deliverables 1. Safe progressive rollout path. 2. Quick rollback switch without redeploy. ## 6) Persistence + Restore Consistency ### Scope 1. Ensure restored dungeons preserve correct walkability + visual tile fidelity for generator used. 2. Persist generator identity/version and snapshot id. 3. Remove V1-only restore assumptions for VNext-generated dungeons. ### Deliverables 1. Rejoin/reload parity with original generated state. ## 7) Boss + Closure Rules Validation ### Scope 1. Enforce: - minimum 1 boss. - tier 6+ multi-boss possible. - clear only when all bosses defeated. 2. Respect `BossesRespawnOnReload` behavior (default false). ### Deliverables 1. Automated verification in simulation tests. ## Milestones 1. M1: VNext core generation stable behind flag. 2. M2: Validation + snapshot compiler integrated. 3. M3: TestGen parity complete. 4. M4: Persistence/rejoin consistency complete. 5. M5: Production rollout by tier bands. ## Acceptance Criteria 1. Corridor width always 2-4. 2. 0 invalid floor cardinal adjacency violations after repair pass. 3. 100% of placed wall tiles resolve to one wall bucket; unresolved placements are flagged and repaired/fallbacked. 4. Wall placement execution order is cardinal pass then unfilled-cell directional completion pass. 5. Tile picks are always from buckets present in the selected palette. 6. Deterministic outputs for fixed seed + snapshot. 7. Every dungeon has >=1 boss; tier 6+ supports multi-boss. 8. Clear condition strictly `defeatedBosses == totalBosses`. 9. TestGen and runtime produce equivalent structural output for same inputs. 10. Rejoin/reload does not corrupt visual state or AI state. ## Risks 1. Legacy content missing bucket/mask metadata. 2. Silent parser assumptions in old data causing invalid compiled snapshots. 3. Performance regressions from repair passes if not bounded. 4. Missing dedicated art for U-shape wall masks can force visual fallbacks. ## Mitigations 1. Strict validation with migration tooling for legacy content. 2. Bounded repair attempts + fallback tile families. 3. Runtime metrics and per-stage timing logs. 4. Add explicit U-shape directional buckets and tiles when art is ready; keep current fallback behavior until then. ## Proposed Implementation Order 1. Runtime report + instrumentation first. 2. Finish VNext core constraints and validations. 3. Build snapshot compiler/caching. 4. Wire admin Validate/Compile. 5. Switch TestGen to runtime generator path. 6. Roll out feature flag by tiers. 7. Finish persistence/rejoin parity and de-risk fallback reduction. ## Review Questions 1. Should tier 6+ boss count scale linearly by tier or by map area budget? 2. Do you want strict generation failure on unresolved bucket adjacency, or auto-repair then warn? 3. Should TestGen default mode be `VNext` once validation passes, or remain `Auto`? 4. Do we enforce one template use per entire dungeon only, or per room category? 5. Should we expose runtime generator mode/tier gating in Admin System panel for live toggling?