# REVAMP Notes: Current Dungeon Builder, TileMaps, and DungeonSimulation This document describes how the current systems work (no code), based on the admin pages and the runtime simulation. ## 1) Dungeon Builder (Admin UI) ### 1.1 Overview Page - The Dungeon Builder landing page shows counts of Tile Templates, Object Templates, Room Templates, and Palettes. - It provides navigation to each editor and a “Test Generator” preview tool. - Recent items are pulled from each template type and displayed with edit links. ### 1.2 Tile Templates **Where:** `/admin/dungeonbuilder/tiles` and `/admin/dungeonbuilder/tiles/edit` **What a Tile Template is:** - A reusable multi-tile pattern (size width/height) composed of tilemap frames. - It has metadata (name, category, biome, tags, weight, tier gating) and tile properties (walkable/blocking flags). - It stores a JSON array of placed cells (`TilesJson`) which maps template grid cells to a sprite sheet frame. **Category and properties:** - Categories include floor/wall/door/etc. (used for filtering and palette grouping). - Properties include: walkable, blocks movement, blocks projectiles, blocks line of sight. **Sockets:** - Each template has edge sockets used for matching/connection during procedural placement. - The editor exposes a socket grid with per-edge cells and three socket types: Open / Closed / Custom. - Socket configuration is stored in JSON (new format) with legacy fields also maintained for backward compatibility. - There is autocomplete for custom socket names, with storage in a dedicated socket names table. **Editor workflow:** - Select a tile sheet, pick a frame, then paint cells in the template grid. - The first tile placed becomes the primary tile definition. - You can resize the template (1x1 up to 10x10), fill all, fill border, or clear. - Tile placements are serialized back to JSON on save. ### 1.3 Room Templates **Where:** `/admin/dungeonbuilder/rooms` and `/admin/dungeonbuilder/rooms/edit` **What a Room Template is:** - A fixed room layout (width/height) containing floor/wall tiles, spawns, and connection points. - Stored as JSON arrays for tile placements, spawns, and connection points. **Editor workflow:** - Grid editor with tools: paint, erase, fill. - Layers: floor, wall, spawn. - Tile palette is built from Tile Templates filtered by selected tilemap sheet and tags. - Floor/wall choice is driven by the selected template’s walkable flag. - Spawn layer supports: player spawn, exit portal, door connection points, chests, and mob spawns. **Data stored:** - TileGridJson: combined floor+wall placements with isWalkable flag. - ConnectionPointsJson: doorways on grid edges with a direction. - MobSpawnsJson: per-cell mob spawns with mob definition id and count. - Player/exit spawn coordinates stored separately. - Object placements exist but are currently stored as empty JSON (not placed in UI). ### 1.4 Object Templates **Where:** `/admin/dungeonbuilder/objects` and `/admin/dungeonbuilder/objects/edit` **What an Object Template is:** - A placeable object (decoration, container, trap, door, vendor, etc.) with sprite, size, interaction, and loot settings. **Key properties:** - Sprite sheet + frame index or a direct CDN image path. - Blocking: movement, projectiles, line of sight. - Animation: isAnimated, frame count, fps, loops, states JSON. - Interaction: interactable, triggered by walk, interaction type/state/cooldown. - Rewards: loot table, gold, XP; trap/hazard damage with damage type. - Generation: weight, tier limits, max per room, placement type. **Editor workflow:** - Pick a sprite sheet and frame; live preview shows selected frame. - Configure animation and interaction settings. - Set generation constraints. ### 1.5 Palettes **Where:** `/admin/dungeonbuilder/palettes` and `/admin/dungeonbuilder/palettes/edit` **What a Palette is:** - A themed collection of templates and rules used by the dungeon generator. **Palette contents:** - Lists of Tile Templates: floors, walls, doors. - Lists of Object Templates: decorations, containers, traps. - List of Room Templates. **Palette settings:** - Room count min/max and room size ranges. - Corridor width ranges. - Density sliders for decorations/containers/traps. - Biome/tags and enabled flag. ### 1.6 Test Generator **Where:** `/admin/dungeonbuilder/testgen` **What it does:** - Generates a simple dungeon preview with rooms and corridors. - Uses palette settings if selected, otherwise uses override values. - Produces a grid visualization with cell types (floor, wall, door, spawns, mobs, etc.). - Tracks and displays generation stats but does not fully integrate tile templates or sockets. **Generation style:** - Randomly places rectangular rooms with padding. - Connects rooms using L-shaped corridors. - Assigns entrance/exit, places mobs, chests, and decoration cells. ## 2) TileMaps (Admin UI) ### 2.1 TileMap Sheets **Where:** `/admin/tilemaps` **What a TileMap Sheet is:** - A sprite sheet definition with size, tile size, and CDN path. - Includes metadata (name, tags, enabled). - Shows preview image and counts of defined tiles. ### 2.2 TileMap Editor **Where:** `/admin/tilemaps/edit` **What it does:** - Defines a sheet (dimensions, tile size, CDN path) and renders a grid overlay preview. - Allows per-frame tile definitions (TileDefinition) to be created/edited. **TileDefinition fields:** - Name, type, tags, walkable, blocks projectiles, blocks LOS, render layer. - Socket fields: N/E/S/W with optional custom names. **Bulk tools:** - Auto-generate definitions for all frames. - Auto-configure sockets based on type. - Bulk set sockets to a specific type. **CDN integration:** - A CDN browser lists textures and can auto-fill the sheet path. ## 3) DungeonSimulation (Runtime) ### 3.1 Inputs - Accepts a `DungeonLayout` with: - Rooms (with type and positions) - Walkability grid - Mob spawns, chest spawns - Tile details for visuals (handled elsewhere for rendering) ### 3.2 Initialization - Spawns mobs at layout mob spawn points. - If a specific MobDefinition is set, uses it; otherwise selects by spawn type (normal/elite/boss). - Uses bracket-aware stat scaling from MobDefinition. - Loads abilities from MobDefinition assignments if available, otherwise creates a basic attack. - Spawns chests at layout chest spawns. - Spawns an exit portal in the entrance room (prefers corners away from hallways). ### 3.3 Tick Loop - Runs at 20 ticks/sec. - If dungeon phase is Active: - Updates mobs (AI), processes abilities/attacks. - Updates projectiles and hazard zones. - Always updates players (movement, status effects, regeneration). - Handles corpse cleanup after loot is emptied (when cleared). - Marks dungeon cleared when all mobs are dead and spawns an exit. ### 3.4 Combat and Movement - Movement uses the layout walkability grid (`Layout.IsWalkable`). - Mob AI uses abilities with range checks and cooldowns. - Damage is calculated using CombatCalculator (armor, resistances, etc.). - Status effects and DOT damage are processed each tick. ### 3.5 Events - Generates lists of damage, death, ability, projectile events during tick. - These are returned via TickResult for networking/client updates. ### 3.6 Summoning - Supports runtime mob summoning (queued then spawned at end of tick). ## Observations (Current Couplings) - Tile Templates and TileMap TileDefinitions overlap in “tile properties” but are separate systems. - Room Editor uses Tile Templates, not TileDefinitions, for floor/wall selection. - Tile sockets exist both in TileDefinitions (TileMaps) and TileTemplates (Builder), but with different data shapes. - Test generator uses palette rules but does not apply template sockets or per-tile metadata. - DungeonSimulation only reads the final layout walkability grid and spawn lists; it does not interpret template or tile metadata at runtime. ## Likely Revamp Touchpoints (Non-Prescriptive) - Consolidate tile metadata into a single definition model used by: - TileMaps (definition), - Builder (authoring), - Live editor (runtime overrides). - Replace/retire template socket logic or re-platform it to the unified tile model. - Update Room editor to use unified tile definitions and decoration overlays. - Update generation pipeline to interpret the new tile metadata (walkability, LOS, projectile blocking, interactables). - Keep DungeonSimulation driven by resolved layout (walkability + overlays) rather than editor-specific concepts. ## Decisions / Direction (from discussion) - **Connection rules must support 1->many, many<->many, and 1->1**. The bucket model should allow explicit allow-lists (and optional weights) so a single bucket can target many, many buckets can target many, or exact 1-1 can be enforced. - **Rules are global** (not per-palette), so one consistent connectivity grammar applies across dungeon + overworld. Palettes should filter which buckets/tiles are allowed in a given theme. - **Biome is a bucket**. Biome membership should be expressible as bucket assignment (e.g., `biome_forest`, `biome_tundra`) and used in the same connectivity system. - **Multi-tile patterns are undecided**. Keep open whether to retain “stamps” / patterns in Builder or simplify to single-tile defs + paint tools.