backend-infra-engineer: Release v0.3.2 snapshot
This commit is contained in:
scawful
263
docs/F1-dungeon-editor-guide.md
Normal file
263
docs/F1-dungeon-editor-guide.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# F2: Dungeon Editor v2 - Complete Guide
|
||||
|
||||
**Last Updated**: October 10, 2025
|
||||
**Related**: [E2-development-guide.md](E2-development-guide.md), [E5-debugging-guide.md](E5-debugging-guide.md)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The Dungeon Editor uses a modern card-based architecture (DungeonEditorV2) with self-contained room rendering. This guide covers the architecture, recent refactoring work, and next development steps.
|
||||
|
||||
### Key Features
|
||||
- **Visual room editing** with 512x512 canvas per room
|
||||
- **Object position visualization** - Colored outlines by layer (Red/Green/Blue)
|
||||
- **Per-room settings** - Independent BG1/BG2 visibility and layer types
|
||||
- **Flexible docking** - EditorCard system for custom workspace layouts
|
||||
- **Self-contained rooms** - Each room owns its bitmaps and palettes
|
||||
- **Overworld integration** - Double-click entrances to open dungeon rooms
|
||||
|
||||
---
|
||||
|
||||
### Architecture Improvements
|
||||
1. **Room Buffers Decoupled** - No dependency on Arena graphics sheets
|
||||
2. **ObjectRenderer Removed** - Standardized on ObjectDrawer (~1000 lines deleted)
|
||||
3. **LoadGraphicsSheetsIntoArena Removed** - Using per-room graphics (~66 lines)
|
||||
4. **Old Tab System Removed** - EditorCard is the standard
|
||||
5. **Texture Atlas Infrastructure** - Future-proof stub created
|
||||
6. **Test Suite Cleaned** - Deleted 1270 lines of redundant tests
|
||||
|
||||
### UI Improvements
|
||||
- Room ID in card title: `[003] Room Name`
|
||||
- Properties reorganized into clean 4-column table
|
||||
- Compact layer controls (1 row instead of 3)
|
||||
- Room graphics canvas height fixed (1025px → 257px)
|
||||
- Object count in status bar
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Component Overview
|
||||
|
||||
```
|
||||
DungeonEditorV2 (UI Layer)
|
||||
├─ Card-based UI system
|
||||
├─ Room window management
|
||||
├─ Component coordination
|
||||
└─ Lazy loading
|
||||
|
||||
DungeonEditorSystem (Backend Layer)
|
||||
├─ Sprite/Item/Entrance/Door/Chest management
|
||||
├─ Undo/Redo functionality
|
||||
├─ Room properties management
|
||||
└─ Dungeon-wide operations
|
||||
|
||||
Room (Data Layer)
|
||||
├─ Self-contained buffers (bg1_buffer_, bg2_buffer_)
|
||||
├─ Object storage (tile_objects_)
|
||||
├─ Graphics loading
|
||||
└─ Rendering pipeline
|
||||
```
|
||||
|
||||
### Room Rendering Pipeline
|
||||
|
||||
TODO: Update this to latest code.
|
||||
|
||||
```
|
||||
1. LoadRoomGraphics(blockset)
|
||||
└─> Reads blocks[] from ROM
|
||||
└─> Loads blockset data → current_gfx16_
|
||||
|
||||
2. LoadObjects()
|
||||
└─> Parses object data from ROM
|
||||
└─> Creates tile_objects_[]
|
||||
└─> SETS floor1_graphics_, floor2_graphics_ ← CRITICAL!
|
||||
|
||||
3. RenderRoomGraphics() [SELF-CONTAINED]
|
||||
├─> DrawFloor(floor1_graphics_, floor2_graphics_)
|
||||
├─> DrawBackground(current_gfx16_)
|
||||
├─> SetPalette(full_90_color_dungeon_palette)
|
||||
├─> RenderObjectsToBackground()
|
||||
│ └─> ObjectDrawer::DrawObjectList()
|
||||
└─> QueueTextureCommand(UPDATE/CREATE)
|
||||
|
||||
4. DrawRoomBackgroundLayers(room_id)
|
||||
└─> ProcessTextureQueue() → GPU textures
|
||||
└─> canvas_.DrawBitmap(bg1, bg2)
|
||||
|
||||
5. DrawObjectPositionOutlines(room)
|
||||
└─> Colored rectangles by layer
|
||||
└─> Object ID labels
|
||||
```
|
||||
|
||||
### Room Structure (Bottom to Top)
|
||||
|
||||
Understanding ALTTP dungeon composition is critical:
|
||||
|
||||
```
|
||||
Room Composition:
|
||||
├─ Room Layout (BASE LAYER - immovable)
|
||||
│ ├─ Walls (structural boundaries, 7 configurations of squares in 2x2 grid)
|
||||
│ ├─ Floors (walkable areas, repeated tile pattern set to BG1/BG2)
|
||||
├─ Layer 0 Objects (floor decorations, some walls)
|
||||
├─ Layer 1 Objects (chests, decorations)
|
||||
└─ Layer 2 Objects (stairs, transitions)
|
||||
|
||||
Doors: Positioned at room edges to connect rooms
|
||||
```
|
||||
|
||||
**Key Insight**: Layouts are immovable base structure. Objects are placed ON TOP and can be moved/edited. This allows for large rooms, 4-quadrant rooms, tall/wide rooms, etc.
|
||||
|
||||
---
|
||||
|
||||
## Next Development Steps
|
||||
|
||||
### High Priority (Must Do)
|
||||
|
||||
#### 1. Door Rendering at Room Edges
|
||||
**What**: Render doors with proper patterns at room connections
|
||||
|
||||
**Pattern Reference**: ZScream's door drawing patterns
|
||||
|
||||
**Implementation**:
|
||||
```cpp
|
||||
void DungeonCanvasViewer::DrawDoors(const zelda3::Room& room) {
|
||||
// Doors stored in room data
|
||||
// Position at room edges (North/South/East/West)
|
||||
// Use current_gfx16_ graphics data
|
||||
|
||||
// TODO: Get door data from room.GetDoors() or similar
|
||||
// TODO: Use ObjectDrawer patterns for door graphics
|
||||
// TODO: Draw at interpolation points between rooms
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 2. Object Name Labels from String Array
|
||||
**File**: `dungeon_canvas_viewer.cc:416` (DrawObjectPositionOutlines)
|
||||
|
||||
**What**: Show real object names instead of just IDs
|
||||
|
||||
**Implementation**:
|
||||
```cpp
|
||||
// Instead of:
|
||||
std::string label = absl::StrFormat("0x%02X", obj.id_);
|
||||
|
||||
// Use:
|
||||
std::string object_name = GetObjectName(obj.id_);
|
||||
std::string label = absl::StrFormat("%s\n0x%02X", object_name.c_str(), obj.id_);
|
||||
|
||||
// Helper function:
|
||||
std::string GetObjectName(int16_t object_id) {
|
||||
// TODO: Reference ZScream's object name arrays
|
||||
// TODO: Map object ID → name string
|
||||
// Example: 0x10 → "Wall (North)"
|
||||
return "Object";
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 4. Fix Plus Button to Select Any Room
|
||||
**File**: `dungeon_editor_v2.cc:228` (DrawToolset)
|
||||
|
||||
**Current Issue**: Opens Room 0x00 (Ganon) always
|
||||
|
||||
**Fix**:
|
||||
```cpp
|
||||
if (toolbar.AddAction(ICON_MD_ADD, "Open Room")) {
|
||||
// Show room selector dialog instead of opening room 0
|
||||
show_room_selector_ = true;
|
||||
// Or: show room picker popup
|
||||
ImGui::OpenPopup("SelectRoomToOpen");
|
||||
}
|
||||
|
||||
// Add popup:
|
||||
if (ImGui::BeginPopup("SelectRoomToOpen")) {
|
||||
static int selected_room = 0;
|
||||
ImGui::InputInt("Room ID", &selected_room);
|
||||
if (ImGui::Button("Open")) {
|
||||
OnRoomSelected(selected_room);
|
||||
ImGui::CloseCurrentPopup();
|
||||
}
|
||||
ImGui::EndPopup();
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Medium Priority (Should Do)
|
||||
|
||||
#### 6. Fix InputHexByte +/- Button Events
|
||||
**File**: `src/app/gui/input.cc` (likely)
|
||||
|
||||
**Issue**: Buttons don't respond to clicks
|
||||
|
||||
**Investigation Needed**:
|
||||
- Check if button click events are being captured
|
||||
- Verify event logic matches working examples
|
||||
- Keep existing event style if it works elsewhere
|
||||
|
||||
|
||||
### Lower Priority (Nice to Have)
|
||||
|
||||
#### 9. Move Backend Logic to DungeonEditorSystem
|
||||
**What**: Separate UI (V2) from data operations (System)
|
||||
|
||||
**Migration**:
|
||||
- Sprite management → DungeonEditorSystem
|
||||
- Item management → DungeonEditorSystem
|
||||
- Entrance/Door/Chest → DungeonEditorSystem
|
||||
- Undo/Redo → DungeonEditorSystem
|
||||
|
||||
**Result**: DungeonEditorV2 becomes pure UI coordinator
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Build & Run
|
||||
```bash
|
||||
cd /Users/scawful/Code/yaze
|
||||
cmake --preset mac-ai -B build_ai
|
||||
cmake --build build_ai --target yaze -j12
|
||||
|
||||
# Run dungeon editor
|
||||
./build_ai/bin/yaze.app/Contents/MacOS/yaze --rom_file=zelda3.sfc --editor=Dungeon
|
||||
|
||||
# Open specific room
|
||||
./build_ai/bin/yaze.app/Contents/MacOS/yaze --rom_file=zelda3.sfc --editor=Dungeon --cards="Room 0x00"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing & Verification
|
||||
|
||||
### Debug Commands
|
||||
```bash
|
||||
# Verify floor values load correctly
|
||||
./build_ai/bin/yaze.app/Contents/MacOS/yaze --rom_file=zelda3.sfc --editor=Dungeon 2>&1 | grep "floor1="
|
||||
|
||||
# Expected: floor1=4, floor2=8 (NOT 0!)
|
||||
|
||||
# Check object rendering
|
||||
./build_ai/bin/yaze.app/Contents/MacOS/yaze --rom_file=zelda3.sfc --editor=Dungeon 2>&1 | grep "Drawing.*objects"
|
||||
|
||||
# Check object drawing details
|
||||
./build_ai/bin/yaze.app/Contents/MacOS/yaze --rom_file=zelda3.sfc --editor=Dungeon 2>&1 | grep "Writing Tile16"
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **E2-development-guide.md** - Core architectural patterns
|
||||
- **E5-debugging-guide.md** - Debugging workflows
|
||||
- **F1-dungeon-editor-guide.md** - Original dungeon guide (may be outdated)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: October 10, 2025
|
||||
**Contributors**: Dungeon Editor Refactoring Session
|
||||
|
||||
|
||||
Reference in New Issue
Block a user