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

6.6 KiB

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?