From 8a839ba56745a3601f25cb3dd66b3f1ddf553fab Mon Sep 17 00:00:00 2001 From: scawful Date: Fri, 7 Nov 2025 08:59:11 -0500 Subject: [PATCH] docs: reorganize documentation layout --- .github/workflows/doxy.yml | 6 +- Doxyfile | 18 +- README.md | 174 ++---- docs/index.md | 109 +--- docs/internal/README.md | 15 + .../agents/agent-architecture.md} | 0 .../agents/ai-agent-debugging-guide.md} | 0 .../agents/overworld-agent-guide.md} | 0 .../agents/z3ed-command-abstraction.md} | 0 .../agents/z3ed-refactoring.md} | 0 .../blueprints/architecture-refactor-plan.md} | 0 .../editor-manager-architecture.md} | 0 .../renderer-migration-complete.md} | 0 .../blueprints/renderer-migration-plan.md} | 0 .../blueprints/test-dashboard-refactor.md} | 0 .../blueprints/zelda3-library-refactor.md} | 0 docs/{ => internal/legacy}/BUILD-GUIDE.md | 0 docs/{ => internal/legacy}/BUILD.md | 0 .../research/apu-timing-analysis.md} | 0 .../research/emulator-debugging-vision.md} | 0 .../research/emulator-improvements.md} | 0 docs/{ => internal/research}/web-ideas.md | 0 docs/{ => internal/research}/yaze.org | 0 .../code-review-critical-next-steps.md | 573 ++++++++++++++++++ .../roadmaps/feature-parity-analysis.md} | 0 .../roadmaps/future-improvements.md} | 0 .../roadmaps/roadmap.md} | 0 .../build/build-from-source.md} | 6 +- .../build/platform-compatibility.md} | 0 .../build/presets.md} | 0 .../build/troubleshooting.md} | 0 .../developer/api-reference.md} | 0 .../developer/architecture.md} | 2 +- .../developer/asm-style-guide.md} | 0 .../developer/canvas-system.md} | 0 .../developer/debug-flags.md} | 0 .../developer/debugging-guide.md} | 2 +- .../developer/dependency-architecture.md} | 24 +- .../developer/emulator-development-guide.md} | 0 .../developer/git-workflow.md} | 3 +- .../developer/gui-consistency-guide.md} | 2 +- .../developer/networking.md} | 0 .../developer/overworld-entity-system.md} | 0 .../developer/palette-system-overview.md} | 0 .../developer/testing-guide.md} | 0 .../developer/testing-without-roms.md} | 6 +- .../developer/tile16-palette-system.md} | 0 docs/public/index.md | 52 ++ .../overview/getting-started.md} | 0 .../reference/changelog.md} | 0 .../reference/rom-reference.md} | 0 .../usage/dungeon-editor.md} | 9 +- .../usage/overworld-loading.md} | 2 +- .../usage/z3ed-cli.md} | 6 +- 54 files changed, 755 insertions(+), 254 deletions(-) create mode 100644 docs/internal/README.md rename docs/{C3-agent-architecture.md => internal/agents/agent-architecture.md} (100%) rename docs/{E9-ai-agent-debugging-guide.md => internal/agents/ai-agent-debugging-guide.md} (100%) rename docs/{F4-overworld-agent-guide.md => internal/agents/overworld-agent-guide.md} (100%) rename docs/{C5-z3ed-command-abstraction.md => internal/agents/z3ed-command-abstraction.md} (100%) rename docs/{C4-z3ed-refactoring.md => internal/agents/z3ed-refactoring.md} (100%) rename docs/{B7-architecture-refactoring-plan.md => internal/blueprints/architecture-refactor-plan.md} (100%) rename docs/{H2-editor-manager-architecture.md => internal/blueprints/editor-manager-architecture.md} (100%) rename docs/{G3-renderer-migration-complete.md => internal/blueprints/renderer-migration-complete.md} (100%) rename docs/{G2-renderer-migration-plan.md => internal/blueprints/renderer-migration-plan.md} (100%) rename docs/{A2-test-dashboard-refactoring.md => internal/blueprints/test-dashboard-refactor.md} (100%) rename docs/{B6-zelda3-library-refactoring.md => internal/blueprints/zelda3-library-refactor.md} (100%) rename docs/{ => internal/legacy}/BUILD-GUIDE.md (100%) rename docs/{ => internal/legacy}/BUILD.md (100%) rename docs/{E10-apu-timing-analysis.md => internal/research/apu-timing-analysis.md} (100%) rename docs/{E8-emulator-debugging-vision.md => internal/research/emulator-debugging-vision.md} (100%) rename docs/{E6-emulator-improvements.md => internal/research/emulator-improvements.md} (100%) rename docs/{ => internal/research}/web-ideas.md (100%) rename docs/{ => internal/research}/yaze.org (100%) create mode 100644 docs/internal/roadmaps/code-review-critical-next-steps.md rename docs/{H3-feature-parity-analysis.md => internal/roadmaps/feature-parity-analysis.md} (100%) rename docs/{I2-future-improvements.md => internal/roadmaps/future-improvements.md} (100%) rename docs/{I1-roadmap.md => internal/roadmaps/roadmap.md} (100%) rename docs/{B1-build-instructions.md => public/build/build-from-source.md} (98%) rename docs/{B2-platform-compatibility.md => public/build/platform-compatibility.md} (100%) rename docs/{B3-build-presets.md => public/build/presets.md} (100%) rename docs/{BUILD-TROUBLESHOOTING.md => public/build/troubleshooting.md} (100%) rename docs/{E3-api-reference.md => public/developer/api-reference.md} (100%) rename docs/{E2-development-guide.md => public/developer/architecture.md} (99%) rename docs/{E1-asm-style-guide.md => public/developer/asm-style-guide.md} (100%) rename docs/{G1-canvas-guide.md => public/developer/canvas-system.md} (100%) rename docs/{E7-debugging-startup-flags.md => public/developer/debug-flags.md} (100%) rename docs/{E5-debugging-guide.md => public/developer/debugging-guide.md} (99%) rename docs/{A1-yaze-dependency-architecture.md => public/developer/dependency-architecture.md} (98%) rename docs/{E4-Emulator-Development-Guide.md => public/developer/emulator-development-guide.md} (100%) rename docs/{B4-git-workflow.md => public/developer/git-workflow.md} (99%) rename docs/{G5-gui-consistency-guide.md => public/developer/gui-consistency-guide.md} (99%) rename docs/{B5-architecture-and-networking.md => public/developer/networking.md} (100%) rename docs/{F5-overworld-entity-system.md => public/developer/overworld-entity-system.md} (100%) rename docs/{G3-palete-system-overview.md => public/developer/palette-system-overview.md} (100%) rename docs/{A1-testing-guide.md => public/developer/testing-guide.md} (100%) rename docs/{C2-testing-without-roms.md => public/developer/testing-without-roms.md} (97%) rename docs/{F2-tile16-editor-palette-system.md => public/developer/tile16-palette-system.md} (100%) create mode 100644 docs/public/index.md rename docs/{A1-getting-started.md => public/overview/getting-started.md} (100%) rename docs/{H1-changelog.md => public/reference/changelog.md} (100%) rename docs/{R1-alttp-rom-reference.md => public/reference/rom-reference.md} (100%) rename docs/{F1-dungeon-editor-guide.md => public/usage/dungeon-editor.md} (95%) rename docs/{F3-overworld-loading.md => public/usage/overworld-loading.md} (99%) rename docs/{C1-z3ed-agent-guide.md => public/usage/z3ed-cli.md} (99%) diff --git a/.github/workflows/doxy.yml b/.github/workflows/doxy.yml index cfb87133..caafc7d4 100644 --- a/.github/workflows/doxy.yml +++ b/.github/workflows/doxy.yml @@ -54,7 +54,7 @@ jobs: - name: Clean previous build if: steps.changes.outputs.docs_changed == 'true' - run: rm -rf html + run: rm -rf build/docs - name: Generate Doxygen documentation if: steps.changes.outputs.docs_changed == 'true' @@ -68,7 +68,7 @@ jobs: uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./html + publish_dir: ./build/docs/html commit_message: 'docs: update API documentation' - name: Summary @@ -78,4 +78,4 @@ jobs: echo "πŸ“– View at: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}" else echo "⏭️ Documentation build skipped - no relevant changes detected" - fi \ No newline at end of file + fi diff --git a/Doxyfile b/Doxyfile index 4193163b..86370024 100644 --- a/Doxyfile +++ b/Doxyfile @@ -74,7 +74,7 @@ PROJECT_ICON = "assets/yaze.ico" # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = +OUTPUT_DIRECTORY = build/docs # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096 # sub-directories (in 2 levels) under the output directory of each output format @@ -949,7 +949,9 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = +INPUT = docs/public \ + src \ + incl # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -1055,10 +1057,12 @@ RECURSIVE = YES # run. EXCLUDE = assets/ \ - build/ \ - cmake/ \ - docs/archive/ \ - src/lib/ \ + build/ \ + cmake/ \ + docs/html/ \ + docs/latex/ \ + docs/internal/ \ + src/lib/ # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -1169,7 +1173,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = getting-started.md +USE_MDFILE_AS_MAINPAGE = docs/public/index.md # The Fortran standard specifies that for fixed formatted Fortran code all # characters from position 72 are to be considered as comment. A common diff --git a/README.md b/README.md index 567709f6..11394b65 100644 --- a/README.md +++ b/README.md @@ -4,139 +4,93 @@ [![Code Quality](https://github.com/scawful/yaze/workflows/Code%20Quality/badge.svg)](https://github.com/scawful/yaze/actions) [![Security](https://github.com/scawful/yaze/workflows/Security%20Scanning/badge.svg)](https://github.com/scawful/yaze/actions) [![Release](https://github.com/scawful/yaze/workflows/Release/badge.svg)](https://github.com/scawful/yaze/actions) -[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +[![License](https://img.shields.io/badge/license-GPLv3-blue.svg)](LICENSE) -A modern, cross-platform editor for The Legend of Zelda: A Link to the Past ROM hacking, built with C++20 and featuring complete Asar 65816 assembler integration. +A cross-platform Zelda 3 ROM editor with a modern C++ GUI, Asar 65816 assembler integration, and an automation-friendly CLI (`z3ed`). YAZE bundles its toolchain, offers AI-assisted editing flows, and targets reproducible builds on Windows, macOS, and Linux. -## Version 0.3.2 - Release +## Highlights +- **All-in-one editing**: Overworld, dungeon, sprite, palette, and messaging tools with live previews. +- **Assembler-first workflow**: Built-in Asar integration, symbol extraction, and patch validation. +- **Automation & AI**: `z3ed` exposes CLI/TUI automation, proposal workflows, and optional AI agents. +- **Testing & CI hooks**: CMake presets, ROM-less test fixtures, and gRPC-based GUI automation support. +- **Cross-platform toolchains**: Single source tree targeting MSVC, Clang, and GCC with identical presets. -#### z3ed agent - AI-powered CLI assistant -- **AI-assisted ROM hacking** with ollama and Gemini support -- **Natural language commands** for editing and querying ROM data -- **Tool calling** for structured data extraction and modification -- **Interactive chat** with conversation history and context - -#### ZSCustomOverworld v3 -- **Enhanced overworld editing** capabilities -- **Advanced map properties** and metadata support -- **Custom graphics support** and tile management -- **Improved compatibility** with existing projects - -#### Asar 65816 Assembler Integration -- **Cross-platform ROM patching** with assembly code support -- **Symbol extraction** with addresses and opcodes from assembly files -- **Assembly validation** with comprehensive error reporting -- **Modern C++ API** with safe memory management - -#### Advanced Features -- **Theme Management**: Complete theme system with 5+ built-in themes and custom theme editor -- **Multi-Session Support**: Work with multiple ROMs simultaneously in docked workspace -- **Enhanced Welcome Screen**: Themed interface with quick access to all editors -- **Message Editing**: Enhanced text editing interface with real-time preview -- **GUI Docking**: Flexible workspace management with customizable layouts -- **Modern CLI**: Enhanced z3ed tool with interactive TUI and subcommands -- **Cross-Platform**: Full support for Windows, macOS, and Linux +## Project Status +`0.3.x` builds are in active development. Release automation is being reworked, so packaged builds may lag behind main. Follow `develop` for the most accurate view of current functionality. ## Quick Start -### Build +### Clone & Bootstrap ```bash -# Clone with submodules git clone --recursive https://github.com/scawful/yaze.git cd yaze - -# Build with CMake -cmake --preset debug # macOS -cmake -B build && cmake --build build # Linux/Windows - -# Windows-specific -scripts\verify-build-environment.ps1 # Verify your setup -cmake --preset windows-debug # Basic build -cmake --preset windows-ai-debug # With AI features -cmake --build build --config Debug # Build ``` -### Applications -- **yaze**: Complete GUI editor for Zelda 3 ROM hacking -- **z3ed**: Command-line tool with interactive interface -- **yaze_test**: Comprehensive test suite for development - -## Usage - -### GUI Editor -Launch the main application to edit Zelda 3 ROMs: -- Load ROM files using native file dialogs -- Edit overworld maps, dungeons, sprites, and graphics -- Apply assembly patches with integrated Asar support -- Export modifications as patches or modified ROMs - -### Command Line Tool +Run the environment verifier once per machine: ```bash -# Apply assembly patch -z3ed asar patch.asm --rom=zelda3.sfc +# macOS / Linux +./scripts/verify-build-environment.sh --fix -# Extract symbols from assembly -z3ed extract patch.asm - -# Interactive mode -z3ed --tui +# Windows (PowerShell) +.\scripts\verify-build-environment.ps1 -FixIssues ``` -### C++ API -```cpp -#include "yaze.h" +### Configure & Build +```bash +# macOS +cmake --preset mac-dbg +cmake --build --preset mac-dbg -// Load ROM and apply patch -yaze_project_t* project = yaze_load_project("zelda3.sfc"); -yaze_apply_asar_patch(project, "patch.asm"); -yaze_save_project(project, "modified.sfc"); +# Linux +cmake --preset lin-dbg +cmake --build --preset lin-dbg + +# Windows +cmake --preset win-dbg +cmake --build --preset win-dbg --target yaze + +# Enable AI + gRPC tooling (any platform) +cmake --preset mac-ai +cmake --build --preset mac-ai --target yaze z3ed ``` +## Applications & Workflows +- **`./build/bin/yaze`** – full GUI editor with multi-session dockspace, theming, and ROM patching. +- **`./build/bin/z3ed --tui`** – CLI/TUI companion for scripting, AI-assisted edits, and Asar workflows. +- **`./build_ai/bin/yaze_test --unit|--integration|--e2e`** – structured test runner for quick regression checks. + +Typical commands: +```bash +# Launch GUI with a ROM +./build/bin/yaze zelda3.sfc + +# Apply a patch via CLI +./build/bin/z3ed asar patch.asm --rom zelda3.sfc + +# Run focused tests +cmake --build --preset mac-ai --target yaze_test +./build_ai/bin/yaze_test --unit +``` + +## Testing +- `./build_ai/bin/yaze_test --unit` for fast checks; add `--integration` or `--e2e --show-gui` for broader coverage. +- `ctest --preset dev` mirrors CI’s stable set; `ctest --preset all` runs the full matrix. +- Set `YAZE_TEST_ROM_PATH` or pass `--rom-path` when a test needs a real ROM image. + ## Documentation +- Human-readable docs live under `docs/public/` with an entry point at [`docs/public/index.md`](docs/public/index.md). +- Run `doxygen Doxyfile` to generate API + guide pages (`build/docs/html` and `build/docs/latex`). +- Agent playbooks, architecture notes, and testing recipes now live in [`docs/internal/`](docs/internal/README.md). -- [Getting Started](docs/01-getting-started.md) - Setup and basic usage -- [Build Instructions](docs/02-build-instructions.md) - Building from source -- [API Reference](docs/04-api-reference.md) - Programming interface -- [Contributing](docs/B1-contributing.md) - Development guidelines - -**[Complete Documentation](docs/index.md)** - -## Supported Platforms - -- **Windows** (MSVC 2019+, MinGW) -- **macOS** (Intel and Apple Silicon) -- **Linux** (GCC 13+, Clang 16+) -## ROM Compatibility - -- Original Zelda 3 ROMs (US/Japan versions) -- ZSCustomOverworld v2/v3 enhanced overworld features -- Community ROM hacks and modifications - -## Contributing - -See [Contributing Guide](docs/B1-contributing.md) for development guidelines. - -**Community**: [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk) +## Contributing & Community +- Review [`CONTRIBUTING.md`](CONTRIBUTING.md) and the build/test guides in `docs/public/`. +- Conventional commit messages (`feat:`, `fix:`, etc.) keep history clean; use topic branches for larger work. +- Chat with the team on [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk). ## License +YAZE is licensed under the GNU GPL v3. See [`LICENSE`](LICENSE) for details and third-party notices. -GNU GPL v3 - See [LICENSE](LICENSE) for details. - -## πŸ™ Acknowledgments - -Takes inspiration from: -- [Hyrule Magic](https://www.romhacking.net/utilities/200/) - Original Zelda 3 editor -- [ZScream](https://github.com/Zarby89/ZScreamDungeon) - Dungeon editing capabilities -- [Asar](https://github.com/RPGHacker/asar) - 65816 assembler integration - -## πŸ“Έ Screenshots - +## Screenshots ![YAZE GUI Editor](https://github.com/scawful/yaze/assets/47263509/8b62b142-1de4-4ca4-8c49-d50c08ba4c8e) - ![Dungeon Editor](https://github.com/scawful/yaze/assets/47263509/d8f0039d-d2e4-47d7-b420-554b20ac626f) - ![Overworld Editor](https://github.com/scawful/yaze/assets/47263509/34b36666-cbea-420b-af90-626099470ae4) - ---- - -**Ready to hack Zelda 3? [Get started now!](docs/01-getting-started.md)** \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index d1e90535..592a844f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,104 +1,9 @@ -# yaze Documentation +# Documentation Relocated -Welcome to the official documentation for yaze, a comprehensive ROM editor for The Legend of Zelda: A Link to the Past. +The published documentation now lives under [`docs/public`](public/index.md) so that Doxygen can +focus on the curated guides and references. All planning notes, AI/agent workflows, and research +documents have been moved to the repository-level [`docs/internal/`](../docs/internal/README.md). -## A: Getting Started & Testing -- [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) - 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) - 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 -- [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 - -## G: Graphics & GUI Systems -- [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 - -## R: ROM Reference -- [R1: A Link to the Past ROM Reference](R1-alttp-rom-reference.md) - ALTTP ROM structures, graphics, palettes, and compression - ---- - -## Documentation Standards - -### Naming Convention -- **A-series**: Getting Started & Testing -- **B-series**: Build, Platform & Git Workflow -- **C-series**: CLI Tools (`z3ed`) -- **E-series**: Development, API & Emulator -- **F-series**: Feature-Specific Technical Docs -- **G-series**: Graphics & GUI Systems -- **H-series**: Project Info (Changelog, etc.) -- **I-series**: Roadmap & Vision -- **R-series**: ROM Technical Reference - -### File Naming -- Use descriptive, kebab-case names -- 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 - -### Doxygen Integration Tips -- Add a short `@mainpage` block to `docs/index.md` so generated HTML mirrors the - manual structure. -- Define high-level groups with `@defgroup` (`getting_started`, `building`, - `graphics_gui`, etc.) and attach individual docs using `@page ... @ingroup`. -- Use `@subpage`, `@section`, and `@subsection` when a document benefits from - nested navigation. -- Configure `Doxyfile` with `USE_MDFILE_AS_MAINPAGE = docs/index.md`, - `FILE_PATTERNS = *.md *.h *.cc`, and `EXTENSION_MAPPING = md=C++` to combine - Markdown and source comments. -- Keep Markdown reader-friendlyβ€”wrap Doxygen directives in comment fences (`/**` - … `*/`) so they are ignored by GitHub while remaining visible to the - generator. - ---- - -*Last updated: October 13, 2025 - Version 0.3.2* +Update your bookmarks: +- Public site entry point: [`docs/public/index.md`](public/index.md) +- Internal docs: [`docs/internal/README.md`](../docs/internal/README.md) diff --git a/docs/internal/README.md b/docs/internal/README.md new file mode 100644 index 00000000..a5b0b93a --- /dev/null +++ b/docs/internal/README.md @@ -0,0 +1,15 @@ +# YAZE Handbook + +Internal documentation for planning, AI agents, research, and historical build notes. These +files are intentionally excluded from the public Doxygen site so they can remain verbose and +speculative without impacting the published docs. + +## Sections +- `agents/` – z3ed and AI agent playbooks, command abstractions, and debugging guides. +- `blueprints/` – architectural proposals, refactors, and technical deep dives. +- `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. + +When adding new internal docs, place them under the appropriate subdirectory here instead of +`docs/`. diff --git a/docs/C3-agent-architecture.md b/docs/internal/agents/agent-architecture.md similarity index 100% rename from docs/C3-agent-architecture.md rename to docs/internal/agents/agent-architecture.md diff --git a/docs/E9-ai-agent-debugging-guide.md b/docs/internal/agents/ai-agent-debugging-guide.md similarity index 100% rename from docs/E9-ai-agent-debugging-guide.md rename to docs/internal/agents/ai-agent-debugging-guide.md diff --git a/docs/F4-overworld-agent-guide.md b/docs/internal/agents/overworld-agent-guide.md similarity index 100% rename from docs/F4-overworld-agent-guide.md rename to docs/internal/agents/overworld-agent-guide.md diff --git a/docs/C5-z3ed-command-abstraction.md b/docs/internal/agents/z3ed-command-abstraction.md similarity index 100% rename from docs/C5-z3ed-command-abstraction.md rename to docs/internal/agents/z3ed-command-abstraction.md diff --git a/docs/C4-z3ed-refactoring.md b/docs/internal/agents/z3ed-refactoring.md similarity index 100% rename from docs/C4-z3ed-refactoring.md rename to docs/internal/agents/z3ed-refactoring.md diff --git a/docs/B7-architecture-refactoring-plan.md b/docs/internal/blueprints/architecture-refactor-plan.md similarity index 100% rename from docs/B7-architecture-refactoring-plan.md rename to docs/internal/blueprints/architecture-refactor-plan.md diff --git a/docs/H2-editor-manager-architecture.md b/docs/internal/blueprints/editor-manager-architecture.md similarity index 100% rename from docs/H2-editor-manager-architecture.md rename to docs/internal/blueprints/editor-manager-architecture.md diff --git a/docs/G3-renderer-migration-complete.md b/docs/internal/blueprints/renderer-migration-complete.md similarity index 100% rename from docs/G3-renderer-migration-complete.md rename to docs/internal/blueprints/renderer-migration-complete.md diff --git a/docs/G2-renderer-migration-plan.md b/docs/internal/blueprints/renderer-migration-plan.md similarity index 100% rename from docs/G2-renderer-migration-plan.md rename to docs/internal/blueprints/renderer-migration-plan.md diff --git a/docs/A2-test-dashboard-refactoring.md b/docs/internal/blueprints/test-dashboard-refactor.md similarity index 100% rename from docs/A2-test-dashboard-refactoring.md rename to docs/internal/blueprints/test-dashboard-refactor.md diff --git a/docs/B6-zelda3-library-refactoring.md b/docs/internal/blueprints/zelda3-library-refactor.md similarity index 100% rename from docs/B6-zelda3-library-refactoring.md rename to docs/internal/blueprints/zelda3-library-refactor.md diff --git a/docs/BUILD-GUIDE.md b/docs/internal/legacy/BUILD-GUIDE.md similarity index 100% rename from docs/BUILD-GUIDE.md rename to docs/internal/legacy/BUILD-GUIDE.md diff --git a/docs/BUILD.md b/docs/internal/legacy/BUILD.md similarity index 100% rename from docs/BUILD.md rename to docs/internal/legacy/BUILD.md diff --git a/docs/E10-apu-timing-analysis.md b/docs/internal/research/apu-timing-analysis.md similarity index 100% rename from docs/E10-apu-timing-analysis.md rename to docs/internal/research/apu-timing-analysis.md diff --git a/docs/E8-emulator-debugging-vision.md b/docs/internal/research/emulator-debugging-vision.md similarity index 100% rename from docs/E8-emulator-debugging-vision.md rename to docs/internal/research/emulator-debugging-vision.md diff --git a/docs/E6-emulator-improvements.md b/docs/internal/research/emulator-improvements.md similarity index 100% rename from docs/E6-emulator-improvements.md rename to docs/internal/research/emulator-improvements.md diff --git a/docs/web-ideas.md b/docs/internal/research/web-ideas.md similarity index 100% rename from docs/web-ideas.md rename to docs/internal/research/web-ideas.md diff --git a/docs/yaze.org b/docs/internal/research/yaze.org similarity index 100% rename from docs/yaze.org rename to docs/internal/research/yaze.org diff --git a/docs/internal/roadmaps/code-review-critical-next-steps.md b/docs/internal/roadmaps/code-review-critical-next-steps.md new file mode 100644 index 00000000..0cf3a459 --- /dev/null +++ b/docs/internal/roadmaps/code-review-critical-next-steps.md @@ -0,0 +1,573 @@ +# YAZE Code Review: Critical Next Steps for Release + +**Date**: January 31, 2025 +**Version**: 0.3.2 (Pre-Release) +**Status**: Comprehensive Code Review Complete + +--- + +## Executive Summary + +YAZE is in a strong position for release with **90% feature parity** achieved on the develop branch and significant architectural improvements. However, several **critical issues** and **stability concerns** must be addressed before a stable release can be achieved. + +### Key Metrics +- **Feature Parity**: 90% (develop branch) vs master +- **Code Quality**: 44% reduction in EditorManager code (3710 β†’ 2076 lines) +- **Build Status**: βœ… Compiles successfully on all platforms +- **Test Coverage**: 46+ core tests, E2E framework in place +- **Known Critical Bugs**: 6 high-priority issues +- **Stability Risks**: 3 major areas requiring attention + +--- + +## πŸ”΄ CRITICAL: Must Fix Before Release + +### 1. Tile16 Editor Palette System Issues (Priority: HIGH) + +**Status**: Partially fixed, critical bugs remain + +**Active Issues**: +1. **Tile8 Source Canvas Palette Issues** - Source tiles show incorrect colors +2. **Palette Button Functionality** - Buttons 0-7 don't update palettes correctly +3. **Color Alignment Between Canvases** - Inconsistent colors across canvases + +**Impact**: Blocks proper tile editing workflow, users cannot preview tiles accurately + +**Root Cause**: Area graphics not receiving proper palette application, palette switching logic incomplete + +**Files**: +- `src/app/editor/graphics/tile16_editor.cc` +- `docs/F2-tile16-editor-palette-system.md` + +**Effort**: 4-6 hours +**Risk**: Medium - Core editing functionality affected + +--- + +### 2. Overworld Sprite Movement Bug (Priority: HIGH) + +**Status**: Active bug, blocking sprite editing + +**Issue**: Sprites are not responding to drag operations on overworld canvas + +**Impact**: Blocks sprite editing workflow completely + +**Location**: Overworld canvas interaction system + +**Files**: +- `src/app/editor/overworld/overworld_map.cc` +- `src/app/editor/overworld/overworld_editor.cc` + +**Effort**: 2-4 hours +**Risk**: High - Core feature broken + +--- + +### 3. Canvas Multi-Select Intersection Drawing Bug (Priority: MEDIUM) + +**Status**: Known bug with E2E test coverage + +**Issue**: Selection box rendering incorrect when crossing 512px boundaries + +**Impact**: Selection tool unreliable for large maps + +**Location**: Canvas selection system + +**Test Coverage**: E2E test exists (`canvas_selection_test`) + +**Files**: +- `src/app/gfx/canvas/canvas.cc` +- `test/e2e/canvas_selection_e2e_tests.cc` + +**Effort**: 3-5 hours +**Risk**: Medium - Workflow impact + +--- + +### 4. Emulator Audio System (Priority: CRITICAL) + +**Status**: Audio output broken, investigation needed + +**Issue**: SDL2 audio device initialized but no sound plays + +**Root Cause**: Multiple potential issues: +- Audio buffer size mismatch (fixed in recent changes) +- Format conversion problems (SPC700 β†’ SDL2) +- Device paused state +- APU timing issues (handshake problems identified) + +**Impact**: Core emulator feature non-functional + +**Files**: +- `src/app/emu/emulator.cc` +- `src/app/platform/window.cc` +- `src/app/emu/audio/` (IAudioBackend) +- `docs/E8-emulator-debugging-vision.md` + +**Effort**: 4-6 hours (investigation + fix) +**Risk**: High - Core feature broken + +**Documentation**: Comprehensive debugging guide in `E8-emulator-debugging-vision.md` + +--- + +### 5. Right-Click Context Menu Tile16 Display Bug (Priority: LOW) + +**Status**: Intermittent bug + +**Issue**: Context menu displays abnormally large tile16 preview randomly + +**Impact**: UI polish issue, doesn't block functionality + +**Location**: Right-click context menu + +**Effort**: 2-3 hours +**Risk**: Low - Cosmetic issue + +--- + +### 6. Overworld Map Properties Panel Popup (Priority: MEDIUM) + +**Status**: Display issues + +**Issue**: Modal popup positioning or rendering issues + +**Similar to**: Canvas popup fixes (now resolved) + +**Potential Fix**: Apply same solution as canvas popup refactoring + +**Effort**: 1-2 hours +**Risk**: Low - Can use known fix pattern + +--- + +## 🟑 STABILITY: Critical Areas Requiring Attention + +### 1. EditorManager Refactoring - Manual Testing Required + +**Status**: 90% feature parity achieved, needs validation + +**Critical Gap**: Manual testing phase not completed (2-3 hours planned) + +**Remaining Work**: +- [ ] Test all 34 editor cards open/close properly +- [ ] Verify DockBuilder layouts for all 10 editor types +- [ ] Test all keyboard shortcuts without conflicts +- [ ] Multi-session testing with independent card visibility +- [ ] Verify sidebar collapse/expand (Ctrl+B) + +**Files**: +- `docs/H3-feature-parity-analysis.md` +- `docs/H2-editor-manager-architecture.md` + +**Risk**: Medium - Refactoring may have introduced regressions + +**Recommendation**: Run comprehensive manual testing before release + +--- + +### 2. E2E Test Suite - Needs Updates for New Architecture + +**Status**: Tests exist but need updating + +**Issue**: E2E tests written for old monolithic architecture, new card-based system needs test updates + +**Examples**: +- `dungeon_object_rendering_e2e_tests.cc` - Needs rewrite for DungeonEditorV2 +- Old window references need updating to new card names + +**Files**: +- `test/e2e/dungeon_object_rendering_e2e_tests.cc` +- `test/e2e/dungeon_editor_smoke_test.cc` + +**Effort**: 4-6 hours +**Risk**: Medium - Test coverage gaps + +--- + +### 3. Memory Management & Resource Cleanup + +**Status**: Generally good, but some areas need review + +**Known Issues**: +- βœ… Audio buffer allocation bug fixed (was using single value instead of array) +- βœ… Tile cache `std::move()` issues fixed (SIGBUS errors resolved) +- ⚠️ Slow shutdown noted in `window.cc` (line 146: "TODO: BAD FIX, SLOW SHUTDOWN TAKES TOO LONG NOW") +- ⚠️ Graphics arena shutdown sequence (may need optimization) + +**Files**: +- `src/app/platform/window.cc` (line 146) +- `src/app/gfx/resource/arena.cc` +- `src/app/gfx/resource/memory_pool.cc` + +**Effort**: 2-4 hours (investigation + optimization) +**Risk**: Low-Medium - Performance impact, not crashes + +--- + +## 🟒 IMPLEMENTATION: Missing Features for Release + +### 1. Global Search Enhancements (Priority: MEDIUM) + +**Status**: Core search works, enhancements missing + +**Missing Features**: +- Text/message string searching (40 min) +- Map name and room name searching (40 min) +- Memory address and label searching (60 min) +- Search result caching for performance (30 min) + +**Total Effort**: 4-6 hours +**Impact**: Nice-to-have enhancement + +**Files**: +- `src/app/editor/ui/ui_coordinator.cc` + +--- + +### 2. Layout Persistence (Priority: LOW) + +**Status**: Default layouts work, persistence stubbed + +**Missing**: +- `SaveCurrentLayout()` method (45 min) +- `LoadLayout()` method (45 min) +- Layout presets (Developer/Designer/Modder) (2 hours) + +**Total Effort**: 3-4 hours +**Impact**: Enhancement, not blocking + +**Files**: +- `src/app/editor/ui/layout_manager.cc` + +--- + +### 3. Keyboard Shortcut Rebinding UI (Priority: LOW) + +**Status**: Shortcuts work, rebinding UI missing + +**Missing**: +- Shortcut rebinding UI in Settings > Shortcuts card (2 hours) +- Shortcut persistence to user config file (1 hour) +- Shortcut reset to defaults (30 min) + +**Total Effort**: 3-4 hours +**Impact**: Enhancement + +--- + +### 4. ZSCustomOverworld Features (Priority: MEDIUM) + +**Status**: Partial implementation + +**Missing**: +- ZSCustomOverworld Main Palette support +- ZSCustomOverworld Custom Area BG Color support +- Fix sprite icon draw positions +- Fix exit icon draw positions + +**Dependencies**: Custom overworld data loading (complete) + +**Files**: +- `src/app/editor/overworld/overworld_map.cc` + +**Effort**: 8-12 hours +**Impact**: Feature completeness for ZSCOW users + +--- + +### 5. z3ed Agent Execution Loop (MCP) (Priority: LOW) + +**Status**: Agent framework foundation complete + +**Missing**: Complete agent execution loop with MCP protocol + +**Dependencies**: Agent framework foundation (complete) + +**Files**: +- `src/cli/service/agent/conversational_agent_service.cc` + +**Effort**: 8-12 hours +**Impact**: Future feature, not blocking release + +--- + +## πŸ“Š Release Readiness Assessment + +### βœ… Strengths + +1. **Architecture**: Excellent refactoring with 44% code reduction +2. **Build System**: Stable across all platforms (Windows, macOS, Linux) +3. **CI/CD**: Comprehensive pipeline with automated testing +4. **Documentation**: Extensive documentation (48+ markdown files) +5. **Feature Parity**: 90% achieved with master branch +6. **Test Coverage**: 46+ core tests with E2E framework + +### ⚠️ Concerns + +1. **Critical Bugs**: 6 high-priority bugs need fixing +2. **Manual Testing**: 2-3 hours of validation not completed +3. **E2E Tests**: Need updates for new architecture +4. **Audio System**: Core feature broken (emulator) +5. **Tile16 Editor**: Palette system issues blocking workflow + +### πŸ“ˆ Metrics + +| Category | Status | Completion | +|----------|--------|------------| +| Build Stability | βœ… | 100% | +| Feature Parity | 🟑 | 90% | +| Test Coverage | 🟑 | 70% (needs updates) | +| Critical Bugs | πŸ”΄ | 0% (6 bugs) | +| Documentation | βœ… | 95% | +| Performance | βœ… | 95% | + +--- + +## 🎯 Recommended Release Plan + +### Phase 1: Critical Fixes (1-2 weeks) + +**Must Complete Before Release**: + +1. **Tile16 Editor Palette Fixes** (4-6 hours) + - Fix palette button functionality + - Fix tile8 source canvas palette application + - Align colors between canvases + +2. **Overworld Sprite Movement** (2-4 hours) + - Fix drag operation handling + - Test sprite placement workflow + +3. **Emulator Audio System** (4-6 hours) + - Investigate root cause + - Fix audio output + - Verify playback works + +4. **Canvas Multi-Select Bug** (3-5 hours) + - Fix 512px boundary crossing + - Verify with existing E2E test + +5. **Manual Testing Suite** (2-3 hours) + - Test all 34 cards + - Verify layouts + - Test shortcuts + +**Total**: 15-24 hours (2-3 days full-time) + +--- + +### Phase 2: Stability Improvements (1 week) + +**Should Complete Before Release**: + +1. **E2E Test Updates** (4-6 hours) + - Update tests for new card-based architecture + - Add missing test coverage + +2. **Shutdown Performance** (2-4 hours) + - Optimize window shutdown sequence + - Review graphics arena cleanup + +3. **Overworld Map Properties Popup** (1-2 hours) + - Apply canvas popup fix pattern + +**Total**: 7-12 hours (1-2 days) + +--- + +### Phase 3: Enhancement Features (Post-Release) + +**Can Defer to Post-Release**: + +1. Global Search enhancements (4-6 hours) +2. Layout persistence (3-4 hours) +3. Shortcut rebinding UI (3-4 hours) +4. ZSCustomOverworld features (8-12 hours) +5. z3ed agent execution loop (8-12 hours) + +**Total**: 26-38 hours (future releases) + +--- + +## πŸ” Code Quality Observations + +### Positive + +1. **Excellent Documentation**: Comprehensive guides, architecture docs, troubleshooting +2. **Modern C++**: C++23 features, RAII, smart pointers +3. **Cross-Platform**: Consistent behavior across platforms +4. **Error Handling**: absl::Status used throughout +5. **Modular Architecture**: Refactored from monolith to 8 delegated components + +### Areas for Improvement + +1. **TODO Comments**: 153+ TODO items tagged with `[EditorManagerRefactor]` +2. **Test Coverage**: Some E2E tests need architecture updates +3. **Memory Management**: Some shutdown sequences need optimization +4. **Audio System**: Needs investigation and debugging + +--- + +## πŸ“ Specific Code Issues Found + +### High Priority + +1. **Tile16 Editor Palette** (`F2-tile16-editor-palette-system.md:280-297`) + - Palette buttons not updating correctly + - Tile8 source canvas showing wrong colors + +2. **Overworld Sprite Movement** (`yaze.org:13-19`) + - Sprites not responding to drag operations + - Blocks sprite editing workflow + +3. **Emulator Audio** (`E8-emulator-debugging-vision.md:35`) + - Audio output broken + - Comprehensive debugging guide available + +### Medium Priority + +1. **Canvas Multi-Select** (`yaze.org:21-27`) + - Selection box rendering issues at 512px boundaries + - E2E test exists for validation + +2. **EditorManager Testing** (`H3-feature-parity-analysis.md:339-351`) + - Manual testing phase not completed + - 90% feature parity needs validation + +### Low Priority + +1. **Right-Click Context Menu** (`yaze.org:29-35`) + - Intermittent oversized tile16 display + - Cosmetic issue + +2. **Shutdown Performance** (`window.cc:146`) + - Slow shutdown noted in code + - TODO comment indicates known issue + +--- + +## πŸš€ Immediate Action Items + +### This Week + +1. **Fix Tile16 Editor Palette Buttons** (4-6 hours) + - Priority: HIGH + - Blocks: Tile editing workflow + +2. **Fix Overworld Sprite Movement** (2-4 hours) + - Priority: HIGH + - Blocks: Sprite editing + +3. **Investigate Emulator Audio** (4-6 hours) + - Priority: CRITICAL + - Blocks: Core emulator feature + +### Next Week + +1. **Complete Manual Testing** (2-3 hours) + - Priority: HIGH + - Blocks: Release confidence + +2. **Fix Canvas Multi-Select** (3-5 hours) + - Priority: MEDIUM + - Blocks: Workflow quality + +3. **Update E2E Tests** (4-6 hours) + - Priority: MEDIUM + - Blocks: Test coverage confidence + +--- + +## πŸ“š Documentation Status + +### Excellent Coverage + +- βœ… Architecture documentation (`H2-editor-manager-architecture.md`) +- βœ… Feature parity analysis (`H3-feature-parity-analysis.md`) +- βœ… Build troubleshooting (`BUILD-TROUBLESHOOTING.md`) +- βœ… Emulator debugging vision (`E8-emulator-debugging-vision.md`) +- βœ… Tile16 editor palette system (`F2-tile16-editor-palette-system.md`) + +### Could Use Updates + +- ⚠️ API documentation generation (TODO in `yaze.org:344`) +- ⚠️ User guide for ROM hackers (TODO in `yaze.org:349`) + +--- + +## 🎯 Success Criteria for Release + +### Must Have (Blocking Release) + +- [ ] All 6 critical bugs fixed +- [ ] Manual testing suite completed +- [ ] Emulator audio working +- [ ] Tile16 editor palette system functional +- [ ] Overworld sprite movement working +- [ ] Canvas multi-select fixed +- [ ] No known crashes or data corruption + +### Should Have (Release Quality) + +- [ ] E2E tests updated for new architecture +- [ ] Shutdown performance optimized +- [ ] All 34 cards tested and working +- [ ] All 10 layouts verified +- [ ] Keyboard shortcuts tested + +### Nice to Have (Post-Release) + +- [ ] Global Search enhancements +- [ ] Layout persistence +- [ ] Shortcut rebinding UI +- [ ] ZSCustomOverworld features complete + +--- + +## πŸ“Š Estimated Timeline + +### Conservative Estimate (Full-Time) + +- **Phase 1 (Critical Fixes)**: 2-3 days (15-24 hours) +- **Phase 2 (Stability)**: 1-2 days (7-12 hours) +- **Total**: 3-5 days to release-ready state + +### With Part-Time Development + +- **Phase 1**: 1-2 weeks +- **Phase 2**: 1 week +- **Total**: 2-3 weeks to release-ready state + +--- + +## πŸ”— Related Documents + +- `docs/H3-feature-parity-analysis.md` - Feature parity status +- `docs/H2-editor-manager-architecture.md` - Architecture details +- `docs/F2-tile16-editor-palette-system.md` - Tile16 editor issues +- `docs/E8-emulator-debugging-vision.md` - Emulator audio debugging +- `docs/yaze.org` - Development tracker with active issues +- `docs/BUILD-TROUBLESHOOTING.md` - Build system issues +- `.github/workflows/ci.yml` - CI/CD pipeline status + +--- + +## βœ… Conclusion + +YAZE is **very close to release** with excellent architecture and comprehensive documentation. The main blockers are: + +1. **6 critical bugs** requiring 15-24 hours of focused work +2. **Manual testing validation** (2-3 hours) +3. **Emulator audio system** investigation (4-6 hours) + +With focused effort on critical fixes, YAZE can achieve a stable release in **2-3 weeks** (part-time) or **3-5 days** (full-time). + +**Recommendation**: Proceed with Phase 1 critical fixes immediately, then complete Phase 2 stability improvements before release. Enhancement features can be deferred to post-release updates. + +--- + +**Document Status**: Complete +**Last Updated**: January 31, 2025 +**Review Status**: Ready for implementation planning + diff --git a/docs/H3-feature-parity-analysis.md b/docs/internal/roadmaps/feature-parity-analysis.md similarity index 100% rename from docs/H3-feature-parity-analysis.md rename to docs/internal/roadmaps/feature-parity-analysis.md diff --git a/docs/I2-future-improvements.md b/docs/internal/roadmaps/future-improvements.md similarity index 100% rename from docs/I2-future-improvements.md rename to docs/internal/roadmaps/future-improvements.md diff --git a/docs/I1-roadmap.md b/docs/internal/roadmaps/roadmap.md similarity index 100% rename from docs/I1-roadmap.md rename to docs/internal/roadmaps/roadmap.md diff --git a/docs/B1-build-instructions.md b/docs/public/build/build-from-source.md similarity index 98% rename from docs/B1-build-instructions.md rename to docs/public/build/build-from-source.md index 111199e0..48ee0452 100644 --- a/docs/B1-build-instructions.md +++ b/docs/public/build/build-from-source.md @@ -26,7 +26,7 @@ The script checks for required tools like CMake, a C++23 compiler, and platform- ## 2. Quick Start: Building with Presets -We use CMake Presets for simple, one-command builds. See the [CMake Presets Guide](B3-build-presets.md) for a full list. +We use CMake Presets for simple, one-command builds. See the [CMake Presets Guide](presets.md) for a full list. ### macOS ```bash @@ -100,7 +100,7 @@ sudo apt-get install -y build-essential cmake ninja-build pkg-config \ ## 5. Testing -The project uses CTest and GoogleTest. Tests are organized into categories using labels. See the [Testing Guide](A1-testing-guide.md) for details. +The project uses CTest and GoogleTest. Tests are organized into categories using labels. See the [Testing Guide](../developer/testing-guide.md) for details. ### Running Tests with Presets @@ -314,4 +314,4 @@ taskkill /F /IM yaze.exe #### File Path Length Limit on Windows **Cause**: By default, Windows has a 260-character path limit, which can be exceeded by nested dependencies. -**Solution**: The verification script checks for this. Use the `-FixIssues` flag or run `git config --global core.longpaths true` to enable long path support. \ No newline at end of file +**Solution**: The verification script checks for this. Use the `-FixIssues` flag or run `git config --global core.longpaths true` to enable long path support. diff --git a/docs/B2-platform-compatibility.md b/docs/public/build/platform-compatibility.md similarity index 100% rename from docs/B2-platform-compatibility.md rename to docs/public/build/platform-compatibility.md diff --git a/docs/B3-build-presets.md b/docs/public/build/presets.md similarity index 100% rename from docs/B3-build-presets.md rename to docs/public/build/presets.md diff --git a/docs/BUILD-TROUBLESHOOTING.md b/docs/public/build/troubleshooting.md similarity index 100% rename from docs/BUILD-TROUBLESHOOTING.md rename to docs/public/build/troubleshooting.md diff --git a/docs/E3-api-reference.md b/docs/public/developer/api-reference.md similarity index 100% rename from docs/E3-api-reference.md rename to docs/public/developer/api-reference.md diff --git a/docs/E2-development-guide.md b/docs/public/developer/architecture.md similarity index 99% rename from docs/E2-development-guide.md rename to docs/public/developer/architecture.md index c3a4b687..9ac2abbb 100644 --- a/docs/E2-development-guide.md +++ b/docs/public/developer/architecture.md @@ -164,7 +164,7 @@ See [debugging-startup-flags.md](debugging-startup-flags.md) for complete docume ### 5.2. Testing Strategies -For a comprehensive overview of debugging tools and testing strategies, including how to use the logging framework, command-line test runners, and the GUI automation harness for AI agents, please refer to the [Debugging and Testing Guide](E5-debugging-guide.md). +For a comprehensive overview of debugging tools and testing strategies, including how to use the logging framework, command-line test runners, and the GUI automation harness for AI agents, please refer to the [Debugging and Testing Guide](debugging-guide.md). ## 5. Command-Line Flag Standardization diff --git a/docs/E1-asm-style-guide.md b/docs/public/developer/asm-style-guide.md similarity index 100% rename from docs/E1-asm-style-guide.md rename to docs/public/developer/asm-style-guide.md diff --git a/docs/G1-canvas-guide.md b/docs/public/developer/canvas-system.md similarity index 100% rename from docs/G1-canvas-guide.md rename to docs/public/developer/canvas-system.md diff --git a/docs/E7-debugging-startup-flags.md b/docs/public/developer/debug-flags.md similarity index 100% rename from docs/E7-debugging-startup-flags.md rename to docs/public/developer/debug-flags.md diff --git a/docs/E5-debugging-guide.md b/docs/public/developer/debugging-guide.md similarity index 99% rename from docs/E5-debugging-guide.md rename to docs/public/developer/debugging-guide.md index 4cb1dac9..80a2b67d 100644 --- a/docs/E5-debugging-guide.md +++ b/docs/public/developer/debugging-guide.md @@ -213,7 +213,7 @@ The `--watch` flag streams results back to the CLI in real-time. The agent can p ## 4. Advanced Debugging Tools -For more complex issues, especially within the emulator, `yaze` provides several advanced debugging windows. These are covered in detail in the [Emulator Development Guide](E4-Emulator-Development-Guide.md). +For more complex issues, especially within the emulator, `yaze` provides several advanced debugging windows. These are covered in detail in the [Emulator Development Guide](emulator-development-guide.md). - **Disassembly Viewer**: A live, interactive view of the 65816 and SPC700 CPU execution. - **Breakpoint Manager**: Set breakpoints on code execution, memory reads, or memory writes. diff --git a/docs/A1-yaze-dependency-architecture.md b/docs/public/developer/dependency-architecture.md similarity index 98% rename from docs/A1-yaze-dependency-architecture.md rename to docs/public/developer/dependency-architecture.md index 42a0fc9b..1bb7cb59 100644 --- a/docs/A1-yaze-dependency-architecture.md +++ b/docs/public/developer/dependency-architecture.md @@ -3,7 +3,7 @@ **Author**: Claude (Anthropic AI Assistant) **Date**: 2025-10-13 **Status**: Reference Document -**Related Docs**: [C4-z3ed-refactoring.md](C4-z3ed-refactoring.md), [B6-zelda3-library-refactoring.md](B6-zelda3-library-refactoring.md), [A2-test-dashboard-refactoring.md](A2-test-dashboard-refactoring.md) +**Related Docs**: [../../internal/agents/z3ed-refactoring.md](../../internal/agents/z3ed-refactoring.md), [../../internal/blueprints/zelda3-library-refactor.md](../../internal/blueprints/zelda3-library-refactor.md), [../../internal/blueprints/test-dashboard-refactor.md](../../internal/blueprints/test-dashboard-refactor.md) --- @@ -369,7 +369,7 @@ Result: Neither can be built first, causes linking issues - Test dashboard cannot be excluded from release builds cleanly - Changes to test infrastructure force editor rebuilds -**Solution** (from A2-test-dashboard-refactoring.md): +**Solution** (from ../../internal/blueprints/test-dashboard-refactor.md): ``` test_framework (core logic only) β”œβ”€β†’ yaze_util, absl (no app dependencies) @@ -526,7 +526,7 @@ Reality: Used by both yaze app AND z3ed CLI Problem: cli/ cannot depend on app/ (architectural violation) ``` -**Solution** (from B6-zelda3-library-refactoring.md): +**Solution** (from ../../internal/blueprints/zelda3-library-refactor.md): - Move: `src/app/zelda3/` β†’ `src/zelda3/` - Update all includes: `#include "app/zelda3/...` β†’ `#include "zelda3/...` - Establish as proper shared core component @@ -542,7 +542,7 @@ Problem: Cannot exclude test dashboard from release builds Cannot build minimal test framework ``` -**Solution** (from A2-test-dashboard-refactoring.md): +**Solution** (from ../../internal/blueprints/test-dashboard-refactor.md): - Move: `src/app/test/` β†’ `src/test/framework/` + `src/test/suites/` - Separate: `TestManager` (core) from `TestDashboard` (GUI) - Make: `test_dashboard` conditionally compiled @@ -1202,7 +1202,7 @@ yaze_editor (INTERFACE): **Timeline**: 1 week **Status**: Proposed -**Reference**: A2-test-dashboard-refactoring.md +**Reference**: ../../internal/blueprints/test-dashboard-refactor.md **Tasks**: 1. Create `src/test/framework/` directory structure @@ -1223,7 +1223,7 @@ yaze_editor (INTERFACE): **Timeline**: 1.5-2 weeks **Status**: Proposed -**Reference**: B6-zelda3-library-refactoring.md +**Reference**: ../../internal/blueprints/zelda3-library-refactor.md **Tasks**: 1. **Week 1**: Physical move @@ -1780,16 +1780,16 @@ Measured on Apple M1 Max, 32 GB RAM, macOS 14.0 ### Primary Documents -- **C4-z3ed-refactoring.md**: CLI command abstraction (COMPLETED ) -- **B6-zelda3-library-refactoring.md**: Zelda3 move & decomposition (PROPOSED πŸ”΄) -- **A2-test-dashboard-refactoring.md**: Test infrastructure separation (PROPOSED πŸ”΄) +- **../../internal/agents/z3ed-refactoring.md**: CLI command abstraction (COMPLETED ) +- **../../internal/blueprints/zelda3-library-refactor.md**: Zelda3 move & decomposition (PROPOSED πŸ”΄) +- **../../internal/blueprints/test-dashboard-refactor.md**: Test infrastructure separation (PROPOSED πŸ”΄) - **This Document (A1)**: Comprehensive dependency analysis (NEW πŸ“„) ### Related Refactoring Documents - **docs/gfx-refactor.md**: Graphics tier decomposition (COMPLETED ) - **docs/gui-refactor.md**: GUI tier decomposition (COMPLETED ) -- **docs/G3-renderer-migration-complete.md**: Renderer abstraction (COMPLETED ) +- **../../internal/blueprints/renderer-migration-complete.md**: Renderer abstraction (COMPLETED ) ### Build System Documentation @@ -1801,9 +1801,9 @@ Measured on Apple M1 Max, 32 GB RAM, macOS 14.0 ### Architecture Documentation - **docs/CLAUDE.md**: Project overview and guidelines -- **docs/B2-platform-compatibility.md**: Platform notes, Windows Clang +- **../build/platform-compatibility.md**: Platform notes, Windows Clang workarounds, and CI/CD guidance -- **docs/B4-git-workflow.md**: Git workflow and branching +- **git-workflow.md**: Git workflow and branching ### External Resources diff --git a/docs/E4-Emulator-Development-Guide.md b/docs/public/developer/emulator-development-guide.md similarity index 100% rename from docs/E4-Emulator-Development-Guide.md rename to docs/public/developer/emulator-development-guide.md diff --git a/docs/B4-git-workflow.md b/docs/public/developer/git-workflow.md similarity index 99% rename from docs/B4-git-workflow.md rename to docs/public/developer/git-workflow.md index f0962dc5..4a67c59f 100644 --- a/docs/B4-git-workflow.md +++ b/docs/public/developer/git-workflow.md @@ -332,7 +332,7 @@ Follow **Semantic Versioning (SemVer)**: `MAJOR.MINOR.PATCH` 2. **Update version numbers** - `CMakeLists.txt` - - `docs/H1-changelog.md` + - `../reference/changelog.md` - `README.md` 3. **Update documentation** @@ -554,4 +554,3 @@ No need for release branches or complex merging until you have multiple contribu - [Git Flow](https://nvie.com/posts/a-successful-git-branching-model/) - [Conventional Commits](https://www.conventionalcommits.org/) - [Semantic Versioning](https://semver.org/) - diff --git a/docs/G5-gui-consistency-guide.md b/docs/public/developer/gui-consistency-guide.md similarity index 99% rename from docs/G5-gui-consistency-guide.md rename to docs/public/developer/gui-consistency-guide.md index 4dc790be..0cb180c5 100644 --- a/docs/G5-gui-consistency-guide.md +++ b/docs/public/developer/gui-consistency-guide.md @@ -807,7 +807,7 @@ Use this checklist when converting an editor to the card-based architecture: ### Documentation Phase - [ ] Document keyboard shortcuts in header comment -- [ ] Update E2-development-guide.md editor status if applicable +- [ ] Update `architecture.md` editor status if applicable - [ ] Add example to this guide if pattern is novel - [ ] Update CLAUDE.md if editor behavior changed significantly diff --git a/docs/B5-architecture-and-networking.md b/docs/public/developer/networking.md similarity index 100% rename from docs/B5-architecture-and-networking.md rename to docs/public/developer/networking.md diff --git a/docs/F5-overworld-entity-system.md b/docs/public/developer/overworld-entity-system.md similarity index 100% rename from docs/F5-overworld-entity-system.md rename to docs/public/developer/overworld-entity-system.md diff --git a/docs/G3-palete-system-overview.md b/docs/public/developer/palette-system-overview.md similarity index 100% rename from docs/G3-palete-system-overview.md rename to docs/public/developer/palette-system-overview.md diff --git a/docs/A1-testing-guide.md b/docs/public/developer/testing-guide.md similarity index 100% rename from docs/A1-testing-guide.md rename to docs/public/developer/testing-guide.md diff --git a/docs/C2-testing-without-roms.md b/docs/public/developer/testing-without-roms.md similarity index 97% rename from docs/C2-testing-without-roms.md rename to docs/public/developer/testing-without-roms.md index c61b042c..79dd8360 100644 --- a/docs/C2-testing-without-roms.md +++ b/docs/public/developer/testing-without-roms.md @@ -269,9 +269,9 @@ if (status.ok()) { ## Related Documentation -- [C1: z3ed Agent Guide](C1-z3ed-agent-guide.md) - Main agent documentation -- [A1: Testing Guide](A1-testing-guide.md) - General testing strategy -- [E3: API Reference](E3-api-reference.md) - ROM API documentation +- [z3ed CLI Guide](../usage/z3ed-cli.md) - Main agent and CLI documentation +- [Testing Guide](testing-guide.md) - General testing strategy +- [API Reference](api-reference.md) - ROM API documentation --- diff --git a/docs/F2-tile16-editor-palette-system.md b/docs/public/developer/tile16-palette-system.md similarity index 100% rename from docs/F2-tile16-editor-palette-system.md rename to docs/public/developer/tile16-palette-system.md diff --git a/docs/public/index.md b/docs/public/index.md new file mode 100644 index 00000000..5e5cf53d --- /dev/null +++ b/docs/public/index.md @@ -0,0 +1,52 @@ +/** +@mainpage YAZE Documentation +@tableofcontents +*/ + +# YAZE Documentation + +YAZE documentation now focuses on concise, Doxygen-friendly sections. Use the categories +below for human-readable guides and reference material. Internal planning, AI agent playbooks, +and research notes were moved to `docs/internal/` so the public docs stay focused. + +## Overview +- [Getting Started](overview/getting-started.md) + +## Build & Tooling +- [Build From Source](build/build-from-source.md) +- [Platform Compatibility](build/platform-compatibility.md) +- [CMake Presets](build/presets.md) +- [Build Troubleshooting](build/troubleshooting.md) + +## Usage Guides +- [Dungeon Editor](usage/dungeon-editor.md) +- [Overworld Loading](usage/overworld-loading.md) +- [z3ed CLI](usage/z3ed-cli.md) +- [Examples & Recipes](examples/) + +## Developer Guides +- [Architecture Overview](developer/architecture.md) +- [Dependency Architecture](developer/dependency-architecture.md) +- [Git Workflow](developer/git-workflow.md) +- [Networking Overview](developer/networking.md) +- [Testing Guide](developer/testing-guide.md) +- [Testing Without ROMs](developer/testing-without-roms.md) +- [Debugging Guide](developer/debugging-guide.md) +- [Debug Flags](developer/debug-flags.md) +- [Assembler Style Guide](developer/asm-style-guide.md) +- [API Reference](developer/api-reference.md) +- [Emulator Development Guide](developer/emulator-development-guide.md) +- [Canvas System](developer/canvas-system.md) +- [Palette System Overview](developer/palette-system-overview.md) +- [Tile16 Palette System](developer/tile16-palette-system.md) +- [Overworld Entity System](developer/overworld-entity-system.md) +- [GUI Consistency Guide](developer/gui-consistency-guide.md) + +## Reference +- [ROM Reference](reference/rom-reference.md) +- [Changelog](reference/changelog.md) + +--- + +Need editor playbooks, refactors, or AI workflows? Head over to [`docs/internal/`](../internal/README.md) +for internal documentation that stays out of the public Doxygen site. diff --git a/docs/A1-getting-started.md b/docs/public/overview/getting-started.md similarity index 100% rename from docs/A1-getting-started.md rename to docs/public/overview/getting-started.md diff --git a/docs/H1-changelog.md b/docs/public/reference/changelog.md similarity index 100% rename from docs/H1-changelog.md rename to docs/public/reference/changelog.md diff --git a/docs/R1-alttp-rom-reference.md b/docs/public/reference/rom-reference.md similarity index 100% rename from docs/R1-alttp-rom-reference.md rename to docs/public/reference/rom-reference.md diff --git a/docs/F1-dungeon-editor-guide.md b/docs/public/usage/dungeon-editor.md similarity index 95% rename from docs/F1-dungeon-editor-guide.md rename to docs/public/usage/dungeon-editor.md index 5fa0fba2..2f0b1695 100644 --- a/docs/F1-dungeon-editor-guide.md +++ b/docs/public/usage/dungeon-editor.md @@ -1,7 +1,7 @@ # 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) +**Related**: [Architecture Overview](../developer/architecture.md), [Debugging Guide](../developer/debugging-guide.md) --- @@ -251,13 +251,12 @@ cmake --build build_ai --target yaze -j12 ## 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) +- **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 - diff --git a/docs/F3-overworld-loading.md b/docs/public/usage/overworld-loading.md similarity index 99% rename from docs/F3-overworld-loading.md rename to docs/public/usage/overworld-loading.md index b3a3335c..c0099dc7 100644 --- a/docs/F3-overworld-loading.md +++ b/docs/public/usage/overworld-loading.md @@ -385,7 +385,7 @@ at `+0x1000`. - Light World palette: `0x055B27` (128 colors) - Dark World palette: `0x055C27` (128 colors) -- Conversion uses the shared helper discussed in [G3-palete-system-overview.md](G3-palete-system-overview.md). +- Conversion uses the shared helper discussed in [Palette System Overview](../developer/palette-system-overview.md). ### Custom Map Import/Export diff --git a/docs/C1-z3ed-agent-guide.md b/docs/public/usage/z3ed-cli.md similarity index 99% rename from docs/C1-z3ed-agent-guide.md rename to docs/public/usage/z3ed-cli.md index 4b3db54b..6ba7a691 100644 --- a/docs/C1-z3ed-agent-guide.md +++ b/docs/public/usage/z3ed-cli.md @@ -149,7 +149,7 @@ Key benefits: - Cuts individual command implementations by about half. - Establishes consistent patterns across the CLI for easier testing and automation. -See [Command Abstraction Guide](C5-z3ed-command-abstraction.md) for migration details. +See [Command Abstraction Guide](../../internal/agents/z3ed-command-abstraction.md) for migration details. ## 4. Agentic & Generative Workflow (MCP) @@ -998,7 +998,7 @@ The AI response appears in your chat history and can reference specific details ### Active & Next Steps -1. **CLI Command Refactoring (Phase 2)**: Complete migration of tool_commands.cc to use new abstraction layer. Refactor 15+ commands to eliminate ~1300 lines of duplication. Add comprehensive unit tests. (See [Command Abstraction Guide](C5-z3ed-command-abstraction.md)) +1. **CLI Command Refactoring (Phase 2)**: Complete migration of tool_commands.cc to use new abstraction layer. Refactor 15+ commands to eliminate ~1300 lines of duplication. Add comprehensive unit tests. (See [Command Abstraction Guide](../../internal/agents/z3ed-command-abstraction.md)) 2. **Harden Live LLM Tooling**: Finalize native function-calling loops with Ollama/Gemini and broaden safe read-only tool coverage for dialogue, sprite, and region introspection. 3. **Real-Time Transport Upgrade**: Replace HTTP polling with full WebSocket support across CLI/editor and expose ROM sync, snapshot, and proposal voting controls directly inside the AgentChat widget. 4. **Cross-Platform Certification**: Complete Windows validation for AI, gRPC, collaboration, and build presets leveraging the documented vcpkg workflow. @@ -1033,7 +1033,7 @@ The AI response appears in your chat history and can reference specific details - **Command Abstraction Layer**: Three-tier abstraction system (`CommandContext`, `ArgumentParser`, `OutputFormatter`) to eliminate code duplication across CLI commands - **CommandHandler Base Class**: Structured base class for consistent command implementation with automatic context management - **Refactoring Framework**: Complete migration guide and examples showing 50-60% code reduction per command -- **Documentation**: Comprehensive [Command Abstraction Guide](C5-z3ed-command-abstraction.md) with migration checklist and testing strategies +- **Documentation**: Comprehensive [Command Abstraction Guide](../../internal/agents/z3ed-command-abstraction.md) with migration checklist and testing strategies #### Code Quality & Maintainability - **Duplication Elimination**: New abstraction layer removes ~1300 lines of duplicated code across tool commands