Files
systemrevivalserver/TileManagementRevamp.md
2026-01-31 18:51:45 -05:00

8.2 KiB
Raw Permalink Blame History

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.