docs: reorganize documentation layout
This commit is contained in:
scawful
6
.github/workflows/doxy.yml
vendored
6
.github/workflows/doxy.yml
vendored
@@ -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
|
||||
fi
|
||||
|
||||
18
Doxyfile
18
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
|
||||
|
||||
174
README.md
174
README.md
@@ -4,139 +4,93 @@
|
||||
[](https://github.com/scawful/yaze/actions)
|
||||
[](https://github.com/scawful/yaze/actions)
|
||||
[](https://github.com/scawful/yaze/actions)
|
||||
[](LICENSE)
|
||||
[](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
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
**Ready to hack Zelda 3? [Get started now!](docs/01-getting-started.md)**
|
||||
109
docs/index.md
109
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)
|
||||
|
||||
15
docs/internal/README.md
Normal file
15
docs/internal/README.md
Normal file
@@ -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/`.
|
||||
573
docs/internal/roadmaps/code-review-critical-next-steps.md
Normal file
573
docs/internal/roadmaps/code-review-critical-next-steps.md
Normal file
@@ -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
|
||||
|
||||
@@ -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.
|
||||
**Solution**: The verification script checks for this. Use the `-FixIssues` flag or run `git config --global core.longpaths true` to enable long path support.
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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/)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
---
|
||||
|
||||
52
docs/public/index.md
Normal file
52
docs/public/index.md
Normal file
@@ -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.
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user