9.1 KiB
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
DungeonLayoutwith:- 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.