Files
systemrevivalserver/BuilderExecutionPlan_Draft.md
dingo 1f68928c83 Document pending U-shape wall tile gap and add temp ability test seed script
- 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
2026-02-10 14:03:27 -05:00

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?