197 lines
9.1 KiB
Markdown
197 lines
9.1 KiB
Markdown
# 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.
|