scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: apply clang-format to all source files

Browse Source 
Fixes formatting violations that were causing CI failures.
Applied clang-format-14 to ensure consistent code formatting
across the codebase.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
scawful
2025-11-20 01:35:33 -05:00
parent c2bb90a3f1
commit fa3da8fc27
600 changed files with 32605 additions and 27962 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/internal/README.md
View File

@@ -10,6 +10,22 @@ speculative without impacting the published docs.
- `roadmaps/` – sequencing, feature parity analysis, and postmortems.
- `research/` – emulator investigations, timing analyses, web ideas, and development trackers.
- `legacy/` – superseded build guides and other historical docs kept for reference.
- `agents/` – includes the coordination board, personas, GH Actions remote guide, and helper scripts
(`scripts/agents/`) for common agent workflows.
When adding new internal docs, place them under the appropriate subdirectory here instead of
`docs/`.
## Version Control & Safety Guidelines
- **Coordinate before forceful changes**: Never rewrite history on shared branches. Use dedicated
feature/bugfix branches (see `docs/public/developer/git-workflow.md`) and keep `develop/master`
clean.
- **Back up ROMs and assets**: Treat sample ROMs, palettes, and project files as irreplaceable. Work
on copies, and enable the editor’s automatic backup setting before testing risky changes.
- **Run scripts/verify-build-environment.* after pulling significant build changes** to avoid
drifting tooling setups.
- **Document risky operations**: When touching migrations, asset packers, or scripts that modify
files in bulk, add notes under `docs/internal/roadmaps/` or `blueprints/` so others understand the
impact.
- **Use the coordination board** for any change that affects multiple personas or large parts of the
tree; log blockers and handoffs to reduce conflicting edits.

10
docs/public/developer/git-workflow.md
View File

@@ -13,6 +13,8 @@
- **Solo work**: Push directly when you're the only one working
- Warning: **Breaking changes**: Use feature branches and document in changelog
- Warning: **Major refactors**: Use feature branches for safety (can always revert)
- **Always keep local backups**: copy ROMs/assets before editing; never risk the only copy.
- **Before rebasing/rewriting history**, stash or copy work elsewhere to prevent accidental loss.
**Why relaxed?**
- Small team / solo development
@@ -199,6 +201,14 @@ git branch -d release/v0.4.0
- `experiment/vulkan-renderer`
- `experiment/wasm-build`
## Git Safety Crash Course
- Run `git status` often and avoid staging ROMs or build artifacts; add ignore rules when necessary.
- Never force-push shared branches (`develop`, `master`). PRs and feature branches are safer places
for rewrites.
- Keep backups of any tools that mutate large files (scripts, automation) so you can revert quickly.
- Before deleting branches that touched ROMs/assets, confirm those files were merged and backed up.
**Rules:**
- Branch from: `develop` or `master`
- May never merge (prototypes, research)

2
docs/public/developer/networking.md
View File

@@ -1,6 +1,6 @@
# B5 - Architecture and Networking
This document provides a comprehensive overview of the yaze application's architecture, focusing on its service-oriented design, gRPC integration, and real-time collaboration features.
This document provides a comprehensive overview of the yaze application's architecture, focusing on its service-oriented design, gRPC integration, and real-time collaboration features. For build/preset instructions when enabling gRPC/automation presets, refer to the [Build & Test Quick Reference](../build/quick-reference.md).
## 1. High-Level Architecture

5
docs/public/developer/testing-guide.md
View File

@@ -62,6 +62,9 @@ Based on the directory structure, tests fall into the following categories:
## 3. Running Tests
> 💡 Need a refresher on presets/commands? See the [Build & Test Quick Reference](../build/quick-reference.md)
> for the canonical `cmake`, `ctest`, and helper script usage before running the commands below.
### Using the Enhanced Test Runner (`yaze_test`)
The most flexible way to run tests is by using the `yaze_test` executable directly. It provides flags to filter tests by category, which is ideal for development and AI agent workflows.
@@ -147,4 +150,4 @@ To run E2E tests and see the GUI interactions, use the `--show-gui` flag.
The GUI testing framework is designed for AI agent automation. All major UI elements are registered with stable IDs, allowing an agent to "discover" and interact with them programmatically via the `z3ed` CLI.
Refer to the `z3ed` agent guide for details on using commands like `z3ed gui discover`, `z3ed gui click`, and `z3ed agent test replay`.
Refer to the `z3ed` agent guide for details on using commands like `z3ed gui discover`, `z3ed gui click`, and `z3ed agent test replay`.

