feat(docs): add comprehensive refactoring plans for test dashboard and zelda3 library
- Introduced detailed refactoring plans for the in-app test dashboard and the zelda3 library, addressing architectural issues and improving modularity. - The test dashboard plan outlines a decoupled architecture, enhancing maintainability and build efficiency. - The zelda3 library plan proposes a migration to a core shared library structure, improving incremental build times and clarifying domain boundaries. Benefits: - Enhances the overall structure and maintainability of the codebase. - Facilitates future development and testing efforts by establishing clear architectural guidelines.
This commit is contained in:
scawful
127
docs/A2-test-dashboard-refactoring.md
Normal file
127
docs/A2-test-dashboard-refactoring.md
Normal file
@@ -0,0 +1,127 @@
|
||||
YAZE GUI Test Integration Refactoring Plan
|
||||
|
||||
Author: Gemini
|
||||
Date: 2025-10-11
|
||||
Status: Proposed
|
||||
|
||||
1. Introduction & Motivation
|
||||
|
||||
The yaze application includes a valuable feature for developers: an in-application "Test Dashboard" that allows for
|
||||
viewing and running various test suites directly within the GUI. However, the current implementation, located primarily
|
||||
in src/app/test/, is tightly coupled with both the main application and the command-line test executables.
|
||||
|
||||
This tight coupling has led to several architectural and practical problems:
|
||||
* Conditional Compilation Complexity: Excluding the test dashboard from release or CI/CD builds is difficult, as its code
|
||||
is intertwined with core application logic. This unnecessarily bloats release binaries with test code.
|
||||
* Circular Dependencies: The yaze_test_support library, which contains the TestManager, links against nearly all other
|
||||
application libraries (yaze_editor, yaze_gui, etc.). When the main application also links against yaze_test_support to
|
||||
display the dashboard, it creates a confusing and potentially circular dependency graph that complicates the build
|
||||
process.
|
||||
* Mixed Concerns: The current TestManager is responsible for both the core logic of running tests and the UI logic for
|
||||
displaying the dashboard. This violates the Single-Responsibility Principle and makes the code harder to maintain.
|
||||
|
||||
This document proposes a plan to refactor the test integration system into a modular, layered, and conditionally
|
||||
compiled architecture.
|
||||
|
||||
2. Goals
|
||||
|
||||
* Decouple Test Infrastructure: Separate the core test framework from the test suites and the GUI dashboard.
|
||||
* Create an Optional Test Dashboard: Make the in-app test dashboard a compile-time feature that can be easily enabled for
|
||||
development builds and disabled for release builds.
|
||||
* Eliminate Complex Dependencies: Remove the need for the main application to link against the entire suite of test
|
||||
implementations, simplifying the build graph.
|
||||
* Improve Maintainability: Create a clean and logical structure for the test system that is easier to understand and
|
||||
extend.
|
||||
|
||||
3. Proposed Architecture
|
||||
|
||||
The test system will be decomposed into three distinct libraries, clearly separating the framework, the UI, and the
|
||||
tests themselves.
|
||||
|
||||
1 +-----------------------------------------------------------------+
|
||||
2 | Main Application ("yaze") |
|
||||
3 | (Conditionally links against test_dashboard) |
|
||||
4 +-----------------------------------------------------------------+
|
||||
5 | ^
|
||||
6 | Optionally depends on |
|
||||
7 v |
|
||||
8 +-----------------+ +-----------------+ +-----------------+
|
||||
9 | test_dashboard | --> | test_framework | <-- | test_suites |
|
||||
10 | (GUI Component) | | (Core Logic) | | (Test Cases) |
|
||||
11 +-----------------+ +-----------------+ +-----------------+
|
||||
12 ^ ^
|
||||
13 | |
|
||||
14 |-------------------------------------------------|
|
||||
15 |
|
||||
16 v
|
||||
17 +-----------------------------------------------------------------+
|
||||
18 | Test Executables (yaze_test_stable, etc.) |
|
||||
19 | (Link against test_framework and test_suites) |
|
||||
20 +-----------------------------------------------------------------+
|
||||
|
||||
3.1. test_framework (New Core Library)
|
||||
* Location: src/test/framework/
|
||||
* Responsibility: Provides the core, non-GUI logic for managing and executing tests.
|
||||
* Contents:
|
||||
* TestManager (core logic only: RunTests, RegisterTestSuite, GetLastResults, etc.).
|
||||
* TestSuite base class and related structs (TestResult, TestResults, etc.).
|
||||
* Dependencies: yaze_util, absl. It will not depend on yaze_gui or any specific test suites.
|
||||
|
||||
3.2. test_suites (New Library)
|
||||
* Location: src/test/suites/
|
||||
* Responsibility: Contains all the actual test implementations.
|
||||
* Contents:
|
||||
* E2ETestSuite, EmulatorTestSuite, IntegratedTestSuite, RomDependentTestSuite, ZSCustomOverworldTestSuite,
|
||||
Z3edAIAgentTestSuite.
|
||||
* Dependencies: test_framework, and any yaze libraries required for testing (e.g., yaze_zelda3, yaze_gfx).
|
||||
|
||||
3.3. test_dashboard (New Conditional GUI Library)
|
||||
* Location: src/app/gui/testing/
|
||||
* Responsibility: Contains all ImGui code for the in-application test dashboard. This library will be conditionally
|
||||
compiled and linked.
|
||||
* Contents:
|
||||
* A new TestDashboard class containing the DrawTestDashboard method (migrated from TestManager).
|
||||
* UI-specific logic for displaying results, configuring tests, and interacting with the TestManager.
|
||||
* Dependencies: test_framework, yaze_gui.
|
||||
|
||||
4. Migration & Refactoring Plan
|
||||
|
||||
1. Create New Directory Structure:
|
||||
* Create src/test/framework/.
|
||||
* Create src/test/suites/.
|
||||
* Create src/app/gui/testing/.
|
||||
|
||||
2. Split `TestManager`:
|
||||
* Move test_manager.h and test_manager.cc to src/test/framework/.
|
||||
* Create a new TestDashboard class in src/app/gui/testing/test_dashboard.h/.cc.
|
||||
* Move the DrawTestDashboard method and all its UI-related helper functions from TestManager into the new
|
||||
TestDashboard class.
|
||||
* The TestDashboard will hold a reference to the TestManager singleton to access results and trigger test runs.
|
||||
|
||||
3. Relocate Test Suites:
|
||||
* Move all ..._test_suite.h files from src/app/test/ to the new src/test/suites/ directory.
|
||||
* Move z3ed_test_suite.cc to src/test/suites/.
|
||||
|
||||
4. Update CMake Configuration:
|
||||
* `src/test/framework/CMakeLists.txt`: Create this file to define the yaze_test_framework static library.
|
||||
* `src/test/suites/CMakeLists.txt`: Create this file to define the yaze_test_suites static library, linking it
|
||||
against yaze_test_framework and other necessary yaze libraries.
|
||||
* `src/app/gui/testing/CMakeLists.txt`: Create this file to define the yaze_test_dashboard static library.
|
||||
* Root `CMakeLists.txt`: Introduce a new option: option(YAZE_WITH_TEST_DASHBOARD "Build the in-application test
|
||||
dashboard" ON).
|
||||
* `src/app/app.cmake`: Modify the yaze executable's target_link_libraries to conditionally link yaze_test_dashboard
|
||||
based on the YAZE_WITH_TEST_DASHBOARD flag.
|
||||
* `test/CMakeLists.txt`: Update the test executables to link against yaze_test_framework and yaze_test_suites.
|
||||
* Remove `src/app/test/test.cmake`: The old yaze_test_support library will be completely replaced by this new
|
||||
structure.
|
||||
|
||||
5. Expected Outcomes
|
||||
|
||||
This plan will resolve the current architectural issues by:
|
||||
* Enabling Clean Builds: Release and CI builds can set YAZE_WITH_TEST_DASHBOARD=OFF, which will prevent the
|
||||
test_dashboard and test_suites libraries from being compiled or linked into the final yaze executable, resulting in a
|
||||
smaller, cleaner binary.
|
||||
* Simplifying Dependencies: The main application will no longer have a convoluted dependency on its own test suites. The
|
||||
dependency graph will be clear and acyclic.
|
||||
* Improving Developer Experience: Developers can enable the dashboard for convenient in-app testing, while the core test
|
||||
infrastructure remains robust and decoupled for command-line execution.
|
||||
133
docs/B6-zelda3-library-refactoring.md
Normal file
133
docs/B6-zelda3-library-refactoring.md
Normal file
@@ -0,0 +1,133 @@
|
||||
YAZE `zelda3` Library Refactoring & Migration Plan
|
||||
|
||||
Author: Gemini
|
||||
Date: 2025-10-11
|
||||
Status: Proposed
|
||||
|
||||
1. Introduction & Motivation
|
||||
|
||||
The zelda3 library, currently located at src/app/zelda3, encapsulates all the data models and logic specific to "A Link
|
||||
to the Past." It serves as the foundational data layer for both the yaze GUI application and the z3ed command-line tool.
|
||||
|
||||
Its current structure and location present two primary challenges:
|
||||
|
||||
1. Monolithic Design: Like the gfx and gui libraries, zelda3 is a single, large static library. This creates a
|
||||
tightly-coupled module where a change to any single component (e.g., dungeon objects) forces a relink of the entire
|
||||
library and all its dependents.
|
||||
2. Incorrect Location: The library resides within src/app/, which is designated for the GUI application's specific code.
|
||||
However, its logic is shared with the cli target. This violates architectural principles and creates an improper
|
||||
dependency from the cli module into the app module's subdirectory.
|
||||
|
||||
This document proposes a comprehensive plan to both refactor the zelda3 library into logical sub-modules and migrate it
|
||||
to a top-level directory (src/zelda3) to correctly establish it as a shared, core component.
|
||||
|
||||
2. Goals
|
||||
|
||||
* Establish as a Core Shared Library: Physically and logically move the library to src/zelda3 to reflect its role as a
|
||||
foundational component for both the application and the CLI.
|
||||
* Improve Incremental Build Times: Decompose the library into smaller, focused modules to minimize the scope of rebuilds
|
||||
and relinks.
|
||||
* Clarify Domain Boundaries: Create a clear separation between the major game systems (Overworld, Dungeon, Sprites, etc.)
|
||||
to improve code organization and maintainability.
|
||||
* Isolate Legacy Code: Encapsulate the legacy Hyrule Magic music tracker code into its own module to separate it from the
|
||||
modern C++ codebase.
|
||||
|
||||
3. Proposed Architecture
|
||||
|
||||
The zelda3 library will be moved to src/zelda3/ and broken down into six distinct, layered libraries.
|
||||
|
||||
```
|
||||
1 +-----------------------------------------------------------------+
|
||||
2 | Executables (yaze, z3ed, tests) |
|
||||
3 +-----------------------------------------------------------------+
|
||||
4 ^
|
||||
5 | Links against
|
||||
6 v
|
||||
7 +-----------------------------------------------------------------+
|
||||
8 | zelda3 (INTERFACE Library) |
|
||||
9 +-----------------------------------------------------------------+
|
||||
10 ^
|
||||
11 | Aggregates
|
||||
12 |-----------------------------------------------------------|
|
||||
13 | | |
|
||||
14 v v v
|
||||
15 +-----------------+ +-----------------+ +---------------------+
|
||||
16 | zelda3_screen |-->| zelda3_dungeon |-->| zelda3_overworld |
|
||||
17 +-----------------+ +-----------------+ +---------------------+
|
||||
18 | | ^ | ^
|
||||
19 | | | | |
|
||||
20 |-----------------|---------|---------|---------|
|
||||
21 | | | | |
|
||||
22 v v | v v
|
||||
23 +-----------------+ +-----------------+ +---------------------+
|
||||
24 | zelda3_music |-->| zelda3_sprite |-->| zelda3_core |
|
||||
25 +-----------------+ +-----------------+ +---------------------+
|
||||
```
|
||||
|
||||
3.1. zelda3_core (Foundation)
|
||||
* Responsibility: Contains fundamental data structures, constants, and labels used across all other zelda3 modules.
|
||||
* Contents: common.h, zelda3_labels.h/.cc, dungeon/dungeon_rom_addresses.h.
|
||||
* Dependencies: yaze_util.
|
||||
|
||||
3.2. zelda3_sprite (Shared Game Entity)
|
||||
* Responsibility: Manages the logic and data for sprites, which are used in both dungeons and the overworld.
|
||||
* Contents: sprite/sprite.h/.cc, sprite/sprite_builder.h/.cc, sprite/overlord.h.
|
||||
* Dependencies: zelda3_core.
|
||||
|
||||
3.3. zelda3_dungeon (Dungeon System)
|
||||
* Responsibility: The complete, self-contained system for all dungeon-related data and logic.
|
||||
* Contents: All files from dungeon/ (room.h/.cc, room_object.h/.cc, dungeon_editor_system.h/.cc, etc.).
|
||||
* Dependencies: zelda3_core, zelda3_sprite.
|
||||
|
||||
3.4. zelda3_overworld (Overworld System)
|
||||
* Responsibility: The complete, self-contained system for all overworld-related data and logic.
|
||||
* Contents: All files from overworld/ (overworld.h/.cc, overworld_map.h/.cc, etc.).
|
||||
* Dependencies: zelda3_core, zelda3_sprite.
|
||||
|
||||
3.5. zelda3_screen (Specific Game Screens)
|
||||
* Responsibility: High-level components representing specific, non-gameplay screens.
|
||||
* Contents: All files from screen/ (dungeon_map.h/.cc, inventory.h/.cc, title_screen.h/.cc).
|
||||
* Dependencies: zelda3_dungeon, zelda3_overworld.
|
||||
|
||||
3.6. zelda3_music (Legacy Isolation)
|
||||
* Responsibility: Encapsulates the legacy Hyrule Magic music tracker code.
|
||||
* Contents: music/tracker.h/.cc.
|
||||
* Dependencies: zelda3_core.
|
||||
|
||||
4. Migration Plan
|
||||
|
||||
This plan details the steps to move the library from src/app/zelda3 to src/zelda3.
|
||||
|
||||
1. Physical File Move:
|
||||
* Move the directory /Users/scawful/Code/yaze/src/app/zelda3 to /Users/scawful/Code/yaze/src/zelda3.
|
||||
|
||||
2. Update CMake Configuration:
|
||||
* In src/CMakeLists.txt, change the line include(zelda3/zelda3_library.cmake) to
|
||||
include(zelda3/zelda3_library.cmake).
|
||||
* In the newly moved src/zelda3/zelda3_library.cmake, update all target_include_directories paths to remove the app/
|
||||
prefix (e.g., change ${CMAKE_SOURCE_DIR}/src/app to ${CMAKE_SOURCE_DIR}/src).
|
||||
|
||||
3. Update Include Directives (Global):
|
||||
* Perform a project-wide search-and-replace for all occurrences of #include "zelda3/ and change them to #include
|
||||
"zelda3/.
|
||||
* This will be the most extensive step, touching files in src/app/, src/cli/, and test/.
|
||||
|
||||
4. Verification:
|
||||
* After the changes, run a full CMake configure and build (cmake --preset mac-dev -B build_ai && cmake --build
|
||||
build_ai) to ensure all paths are correctly resolved and the project compiles successfully.
|
||||
|
||||
5. Implementation Plan (CMake)
|
||||
|
||||
The refactoring will be implemented within the new src/zelda3/zelda3_library.cmake file.
|
||||
|
||||
1. Define Source Groups: Create set() commands for each new library (ZELDA3_CORE_SRC, ZELDA3_DUNGEON_SRC, etc.).
|
||||
2. Create Static Libraries: Use add_library(yaze_zelda3_core STATIC ...) for each module.
|
||||
3. Establish Link Dependencies: Use target_link_libraries to define the dependencies outlined in section 3.
|
||||
4. Create Aggregate Interface Library: The yaze_zelda3 target will be converted to an INTERFACE library that links against
|
||||
all the new sub-libraries, providing a single, convenient link target for yaze_gui, yaze_cli, and the test suites.
|
||||
|
||||
6. Expected Outcomes
|
||||
|
||||
This refactoring and migration will establish the zelda3 library as a true core component of the application. The result
|
||||
will be a more logical and maintainable architecture, significantly faster incremental build times, and a clear
|
||||
separation of concerns that will benefit future development.
|
||||
@@ -2,13 +2,13 @@
|
||||
|
||||
**Branch:** `feature/apu-timing-fix`
|
||||
**Date:** October 10, 2025
|
||||
**Status:** ✅ Implemented - Core Timing Fixed (Minor Audio Glitches Remain)
|
||||
**Status:** Implemented - Core Timing Fixed (Minor Audio Glitches Remain)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Status
|
||||
|
||||
**✅ Completed:**
|
||||
**Completed:**
|
||||
- Atomic `Step()` function for SPC700
|
||||
- Fixed-point cycle ratio (no floating-point drift)
|
||||
- Cycle budget model in APU
|
||||
@@ -17,7 +17,7 @@
|
||||
- Proper branch timing (+2 cycles when taken)
|
||||
- Dummy read/write cycles for MOV and RMW instructions
|
||||
|
||||
**⚠️ Known Issues:**
|
||||
**Known Issues:**
|
||||
- Some audio glitches/distortion during playback
|
||||
- Minor timing inconsistencies under investigation
|
||||
- Can be improved in future iterations
|
||||
@@ -243,16 +243,16 @@ while (cycles_ < target_apu_cycles) {
|
||||
|
||||
### What We're Adopting from LakeSnes
|
||||
|
||||
✅ **Atomic instruction execution** - No `bstep` mechanism
|
||||
✅ **Simple addressing mode functions** - Return address, advance cycles via callbacks
|
||||
✅ **Cycle advancement per memory access** - Every read/write/idle advances cycles
|
||||
**Atomic instruction execution** - No `bstep` mechanism
|
||||
**Simple addressing mode functions** - Return address, advance cycles via callbacks
|
||||
**Cycle advancement per memory access** - Every read/write/idle advances cycles
|
||||
|
||||
### What We're Improving Over LakeSnes
|
||||
|
||||
✅ **Explicit cycle counting** - `Step()` returns exact cycles consumed
|
||||
✅ **Cycle budget model** - Clear loop with explicit cycle advancement
|
||||
✅ **Fixed-point ratio** - Integer arithmetic for perfect precision
|
||||
✅ **Testability** - Easy to verify cycle counts per instruction
|
||||
**Explicit cycle counting** - `Step()` returns exact cycles consumed
|
||||
**Cycle budget model** - Clear loop with explicit cycle advancement
|
||||
**Fixed-point ratio** - Integer arithmetic for perfect precision
|
||||
**Testability** - Easy to verify cycle counts per instruction
|
||||
|
||||
---
|
||||
|
||||
@@ -442,16 +442,16 @@ apu_cycles = (master_cycles * kApuCyclesNumerator) / kApuCyclesDenominator;
|
||||
|
||||
## Implementation Completed
|
||||
|
||||
1. ✅ Create feature branch
|
||||
2. ✅ Analyze current implementation
|
||||
3. ✅ Implement `Spc700::Step()` function
|
||||
4. ✅ Add precise cycle calculation
|
||||
5. ✅ Refactor `Apu::RunCycles`
|
||||
6. ✅ Convert to fixed-point ratio
|
||||
7. ✅ Refactor instructions.cc to be atomic and cycle-accurate
|
||||
8. ✅ Test with Zelda3 ROM
|
||||
9. ⏳ Write unit tests (future work)
|
||||
10. ⏳ Fine-tune audio quality (future work)
|
||||
1. Create feature branch
|
||||
2. Analyze current implementation
|
||||
3. Implement `Spc700::Step()` function
|
||||
4. Add precise cycle calculation
|
||||
5. Refactor `Apu::RunCycles`
|
||||
6. Convert to fixed-point ratio
|
||||
7. Refactor instructions.cc to be atomic and cycle-accurate
|
||||
8. Test with Zelda3 ROM
|
||||
9. Write unit tests (future work)
|
||||
10. Fine-tune audio quality (future work)
|
||||
|
||||
---
|
||||
|
||||
@@ -1,19 +1,23 @@
|
||||
# E6 - GUI Consistency and Card-Based Architecture Guide
|
||||
# G5 - GUI Consistency and Card-Based Architecture Guide
|
||||
|
||||
This guide establishes standards for GUI consistency across all yaze editors, focusing on the modern card-based architecture, theming system, and layout patterns introduced in the Dungeon Editor v2 and Palette Editor refactorings.
|
||||
This guide establishes standards for GUI consistency across all yaze editors, focusing on the modern card-based architecture, theming system, and layout patterns.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Introduction](#1-introduction)
|
||||
2. [Card-Based Architecture](#2-card-based-architecture)
|
||||
3. [Toolset System](#3-toolset-system)
|
||||
4. [Themed Widget System](#4-themed-widget-system)
|
||||
5. [Begin/End Patterns](#5-beginend-patterns)
|
||||
6. [Layout Helpers](#6-layout-helpers)
|
||||
7. [Future Editor Improvements](#7-future-editor-improvements)
|
||||
8. [Migration Checklist](#8-migration-checklist)
|
||||
9. [Code Examples](#9-code-examples)
|
||||
10. [Common Pitfalls](#10-common-pitfalls)
|
||||
3. [VSCode-Style Sidebar System](#3-vscode-style-sidebar-system)
|
||||
4. [Toolset System](#4-toolset-system)
|
||||
5. [GUI Library Architecture](#5-gui-library-architecture)
|
||||
6. [Themed Widget System](#6-themed-widget-system)
|
||||
7. [Begin/End Patterns](#7-beginend-patterns)
|
||||
8. [Currently Integrated Editors](#8-currently-integrated-editors)
|
||||
9. [Layout Helpers](#9-layout-helpers)
|
||||
10. [Workspace Management](#10-workspace-management)
|
||||
11. [Future Editor Improvements](#11-future-editor-improvements)
|
||||
12. [Migration Checklist](#12-migration-checklist)
|
||||
13. [Code Examples](#13-code-examples)
|
||||
14. [Common Pitfalls](#14-common-pitfalls)
|
||||
|
||||
## 1. Introduction
|
||||
|
||||
@@ -107,31 +111,34 @@ void MyEditor::DrawMyCard() {
|
||||
}
|
||||
```
|
||||
|
||||
### Visibility Flag Synchronization
|
||||
### Centralized Visibility Pattern
|
||||
|
||||
Critical pattern for proper card behavior:
|
||||
All editors now use the centralized visibility system where EditorCardManager owns and manages all visibility bools:
|
||||
|
||||
```cpp
|
||||
absl::Status MyEditor::Update() {
|
||||
// For each card, sync visibility flags
|
||||
if (show_my_card_ && my_card_instance_) {
|
||||
// Ensure internal show_ flag is set
|
||||
if (!my_card_instance_->IsVisible()) {
|
||||
my_card_instance_->Show();
|
||||
}
|
||||
// Registration (in Initialize()):
|
||||
card_manager.RegisterCard({
|
||||
.card_id = "music.tracker",
|
||||
.display_name = "Music Tracker",
|
||||
.icon = ICON_MD_MUSIC_NOTE,
|
||||
.category = "Music"
|
||||
});
|
||||
|
||||
my_card_instance_->Draw();
|
||||
|
||||
// Sync back if user closed with X button
|
||||
if (!my_card_instance_->IsVisible()) {
|
||||
show_my_card_ = false;
|
||||
}
|
||||
}
|
||||
|
||||
return absl::OkStatus();
|
||||
// Usage (in Update()):
|
||||
static gui::EditorCard card("Music Tracker", ICON_MD_MUSIC_NOTE);
|
||||
if (card.Begin(card_manager.GetVisibilityFlag("music.tracker"))) {
|
||||
DrawContent();
|
||||
card.End();
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Single source of truth for all card visibility
|
||||
- No scattered bool members in editor classes
|
||||
- Automatic X button close functionality
|
||||
- Consistent behavior across all cards
|
||||
- Easy to query/modify from anywhere
|
||||
|
||||
### Reference Implementations
|
||||
|
||||
**Best Examples:**
|
||||
@@ -145,7 +152,45 @@ absl::Status MyEditor::Update() {
|
||||
- Proper card registration with shortcuts
|
||||
- Room cards in separate docking class
|
||||
|
||||
## 3. Toolset System
|
||||
## 3. VSCode-Style Sidebar System
|
||||
|
||||
### Overview
|
||||
|
||||
The VSCode-style sidebar provides a unified interface for managing editor cards. It's a fixed 48px sidebar on the left edge with icon-based card toggles.
|
||||
|
||||
**Key Features:**
|
||||
- Fixed position on left edge (48px width)
|
||||
- Icon-based card toggles
|
||||
- Category switcher for multi-editor sessions
|
||||
- Card browser button (Ctrl+Shift+B)
|
||||
- Collapse button (Ctrl+B)
|
||||
- Theme-aware styling
|
||||
- Recent categories stack (last 5 used)
|
||||
|
||||
### Usage
|
||||
|
||||
Each card-based editor simply calls:
|
||||
|
||||
```cpp
|
||||
void MyEditor::DrawToolset() {
|
||||
auto& card_manager = gui::EditorCardManager::Get();
|
||||
card_manager.DrawSidebar("MyEditor");
|
||||
}
|
||||
```
|
||||
|
||||
The sidebar automatically reads from the existing card registry - no per-editor configuration needed.
|
||||
|
||||
### Card Browser
|
||||
|
||||
Press `Ctrl+Shift+B` to open the card browser:
|
||||
- Search/filter cards by name
|
||||
- Category tabs
|
||||
- Visibility toggle for all cards
|
||||
- Statistics (total/visible cards)
|
||||
- Preset management
|
||||
- Batch operations (Show All, Hide All per category)
|
||||
|
||||
## 4. Toolset System
|
||||
|
||||
### Overview
|
||||
|
||||
@@ -234,7 +279,69 @@ toolbar.AddV3StatusBadge(rom_->asm_version(), []() {
|
||||
4. **Provide shortcuts**: Include keyboard shortcuts in tooltips
|
||||
5. **Consistent ordering**: Toggles first, properties second, actions third
|
||||
|
||||
## 4. Themed Widget System
|
||||
## 5. GUI Library Architecture
|
||||
|
||||
### Modular Library Structure
|
||||
|
||||
The yaze GUI is organized into focused, layered libraries for improved build times and maintainability:
|
||||
|
||||
**gui_core (Foundation)**
|
||||
- Theme management, colors, styling
|
||||
- Icons, input handling, layout helpers
|
||||
- Dependencies: yaze_util, ImGui, SDL2
|
||||
|
||||
**canvas (Core Widget)**
|
||||
- Canvas widget system
|
||||
- Canvas utilities, modals, context menus
|
||||
- Dependencies: gui_core, yaze_gfx
|
||||
|
||||
**gui_widgets (Reusable Components)**
|
||||
- Themed widgets, palette widgets
|
||||
- Asset browser, text editor, tile selector
|
||||
- Dependencies: gui_core, yaze_gfx
|
||||
|
||||
**gui_automation (Testing & AI)**
|
||||
- Widget ID registry, auto-registration
|
||||
- Widget state capture and measurement
|
||||
- Dependencies: gui_core
|
||||
|
||||
**gui_app (Application-Specific UI)**
|
||||
- EditorCardManager, EditorLayout
|
||||
- Background renderer, collaboration panel
|
||||
- Dependencies: gui_core, gui_widgets, gui_automation
|
||||
|
||||
**yaze_gui (Interface Library)**
|
||||
- Aggregates all sub-libraries
|
||||
- Single link target for executables
|
||||
|
||||
### Theme-Aware Sizing System
|
||||
|
||||
All UI sizing respects the theme's `compact_factor` (0.8-1.2) for global density control:
|
||||
|
||||
```cpp
|
||||
#include "app/gui/layout_helpers.h"
|
||||
|
||||
using gui::LayoutHelpers;
|
||||
|
||||
// Standard widget sizing
|
||||
float widget_height = LayoutHelpers::GetStandardWidgetHeight();
|
||||
float spacing = LayoutHelpers::GetStandardSpacing();
|
||||
float toolbar_height = LayoutHelpers::GetToolbarHeight();
|
||||
|
||||
// All sizing respects: theme.compact_factor * multiplier * ImGui::GetFontSize()
|
||||
```
|
||||
|
||||
**Layout Helpers API:**
|
||||
- `BeginTableWithTheming()` - Tables with automatic theme colors
|
||||
- `BeginCanvasPanel() / EndCanvasPanel()` - Canvas containers
|
||||
- `BeginPaddedPanel() / EndPaddedPanel()` - Consistent padding
|
||||
- `InputHexRow()` - Labeled hex inputs
|
||||
- `BeginPropertyGrid() / EndPropertyGrid()` - 2-column property tables
|
||||
- `PropertyRow()` - Label + widget in table row
|
||||
- `SectionHeader()` - Colored section headers
|
||||
- `HelpMarker()` - Tooltip help icons
|
||||
|
||||
## 6. Themed Widget System
|
||||
|
||||
### Philosophy
|
||||
|
||||
@@ -254,7 +361,7 @@ All theme-aware widgets are prefixed with `Themed*`:
|
||||
### Usage Examples
|
||||
|
||||
```cpp
|
||||
#include "app/gui/themed_widgets.h"
|
||||
#include "app/gui/core/themed_widgets.h"
|
||||
|
||||
using gui::ThemedButton;
|
||||
using gui::ThemedIconButton;
|
||||
@@ -336,7 +443,31 @@ ImGui::PushStyleColor(ImGuiCol_ChildBg, theme.panel_bg_color);
|
||||
ImGui::TextColored(theme.status_error, "Error!");
|
||||
```
|
||||
|
||||
## 5. Begin/End Patterns
|
||||
### WhichKey Command System
|
||||
|
||||
Spacemacs-style hierarchical command navigation:
|
||||
|
||||
```cpp
|
||||
// Press Space → Shows root menu with colored categories
|
||||
// Press category key (e.g., w) → Shows window submenu
|
||||
// Press command key → Executes command and closes
|
||||
// Press ESC → Go back or close
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Fixed bottom bar (150px height)
|
||||
- Color-coded categories
|
||||
- Breadcrumb navigation ("Space > w")
|
||||
- Auto-close after 5 seconds of inactivity
|
||||
|
||||
**Integration:**
|
||||
```cpp
|
||||
command_manager_.RegisterPrefix("w", 'w', "Window", "Window management");
|
||||
command_manager_.RegisterSubcommand("w", "w.s", 's', "Show All", "Show all windows",
|
||||
[this]() { workspace_manager_.ShowAllWindows(); });
|
||||
```
|
||||
|
||||
## 7. Begin/End Patterns
|
||||
|
||||
### Philosophy
|
||||
|
||||
@@ -451,7 +582,29 @@ struct ScopedCard {
|
||||
};
|
||||
```
|
||||
|
||||
## 6. Layout Helpers
|
||||
## 8. Currently Integrated Editors
|
||||
|
||||
The card system is integrated across 11 of 13 editors:
|
||||
|
||||
| Editor | Cards | Status |
|
||||
|--------|-------|--------|
|
||||
| **DungeonEditorV2** | Room selector, canvas, object selector, object editor, entrance editor, tile painter, sprite placer | Complete |
|
||||
| **PaletteEditor** | Group editor, animation editor, color picker | Complete |
|
||||
| **GraphicsEditor** | Sheet editor, browser, player animations, prototype viewer | Complete |
|
||||
| **ScreenEditor** | Dungeon maps, inventory, overworld map, title screen, naming screen | Complete |
|
||||
| **SpriteEditor** | Vanilla sprites, custom sprites | Complete |
|
||||
| **OverworldEditor** | Canvas, tile16/tile8 selectors, area graphics, scratch workspace, GFX groups, usage stats, properties, exits, items, sprites, settings | Complete |
|
||||
| **MessageEditor** | Message list, editor, font atlas, dictionary | Complete |
|
||||
| **HexEditor** | Hex editor with comparison | Complete |
|
||||
| **AssemblyEditor** | Assembly editor, file browser | Complete |
|
||||
| **MusicEditor** | Music tracker, instrument editor, assembly view | Complete |
|
||||
| **Emulator** | CPU debugger, PPU viewer, memory viewer, breakpoints, performance, AI agent, save states, keyboard config, APU debugger, audio mixer | Complete |
|
||||
|
||||
**Not Yet Ported:**
|
||||
- **SettingsEditor** - Monolithic settings window, low usage frequency
|
||||
- **AgentEditor** - Complex AI agent UI, under active development
|
||||
|
||||
## 9. Layout Helpers
|
||||
|
||||
### Overview
|
||||
|
||||
@@ -460,7 +613,7 @@ struct ScopedCard {
|
||||
### Standard Input Widths
|
||||
|
||||
```cpp
|
||||
#include "app/gui/layout_helpers.h"
|
||||
#include "app/gui/core/layout_helpers.h"
|
||||
|
||||
using gui::LayoutHelpers;
|
||||
|
||||
@@ -538,149 +691,50 @@ if (ImGui::BeginTable("##Grid", 2, ImGuiTableFlags_SizingStretchSame)) {
|
||||
}
|
||||
```
|
||||
|
||||
## 7. Future Editor Improvements
|
||||
## 10. Workspace Management
|
||||
|
||||
This section outlines specific improvements needed for each editor to achieve GUI consistency.
|
||||
The workspace manager provides comprehensive window and layout operations:
|
||||
|
||||
### Graphics Editor
|
||||
**Window Management:**
|
||||
- `ShowAllWindows() / HideAllWindows()` - via EditorCardManager
|
||||
- `MaximizeCurrentWindow()` - Dock to central node
|
||||
- `RestoreAllWindows()` - Reset window sizes
|
||||
- `CloseAllFloatingWindows()` - Close undocked windows
|
||||
|
||||
**Current State:** Tab-based UI with multiple editing modes mixed together
|
||||
**Window Navigation:**
|
||||
- `FocusNextWindow() / FocusPreviousWindow()` - Window cycling
|
||||
- `SplitWindowHorizontal() / SplitWindowVertical()` - Split current window
|
||||
- `CloseCurrentWindow()` - Close focused window
|
||||
|
||||
**Needed Improvements:**
|
||||
1. Remove tab-based UI
|
||||
2. Create independent cards:
|
||||
- `GraphicsSheetCard` - Sheet selection and editing
|
||||
- `TitleScreenCard` - Title screen graphics editor
|
||||
- `PaletteEditCard` - Integrated palette editing
|
||||
- `SheetPropertiesCard` - Sheet metadata and properties
|
||||
3. Register all cards with `EditorCardManager`
|
||||
4. Add `Toolset` for mode switching (Draw/Erase/Select)
|
||||
5. Implement keyboard shortcuts:
|
||||
- `Ctrl+Shift+G` - Graphics Control Panel
|
||||
- `Ctrl+Alt+1` - Graphics Sheets
|
||||
- `Ctrl+Alt+2` - Title Screen
|
||||
- `Ctrl+Alt+3` - Palette Editor
|
||||
- `Ctrl+Alt+4` - Sheet Properties
|
||||
|
||||
**Migration Steps:**
|
||||
**Command Integration:**
|
||||
```cpp
|
||||
// 1. Add visibility flags
|
||||
bool show_control_panel_ = true;
|
||||
bool show_graphics_sheets_ = false;
|
||||
bool show_title_screen_ = false;
|
||||
bool show_palette_editor_ = false;
|
||||
|
||||
// 2. Register in Initialize()
|
||||
void GraphicsEditor::Initialize() {
|
||||
auto& card_manager = gui::EditorCardManager::Get();
|
||||
|
||||
card_manager.RegisterCard({
|
||||
.card_id = "graphics.control_panel",
|
||||
.display_name = "Graphics Controls",
|
||||
.icon = ICON_MD_IMAGE,
|
||||
.category = "Graphics",
|
||||
.shortcut_hint = "Ctrl+Shift+G",
|
||||
.visibility_flag = &show_control_panel_,
|
||||
.priority = 10
|
||||
});
|
||||
// Register other cards...
|
||||
}
|
||||
|
||||
// 3. Create card classes
|
||||
class GraphicsSheetCard {
|
||||
public:
|
||||
void Draw();
|
||||
// ...
|
||||
};
|
||||
|
||||
// 4. Update Update() method to draw cards
|
||||
absl::Status GraphicsEditor::Update() {
|
||||
if (show_control_panel_) {
|
||||
DrawControlPanel();
|
||||
}
|
||||
|
||||
if (show_graphics_sheets_) {
|
||||
DrawGraphicsSheetsCard();
|
||||
}
|
||||
// Draw other cards...
|
||||
|
||||
return absl::OkStatus();
|
||||
}
|
||||
workspace_manager_.ExecuteWorkspaceCommand(command_id);
|
||||
// Supports: w.s (show all), w.h (hide all), l.s (save layout), etc.
|
||||
```
|
||||
|
||||
### Sprite Editor
|
||||
## 11. Future Editor Improvements
|
||||
|
||||
**Current State:** Mixed UI with embedded viewers
|
||||
This section outlines remaining improvements for editors not yet fully integrated.
|
||||
|
||||
**Needed Improvements:**
|
||||
1. Convert to card-based architecture
|
||||
2. Create independent cards:
|
||||
- `SpriteListCard` - Searchable sprite list
|
||||
- `SpritePropertiesCard` - Sprite properties editor
|
||||
- `SpritePreviewCard` - Visual sprite preview
|
||||
- `SpriteAnimationCard` - Animation frame editor
|
||||
3. Add `Toolset` with sprite type filters
|
||||
4. Implement keyboard shortcuts:
|
||||
- `Ctrl+Shift+S` - Sprite Control Panel
|
||||
- `Ctrl+Alt+1` - Sprite List
|
||||
- `Ctrl+Alt+2` - Sprite Properties
|
||||
- `Ctrl+Alt+3` - Preview Window
|
||||
- `Ctrl+Alt+4` - Animation Editor
|
||||
### SettingsEditor
|
||||
|
||||
### Message Editor
|
||||
**Current State:** Monolithic settings window
|
||||
|
||||
**Current State:** Partially card-based, needs consistency
|
||||
**Potential Improvements:**
|
||||
1. Split into categorized cards
|
||||
2. Register with EditorCardManager
|
||||
3. Add search/filter functionality
|
||||
|
||||
**Needed Improvements:**
|
||||
1. Unify existing cards with `EditorCardManager`
|
||||
2. Ensure all cards follow Begin/End pattern
|
||||
3. Add keyboard shortcuts:
|
||||
- `Ctrl+Shift+M` - Message Control Panel
|
||||
- `Ctrl+Alt+1` - Message List
|
||||
- `Ctrl+Alt+2` - Message Editor
|
||||
- `Ctrl+Alt+3` - Font Preview
|
||||
4. Replace any hardcoded colors with `Themed*` widgets
|
||||
5. Add `Toolset` for quick message navigation
|
||||
### AgentEditor
|
||||
|
||||
### Music Editor
|
||||
**Current State:** Complex AI agent UI, under active development
|
||||
|
||||
**Current State:** Tracker-based UI, needs modernization
|
||||
**Potential Improvements:**
|
||||
1. Consider card-based refactoring when stable
|
||||
2. Integrate with EditorCardManager
|
||||
3. Add keyboard shortcuts for common operations
|
||||
|
||||
**Needed Improvements:**
|
||||
1. Extract tracker into `TrackerCard`
|
||||
2. Create additional cards:
|
||||
- `InstrumentCard` - Instrument editor
|
||||
- `SequenceCard` - Sequence/pattern editor
|
||||
- `PlaybackCard` - Playback controls and mixer
|
||||
3. Add `Toolset` for playback controls
|
||||
4. Implement keyboard shortcuts:
|
||||
- `Ctrl+Shift+U` - Music Control Panel (U for mUsic)
|
||||
- `Ctrl+Alt+1` - Tracker
|
||||
- `Ctrl+Alt+2` - Instruments
|
||||
- `Ctrl+Alt+3` - Sequences
|
||||
- `Ctrl+Alt+4` - Playback
|
||||
|
||||
### Overworld Editor
|
||||
|
||||
**Current State:** Good modular structure, minor improvements needed
|
||||
|
||||
**Needed Improvements:**
|
||||
1. Verify all property panels use `Themed*` widgets
|
||||
2. Ensure `Toolset` consistency (already has good implementation)
|
||||
3. Document existing keyboard shortcuts in EditorCardManager
|
||||
4. Add minimize-to-icon for control panel
|
||||
5. Consider extracting large panels into separate cards:
|
||||
- `MapPropertiesCard` - Currently inline, could be card
|
||||
- `TileEditCard` - Tile16 editor as independent card
|
||||
|
||||
**Verification Checklist:**
|
||||
- [x] Uses `Toolset` - Yes
|
||||
- [ ] All cards registered with `EditorCardManager` - Needs verification
|
||||
- [ ] No hardcoded colors - Needs audit
|
||||
- [x] Modular entity renderer - Yes
|
||||
- [x] Callback-based communication - Yes
|
||||
|
||||
## 8. Migration Checklist
|
||||
## 12. Migration Checklist
|
||||
|
||||
Use this checklist when converting an editor to the card-based architecture:
|
||||
|
||||
@@ -757,7 +811,7 @@ Use this checklist when converting an editor to the card-based architecture:
|
||||
- [ ] Add example to this guide if pattern is novel
|
||||
- [ ] Update CLAUDE.md if editor behavior changed significantly
|
||||
|
||||
## 9. Code Examples
|
||||
## 13. Code Examples
|
||||
|
||||
### Complete Editor Implementation
|
||||
|
||||
@@ -815,10 +869,10 @@ class MyEditor : public Editor {
|
||||
// my_editor.cc
|
||||
#include "my_editor.h"
|
||||
|
||||
#include "app/gui/editor_card_manager.h"
|
||||
#include "app/gui/editor_layout.h"
|
||||
#include "app/gui/icons.h"
|
||||
#include "app/gui/themed_widgets.h"
|
||||
#include "app/gui/app/editor_card_manager.h"
|
||||
#include "app/gui/app/editor_layout.h"
|
||||
#include "app/gui/core/icons.h"
|
||||
#include "app/gui/core/themed_widgets.h"
|
||||
#include "imgui/imgui.h"
|
||||
|
||||
namespace yaze {
|
||||
@@ -1039,7 +1093,7 @@ void MyEditor::DrawPropertiesCard() {
|
||||
} // namespace yaze
|
||||
```
|
||||
|
||||
## 10. Common Pitfalls
|
||||
## 14. Common Pitfalls
|
||||
|
||||
### 1. Forgetting Bidirectional Visibility Sync
|
||||
|
||||
@@ -1272,3 +1326,7 @@ When adding new editors or refactoring existing ones, refer to:
|
||||
3. **This Guide** - Comprehensive reference for all patterns
|
||||
|
||||
For questions or suggestions about GUI consistency, please open an issue on GitHub or discuss in the development chat.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: October 13, 2025
|
||||
|
||||
@@ -25,29 +25,88 @@ SNES uses 15-bit BGR555 color format:
|
||||
- Each channel: 0-31 (5 bits)
|
||||
- Total possible colors: 32,768
|
||||
|
||||
**Conversion Formulas:**
|
||||
```cpp
|
||||
// From BGR555 to RGB888 (0-255 range)
|
||||
uint8_t red = (snes_color & 0x1F) * 8;
|
||||
uint8_t green = ((snes_color >> 5) & 0x1F) * 8;
|
||||
uint8_t blue = ((snes_color >> 10) & 0x1F) * 8;
|
||||
|
||||
// From RGB888 to BGR555
|
||||
uint16_t snes_color = ((r / 8) & 0x1F) |
|
||||
(((g / 8) & 0x1F) << 5) |
|
||||
(((b / 8) & 0x1F) << 10);
|
||||
```
|
||||
|
||||
#### 16-Color Row Structure
|
||||
|
||||
The SNES organizes palettes in **rows of 16 colors**:
|
||||
- Each row starts with a **transparent color** at indices 0, 16, 32, 48, 64, etc.
|
||||
- Palettes must respect these boundaries for proper display
|
||||
- Multiple sub-palettes can share a row if they're 8 colors or less
|
||||
|
||||
#### Palette Groups
|
||||
|
||||
**Dungeon Palettes** (0xDD734):
|
||||
- 20 palettes × 90 colors each
|
||||
- Structure: 5 full rows (0-79) + 10 colors (80-89)
|
||||
- Transparent at: indices 0, 16, 32, 48, 64
|
||||
- Distributed as: BG1 colors, BG2 colors, sprite colors
|
||||
- Applied per-room via palette ID
|
||||
|
||||
**Overworld Palettes**:
|
||||
- Main: 35 colors per palette (0xDE6C8)
|
||||
- Structure: 2 full rows (0-15, 16-31) + 3 colors (32-34)
|
||||
- Transparent at: 0, 16
|
||||
- Auxiliary: 21 colors per palette (0xDE86C)
|
||||
- Structure: 1 full row (0-15) + 5 colors (16-20)
|
||||
- Transparent at: 0
|
||||
- Animated: 7 colors per palette (0xDE604)
|
||||
- Overlay palette (no transparent)
|
||||
|
||||
**Sprite Palettes**:
|
||||
- Global sprites: 60 colors (0xDD308)
|
||||
- Auxiliary 1: 7 colors per palette (0xDD39E)
|
||||
- Auxiliary 2: 7 colors per palette (0xDD446)
|
||||
- Auxiliary 3: 7 colors per palette (0xDD4E0)
|
||||
- Global sprites: 2 palettes of 60 colors each
|
||||
- Light World: 0xDD218
|
||||
- Dark World: 0xDD290
|
||||
- Structure: 4 rows per set (0-15, 16-31, 32-47, 48-59)
|
||||
- Transparent at: 0, 16, 32, 48
|
||||
- Auxiliary 1: 12 palettes × 7 colors (0xDD39E)
|
||||
- Auxiliary 2: 11 palettes × 7 colors (0xDD446)
|
||||
- Auxiliary 3: 24 palettes × 7 colors (0xDD4E0)
|
||||
- Note: Aux palettes store 7 colors; transparent added at runtime
|
||||
|
||||
**Other Palettes**:
|
||||
- HUD: 32 colors per palette (0xDD218)
|
||||
- Armors: 15 colors per palette (0xDD630)
|
||||
- Swords: 3 colors per palette
|
||||
- Shields: 4 colors per palette
|
||||
- HUD: 2 palettes × 32 colors (0xDD218)
|
||||
- Structure: 2 full rows (0-15, 16-31)
|
||||
- Transparent at: 0, 16
|
||||
- Armors: 5 palettes × 15 colors (0xDD630)
|
||||
- 15 colors + transparent at runtime = full 16-color row
|
||||
- Swords: 4 palettes × 3 colors (overlay, no transparent)
|
||||
- Shields: 3 palettes × 4 colors (overlay, no transparent)
|
||||
- Grass: 3 individual hardcoded colors (LW, DW, Special)
|
||||
- 3D Objects: 2 palettes × 8 colors (Triforce, Crystal)
|
||||
- Overworld Mini Map: 2 palettes × 128 colors
|
||||
- Structure: 8 full rows (0-127)
|
||||
- Transparent at: 0, 16, 32, 48, 64, 80, 96, 112
|
||||
|
||||
#### Palette Application to Graphics
|
||||
|
||||
**8-Color Sub-Palettes:**
|
||||
- Index 0: Transparent (not rendered)
|
||||
- Indices 1-7: Visible colors
|
||||
- Each tile/sprite references a specific 8-color sub-palette
|
||||
|
||||
**Graphics Format:**
|
||||
- 2BPP: 4 colors per tile (uses indices 0-3)
|
||||
- 3BPP: 8 colors per tile (uses indices 0-7)
|
||||
- 4BPP: 16 colors per tile (uses indices 0-15)
|
||||
|
||||
**Rendering Process:**
|
||||
1. Load compressed graphics sheet from ROM
|
||||
2. Decompress and convert to indexed pixels (values 0-7 for 3BPP)
|
||||
3. Select appropriate palette group for room/area
|
||||
4. Map pixel indices to actual colors from palette
|
||||
5. Upload to GPU texture
|
||||
|
||||
## Dungeon System
|
||||
|
||||
@@ -198,5 +257,5 @@ Tile Data:
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: October 9, 2025
|
||||
**Last Updated**: October 13, 2025
|
||||
|
||||
|
||||
@@ -3,52 +3,60 @@
|
||||
Welcome to the official documentation for yaze, a comprehensive ROM editor for The Legend of Zelda: A Link to the Past.
|
||||
|
||||
## A: Getting Started & Testing
|
||||
- [A1: Getting Started](A1-getting-started.md) - Basic setup and usage.
|
||||
- [A2: Testing Guide](A1-testing-guide.md) - The testing framework and best practices.
|
||||
- [A1: Getting Started](A1-getting-started.md) - Basic setup and usage
|
||||
- [A1: Testing Guide](A1-testing-guide.md) - Testing framework and best practices
|
||||
- [A2: Test Dashboard Refactoring](A2-test-dashboard-refactoring.md) - In-app test dashboard architecture
|
||||
|
||||
## B: Build & Platform
|
||||
- [B1: Build Instructions](B1-build-instructions.md) - How to build yaze on Windows, macOS, and Linux.
|
||||
- [B2: Platform Compatibility](B2-platform-compatibility.md) - Cross-platform support details.
|
||||
- [B3: Build Presets](B3-build-presets.md) - A guide to the CMake preset system.
|
||||
- [B4: Git Workflow](B4-git-workflow.md) - Branching strategy, commit conventions, and release process.
|
||||
- [B5: Architecture and Networking](B5-architecture-and-networking.md) - System architecture, gRPC, and networking.
|
||||
- [B1: Build Instructions](B1-build-instructions.md) - How to build yaze on Windows, macOS, and Linux
|
||||
- [B2: Platform Compatibility](B2-platform-compatibility.md) - Cross-platform support details
|
||||
- [B3: Build Presets](B3-build-presets.md) - CMake preset system guide
|
||||
- [B4: Git Workflow](B4-git-workflow.md) - Branching strategy, commit conventions, and release process
|
||||
- [B5: Architecture and Networking](B5-architecture-and-networking.md) - System architecture, gRPC, and networking
|
||||
- [B6: Zelda3 Library Refactoring](B6-zelda3-library-refactoring.md) - Core library modularization plan
|
||||
|
||||
## C: `z3ed` CLI
|
||||
- [C1: `z3ed` Agent Guide](C1-z3ed-agent-guide.md) - The AI-powered command-line interface.
|
||||
- [C2: Testing Without ROMs](C2-testing-without-roms.md) - Using mock ROM mode for testing and CI/CD.
|
||||
- [C1: `z3ed` Agent Guide](C1-z3ed-agent-guide.md) - AI-powered command-line interface
|
||||
- [C2: Testing Without ROMs](C2-testing-without-roms.md) - Mock ROM mode for testing and CI/CD
|
||||
- [C3: Agent Architecture](C3-agent-architecture.md) - AI agent system architecture
|
||||
- [C4: z3ed Refactoring](C4-z3ed-refactoring.md) - CLI tool refactoring summary
|
||||
- [C5: z3ed Command Abstraction](C5-z3ed-command-abstraction.md) - Command system design
|
||||
|
||||
## E: Development & API
|
||||
- [E1: Assembly Style Guide](E1-asm-style-guide.md) - 65816 assembly coding standards.
|
||||
- [E2: Development Guide](E2-development-guide.md) - Core architectural patterns, UI systems, and best practices.
|
||||
- [E3: API Reference](E3-api-reference.md) - C/C++ API documentation for extensions.
|
||||
- [E4: Emulator Development Guide](E4-Emulator-Development-Guide.md) - SNES emulator subsystem implementation guide.
|
||||
- [E5: Debugging Guide](E5-debugging-guide.md) - Debugging techniques and workflows.
|
||||
- [E6: Emulator Improvements](E6-emulator-improvements.md) - Core accuracy and performance improvements roadmap.
|
||||
- [E7: Debugging Startup Flags](E7-debugging-startup-flags.md) - CLI flags for quick editor access and testing.
|
||||
- [E8: Emulator Debugging Vision](E8-emulator-debugging-vision.md) - Long-term vision for Mesen2-level debugging features.
|
||||
- [E1: Assembly Style Guide](E1-asm-style-guide.md) - 65816 assembly coding standards
|
||||
- [E2: Development Guide](E2-development-guide.md) - Core architectural patterns, UI systems, and best practices
|
||||
- [E3: API Reference](E3-api-reference.md) - C/C++ API documentation for extensions
|
||||
- [E4: Emulator Development Guide](E4-Emulator-Development-Guide.md) - SNES emulator subsystem implementation guide
|
||||
- [E5: Debugging Guide](E5-debugging-guide.md) - Debugging techniques and workflows
|
||||
- [E6: Emulator Improvements](E6-emulator-improvements.md) - Core accuracy and performance improvements roadmap
|
||||
- [E7: Debugging Startup Flags](E7-debugging-startup-flags.md) - CLI flags for quick editor access and testing
|
||||
- [E8: Emulator Debugging Vision](E8-emulator-debugging-vision.md) - Long-term vision for Mesen2-level debugging features
|
||||
- [E9: AI Agent Debugging Guide](E9-ai-agent-debugging-guide.md) - Debugging AI agent integration
|
||||
- [E10: APU Timing Analysis](E10-apu-timing-analysis.md) - APU timing fix technical analysis
|
||||
|
||||
## F: Technical Documentation
|
||||
- [F1: Dungeon Editor Guide](F1-dungeon-editor-guide.md) - Master guide to the dungeon editing system.
|
||||
- [F2: Tile16 Editor Palette System](F2-tile16-editor-palette-system.md) - Design of the palette system.
|
||||
- [F3: Overworld Loading](F3-overworld-loading.md) - How vanilla and ZSCustomOverworld maps are loaded.
|
||||
- [F4: Overworld Agent Guide](F4-overworld-agent-guide.md) - AI agent integration for overworld editing.
|
||||
- [F1: Dungeon Editor Guide](F1-dungeon-editor-guide.md) - Master guide to the dungeon editing system
|
||||
- [F2: Tile16 Editor Palette System](F2-tile16-editor-palette-system.md) - Design of the palette system
|
||||
- [F3: Overworld Loading](F3-overworld-loading.md) - How vanilla and ZSCustomOverworld maps are loaded
|
||||
- [F4: Overworld Agent Guide](F4-overworld-agent-guide.md) - AI agent integration for overworld editing
|
||||
|
||||
## G: Graphics & GUI Systems
|
||||
- [G1: Canvas System and Automation](G1-canvas-guide.md) - The core GUI drawing and interaction system.
|
||||
- [G2: Renderer Migration Plan](G2-renderer-migration-plan.md) - Historical plan for renderer refactoring.
|
||||
- [G3: Palette System Overview](G3-palete-system-overview.md) - SNES palette system and editor integration.
|
||||
- [G3: Renderer Migration Complete](G3-renderer-migration-complete.md) - Post-migration analysis and results.
|
||||
- [G4: Canvas Coordinate Fix](G4-canvas-coordinate-fix.md) - Technical deep-dive on canvas coordinate synchronization bug fix.
|
||||
- [G1: Canvas System and Automation](G1-canvas-guide.md) - Core GUI drawing and interaction system
|
||||
- [G2: Renderer Migration Plan](G2-renderer-migration-plan.md) - Historical plan for renderer refactoring
|
||||
- [G3: Palette System Overview](G3-palete-system-overview.md) - SNES palette system and editor integration
|
||||
- [G3: Renderer Migration Complete](G3-renderer-migration-complete.md) - Post-migration analysis and results
|
||||
- [G4: Canvas Coordinate Fix](G4-canvas-coordinate-fix.md) - Canvas coordinate synchronization bug fix
|
||||
- [G5: GUI Consistency Guide](G5-gui-consistency-guide.md) - Card-based architecture and UI standards
|
||||
|
||||
## H: Project Info
|
||||
- [H1: Changelog](H1-changelog.md)
|
||||
|
||||
## I: Roadmap & Vision
|
||||
- [I1: Roadmap](I1-roadmap.md) - Current development roadmap and planned releases.
|
||||
- [I2: Future Improvements](I2-future-improvements.md) - Long-term vision and aspirational features.
|
||||
- [I1: Roadmap](I1-roadmap.md) - Current development roadmap and planned releases
|
||||
- [I2: Future Improvements](I2-future-improvements.md) - Long-term vision and aspirational features
|
||||
|
||||
## R: ROM Reference
|
||||
- [R1: A Link to the Past ROM Reference](R1-alttp-rom-reference.md) - Technical reference for ALTTP ROM structures, graphics, palettes, and compression.
|
||||
- [R1: A Link to the Past ROM Reference](R1-alttp-rom-reference.md) - ALTTP ROM structures, graphics, palettes, and compression
|
||||
|
||||
---
|
||||
|
||||
@@ -70,6 +78,13 @@ Welcome to the official documentation for yaze, a comprehensive ROM editor for T
|
||||
- Prefix with series letter and number (e.g., `E4-emulator-development-guide.md`)
|
||||
- Keep filenames concise but clear
|
||||
|
||||
### Organization Tips
|
||||
For Doxygen integration, this index can be enhanced with:
|
||||
- `@mainpage` directive to make this the main documentation page
|
||||
- `@defgroup` to create logical groupings across files
|
||||
- `@tableofcontents` for automatic TOC generation
|
||||
- See individual files for `@page` and `@section` usage
|
||||
|
||||
---
|
||||
|
||||
*Last updated: October 10, 2025 - Version 0.3.2 (Preparing for Release)*
|
||||
*Last updated: October 13, 2025 - Version 0.3.2*
|
||||
Reference in New Issue
Block a user