Files
systemrevivalserver/DungeonBuilderVNextPlan.md
T
2026-02-08 22:21:03 -05:00

10 KiB

Dungeon Builder VNext (New System Spec)

Core Rules (Authoritative)

  1. Floor tiles may touch only floor tiles that share at least one floor bucket.
  2. A floor tile may belong to multiple buckets.
  3. Floor tiles must not touch floor tiles with no shared bucket on any cardinal side.
  4. Corridors must be 2-4 tiles wide.
  5. Wall placement follows the same bucket compatibility principle (shared wall bucket required where applicable).
  6. Wall tile selection uses neighbor analysis (8 directions) to choose the correct visual tile.
  7. Wall tile selection must support multiple tilesets while preserving correct topology.
  8. Room templates are sampled from the selected palette, but each room slot may choose template stamp or procedural fallback.
  9. The same room template must not be used more than once per dungeon tier run.
  10. Every dungeon must contain at least one boss.
  11. Tier 6+ dungeons increase in scale and may contain multiple bosses.
  12. Dungeon clear/closure requires all bosses to be defeated.
  13. Add runtime flag BossesRespawnOnReload (default false for now).

High-Level Generation Strategy

Use a hybrid pipeline:

  1. BSP for macro structure (region partition + room candidate space).
  2. Random Walk for organic connectivity and variation.
  3. Corridor carving with width 2-4.
  4. Floor painting via bucket-constrained compatibility.
  5. Wall synthesis via 8-neighbor bitmask + bucket-specific lookup tables.

Data Model (VNext)

Floor tile definition

  • TileId
  • SheetId
  • FrameIndex
  • FloorBuckets: HashSet<int>
  • Weight
  • Tags

Wall tile definition

  • TileId
  • SheetId
  • FrameIndex
  • WallBuckets: HashSet<int>
  • MaskKey (8-neighbor mask family key)
  • Weight
  • Tags

Bucket adjacency policy

  • BucketId
  • AllowedTouchBuckets: HashSet<int>
  • Applies to floor-floor and wall-wall adjacency checks.

Static wall lookup

  • Dictionary<int bucketId, Dictionary<byte mask, List<WallTileRef>>>
  • Keyed by:
    • bucketId
    • mask from 8-neighbor occupancy (0=empty/wall, 1=floor)

Room template sampling state

  • UsedRoomTemplateIds: HashSet<int> per generated dungeon instance (or per tier-run context).
  • RoomTemplateSamplingMode:
    • TemplateOrProcedural (try template first, allow procedural fallback by chance/rules).
  • NoDuplicateRoomTemplatePerTier: bool = true.

Boss runtime state

  • TotalBossCount
  • BossesDefeatedCount
  • BossesRespawnOnReload: bool = false
  • RequireAllBossesForDungeonClear: bool = true

Topology Encoding for Walls

Neighbor mask convention

  • 8 bits in fixed order:
  1. N
  2. NE
  3. E
  4. SE
  5. S
  6. SW
  7. W
  8. NW
  • Bit value:
    • 1 if neighbor cell is floor.
    • 0 if neighbor cell is empty or wall.

Result

  • Every wall candidate cell computes one mask.
  • Mask + bucket selects correct wall tile variant.
  • This decouples wall correctness from art pack and enables multi-tileset support.

Generation Pipeline (Detailed)

Stage 1: BSP partition

  1. Split map recursively into partitions with min/max room constraints.
  2. Create one room candidate per leaf.
  3. Select room rectangles with padding constraints.
  4. For each room slot, sample palette room templates with uniqueness guard:
  • skip templates in UsedRoomTemplateIds,
  • optionally choose procedural room even when template is available.

Stage 2: Random Walk connectivity overlay

  1. Start from entrance room center.
  2. Random walk toward unconnected room anchors, biasing to nearest disconnected clusters.
  3. Carve walk paths with variable width 2-4.
  4. Merge with BSP corridors for a mixed structured/organic shape.

Stage 3: Floor bucket assignment

  1. Assign each room/corridor a target floor bucket set (theme + biome + substyle).
  2. For each floor cell, pick a floor tile whose bucket set intersects:
  • region target buckets
  • all already-placed cardinal neighbor floor buckets.
  1. If no candidate exists:
  • attempt fallback via bucket adjacency policy,
  • else backtrack local neighborhood and retry.

Stage 4: Wall candidate extraction

  1. Any non-floor cell adjacent to floor (8-neighbor or cardinal, configurable) is a wall candidate.
  2. Determine candidate wall bucket from nearby floor region/theme metadata.

Stage 5: Wall tile selection

  1. Compute 8-neighbor floor mask for each wall candidate.
  2. Query static lookup: wallSet[bucket][mask].
  3. Weighted-random choose tile from that set.
  4. Validate adjacency (optional strict mode): ensure wall-wall bucket compatibility.
  5. Place tile.

Stage 6: Validation pass

  1. Floor adjacency audit:
  • Every cardinal floor-floor edge must share at least one allowed bucket relation.
  1. Wall adjacency audit:
  • Wall neighbors satisfy wall bucket rules.
  1. Connectivity audit:
  • Entrance can reach boss/exit.
  1. Repair pass if violations detected.