1
docs/public/index.md
View File

@@ -13,6 +13,7 @@ and research notes were moved to `docs/internal/` so the public docs stay focuse
- [Getting Started](overview/getting-started.md)
## Build & Tooling
- [Build Quick Reference](build/quick-reference.md)
- [Build From Source](build/build-from-source.md)
- [Platform Compatibility](build/platform-compatibility.md)
- [CMake Presets](build/presets.md)

3
docs/public/overview/getting-started.md
View File

@@ -9,6 +9,9 @@ This software allows you to modify "The Legend of Zelda: A Link to the Past" (US
3. **Select an Editor** from the main toolbar (e.g., Overworld, Dungeon, Graphics).
4. **Make Changes** and save your project.
> Building from source or enabling AI tooling? Use the
> [Build & Test Quick Reference](../build/quick-reference.md) for the canonical commands and presets.
## General Tips
- **Experiment Flags**: Enable or disable new features in `File > Options > Experiment Flags`.

314
docs/public/usage/dungeon-editor.md
View File

@@ -1,262 +1,116 @@
# F2: Dungeon Editor v2 - Complete Guide
# F2: Dungeon Editor v2 Guide
**Last Updated**: October 10, 2025
**Related**: [Architecture Overview](../developer/architecture.md), [Debugging Guide](../developer/debugging-guide.md)
**Scope**: DungeonEditorV2 (card-based UI), DungeonEditorSystem, dungeon canvases
**Related**: [Architecture Overview](../developer/architecture.md), [Canvas System](../developer/canvas-system.md)
---
## Overview
## 1. 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.
The Dungeon Editor ships with the multi-card workspace introduced in the 0.3.x releases.
Self-contained room buffers keep graphics, objects, and palettes isolated so you can switch between
rooms without invalidating the entire renderer.
### 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
- 512×512 canvas per room with pan/zoom, grid, and collision overlays.
- Layer-specific visualization (BG1/BG2 toggles, colored object outlines, slot labels).
- Modular cards for rooms, objects, palettes, entrances, and toolsets.
- Undo/Redo shared across cards via `DungeonEditorSystem`.
- Tight overworld integration: double-click an entrance to open the linked dungeon room.
---
### 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
## 2. Architecture Snapshot
```
DungeonEditorV2 (UI Layer)
├─ Card-based UI system
├─ Room window management
├─ Component coordination
└─ Lazy loading
DungeonEditorV2 (UI)
├─ Cards & docking
├─ Canvas presenter
└─ Menu + toolbar actions
DungeonEditorSystem (Backend Layer)
├─ Sprite/Item/Entrance/Door/Chest management
├─ Undo/Redo functionality
├─ Room properties management
└─ Dungeon-wide operations
DungeonEditorSystem (Backend)
├─ Room/session state
├─ Undo/Redo stack
├─ Sprite/entrance/item helpers
└─ Persistence + ROM writes
Room (Data Layer)
├─ Self-contained buffers (bg1_buffer_, bg2_buffer_)
├─ Object storage (tile_objects_)
├─ Graphics loading
└─ Rendering pipeline
Room Model (Data)
├─ bg1_buffer_, bg2_buffer_
├─ tile_objects_, door data, metadata
└─ Palette + blockset caches
```
### Room Rendering Pipeline
1. **Load** – `DungeonRoomLoader` reads the room header, blockset pointers, and door/entrance
metadata, producing a `Room` instance with immutable layout info.
2. **Decode** – The requested blockset is converted into `current_gfx16_` bitmaps; objects are parsed
into `tile_objects_` grouped by layer and palette slot.
3. **Draw** – `DungeonCanvasViewer` builds BG1/BG2 bitmaps, then overlays each object layer via
`ObjectDrawer`. Palette state comes from the room’s 90-color dungeon palette.
4. **Queue** – The finished bitmaps are pushed into the graphics `Arena`, which uploads a bounded
number of textures per frame so UI latency stays flat.
5. **Present** – When textures become available, the canvas displays the layers, draws interaction
widgets (selection rectangles, door gizmos, entity labels), and applies zoom/grid settings.
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.
Changing tiles, palettes, or objects invalidates the affected room cache so steps 2–5 rerun only for
that room.
---
## Next Development Steps
## 3. Editing Workflow
### High Priority (Must Do)
### Opening Rooms
1. Launch `yaze` with a ROM (`./build/bin/yaze --rom_file=zelda3.sfc`).
2. Use the **Room Matrix** or **Rooms List** card to choose a room. The toolbar “+” button also opens
the selector.
3. Pin multiple rooms by opening them in separate cards; each card maintains its own canvas state.
#### 1. Door Rendering at Room Edges
**What**: Render doors with proper patterns at room connections
### Working with Cards
**Pattern Reference**: ZScream's door drawing patterns
| Card | Purpose |
|------|---------|
| **Room Graphics** | Primary canvas, BG toggles, collision/grid switches. |
| **Object Editor** | Filter by type/layer, edit coordinates, duplicate/delete objects. |
| **Palette Editor** | Adjust per-room palette slots and preview results immediately. |
| **Entrances List** | Jump between overworld entrances and their mapped rooms. |
| **Room Matrix** | Visual grid of all rooms grouped per dungeon for quick navigation. |
**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
}
```
Cards can be docked, detached, or saved as workspace presets; use the sidebar to store favorite
layouts (e.g., Room Graphics + Object Editor + Palette).
### Canvas Interactions
- Left-click to select an object; Shift-click to add to the selection.
- Drag handles to move objects or use the property grid for precise coordinates.
- Right-click to open the context menu, which includes quick inserts for common objects and a “jump
to entrance” helper.
- Hold Space to pan, use mouse wheel (or trackpad pinch) to zoom. The status footer shows current
zoom and cursor coordinates.
- Enable **Object Labels** from the toolbar to show layer-colored labels (e.g., `L1 Chest 0x23`).
### Saving & Undo
- The editor queues every change through `DungeonEditorSystem`. Use `Cmd/Ctrl+Z` and `Cmd/Ctrl+Shift+Z`
to undo/redo across cards.
- Saving writes back the room buffers, door metadata, and palettes for the active session. Keep
backups enabled (`File → Options → Experiment Flags`) for safety.
---
#### 2. Object Name Labels from String Array
**File**: `dungeon_canvas_viewer.cc:416` (DrawObjectPositionOutlines)
## 4. Tips & Troubleshooting
**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";
}
```
- **Layer sanity**: If objects appear on the wrong layer, check the BG toggles in Room Graphics and
the layer filter in Object Editor—they operate independently.
- **Palette issues**: Palettes are per room. After editing, ensure `Palette Editor` writes the new
values before switching rooms; the status footer confirms pending writes.
- **Door alignment**: Use the entrance/door inspector popup (right-click a door marker) to verify
leads-to IDs without leaving the canvas.
- **Performance**: Large ROMs with many rooms can accumulate textures. If the editor feels sluggish,
close unused room cards; each card releases its textures when closed.
---
#### 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
- **Architecture Overview** (`../developer/architecture.md`) - Core architectural patterns
- **Debugging Guide** (`../developer/debugging-guide.md`) - Debugging workflows
- **Legacy context** - This document supersedes the legacy `F1-dungeon-editor-guide.md`.
---
**Last Updated**: October 10, 2025
**Contributors**: Dungeon Editor Refactoring Session
## 5. Related Docs
- [Developer Architecture Overview](../developer/architecture.md) – patterns shared across editors.
- [Canvas System Guide](../developer/canvas-system.md) – detailed explanation of canvas usage,
context menus, and popups.
- [Debugging Guide](../developer/debugging-guide.md) – startup flags and logging tips (e.g.,
`--editor=Dungeon --cards="Room 0"` for focused debugging).