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