- 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
178 lines
6.6 KiB
Markdown
178 lines
6.6 KiB
Markdown
# 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?
|