# 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.