Stage 7: Boss allocation and clear rules

  1. Compute boss count by tier:
  • Tier 1-5: minimum 1.
  • Tier 6+: >=1, with multi-boss allowed by tier scaling config.
  1. Ensure at least one valid boss room/spawn exists.
  2. Mark dungeon clear condition as:
  • BossesDefeatedCount >= TotalBossCount.
  1. On reload/restore:
  • if BossesRespawnOnReload == false, defeated bosses stay defeated.
  • if true, bosses respawn by configured behavior.

Determinism

  • All random operations must use one seeded RNG stream with sub-streams per stage:
    • rngRooms, rngWalk, rngFloors, rngWalls, rngProps.
  • Same seed + same content snapshot must produce identical layout.
  • Room template uniqueness decisions must also be seed-deterministic.

Performance Targets

  • No DB reads in inner placement loops.
  • Preload content into immutable runtime caches:
    • floor bucket index
    • wall mask lookup
    • bucket adjacency map
  • Target: <=100ms generation for standard dungeon sizes on warm cache.

Admin Authoring Requirements

New builder UX primitives

  1. Bucket editor:
  • create floor/wall buckets,
  • define allowed-touch matrix.
  1. Floor tile editor:
  • assign tile to one or more floor buckets.
  1. Wall tile editor:
  • assign tile to one or more wall buckets,
  • assign supported masks.
  1. Mask visualizer:
  • click neighbors to toggle bits and preview selected wall tiles.

Validation in UI

  • Real-time warnings:
    • floor tile with no buckets,
    • wall tile with no masks,
    • bucket with empty compatibility map.

Suggested C# Runtime Shapes

public readonly record struct BucketId(int Value);

public sealed class FloorTileDef {
    public int TileId { get; init; }
    public int SheetId { get; init; }
    public int FrameIndex { get; init; }
    public HashSet<BucketId> Buckets { get; init; } = new();
    public int Weight { get; init; } = 100;
}

public sealed class WallTileDef {
    public int TileId { get; init; }
    public int SheetId { get; init; }
    public int FrameIndex { get; init; }
    public HashSet<BucketId> Buckets { get; init; } = new();
    public byte Mask { get; init; }
    public int Weight { get; init; } = 100;
}

public sealed class BucketAdjacency {
    public Dictionary<BucketId, HashSet<BucketId>> AllowedTouches { get; init; } = new();
}

public sealed class WallMaskLibrary {
    public Dictionary<BucketId, Dictionary<byte, List<WallTileDef>>> ByBucketMask { get; init; } = new();
}

public sealed class DungeonRunRules {
    public bool NoDuplicateRoomTemplatePerTier { get; init; } = true;
    public bool RequireAllBossesForDungeonClear { get; init; } = true;
    public bool BossesRespawnOnReload { get; init; } = false;
}

public sealed class DungeonBossState {
    public int TotalBossCount { get; set; }
    public int BossesDefeatedCount { get; set; }
    public bool IsClearConditionMet => BossesDefeatedCount >= TotalBossCount;
}

Rollout Plan

  1. Build standalone DungeonGeneratorVNext behind feature flag.
  2. Add offline test harness:
    • run N seeds,
    • report invalid adjacency/connectivity cases.
  3. Integrate admin TestGen to run VNext side-by-side with current generator.
  4. Switch runtime creation to VNext when validation metrics pass.
  5. Keep old generators as emergency fallback for one release window.

Implementation Status

  • Runtime boss clear state now supports multi-boss semantics (TotalBossCount, BossesDefeatedCount, clear when all defeated).
  • Runtime empty-dungeon cleanup/persistence now uses all-bosses-defeated condition instead of first-boss-killed condition.
  • Added runtime flag BossesRespawnOnReload (default false) and wired respawn behavior to preserve defeated bosses when false.
  • Admin-spawned bosses now increment runtime boss target count.
  • Restore path now reapplies defeated-boss progress from persisted mob state (including runtime/admin-spawned boss IDs).
  • Persist BossesRespawnOnReload in persisted dungeon runtime metadata (JSON payload, backward-compatible with legacy list format).
  • Replace current generators with full DungeonGeneratorVNext (BSP + Random Walk + bucket-constrained floors/walls).
  • Add VNext offline validation harness and side-by-side /admin/dungeonbuilder/testgen integration.

Current VNext Scaffold Notes

  • DungeonGeneratorVNext scaffold class added and feature-flagged (Dungeon:EnableVNextGenerator or env DUNGEON_VNEXT_ENABLED).
  • Runtime generation flow now calls shared helper: VNext -> V3 -> V2 -> V1 fallback.
  • VNext now has a first-pass native layout pipeline:
    • BSP-style partition + room carving
    • Random-walk corridor carving with 2-4 tile width
    • Tier-scaled dungeon size and room count
    • Multi-boss room allocation for tier 6+
    • Deterministic spawn/chest placement with at least one boss spawn
  • Remaining VNext work: bucket-constrained floor/wall authoring rules, wall 8-neighbor mask resolution, validation/repair passes, and admin test harness parity.

Acceptance Criteria

  1. No invalid floor-floor bucket adjacency in validation output.
  2. Corridor width always in [2,4].
  3. Wall masks resolve to valid tile in >=99.9% placements (rest repaired/fallbacked).
  4. Deterministic output for fixed seed/content snapshot.
  5. Admin can author new tilesets without changing placement logic code.
  6. No duplicate room template IDs appear in a generated dungeon for the same tier-run.
  7. Every generated dungeon has at least one boss.
  8. Tier 6+ can generate multi-boss layouts and dungeon only clears after all are defeated.
  9. Boss reload behavior is controlled by BossesRespawnOnReload and defaults to false.