262 lines
10 KiB
Markdown
262 lines
10 KiB
Markdown
# 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.
|
|
3. 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.
|
|
2. Wall adjacency audit:
|
|
- Wall neighbors satisfy wall bucket rules.
|
|
3. Connectivity audit:
|
|
- Entrance can reach boss/exit.
|
|
4. 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.
|
|
2. Ensure at least one valid boss room/spawn exists.
|
|
3. Mark dungeon clear condition as:
|
|
- `BossesDefeatedCount >= TotalBossCount`.
|
|
4. 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.
|
|
2. Floor tile editor:
|
|
- assign tile to one or more floor buckets.
|
|
3. Wall tile editor:
|
|
- assign tile to one or more wall buckets,
|
|
- assign supported masks.
|
|
4. 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
|
|
|
|
```csharp
|
|
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
|
|
- [x] Runtime boss clear state now supports multi-boss semantics (`TotalBossCount`, `BossesDefeatedCount`, clear when all defeated).
|
|
- [x] Runtime empty-dungeon cleanup/persistence now uses all-bosses-defeated condition instead of first-boss-killed condition.
|
|
- [x] Added runtime flag `BossesRespawnOnReload` (default `false`) and wired respawn behavior to preserve defeated bosses when `false`.
|
|
- [x] Admin-spawned bosses now increment runtime boss target count.
|
|
- [x] Restore path now reapplies defeated-boss progress from persisted mob state (including runtime/admin-spawned boss IDs).
|
|
- [x] 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`.
|