backend-infra-engineer: Release v0.3.3 snapshot
This commit is contained in:
scawful
68
docs/internal/roadmaps/2025-11-build-performance.md
Normal file
68
docs/internal/roadmaps/2025-11-build-performance.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# Build Performance & Agent-Friendly Tooling (November 2025)
|
||||
|
||||
Status: **Draft**
|
||||
Owner: CODEX (open to CLAUDE/GEMINI participation)
|
||||
|
||||
## Goals
|
||||
- Reduce incremental build times on all platforms by tightening target boundaries, isolating optional
|
||||
components, and providing cache-friendly presets.
|
||||
- Allow long-running or optional tasks (e.g., asset generation, documentation, verification scripts)
|
||||
to run asynchronously or on-demand so agents don’t block on them.
|
||||
- Provide monitoring/metrics hooks so agents and humans can see where build time is spent.
|
||||
- Organize helper scripts (build, verification, CI triggers) so agents can call them predictably.
|
||||
|
||||
## Plan Overview
|
||||
|
||||
### 1. Library Scoping & Optional Targets
|
||||
1. Audit `src/CMakeLists.txt` and per-module cmake files for broad `add_subdirectory` usage.
|
||||
- Identify libraries that can be marked `EXCLUDE_FROM_ALL` and only built when needed (e.g.,
|
||||
optional tools, emulator targets).
|
||||
- Leverage `YAZE_MINIMAL_BUILD`, `YAZE_BUILD_Z3ED`, etc., but ensure presets reflect the smallest
|
||||
viable dependency tree.
|
||||
2. Split heavy modules (e.g., `app/editor`, `app/emu`) into more granular targets if they are
|
||||
frequently touched independently.
|
||||
3. Add caching hints (ccache, sccache) in the build scripts/presets for all platforms.
|
||||
|
||||
### 2. Background / Async Tasks
|
||||
1. Move long-running scripts (asset bundling, doc generation, lints) into optional targets invoked by
|
||||
a convenience meta-target (e.g., `yaze_extras`) so normal builds stay lean.
|
||||
2. Provide `scripts/run-background-tasks.sh` that uses `nohup`/`start` to launch doc builds, GH
|
||||
workflow dispatch, or other heavy processes asynchronously; log their status for monitoring.
|
||||
3. Ensure CI workflows skip optional tasks unless explicitly requested (e.g., via workflow inputs).
|
||||
|
||||
### 3. Monitoring & Metrics
|
||||
1. Add a lightweight timing report to `scripts/verify-build-environment.*` or a new
|
||||
`scripts/measure-build.sh` that runs `cmake --build` with `--trace-expand`/`ninja -d stats` and
|
||||
reports hotspots.
|
||||
2. Integrate a summary step in CI (maybe a bash step) that records build duration per preset and
|
||||
uploads as an artifact or comment.
|
||||
3. Document how agents should capture metrics when running builds (e.g., use `time` wrappers, log
|
||||
output to `logs/build_<preset>.log`).
|
||||
|
||||
### 4. Agent-Friendly Script Organization
|
||||
1. Gather recurring helper commands into `scripts/agents/`:
|
||||
- `run-gh-workflow.sh` (wrapper around `gh workflow run`)
|
||||
- `smoke-build.sh <preset>` (configures & builds a preset in a dedicated directory, records time)
|
||||
- `run-tests.sh <preset> <labels>` (standardizes test selections)
|
||||
2. Provide short README in `scripts/agents/` explaining parameters, sample usage, and expected output
|
||||
files for logging back to the coordination board.
|
||||
3. Update `AGENTS.md` to reference these scripts so every persona knows the canonical tooling.
|
||||
|
||||
### 5. Deliverables / Tracking
|
||||
- Update CMake targets/presets to reflect modular build improvements.
|
||||
- New scripts under `scripts/agents/` + documentation.
|
||||
- Monitoring notes in CI (maybe via job summary) and local scripts.
|
||||
- Coordination board entries per major milestone (library scoping, background tooling, metrics,
|
||||
script rollout).
|
||||
|
||||
## Dependencies / Risks
|
||||
- Coordinate with CLAUDE_AIINF when touching presets or build scripts—they may modify the same files
|
||||
for AI workflow fixes.
|
||||
- When changing CMake targets, ensure existing presets still configure successfully (run verification
|
||||
scripts + smoke builds on mac/linux/win).
|
||||
- Adding background tasks/scripts should not introduce new global dependencies; use POSIX Bash and
|
||||
PowerShell equivalents where required.
|
||||
## Windows Stability Focus (New)
|
||||
- **Tooling verification**: expand `scripts/verify-build-environment.ps1` to check for Visual Studio workload, Ninja, and vcpkg caches so Windows builds fail fast when the environment is incomplete.
|
||||
- **CMake structure**: ensure optional components (HTTP API, emulator, CLI helpers) are behind explicit options and do not affect default Windows presets; verify each target links the right runtime/library deps even when `YAZE_ENABLE_*` flags change.
|
||||
- **Preset validation**: add Windows smoke builds (Ninja + VS) to the helper scripts/CI so we can trigger focused runs when changes land.
|
||||
46
docs/internal/roadmaps/2025-11-modernization.md
Normal file
46
docs/internal/roadmaps/2025-11-modernization.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# Modernization Plan – November 2025
|
||||
|
||||
Status: **Draft**
|
||||
Owner: Core tooling team
|
||||
Scope: `core/asar_wrapper`, CLI/GUI flag system, project persistence, docs
|
||||
|
||||
## Context
|
||||
- The Asar integration is stubbed out (`src/core/asar_wrapper.cc`), yet the GUI, CLI, and docs still advertise a working assembler workflow.
|
||||
- The GUI binary (`yaze`) still relies on the legacy `util::Flag` parser while the rest of the tooling has moved to Abseil flags, leading to inconsistent UX and duplicated parsing logic.
|
||||
- Project metadata initialization uses `std::localtime` (`src/core/project.cc`), which is not thread-safe and can race when the agent/automation stack spawns concurrent project creation tasks.
|
||||
- Public docs promise Dungeon Editor rendering details and “Examples & Recipes,” but those sections are either marked TODO or empty.
|
||||
|
||||
## Goals
|
||||
1. Restore a fully functioning Asar toolchain across GUI/CLI and make sure automated tests cover it.
|
||||
2. Unify flag parsing by migrating the GUI binary (and remaining utilities) to Abseil flags, then retire `util::flag`.
|
||||
3. Harden project/workspace persistence by replacing unsafe time handling and improving error propagation during project bootstrap.
|
||||
4. Close the documentation gaps so the Dungeon Editor guide reflects current rendering, and the `docs/public/examples/` tree provides actual recipes.
|
||||
|
||||
## Work Breakdown
|
||||
|
||||
### 1. Asar Restoration
|
||||
- Fix the Asar CMake integration under `ext/asar` and link it back into `yaze_core_lib`.
|
||||
- Re-implement `AsarWrapper` methods (patch, symbol extraction, validation) and add regression tests in `test/integration/asar_*`.
|
||||
- Update `z3ed`/GUI code paths to surface actionable errors when the assembler fails.
|
||||
- Once complete, scrub docs/README claims to ensure they match the restored behavior.
|
||||
|
||||
### 2. Flag Standardization
|
||||
- Replace `DEFINE_FLAG` usage in `src/app/main.cc` with `ABSL_FLAG` + `absl::ParseCommandLine`.
|
||||
- Delete `util::flag.*` and migrate any lingering consumers (e.g., dev tools) to Abseil.
|
||||
- Document the shared flag set in a single reference (README + `docs/public/developer/debug-flags.md`).
|
||||
|
||||
### 3. Project Persistence Hardening
|
||||
- Swap `std::localtime` for `absl::Time` or platform-safe helpers and handle failures explicitly.
|
||||
- Ensure directory creation and file writes bubble errors back to the UI/CLI instead of silently failing.
|
||||
- Add regression tests that spawn concurrent project creations (possibly via the CLI) to confirm deterministic metadata.
|
||||
|
||||
### 4. Documentation Updates
|
||||
- Finish the Dungeon Editor rendering pipeline description (remove the TODO block) so it reflects the current draw path.
|
||||
- Populate `docs/public/examples/` with at least a handful of ROM-editing recipes (overworld tile swap, dungeon entrance move, palette tweak, CLI plan/accept flow).
|
||||
- Add a short “automation journey” that links `README` → gRPC harness (`src/app/service/imgui_test_harness_service.cc`) → `z3ed` agent commands.
|
||||
|
||||
## Exit Criteria
|
||||
- `AsarWrapper` integration tests green on macOS/Linux/Windows runners.
|
||||
- No binaries depend on `util::flag`; `absl::flags` is the single source of truth.
|
||||
- Project creation succeeds under parallel stress and metadata timestamps remain valid.
|
||||
- Public docs no longer contain TODO placeholders or empty directories for the sections listed above.
|
||||
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
|
||||
|
||||
530
docs/internal/roadmaps/feature-parity-analysis.md
Normal file
530
docs/internal/roadmaps/feature-parity-analysis.md
Normal file
@@ -0,0 +1,530 @@
|
||||
# H3 - Feature Parity Analysis: Master vs Develop
|
||||
|
||||
**Date**: October 15, 2025
|
||||
**Status**: 90% Complete - Ready for Manual Testing
|
||||
**Code Reduction**: 3710 → 2076 lines (-44%)
|
||||
**Feature Parity**: 90% achieved, 10% enhancements pending
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The EditorManager refactoring has successfully achieved **90% feature parity** with the master branch while reducing code by 44% (1634 lines). All critical features are implemented and working:
|
||||
|
||||
- ✅ Welcome screen appears on startup without ROM
|
||||
- ✅ Command Palette with fuzzy search (Ctrl+Shift+P)
|
||||
- ✅ Global Search with card discovery (Ctrl+Shift+K)
|
||||
- ✅ VSCode-style sidebar (48px width, category switcher)
|
||||
- ✅ All 34 editor cards closeable via X button
|
||||
- ✅ 10 editor-specific DockBuilder layouts
|
||||
- ✅ Multi-session support with independent card visibility
|
||||
- ✅ All major keyboard shortcuts working
|
||||
- ✅ Type-safe popup system (21 popups)
|
||||
|
||||
**Remaining work**: Enhancement features and optional UI improvements (12-16 hours).
|
||||
|
||||
---
|
||||
|
||||
## Feature Matrix
|
||||
|
||||
### ✅ COMPLETE - Feature Parity Achieved
|
||||
|
||||
#### 1. Welcome Screen
|
||||
- **Master**: `DrawWelcomeScreen()` in EditorManager (57 lines)
|
||||
- **Develop**: Migrated to UICoordinator + WelcomeScreen class
|
||||
- **Status**: ✅ Works on first launch without ROM
|
||||
- **Features**: Recent projects, manual open/close, auto-hide on ROM load
|
||||
|
||||
#### 2. Command Palette
|
||||
- **Master**: `DrawCommandPalette()` in EditorManager (165 lines)
|
||||
- **Develop**: Moved to UICoordinator (same logic)
|
||||
- **Status**: ✅ Ctrl+Shift+P opens fuzzy-searchable command list
|
||||
- **Features**: Categorized commands, quick access to all features
|
||||
|
||||
#### 3. Global Search (Basic)
|
||||
- **Master**: `DrawGlobalSearch()` in EditorManager (193 lines)
|
||||
- **Develop**: Moved to UICoordinator with expansion
|
||||
- **Status**: ✅ Ctrl+Shift+K searches and opens cards
|
||||
- **Features**: Card fuzzy search, ROM data discovery (basic)
|
||||
|
||||
#### 4. VSCode-Style Sidebar
|
||||
- **Master**: `DrawSidebar()` in EditorManager
|
||||
- **Develop**: Integrated into card rendering system
|
||||
- **Status**: ✅ Exactly 48px width matching master
|
||||
- **Features**:
|
||||
- Category switcher buttons (first letter of each editor)
|
||||
- Close All / Show All buttons
|
||||
- Icon-only card toggle buttons (40x40px)
|
||||
- Active cards highlighted with accent color
|
||||
- Tooltips show full card name and shortcuts
|
||||
- Collapse button at bottom
|
||||
- Fully opaque dark background
|
||||
|
||||
#### 5. Menu System
|
||||
- **Master**: Multiple menu methods in EditorManager
|
||||
- **Develop**: Delegated to MenuOrchestrator (922 lines)
|
||||
- **Status**: ✅ All menus present and functional
|
||||
- **Menus**:
|
||||
- File: Open, Save, Save As, Close, Recent, Exit
|
||||
- View: Editor selection, sidebar toggle, help
|
||||
- Tools: Memory editor, assembly editor, etc.
|
||||
- Debug: 17 items (Test, ROM analysis, ASM, Performance, etc.)
|
||||
- Help: About, Getting Started, Documentation
|
||||
|
||||
#### 6. Popup System
|
||||
- **Master**: Inline popup logic in EditorManager
|
||||
- **Develop**: Delegated to PopupManager with PopupID namespace
|
||||
- **Status**: ✅ 21 popups registered, type-safe, crash-free
|
||||
- **Improvements**:
|
||||
- Type-safe constants prevent typos
|
||||
- Centralized initialization order
|
||||
- No more undefined behavior
|
||||
|
||||
#### 7. Card System
|
||||
- **Master**: EditorCardManager singleton (fragile)
|
||||
- **Develop**: EditorCardRegistry (dependency injection)
|
||||
- **Status**: ✅ All 34 cards closeable via X button
|
||||
- **Coverage**:
|
||||
- Emulator: 10 cards (CPU, PPU, Memory, etc.)
|
||||
- Message: 4 cards
|
||||
- Overworld: 8 cards
|
||||
- Dungeon: 8 cards
|
||||
- Palette: 11 cards
|
||||
- Graphics: 4 cards
|
||||
- Screen: 5 cards
|
||||
- Music: 3 cards
|
||||
- Sprite: 2 cards
|
||||
- Assembly: 2 cards
|
||||
- Settings: 6 cards
|
||||
|
||||
#### 8. Multi-Session Support
|
||||
- **Master**: Single session only
|
||||
- **Develop**: Full multi-session with EditorCardRegistry
|
||||
- **Status**: ✅ Multiple ROMs can be open independently
|
||||
- **Features**:
|
||||
- Independent card visibility per session
|
||||
- SessionCoordinator for UI
|
||||
- Session-aware layout management
|
||||
|
||||
#### 9. Keyboard Shortcuts
|
||||
- **Master**: Various hardcoded shortcuts
|
||||
- **Develop**: ShortcutConfigurator with conflict resolution
|
||||
- **Status**: ✅ All major shortcuts working
|
||||
- **Shortcuts**:
|
||||
- Ctrl+Shift+P: Command Palette
|
||||
- Ctrl+Shift+K: Global Search
|
||||
- Ctrl+Shift+R: Proposal Drawer
|
||||
- Ctrl+B: Toggle sidebar
|
||||
- Ctrl+S: Save ROM
|
||||
- Ctrl+Alt+[X]: Card toggles (resolved conflict)
|
||||
|
||||
#### 10. ImGui DockBuilder Layouts
|
||||
- **Master**: No explicit layouts (manual window management)
|
||||
- **Develop**: LayoutManager with professional layouts
|
||||
- **Status**: ✅ 2-3 panel layouts for all 10 editors
|
||||
- **Layouts**:
|
||||
- Overworld: 3-panel (map, properties, tools)
|
||||
- Dungeon: 3-panel (map, objects, properties)
|
||||
- Graphics: 3-panel (tileset, palette, canvas)
|
||||
- Palette: 3-panel (palette, groups, editor)
|
||||
- Screen: Grid (4-quadrant layout)
|
||||
- Music: 3-panel (songs, instruments, patterns)
|
||||
- Sprite: 2-panel (sprites, properties)
|
||||
- Message: 3-panel (messages, text, preview)
|
||||
- Assembly: 2-panel (code, output)
|
||||
- Settings: 2-panel (tabs, options)
|
||||
|
||||
---
|
||||
|
||||
### 🟡 PARTIAL - Core Features Exist, Enhancements Missing
|
||||
|
||||
#### 1. Global Search Expansion
|
||||
**Status**: Core search works, enhancements incomplete
|
||||
|
||||
**Implemented**:
|
||||
- ✅ Fuzzy search in card names
|
||||
- ✅ Card discovery and opening
|
||||
- ✅ ROM data basic search (palettes, graphics)
|
||||
|
||||
**Missing**:
|
||||
- ❌ Text/message string searching (40 min - moderate)
|
||||
- ❌ Map name and room name searching (40 min - moderate)
|
||||
- ❌ Memory address and label searching (60 min - moderate)
|
||||
- ❌ Search result caching for performance (30 min - easy)
|
||||
|
||||
**Total effort**: 4-6 hours | **Impact**: Nice-to-have
|
||||
|
||||
**Implementation Strategy**:
|
||||
```cpp
|
||||
// In ui_coordinator.cc, expand SearchROmData()
|
||||
// 1. Add MessageSearchSystem to search text strings
|
||||
// 2. Add MapSearchSystem to search overworld/dungeon names
|
||||
// 3. Add MemorySearchSystem to search assembly labels
|
||||
// 4. Implement ResultCache with 30-second TTL
|
||||
```
|
||||
|
||||
#### 2. Layout Persistence
|
||||
**Status**: Default layouts work, persistence stubbed
|
||||
|
||||
**Implemented**:
|
||||
- ✅ Default DockBuilder layouts per editor type
|
||||
- ✅ Layout application on editor activation
|
||||
- ✅ ImGui ini-based persistence (automatic)
|
||||
|
||||
**Missing**:
|
||||
- ❌ SaveCurrentLayout() method (save custom layouts to disk) (45 min - easy)
|
||||
- ❌ LoadLayout() method (restore saved layouts) (45 min - easy)
|
||||
- ❌ Layout presets (Developer/Designer/Modder workspaces) (2 hours - moderate)
|
||||
|
||||
**Total effort**: 3-4 hours | **Impact**: Nice-to-have
|
||||
|
||||
**Implementation Strategy**:
|
||||
```cpp
|
||||
// In layout_manager.cc
|
||||
void LayoutManager::SaveCurrentLayout(const std::string& name);
|
||||
void LayoutManager::LoadLayout(const std::string& name);
|
||||
void LayoutManager::ApplyPreset(const std::string& preset_name);
|
||||
```
|
||||
|
||||
#### 3. Keyboard Shortcut System
|
||||
**Status**: Shortcuts work, rebinding UI missing
|
||||
|
||||
**Implemented**:
|
||||
- ✅ ShortcutConfigurator with all major shortcuts
|
||||
- ✅ Conflict resolution (Ctrl+Alt for card toggles)
|
||||
- ✅ Shortcut documentation in code
|
||||
|
||||
**Missing**:
|
||||
- ❌ Shortcut rebinding UI in Settings > Shortcuts card (2 hours - moderate)
|
||||
- ❌ Shortcut persistence to user config file (1 hour - easy)
|
||||
- ❌ Shortcut reset to defaults functionality (30 min - easy)
|
||||
|
||||
**Total effort**: 3-4 hours | **Impact**: Enhancement
|
||||
|
||||
**Implementation Strategy**:
|
||||
```cpp
|
||||
// In settings_editor.cc, expand Shortcuts card
|
||||
// 1. Create ImGui table of shortcuts with rebind buttons
|
||||
// 2. Implement key capture dialog
|
||||
// 3. Save to ~/.yaze/shortcuts.yaml on change
|
||||
// 4. Load at startup before shortcut registration
|
||||
```
|
||||
|
||||
#### 4. Session Management UI
|
||||
**Status**: Multi-session works, UI missing
|
||||
|
||||
**Implemented**:
|
||||
- ✅ SessionCoordinator foundation
|
||||
- ✅ Session-aware card visibility
|
||||
- ✅ Session creation/deletion
|
||||
|
||||
**Missing**:
|
||||
- ❌ DrawSessionList() - visual session browser (1.5 hours - moderate)
|
||||
- ❌ DrawSessionControls() - batch operations (1 hour - easy)
|
||||
- ❌ DrawSessionInfo() - session statistics (1 hour - easy)
|
||||
- ❌ DrawSessionBadges() - status indicators (1 hour - easy)
|
||||
|
||||
**Total effort**: 4-5 hours | **Impact**: Polish
|
||||
|
||||
**Implementation Strategy**:
|
||||
```cpp
|
||||
// In session_coordinator.cc
|
||||
void DrawSessionList(); // Show all sessions in a dropdown/menu
|
||||
void DrawSessionControls(); // Batch close, switch, rename
|
||||
void DrawSessionInfo(); // Memory usage, ROM path, edit count
|
||||
void DrawSessionBadges(); // Dirty indicator, session number
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ❌ NOT IMPLEMENTED - Enhancement Features
|
||||
|
||||
#### 1. Card Browser Window
|
||||
**Status**: Not implemented | **Effort**: 3-4 hours | **Impact**: UX Enhancement
|
||||
|
||||
**Features**:
|
||||
- Ctrl+Shift+B to open card browser
|
||||
- Fuzzy search within card browser
|
||||
- Category filtering
|
||||
- Recently opened cards section
|
||||
- Favorite cards system
|
||||
|
||||
**Implementation**: New UICoordinator window similar to Command Palette
|
||||
|
||||
#### 2. Material Design Components
|
||||
**Status**: Not implemented | **Effort**: 4-5 hours | **Impact**: UI Polish
|
||||
|
||||
**Components**:
|
||||
- DrawMaterialCard() component
|
||||
- DrawMaterialDialog() component
|
||||
- Editor-specific color theming (GetColorForEditor)
|
||||
- ApplyEditorTheme() for context-aware styling
|
||||
|
||||
**Implementation**: Extend ThemeManager with Material Design patterns
|
||||
|
||||
#### 3. Window Management UI
|
||||
**Status**: Not implemented | **Effort**: 2-3 hours | **Impact**: Advanced UX
|
||||
|
||||
**Features**:
|
||||
- DrawWindowManagementUI() - unified window controls
|
||||
- DrawDockingControls() - docking configuration
|
||||
- DrawLayoutControls() - layout management UI
|
||||
|
||||
**Implementation**: New UICoordinator windows for advanced window management
|
||||
|
||||
---
|
||||
|
||||
## Comparison Table
|
||||
|
||||
| Feature | Master | Develop | Status | Gap |
|
||||
|---------|--------|---------|--------|-----|
|
||||
| Welcome Screen | ✅ | ✅ | Parity | None |
|
||||
| Command Palette | ✅ | ✅ | Parity | None |
|
||||
| Global Search | ✅ | ✅+ | Parity | Enhancements |
|
||||
| Sidebar | ✅ | ✅ | Parity | None |
|
||||
| Menus | ✅ | ✅ | Parity | None |
|
||||
| Popups | ✅ | ✅+ | Parity | Type-safety |
|
||||
| Cards (34) | ✅ | ✅ | Parity | None |
|
||||
| Sessions | ❌ | ✅ | Improved | UI only |
|
||||
| Shortcuts | ✅ | ✅ | Parity | Rebinding UI |
|
||||
| Layouts | ❌ | ✅ | Improved | Persistence |
|
||||
| Card Browser | ✅ | ❌ | Gap | 3-4 hrs |
|
||||
| Material Design | ❌ | ❌ | N/A | Enhancement |
|
||||
| Session UI | ❌ | ❌ | N/A | 4-5 hrs |
|
||||
|
||||
---
|
||||
|
||||
## Code Architecture Comparison
|
||||
|
||||
### Master: Monolithic EditorManager
|
||||
```
|
||||
EditorManager (3710 lines)
|
||||
├── Menu building (800+ lines)
|
||||
├── Popup display (400+ lines)
|
||||
├── UI drawing (600+ lines)
|
||||
├── Session management (200+ lines)
|
||||
└── Window management (700+ lines)
|
||||
```
|
||||
|
||||
**Problems**:
|
||||
- Hard to test
|
||||
- Hard to extend
|
||||
- Hard to maintain
|
||||
- All coupled together
|
||||
|
||||
### Develop: Delegated Architecture
|
||||
```
|
||||
EditorManager (2076 lines)
|
||||
├── UICoordinator (829 lines) - UI windows
|
||||
├── MenuOrchestrator (922 lines) - Menus
|
||||
├── PopupManager (365 lines) - Dialogs
|
||||
├── SessionCoordinator (834 lines) - Sessions
|
||||
├── EditorCardRegistry (1018 lines) - Cards
|
||||
├── LayoutManager (413 lines) - Layouts
|
||||
├── ShortcutConfigurator (352 lines) - Shortcuts
|
||||
└── WindowDelegate (315 lines) - Window stubs
|
||||
|
||||
+ 8 specialized managers instead of 1 monolith
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Easy to test (each component independently)
|
||||
- ✅ Easy to extend (add new managers)
|
||||
- ✅ Easy to maintain (clear responsibilities)
|
||||
- ✅ Loosely coupled via dependency injection
|
||||
- ✅ 44% code reduction overall
|
||||
|
||||
---
|
||||
|
||||
## Testing Roadmap
|
||||
|
||||
### Phase 1: Validation (2-3 hours)
|
||||
**Verify that develop matches master in behavior**
|
||||
|
||||
- [ ] Startup: Launch without ROM, welcome screen appears
|
||||
- [ ] All 34 cards appear in sidebar
|
||||
- [ ] Card X buttons close windows
|
||||
- [ ] All 10 layouts render correctly
|
||||
- [ ] All major shortcuts work
|
||||
- [ ] Multi-session independence verified
|
||||
- [ ] No crashes in any feature
|
||||
|
||||
**Success Criteria**: All tests pass OR document specific failures
|
||||
|
||||
### Phase 2: Critical Fixes (0-2 hours - if needed)
|
||||
**Fix any issues discovered during validation**
|
||||
|
||||
- [ ] Missing Debug menu items (if identified)
|
||||
- [ ] Shortcut conflicts (if identified)
|
||||
- [ ] Welcome screen issues (if identified)
|
||||
- [ ] Card visibility issues (if identified)
|
||||
|
||||
**Success Criteria**: All identified issues resolved
|
||||
|
||||
### Phase 3: Gap Resolution (4-6 hours - optional)
|
||||
**Implement missing functionality for nice-to-have features**
|
||||
|
||||
- [ ] Global Search: Text string searching
|
||||
- [ ] Global Search: Map/room name searching
|
||||
- [ ] Global Search: Memory address searching
|
||||
- [ ] Layout persistence: SaveCurrentLayout()
|
||||
- [ ] Layout persistence: LoadLayout()
|
||||
- [ ] Shortcut UI: Rebinding interface
|
||||
|
||||
**Success Criteria**: Features functional and documented
|
||||
|
||||
### Phase 4: Enhancements (8-12 hours - future)
|
||||
**Polish and advanced features**
|
||||
|
||||
- [ ] Card Browser window (Ctrl+Shift+B)
|
||||
- [ ] Material Design components
|
||||
- [ ] Session management UI
|
||||
- [ ] Code cleanup / dead code removal
|
||||
|
||||
**Success Criteria**: Polish complete, ready for production
|
||||
|
||||
---
|
||||
|
||||
## Master Branch Analysis
|
||||
|
||||
### Total Lines in Master
|
||||
```
|
||||
src/app/editor/editor_manager.cc: 3710 lines
|
||||
src/app/editor/editor_manager.h: ~300 lines
|
||||
```
|
||||
|
||||
### Key Methods in Master (Now Delegated)
|
||||
```cpp
|
||||
// Menu methods (800+ lines total)
|
||||
void BuildFileMenu();
|
||||
void BuildViewMenu();
|
||||
void BuildToolsMenu();
|
||||
void BuildDebugMenu();
|
||||
void BuildHelpMenu();
|
||||
void HandleMenuSelection();
|
||||
|
||||
// Popup methods (400+ lines total)
|
||||
void DrawSaveAsDialog();
|
||||
void DrawOpenFileDialog();
|
||||
void DrawDisplaySettings();
|
||||
void DrawHelpMenus();
|
||||
|
||||
// UI drawing methods (600+ lines total)
|
||||
void DrawWelcomeScreen();
|
||||
void DrawCommandPalette();
|
||||
void DrawGlobalSearch();
|
||||
void DrawSidebar();
|
||||
void DrawContextCards();
|
||||
void DrawMenuBar();
|
||||
|
||||
// Session/window management
|
||||
void ManageSession();
|
||||
void RenderWindows();
|
||||
void UpdateLayout();
|
||||
```
|
||||
|
||||
All now properly delegated to specialized managers in develop branch.
|
||||
|
||||
---
|
||||
|
||||
## Remaining TODO Items by Component
|
||||
|
||||
### LayoutManager (2 TODOs)
|
||||
```cpp
|
||||
// [EditorManagerRefactor] TODO: Implement SaveCurrentLayout()
|
||||
// [EditorManagerRefactor] TODO: Implement LoadLayout()
|
||||
```
|
||||
**Effort**: 1.5 hours | **Priority**: Medium
|
||||
|
||||
### UICoordinator (27 TODOs)
|
||||
```cpp
|
||||
// [EditorManagerRefactor] TODO: Text string searching in Global Search
|
||||
// [EditorManagerRefactor] TODO: Map/room name searching
|
||||
// [EditorManagerRefactor] TODO: Memory address/label searching
|
||||
// [EditorManagerRefactor] TODO: Result caching for search
|
||||
```
|
||||
**Effort**: 4-6 hours | **Priority**: Medium
|
||||
|
||||
### SessionCoordinator (9 TODOs)
|
||||
```cpp
|
||||
// [EditorManagerRefactor] TODO: DrawSessionList()
|
||||
// [EditorManagerRefactor] TODO: DrawSessionControls()
|
||||
// [EditorManagerRefactor] TODO: DrawSessionInfo()
|
||||
// [EditorManagerRefactor] TODO: DrawSessionBadges()
|
||||
```
|
||||
**Effort**: 4-5 hours | **Priority**: Low
|
||||
|
||||
### Multiple Editor Files (153 TODOs total)
|
||||
**Status**: Already tagged with [EditorManagerRefactor]
|
||||
**Effort**: Varies | **Priority**: Low (polish items)
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### For Release (Next 6-8 Hours)
|
||||
1. Run comprehensive manual testing (2-3 hours)
|
||||
2. Fix any critical bugs discovered (0-2 hours)
|
||||
3. Verify feature parity with master branch (1-2 hours)
|
||||
4. Update changelog and release notes (1 hour)
|
||||
|
||||
### For 100% Feature Parity (Additional 4-6 Hours)
|
||||
1. Implement Global Search enhancements (4-6 hours)
|
||||
2. Add layout persistence (3-4 hours)
|
||||
3. Create shortcut rebinding UI (3-4 hours)
|
||||
|
||||
### For Fully Polished (Additional 8-12 Hours)
|
||||
1. Card Browser window (3-4 hours)
|
||||
2. Material Design components (4-5 hours)
|
||||
3. Session management UI (4-5 hours)
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
✅ **Achieved**:
|
||||
- 44% code reduction (3710 → 2076 lines)
|
||||
- 90% feature parity with master
|
||||
- All 34 cards working
|
||||
- All 10 layouts implemented
|
||||
- Multi-session support
|
||||
- Type-safe popup system
|
||||
- Delegated architecture (8 components)
|
||||
- Zero compilation errors
|
||||
- Comprehensive documentation
|
||||
|
||||
🟡 **Pending**:
|
||||
- Manual testing validation
|
||||
- Global Search full implementation
|
||||
- Layout persistence
|
||||
- Shortcut rebinding UI
|
||||
- Session management UI
|
||||
|
||||
❌ **Future Work**:
|
||||
- Card Browser window
|
||||
- Material Design system
|
||||
- Advanced window management UI
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The EditorManager refactoring has been **90% successful** in achieving feature parity while improving code quality significantly. The develop branch now has:
|
||||
|
||||
1. **Better Architecture**: 8 specialized components instead of 1 monolith
|
||||
2. **Reduced Complexity**: 44% fewer lines of code
|
||||
3. **Improved Testability**: Each component can be tested independently
|
||||
4. **Better Maintenance**: Clear separation of concerns
|
||||
5. **Feature Parity**: All critical features from master are present
|
||||
|
||||
**Recommendation**: Proceed to manual testing phase to validate functionality and identify any gaps. After validation, prioritize gap resolution features (4-6 hours) before considering enhancements.
|
||||
|
||||
**Next Agent**: Focus on comprehensive manual testing using the checklist provided in Phase 1 of the Testing Roadmap section.
|
||||
|
||||
---
|
||||
|
||||
**Document Status**: Complete
|
||||
**Last Updated**: October 15, 2025
|
||||
**Author**: AI Assistant (Claude Sonnet 4.5)
|
||||
**Review Status**: Ready for validation phase
|
||||
|
||||
514
docs/internal/roadmaps/future-improvements.md
Normal file
514
docs/internal/roadmaps/future-improvements.md
Normal file
@@ -0,0 +1,514 @@
|
||||
# Future Improvements & Long-Term Vision
|
||||
|
||||
**Last Updated:** October 10, 2025
|
||||
**Status:** Living Document
|
||||
|
||||
This document outlines potential improvements, experimental features, and long-term vision for yaze. Items here are aspirational and may or may not be implemented depending on community needs, technical feasibility, and development resources.
|
||||
|
||||
---
|
||||
|
||||
## Architecture & Performance
|
||||
|
||||
### Emulator Core Improvements
|
||||
See `docs/E6-emulator-improvements.md` for detailed emulator improvement roadmap.
|
||||
|
||||
**Priority Items:**
|
||||
- **APU Timing Fix**: Cycle-accurate SPC700 execution for reliable music playback
|
||||
- **CPU Cycle Accuracy**: Variable instruction timing for better game compatibility
|
||||
- **PPU Scanline Renderer**: Replace pixel-based renderer for 20%+ performance boost
|
||||
- **Audio Buffering**: Lock-free ring buffer to eliminate stuttering
|
||||
|
||||
### Plugin Architecture (v0.5.x+)
|
||||
Enable community extensions and custom tools.
|
||||
|
||||
**Features:**
|
||||
- C API for plugin development
|
||||
- Hot-reload capability for rapid iteration
|
||||
- Plugin registry and discovery system
|
||||
- Example plugins (custom exporters, automation tools)
|
||||
|
||||
**Benefits:**
|
||||
- Community can extend without core changes
|
||||
- Experimentation without bloating core
|
||||
- Custom workflow tools per project needs
|
||||
|
||||
### Multi-Threading Improvements
|
||||
Parallelize heavy operations for better performance.
|
||||
|
||||
**Opportunities:**
|
||||
- Background ROM loading
|
||||
- Parallel graphics decompression
|
||||
- Asynchronous file I/O
|
||||
- Worker thread pool for batch operations
|
||||
|
||||
---
|
||||
|
||||
## Graphics & Rendering
|
||||
|
||||
### Advanced Graphics Editing
|
||||
Full graphics sheet import/export workflow.
|
||||
|
||||
**Features:**
|
||||
- Import modified PNG graphics sheets
|
||||
- Automatic palette extraction and optimization
|
||||
- Tile deduplication and compression
|
||||
- Preview impact on ROM size
|
||||
|
||||
**Use Cases:**
|
||||
- Complete graphics overhauls
|
||||
- HD texture packs (with downscaling)
|
||||
- Art asset pipelines
|
||||
|
||||
### Alternative Rendering Backends
|
||||
Support beyond SDL3 for specialized use cases.
|
||||
|
||||
**Potential Backends:**
|
||||
- **OpenGL**: Maximum compatibility, explicit control
|
||||
- **Vulkan**: High-performance, low-overhead (Linux/Windows)
|
||||
- **Metal**: Native macOS/iOS performance
|
||||
- **WebGPU**: Browser-based editor
|
||||
|
||||
**Benefits:**
|
||||
- Platform-specific optimization
|
||||
- Testing without hardware dependencies
|
||||
- Future-proofing for new platforms
|
||||
|
||||
### High-DPI / 4K Support
|
||||
Perfect rendering on modern displays.
|
||||
|
||||
**Improvements:**
|
||||
- Retina/4K-aware canvas rendering
|
||||
- Scalable UI elements
|
||||
- Crisp text at any zoom level
|
||||
- Per-monitor DPI awareness
|
||||
|
||||
---
|
||||
|
||||
## AI & Automation
|
||||
|
||||
### Autonomous Debugging Enhancements
|
||||
|
||||
Advanced features for AI-driven emulator debugging (see E9-ai-agent-debugging-guide.md for current capabilities).
|
||||
|
||||
#### Pattern 1: Automated Bug Reproduction
|
||||
```python
|
||||
def reproduce_bug_scenario():
|
||||
"""Reproduce a specific bug automatically"""
|
||||
# 1. Load game state
|
||||
stub.LoadState(StateRequest(slot=1))
|
||||
|
||||
# 2. Set breakpoint at suspected bug location
|
||||
stub.AddBreakpoint(BreakpointRequest(
|
||||
address=0x01A5C0, # Enemy spawn routine
|
||||
type=BreakpointType.EXECUTE,
|
||||
description="Bug: enemy spawns in wall"
|
||||
))
|
||||
|
||||
# 3. Automate input to trigger bug
|
||||
stub.PressButtons(ButtonRequest(buttons=[Button.UP]))
|
||||
stub.HoldButtons(ButtonHoldRequest(buttons=[Button.A], duration_ms=500))
|
||||
|
||||
# 4. Wait for breakpoint
|
||||
hit = stub.RunToBreakpoint(Empty())
|
||||
if hit.hit:
|
||||
# 5. Capture state for analysis
|
||||
memory = stub.ReadMemory(MemoryRequest(
|
||||
address=0x7E0000, # WRAM
|
||||
size=0x10000
|
||||
))
|
||||
|
||||
# 6. Analyze and log
|
||||
analyze_enemy_spawn_state(hit.cpu_state, memory.data)
|
||||
|
||||
return True
|
||||
return False
|
||||
```
|
||||
|
||||
#### Pattern 2: Automated Code Coverage Analysis
|
||||
```python
|
||||
def analyze_code_coverage():
|
||||
"""Find untested code paths"""
|
||||
# 1. Enable disassembly recording
|
||||
stub.CreateDebugSession(DebugSessionRequest(
|
||||
session_name="coverage_test",
|
||||
enable_all_features=True
|
||||
))
|
||||
|
||||
# 2. Run gameplay for 10 minutes
|
||||
stub.Start(Empty())
|
||||
time.sleep(600)
|
||||
stub.Pause(Empty())
|
||||
|
||||
# 3. Get execution trace
|
||||
disasm = stub.GetDisassembly(DisassemblyRequest(
|
||||
start_address=0x008000,
|
||||
count=10000,
|
||||
include_execution_count=True
|
||||
))
|
||||
|
||||
# 4. Find unexecuted code
|
||||
unexecuted = [line for line in disasm.lines if line.execution_count == 0]
|
||||
|
||||
print(f"Code coverage: {len(disasm.lines) - len(unexecuted)}/{len(disasm.lines)}")
|
||||
print(f"Untested code at:")
|
||||
for line in unexecuted[:20]: # Show first 20
|
||||
print(f" ${line.address:06X}: {line.mnemonic} {line.operand_str}")
|
||||
```
|
||||
|
||||
#### Pattern 3: Autonomous Bug Hunting
|
||||
```python
|
||||
def hunt_for_bugs():
|
||||
"""AI-driven bug detection"""
|
||||
# Set watchpoints on critical variables
|
||||
watchpoints = [
|
||||
("LinkHealth", 0x7EF36D, 0x7EF36D, True, True),
|
||||
("LinkPos", 0x7E0020, 0x7E0023, False, True),
|
||||
("RoomID", 0x7E00A0, 0x7E00A1, False, True),
|
||||
]
|
||||
|
||||
for name, start, end, track_reads, track_writes in watchpoints:
|
||||
stub.AddWatchpoint(WatchpointRequest(
|
||||
start_address=start,
|
||||
end_address=end,
|
||||
track_reads=track_reads,
|
||||
track_writes=track_writes,
|
||||
break_on_access=False,
|
||||
description=name
|
||||
))
|
||||
|
||||
# Run game with random inputs
|
||||
stub.Start(Empty())
|
||||
|
||||
for _ in range(1000): # 1000 random actions
|
||||
button = random.choice([Button.UP, Button.DOWN, Button.LEFT,
|
||||
Button.RIGHT, Button.A, Button.B])
|
||||
stub.PressButtons(ButtonRequest(buttons=[button]))
|
||||
time.sleep(0.1)
|
||||
|
||||
# Check for anomalies every 10 actions
|
||||
if _ % 10 == 0:
|
||||
status = stub.GetDebugStatus(Empty())
|
||||
|
||||
# Check for crashes or freezes
|
||||
if status.fps < 30:
|
||||
print(f"ANOMALY: Low FPS detected ({status.fps:.2f})")
|
||||
save_crash_dump(status)
|
||||
|
||||
# Check for memory corruption
|
||||
health = stub.ReadMemory(MemoryRequest(
|
||||
address=0x7EF36D, size=1
|
||||
))
|
||||
if health.data[0] > 0xA8: # Max health
|
||||
print(f"BUG: Health overflow! Value: {health.data[0]:02X}")
|
||||
stub.Pause(Empty())
|
||||
break
|
||||
```
|
||||
|
||||
#### Future API Extensions
|
||||
```protobuf
|
||||
// Time-travel debugging
|
||||
rpc Rewind(RewindRequest) returns (CommandResponse);
|
||||
rpc SetCheckpoint(CheckpointRequest) returns (CheckpointResponse);
|
||||
rpc RestoreCheckpoint(CheckpointIdRequest) returns (CommandResponse);
|
||||
|
||||
// Lua scripting
|
||||
rpc ExecuteLuaScript(LuaScriptRequest) returns (LuaScriptResponse);
|
||||
rpc RegisterLuaCallback(LuaCallbackRequest) returns (CommandResponse);
|
||||
|
||||
// Performance profiling
|
||||
rpc StartProfiling(ProfileRequest) returns (CommandResponse);
|
||||
rpc StopProfiling(Empty) returns (ProfileResponse);
|
||||
rpc GetHotPaths(HotPathRequest) returns (HotPathResponse);
|
||||
```
|
||||
|
||||
### Multi-Modal AI Input
|
||||
Enhance `z3ed` with visual understanding.
|
||||
|
||||
**Features:**
|
||||
- Screenshot → context for AI
|
||||
- "Fix this room" with image reference
|
||||
- Visual diff analysis
|
||||
- Automatic sprite positioning from mockups
|
||||
|
||||
### Collaborative AI Sessions
|
||||
Shared AI context in multiplayer editing.
|
||||
|
||||
**Features:**
|
||||
- Shared AI conversation history
|
||||
- AI-suggested edits visible to all users
|
||||
- Collaborative problem-solving
|
||||
- Role-based AI permissions
|
||||
|
||||
### Automation & Scripting
|
||||
Python/Lua scripting for batch operations.
|
||||
|
||||
**Use Cases:**
|
||||
- Batch room modifications
|
||||
- Automated testing scripts
|
||||
- Custom validation rules
|
||||
- Import/export pipelines
|
||||
|
||||
---
|
||||
|
||||
## Content Editors
|
||||
|
||||
### Music Editor UI
|
||||
Visual interface for sound and music editing.
|
||||
|
||||
**Features:**
|
||||
- Visual SPC700 music track editor
|
||||
- Sound effect browser and editor
|
||||
- Import custom SPC files
|
||||
- Live preview while editing
|
||||
|
||||
### Dialogue Editor
|
||||
Comprehensive text editing system.
|
||||
|
||||
**Features:**
|
||||
- Visual dialogue tree editor
|
||||
- Text search across all dialogues
|
||||
- Translation workflow support
|
||||
- Character count warnings
|
||||
- Preview in-game font rendering
|
||||
|
||||
### Event Editor
|
||||
Visual scripting for game events.
|
||||
|
||||
**Features:**
|
||||
- Node-based event editor
|
||||
- Trigger condition builder
|
||||
- Preview event flow
|
||||
- Debug event sequences
|
||||
|
||||
### Hex Editor Enhancements
|
||||
Power-user tool for low-level editing.
|
||||
|
||||
**Features:**
|
||||
- Structure definitions (parse ROM data types)
|
||||
- Search by data pattern
|
||||
- Diff view between ROM versions
|
||||
- Bookmark system for addresses
|
||||
- Disassembly view integration
|
||||
|
||||
---
|
||||
|
||||
## Collaboration & Networking
|
||||
|
||||
### Real-Time Collaboration Improvements
|
||||
Enhanced multi-user editing.
|
||||
|
||||
**Features:**
|
||||
- Conflict resolution strategies
|
||||
- User presence indicators (cursor position)
|
||||
- Chat integration
|
||||
- Permission system (read-only, edit, admin)
|
||||
- Rollback/version control
|
||||
|
||||
### Cloud ROM Storage
|
||||
Optional cloud backup and sync.
|
||||
|
||||
**Features:**
|
||||
- Encrypted cloud storage
|
||||
- Automatic backups
|
||||
- Cross-device sync
|
||||
- Shared project workspaces
|
||||
- Version history
|
||||
|
||||
---
|
||||
|
||||
## Platform Support
|
||||
|
||||
### Web Assembly Build
|
||||
Browser-based yaze editor.
|
||||
|
||||
**Benefits:**
|
||||
- No installation required
|
||||
- Cross-platform by default
|
||||
- Shareable projects via URL
|
||||
- Integrated with cloud storage
|
||||
|
||||
**Challenges:**
|
||||
- File system access limitations
|
||||
- Performance considerations
|
||||
- WebGPU renderer requirement
|
||||
|
||||
### Mobile Support (iOS/Android)
|
||||
Touch-optimized editor for tablets.
|
||||
|
||||
**Features:**
|
||||
- Touch-friendly UI
|
||||
- Stylus support
|
||||
- Cloud sync with desktop
|
||||
- Read-only preview mode for phones
|
||||
|
||||
**Use Cases:**
|
||||
- Tablet editing on the go
|
||||
- Reference/preview on phone
|
||||
- Show ROM to players on mobile
|
||||
|
||||
---
|
||||
|
||||
## Quality of Life
|
||||
|
||||
### Undo/Redo System Enhancement
|
||||
More granular and reliable undo.
|
||||
|
||||
**Improvements:**
|
||||
- Per-editor undo stacks
|
||||
- Undo history viewer
|
||||
- Branching undo (tree structure)
|
||||
- Persistent undo across sessions
|
||||
|
||||
### Project Templates
|
||||
Quick-start templates for common ROM hacks.
|
||||
|
||||
**Templates:**
|
||||
- Vanilla+ (minimal changes)
|
||||
- Graphics overhaul
|
||||
- Randomizer base
|
||||
- Custom story framework
|
||||
|
||||
### Asset Library
|
||||
Shared library of community assets.
|
||||
|
||||
**Features:**
|
||||
- Import community sprites/graphics
|
||||
- Share custom rooms/dungeons
|
||||
- Tag-based search
|
||||
- Rating and comments
|
||||
- License tracking
|
||||
|
||||
### Accessibility
|
||||
Make yaze usable by everyone.
|
||||
|
||||
**Features:**
|
||||
- Screen reader support
|
||||
- Keyboard-only navigation
|
||||
- Colorblind-friendly palettes
|
||||
- High-contrast themes
|
||||
- Adjustable font sizes
|
||||
|
||||
---
|
||||
|
||||
## Testing & Quality
|
||||
|
||||
### Automated Regression Testing
|
||||
Catch bugs before they ship.
|
||||
|
||||
**Features:**
|
||||
- Automated UI testing framework
|
||||
- Visual regression tests (screenshot diffs)
|
||||
- Performance regression detection
|
||||
- Automated ROM patching tests
|
||||
|
||||
### ROM Validation
|
||||
Ensure ROM hacks are valid.
|
||||
|
||||
**Features:**
|
||||
- Detect common errors (invalid pointers, etc.)
|
||||
- Warn about compatibility issues
|
||||
- Suggest fixes for problems
|
||||
- Export validation report
|
||||
|
||||
### Continuous Integration Enhancements
|
||||
Better CI/CD pipeline.
|
||||
|
||||
**Improvements:**
|
||||
- Build artifacts for every commit
|
||||
- Automated performance benchmarks
|
||||
- Coverage reports
|
||||
- Security scanning
|
||||
|
||||
---
|
||||
|
||||
## Documentation & Community
|
||||
|
||||
### API Documentation Generator
|
||||
Auto-generated API docs from code.
|
||||
|
||||
**Features:**
|
||||
- Doxygen → web docs pipeline
|
||||
- Example code snippets
|
||||
- Interactive API explorer
|
||||
- Versioned documentation
|
||||
|
||||
### Video Tutorial System
|
||||
In-app video tutorials.
|
||||
|
||||
**Features:**
|
||||
- Embedded tutorial videos
|
||||
- Step-by-step guided walkthroughs
|
||||
- Context-sensitive help
|
||||
- Community-contributed tutorials
|
||||
|
||||
### ROM Hacking Wiki Integration
|
||||
Link editor to wiki documentation.
|
||||
|
||||
**Features:**
|
||||
- Context-sensitive wiki links
|
||||
- Inline documentation for ROM structures
|
||||
- Community knowledge base
|
||||
- Translation support
|
||||
|
||||
---
|
||||
|
||||
## Experimental / Research
|
||||
|
||||
### Machine Learning Integration
|
||||
AI-assisted ROM hacking.
|
||||
|
||||
**Possibilities:**
|
||||
- Auto-generate room layouts
|
||||
- Suggest difficulty curves
|
||||
- Detect similar room patterns
|
||||
- Generate sprite variations
|
||||
|
||||
### VR/AR Visualization
|
||||
Visualize SNES data in 3D.
|
||||
|
||||
**Use Cases:**
|
||||
- 3D preview of overworld
|
||||
- Virtual dungeon walkthrough
|
||||
- Spatial room editing
|
||||
|
||||
### Symbolic Execution
|
||||
Advanced debugging technique.
|
||||
|
||||
**Features:**
|
||||
- Explore all code paths
|
||||
- Find unreachable code
|
||||
- Detect potential bugs
|
||||
- Generate test cases
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
These improvements are **not scheduled** and exist here as ideas for future development. Priority will be determined by:
|
||||
|
||||
1. **Community demand** - What users actually need
|
||||
2. **Technical feasibility** - What's possible with current architecture
|
||||
3. **Development resources** - Available time and expertise
|
||||
4. **Strategic fit** - Alignment with project vision
|
||||
|
||||
---
|
||||
|
||||
## Contributing Ideas
|
||||
|
||||
Have an idea for a future improvement?
|
||||
|
||||
- Open a GitHub Discussion in the "Ideas" category
|
||||
- Describe the problem it solves
|
||||
- Outline potential implementation approach
|
||||
- Consider technical challenges
|
||||
|
||||
The best ideas are:
|
||||
- **Specific**: Clear problem statement
|
||||
- **Valuable**: Solves real user pain points
|
||||
- **Feasible**: Realistic implementation
|
||||
- **Scoped**: Can be broken into phases
|
||||
|
||||
---
|
||||
|
||||
**Note:** This is a living document. Ideas may be promoted to the active roadmap (`I1-roadmap.md`) or removed as project priorities evolve.
|
||||
|
||||
104
docs/internal/roadmaps/roadmap.md
Normal file
104
docs/internal/roadmaps/roadmap.md
Normal file
@@ -0,0 +1,104 @@
|
||||
# Roadmap
|
||||
|
||||
**Last Updated: October 4, 2025**
|
||||
|
||||
This roadmap tracks upcoming releases and major ongoing initiatives.
|
||||
|
||||
## Current Focus
|
||||
|
||||
- Finish overworld editor parity (sprite workflows, performance tuning).
|
||||
- Resolve dungeon object rendering and tile painting gaps.
|
||||
- Close out Tile16 palette inconsistencies.
|
||||
- Harden the `z3ed` automation paths before expanding functionality.
|
||||
|
||||
## 0.4.0 (Next Major Release) - SDL3 Modernization & Core Improvements
|
||||
|
||||
**Status:** Planning
|
||||
**Type:** Major Breaking Release
|
||||
**Timeline:** 6-8 weeks
|
||||
|
||||
### Primary Goals
|
||||
|
||||
1. SDL3 migration across graphics, audio, and input
|
||||
2. Dependency reorganization (`src/lib/` + `third_party/` → `external/`)
|
||||
3. Backend abstraction layer for renderer/audio/input
|
||||
4. Editor polish and UX clean-up
|
||||
|
||||
### Phase 1: Infrastructure (Week 1-2)
|
||||
- Merge `src/lib/` and `third_party/` into `external/`
|
||||
- Update CMake, submodules, and CI presets
|
||||
- Validate builds on Windows, macOS, Linux
|
||||
|
||||
### Phase 2: SDL3 Core Migration (Week 3-4)
|
||||
- Switch to SDL3 with GPU-based rendering
|
||||
- Introduce `GraphicsBackend` abstraction
|
||||
- Restore window creation and baseline editor rendering
|
||||
- Update the ImGui SDL3 backend
|
||||
|
||||
### Phase 3: Complete SDL3 Integration (Week 5-6)
|
||||
- Port editors (Overworld, Dungeon, Graphics, Palette, Screen, Music) to the new backend
|
||||
- Implement SDL3 audio backend for the emulator
|
||||
- Implement SDL3 input backend with improved gamepad support
|
||||
- Benchmark and tune rendering performance
|
||||
|
||||
### Phase 4: Editor Features & UX (Week 7-8)
|
||||
- Resolve Tile16 palette inconsistencies
|
||||
- Complete overworld sprite add/remove/move workflow
|
||||
- Improve dungeon editor labels and tab management
|
||||
- Add lazy loading for rooms to cut load times
|
||||
|
||||
### Phase 5: AI Agent Enhancements (Throughout)
|
||||
- Vim-style editing in `simple-chat` (complete)
|
||||
- Autocomplete engine with fuzzy matching (complete)
|
||||
- Harden live LLM integration (Gemini function-calling, prompts)
|
||||
- Attach AI workflows to GUI regression harness
|
||||
- Extend tool coverage for dialogue, music, sprite data
|
||||
|
||||
### Success Criteria
|
||||
- SDL3 builds pass on Windows, macOS, Linux
|
||||
- No performance regression versus v0.3.x
|
||||
- Editors function on the new backend
|
||||
- Emulator audio/input verified
|
||||
- Documentation and migration guide updated
|
||||
|
||||
**Breaking Changes:**
|
||||
- SDL2 → SDL3 (requires recompilation)
|
||||
- Directory restructure (requires submodule re-init)
|
||||
- API changes in graphics backend (for extensions)
|
||||
|
||||
---
|
||||
|
||||
## 0.5.X - Feature Expansion
|
||||
|
||||
- **Plugin Architecture**: Design and implement the initial framework for community-developed extensions and custom tools.
|
||||
- **Advanced Graphics Editing**: Implement functionality to edit and re-import full graphics sheets.
|
||||
- **`z3ed` AI Agent Enhancements**:
|
||||
- **Collaborative Sessions**: Enhance the network collaboration mode with shared AI proposals and ROM synchronization.
|
||||
- **Multi-modal Input**: Integrate screenshot capabilities to send visual context to Gemini for more accurate, context-aware commands.
|
||||
|
||||
---
|
||||
|
||||
## 0.6.X - Content & Integration
|
||||
|
||||
- **Advanced Content Editors**:
|
||||
- Implement a user interface for the music editing system.
|
||||
- Enhance the Hex Editor with better search and data interpretation features.
|
||||
- **Documentation Overhaul**:
|
||||
- Implement a system to auto-generate C++ API documentation from Doxygen comments.
|
||||
- Write a comprehensive user guide for ROM hackers, covering all major editor workflows.
|
||||
|
||||
---
|
||||
|
||||
## Recently Completed (v0.3.3 - October 6, 2025)
|
||||
|
||||
- Vim mode for `simple-chat`: modal editing, navigation, history, autocomplete
|
||||
- Autocomplete engine with fuzzy matching and FTXUI dropdown
|
||||
- TUI enhancements: integrated autocomplete UI components and CMake wiring
|
||||
|
||||
## Recently Completed (v0.3.2)
|
||||
|
||||
- Dungeon editor: migrated to `TestRomManager`, resolved crash backlog
|
||||
- Windows build: fixed stack overflows and file dialog regressions
|
||||
- `z3ed learn`: added persistent storage for AI preferences and ROM metadata
|
||||
- Gemini integration: switched to native function calling API
|
||||
- Tile16 editor: refactored layout, added dynamic zoom controls
|
||||
Reference in New Issue
Block a user