293 lines
8.2 KiB
Markdown
293 lines
8.2 KiB
Markdown
# Tile Management Revamp — Verbose Plan (with examples)
|
||
|
||
This is a draft plan for replacing socket-based connections with a bucket/graph system and consolidating tile management across TileMaps, Builder, and runtime generation. It is intentionally verbose and example-driven so we can refine the model before coding.
|
||
|
||
---
|
||
|
||
## 0) Goals (What We Want)
|
||
|
||
- Remove socket matching; replace with bucket-based connectivity rules.
|
||
- Make tile metadata consistent across:
|
||
- TileMaps (sheet registration only)
|
||
- Builder (tile definitions, room templates, object templates)
|
||
- Live editor (overrides)
|
||
- Scale the same model to:
|
||
- Dungeons (procedural rooms + corridors)
|
||
- Overworld (large persistent world)
|
||
- Support connectivity cardinality:
|
||
- 1 → 1 (strict)
|
||
- 1 → many
|
||
- many ↔ many
|
||
- Biomes are buckets.
|
||
|
||
---
|
||
|
||
## 1) Big Picture Architecture
|
||
|
||
### 1.1 TileMaps (Sheet Registry Only)
|
||
- TileMaps only store:
|
||
- CDN path
|
||
- image dimensions
|
||
- tile size
|
||
- enabled flag
|
||
- No gameplay properties live here.
|
||
|
||
### 1.2 Builder (Where Everything Is Defined)
|
||
- Builder owns:
|
||
- Tile Definitions (properties + buckets)
|
||
- Room Templates
|
||
- Object Templates
|
||
- Tile “stamps” (optional multi-tile patterns)
|
||
- Builder becomes the single source of gameplay tile metadata.
|
||
|
||
### 1.3 Generation & Runtime
|
||
- Generator uses buckets + rules to place tiles.
|
||
- Room templates can ignore bucket constraints (painted layouts are authoritative).
|
||
- DungeonSimulation consumes resolved layout (walkability, LOS, projectile blocking, interactions), not editor concepts.
|
||
|
||
---
|
||
|
||
## 2) Data Model (Draft)
|
||
|
||
### 2.1 TileDefinition
|
||
Represents one tile frame and its gameplay meaning.
|
||
|
||
**Fields (proposed):**
|
||
- `id`
|
||
- `sheetId`
|
||
- `frameIndex`
|
||
- `name`
|
||
- `tags` (optional)
|
||
- `buckets: string[]` (one tile can be in many buckets)
|
||
- `properties`
|
||
- `walkable: bool`
|
||
- `blocksLos: bool`
|
||
- `blocksProjectiles: bool`
|
||
- `interactable: bool`
|
||
- `type: floor | wall | decoration | water | etc` (optional — could be a bucket instead)
|
||
- `renderLayer` (visual)
|
||
- `isEnabled`
|
||
|
||
### 2.2 BucketRule (Global)
|
||
Controls which buckets can connect.
|
||
|
||
**Fields (proposed):**
|
||
- `bucket: string`
|
||
- `allows: string[]` (explicit allow-list)
|
||
- `weights?: { bucket: string, weight: float }[]` (optional)
|
||
- `directional?: bool` (optional, default false)
|
||
|
||
**Cardinality support**
|
||
- 1→1: bucket allows exactly one target.
|
||
- 1→many: bucket allows multiple targets.
|
||
- many↔many: multiple buckets allow each other.
|
||
|
||
### 2.3 Palette (Theme Filter + Generation Rules)
|
||
|
||
**Fields (proposed):**
|
||
- `allowedBuckets: string[]`
|
||
- `allowedTileIds: int[]` (optional explicit list)
|
||
- `roomRules: { minRooms, maxRooms, sizes, corridorWidth }`
|
||
- `densityRules: { decorations, containers, traps }`
|
||
|
||
### 2.4 TileInstanceOverride (optional)
|
||
- Used for live editor or per-instance overrides.
|
||
- Applies on top of a TileDefinition.
|
||
|
||
---
|
||
|
||
## 3) Buckets: Examples
|
||
|
||
### 3.1 Basic Dungeon Buckets
|
||
```
|
||
Buckets:
|
||
floor_basic
|
||
wall_outer
|
||
wall_inner
|
||
doorway
|
||
corridor
|
||
deco_wall
|
||
deco_floor
|
||
biome_dungeon
|
||
```
|
||
|
||
### 3.2 Basic Overworld Buckets
|
||
```
|
||
Buckets:
|
||
biome_forest
|
||
biome_plains
|
||
biome_tundra
|
||
ground_grass
|
||
ground_dirt
|
||
water_shallow
|
||
water_deep
|
||
coast
|
||
path
|
||
```
|
||
|
||
### 3.3 Example: Tile Definitions
|
||
**Stone Floor (Dungeon)**
|
||
- buckets: `floor_basic`, `corridor`, `biome_dungeon`
|
||
- walkable: true
|
||
- blocksLos: false
|
||
- blocksProjectiles: false
|
||
|
||
**Dungeon Wall**
|
||
- buckets: `wall_outer`, `biome_dungeon`
|
||
- walkable: false
|
||
- blocksLos: true
|
||
- blocksProjectiles: true
|
||
|
||
**Forest Grass**
|
||
- buckets: `ground_grass`, `biome_forest`
|
||
- walkable: true
|
||
|
||
**Forest Water Edge (Coast)**
|
||
- buckets: `coast`, `biome_forest`, `water_shallow`
|
||
- walkable: false (or true if shallow is walkable)
|
||
|
||
---
|
||
|
||
## 4) BucketRule Examples
|
||
|
||
### 4.1 Dungeon (Global Rules)
|
||
```
|
||
Rule: floor_basic allows [floor_basic, corridor, doorway]
|
||
Rule: corridor allows [corridor, floor_basic, doorway]
|
||
Rule: doorway allows [floor_basic, corridor]
|
||
Rule: wall_outer allows [wall_outer]
|
||
Rule: wall_inner allows [wall_inner]
|
||
Rule: deco_floor allows [floor_basic, corridor]
|
||
```
|
||
|
||
### 4.2 Overworld (Global Rules)
|
||
```
|
||
Rule: ground_grass allows [ground_grass, ground_dirt, path, coast]
|
||
Rule: ground_dirt allows [ground_dirt, ground_grass, path, coast]
|
||
Rule: coast allows [ground_grass, ground_dirt, water_shallow]
|
||
Rule: water_shallow allows [coast, water_shallow, water_deep]
|
||
Rule: water_deep allows [water_shallow, water_deep]
|
||
```
|
||
|
||
### 4.3 1→1 Example
|
||
```
|
||
Rule: doorway_strict allows [corridor_strict]
|
||
Rule: corridor_strict allows [doorway_strict]
|
||
```
|
||
|
||
### 4.4 Weighted Example
|
||
```
|
||
Rule: ground_grass allows [ground_grass (weight 0.7), ground_dirt (weight 0.2), path (weight 0.1)]
|
||
```
|
||
|
||
---
|
||
|
||
## 5) Procedural Generation Strategy (Bucket-Based)
|
||
|
||
### 5.1 Flow (Dungeon)
|
||
1) Choose palette (filters allowed buckets/tiles).
|
||
2) Create room graph (rooms + corridors) ignoring bucket constraints.
|
||
3) Fill room interiors with `floor_basic` bucket.
|
||
4) Build walls from `wall_outer` bucket around floors.
|
||
5) Place doorways where corridors connect to rooms.
|
||
6) Place decorations by choosing tiles from `deco_floor` and `deco_wall` buckets.
|
||
|
||
### 5.2 Flow (Overworld)
|
||
1) Choose biome region per chunk (biome bucket).
|
||
2) Seed ground layer using biome ground buckets.
|
||
3) Apply adjacency rules for transitions (coast, rivers, paths).
|
||
4) Add decorations/objects by bucket + density rules.
|
||
|
||
---
|
||
|
||
## 6) Builder UX Changes (Proposed)
|
||
|
||
### 6.1 Tile Definition Editor
|
||
- Select TileMap sheet
|
||
- Click frame
|
||
- Set properties (walkable, LOS, projectiles, interactable)
|
||
- Assign buckets (multi-select)
|
||
- Optional tags
|
||
|
||
### 6.2 Bucket Manager
|
||
- Define bucket names
|
||
- Define allowed connections (matrix or allow-list)
|
||
- Optional weights
|
||
- Global scope (shared across palettes)
|
||
|
||
### 6.3 Room Template Editor
|
||
- Paint tiles based on Tile Definitions
|
||
- Ignore connectivity/bucket constraints
|
||
- Save grid and spawns as-is
|
||
|
||
### 6.4 Palette Editor
|
||
- Choose bucket sets to enable for generation
|
||
- Choose tile definitions explicitly (optional)
|
||
- Set density rules and room/corridor ranges
|
||
|
||
---
|
||
|
||
## 7) Runtime (DungeonSimulation) Alignment
|
||
|
||
- Simulation does not need to know about buckets.
|
||
- It only needs resolved tile properties:
|
||
- walkable
|
||
- blocks LOS
|
||
- blocks projectiles
|
||
- interactable
|
||
- Generator should output a resolved layout (tile properties per cell).
|
||
|
||
---
|
||
|
||
## 8) Migration Strategy (Phased)
|
||
|
||
### Phase 1: Data Model
|
||
- Add buckets to TileDefinitions in Builder.
|
||
- Add BucketRules as global config.
|
||
- Keep sockets temporarily for compatibility.
|
||
|
||
### Phase 2: Builder UI
|
||
- Tile Definition editor gains bucket assignment.
|
||
- New Bucket Manager UI.
|
||
- Room editor uses TileDefinitions (not socketed TileTemplates).
|
||
|
||
### Phase 3: Generator
|
||
- Remove socket matching.
|
||
- Generate from bucket adjacency rules.
|
||
|
||
### Phase 4: Cleanup
|
||
- Retire socket fields from TileTemplates/TileDefinitions.
|
||
- Remove socket UI.
|
||
|
||
---
|
||
|
||
## 9) Open Decisions
|
||
|
||
- Should TileTemplates remain for multi-tile stamps, or be replaced by “paint + stamps” in Builder?
|
||
- How many decoration layers do we want per tile?
|
||
- Should biome membership be required for all tiles, or optional?
|
||
- Should bucket adjacency allow directional rules (north/south) or always symmetric?
|
||
|
||
---
|
||
|
||
## 10) Next Steps (If This Plan Looks Right)
|
||
|
||
1) Confirm multi-tile pattern approach (keep vs remove).
|
||
2) Decide how BucketRules are stored (DB table vs JSON config).
|
||
3) Draft the minimal schema changes.
|
||
4) Update Builder UX to handle bucket assignments.
|
||
5) Implement generator using bucket adjacency.
|
||
|
||
---
|
||
|
||
End of plan.
|
||
|
||
## Decisions Locked In (from latest notes)
|
||
- Buckets must be add/remove‑able from tiles, with a searchable dropdown (type to filter, then select). Provide multi‑select chips with remove.
|
||
- Bucket rules must allow explicit allow‑lists so a tile/bucket can connect only to specific buckets (e.g., X connects only to Y and Z).
|
||
- Tile type should be editable (e.g., Floor/Wall/Decoration), and membership in that type can be managed (add/remove).
|
||
- TileTemplates decision: **replace with paint + stamps in Builder** (stamps are just saved selections of tiles for fast painting).
|
||
- Decoration layers per tile: **4 layers**.
|
||
- Biome membership: **optional**, with a global checkbox to enforce or not.
|
||
- Bucket adjacency: **non‑directional/symmetric**. Specificity is handled by bucket assignment and allow‑lists.
|