10 KiB
10 KiB
Dungeon Builder VNext (New System Spec)
Core Rules (Authoritative)
- Floor tiles may touch only floor tiles that share at least one floor bucket.
- A floor tile may belong to multiple buckets.
- Floor tiles must not touch floor tiles with no shared bucket on any cardinal side.
- Corridors must be 2-4 tiles wide.
- Wall placement follows the same bucket compatibility principle (shared wall bucket required where applicable).
- Wall tile selection uses neighbor analysis (8 directions) to choose the correct visual tile.
- Wall tile selection must support multiple tilesets while preserving correct topology.
- Room templates are sampled from the selected palette, but each room slot may choose template stamp or procedural fallback.
- The same room template must not be used more than once per dungeon tier run.
- Every dungeon must contain at least one boss.
- Tier 6+ dungeons increase in scale and may contain multiple bosses.
- Dungeon clear/closure requires all bosses to be defeated.
- Add runtime flag
BossesRespawnOnReload(defaultfalsefor now).
High-Level Generation Strategy
Use a hybrid pipeline:
- BSP for macro structure (region partition + room candidate space).
- Random Walk for organic connectivity and variation.
- Corridor carving with width 2-4.
- Floor painting via bucket-constrained compatibility.
- Wall synthesis via 8-neighbor bitmask + bucket-specific lookup tables.
Data Model (VNext)
Floor tile definition
TileIdSheetIdFrameIndexFloorBuckets: HashSet<int>WeightTags
Wall tile definition
TileIdSheetIdFrameIndexWallBuckets: HashSet<int>MaskKey(8-neighbor mask family key)WeightTags
Bucket adjacency policy
BucketIdAllowedTouchBuckets: HashSet<int>- Applies to floor-floor and wall-wall adjacency checks.
Static wall lookup
Dictionary<int bucketId, Dictionary<byte mask, List<WallTileRef>>>- Keyed by:
bucketIdmaskfrom 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
TotalBossCountBossesDefeatedCountBossesRespawnOnReload: bool = falseRequireAllBossesForDungeonClear: bool = true
Topology Encoding for Walls
Neighbor mask convention
- 8 bits in fixed order:
- N
- NE
- E
- SE
- S
- SW
- W
- NW
- Bit value:
1if neighbor cell is floor.0if 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
- Split map recursively into partitions with min/max room constraints.
- Create one room candidate per leaf.
- Select room rectangles with padding constraints.
- 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
- Start from entrance room center.
- Random walk toward unconnected room anchors, biasing to nearest disconnected clusters.
- Carve walk paths with variable width 2-4.
- Merge with BSP corridors for a mixed structured/organic shape.
Stage 3: Floor bucket assignment
- Assign each room/corridor a target floor bucket set (theme + biome + substyle).
- For each floor cell, pick a floor tile whose bucket set intersects:
- region target buckets
- all already-placed cardinal neighbor floor buckets.
- If no candidate exists:
- attempt fallback via bucket adjacency policy,
- else backtrack local neighborhood and retry.
Stage 4: Wall candidate extraction
- Any non-floor cell adjacent to floor (8-neighbor or cardinal, configurable) is a wall candidate.
- Determine candidate wall bucket from nearby floor region/theme metadata.
Stage 5: Wall tile selection
- Compute 8-neighbor floor mask for each wall candidate.
- Query static lookup:
wallSet[bucket][mask]. - Weighted-random choose tile from that set.
- Validate adjacency (optional strict mode): ensure wall-wall bucket compatibility.
- Place tile.
Stage 6: Validation pass
- Floor adjacency audit:
- Every cardinal floor-floor edge must share at least one allowed bucket relation.
- Wall adjacency audit:
- Wall neighbors satisfy wall bucket rules.
- Connectivity audit:
- Entrance can reach boss/exit.
- Repair pass if violations detected.
Stage 7: Boss allocation and clear rules
- Compute boss count by tier:
- Tier 1-5: minimum
1. - Tier 6+:
>=1, with multi-boss allowed by tier scaling config.
- Ensure at least one valid boss room/spawn exists.
- Mark dungeon clear condition as:
BossesDefeatedCount >= TotalBossCount.
- 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
- Bucket editor:
- create floor/wall buckets,
- define allowed-touch matrix.
- Floor tile editor:
- assign tile to one or more floor buckets.
- Wall tile editor:
- assign tile to one or more wall buckets,
- assign supported masks.
- 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
- Build standalone
DungeonGeneratorVNextbehind feature flag. - Add offline test harness:
- run N seeds,
- report invalid adjacency/connectivity cases.
- Integrate admin TestGen to run VNext side-by-side with current generator.
- Switch runtime creation to VNext when validation metrics pass.
- 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(defaultfalse) and wired respawn behavior to preserve defeated bosses whenfalse. - 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
BossesRespawnOnReloadin 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/testgenintegration.
Current VNext Scaffold Notes
DungeonGeneratorVNextscaffold class added and feature-flagged (Dungeon:EnableVNextGeneratoror envDUNGEON_VNEXT_ENABLED).- Runtime generation flow now calls shared helper:
VNext -> V3 -> V2 -> V1fallback. - 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
- No invalid floor-floor bucket adjacency in validation output.
- Corridor width always in
[2,4]. - Wall masks resolve to valid tile in >=99.9% placements (rest repaired/fallbacked).
- Deterministic output for fixed seed/content snapshot.
- Admin can author new tilesets without changing placement logic code.
- No duplicate room template IDs appear in a generated dungeon for the same tier-run.
- Every generated dungeon has at least one boss.
- Tier 6+ can generate multi-boss layouts and dungeon only clears after all are defeated.
- Boss reload behavior is controlled by
BossesRespawnOnReloadand defaults tofalse.