285 lines
9.5 KiB
Markdown
285 lines
9.5 KiB
Markdown
# Initiative: YAZE v0.4.0 - SDL3 Modernization & Emulator Accuracy
|
|
|
|
**Created**: 2025-11-23
|
|
**Last Updated**: 2025-11-27
|
|
**Owner**: Multi-agent coordination
|
|
**Status**: ACTIVE
|
|
**Target Release**: Q1 2026
|
|
|
|
---
|
|
|
|
## Executive Summary
|
|
|
|
YAZE v0.4.0 represents a major release focusing on two pillars:
|
|
1. **Emulator Accuracy** - Implementing cycle-accurate PPU rendering and AI integration
|
|
2. **SDL3 Modernization** - Migrating from SDL2 to SDL3 with backend abstractions
|
|
|
|
This initiative coordinates 7 specialized agents across 5 parallel workstreams.
|
|
|
|
---
|
|
|
|
## Background
|
|
|
|
### Current State (v0.3.9)
|
|
- ✅ AI agent infrastructure complete (z3ed CLI, Phases 1-4)
|
|
- ✅ Card-based UI system functional (EditorManager refactoring complete)
|
|
- ✅ Emulator debugging framework established
|
|
- ✅ CI/CD pipeline optimized (PR runs ~5-10 min)
|
|
- ✅ WASM web port complete (experimental/preview - editors incomplete)
|
|
- ✅ SDL3 backend infrastructure complete (17 abstraction files)
|
|
- ✅ Semantic Inspection API Phase 1 complete
|
|
- ✅ Public documentation reviewed and updated (web app guide added)
|
|
- 🟡 Active work: Emulator render service, input persistence, UI refinements
|
|
- 🟡 Known issues: Dungeon object rendering, ZSOW v3 palettes, WASM release crash
|
|
|
|
### Recently Completed Infrastructure (November 2025)
|
|
- SDL3 backend interfaces (IWindowBackend/IAudioBackend/IInputBackend/IRenderer)
|
|
- WASM platform layer (8 phases complete, experimental/preview status)
|
|
- AI agent tools (meta-tools, schemas, context, batching, validation)
|
|
- EditorManager delegation architecture (8 specialized managers)
|
|
- GUI bug fixes (BeginChild/EndChild patterns, duplicate rendering)
|
|
- Documentation cleanup and web app user guide
|
|
- Format documentation organization (moved to public/reference/)
|
|
|
|
---
|
|
|
|
## Milestones
|
|
|
|
### Milestone 1: Emulator Accuracy (Weeks 1-6)
|
|
|
|
#### 1.1 PPU JIT Catch-up Completion
|
|
**Agent**: `snes-emulator-expert`
|
|
**Status**: IN_PROGRESS (uncommitted work exists)
|
|
**Files**: `src/app/emu/video/ppu.cc`, `src/app/emu/video/ppu.h`
|
|
|
|
**Tasks**:
|
|
- [x] Add `last_rendered_x_` tracking
|
|
- [x] Implement `StartLine()` method
|
|
- [x] Implement `CatchUp(h_pos)` method
|
|
- [ ] Integrate `CatchUp()` calls into `Snes::WriteBBus`
|
|
- [ ] Add unit tests for mid-scanline register writes
|
|
- [ ] Verify with raster-effect test ROMs
|
|
|
|
**Success Criteria**: Games with H-IRQ effects (Tales of Phantasia, Star Ocean) render correctly
|
|
|
|
#### 1.2 Semantic Inspection API
|
|
**Agent**: `ai-infra-architect`
|
|
**Status**: ✅ PHASE 1 COMPLETE
|
|
**Files**: `src/app/emu/debug/semantic_introspection.h/cc`
|
|
|
|
**Tasks**:
|
|
- [x] Create `SemanticIntrospectionEngine` class
|
|
- [x] Connect to `Memory` and `SymbolProvider`
|
|
- [x] Implement `GetPlayerState()` using ALTTP RAM offsets
|
|
- [x] Implement `GetSpriteState()` for sprite tracking
|
|
- [x] Add JSON export for AI consumption
|
|
- [ ] Create debug overlay rendering for vision models (Phase 2)
|
|
|
|
**Success Criteria**: ✅ AI agents can query game state semantically via JSON API
|
|
|
|
#### 1.3 State Injection API
|
|
**Agent**: `snes-emulator-expert`
|
|
**Status**: PLANNED
|
|
**Files**: `src/app/emu/emulator.h/cc`, new `src/app/emu/state_patch.h`
|
|
|
|
**Tasks**:
|
|
- [ ] Define `GameStatePatch` structure
|
|
- [ ] Implement `Emulator::InjectState(patch)`
|
|
- [ ] Add fast-boot capability (skip intro sequences)
|
|
- [ ] Create ALTTP-specific presets (Dungeon Test, Overworld Test)
|
|
- [ ] Integrate with z3ed CLI for "test sprite" workflow
|
|
|
|
**Success Criteria**: Editors can teleport emulator to any game state programmatically
|
|
|
|
#### 1.4 Audio System Fix
|
|
**Agent**: `snes-emulator-expert`
|
|
**Status**: PLANNED
|
|
**Files**: `src/app/emu/audio/`, `src/app/emu/apu/`
|
|
|
|
**Tasks**:
|
|
- [ ] Diagnose SDL2 audio device initialization
|
|
- [ ] Fix SPC700 → SDL2 format conversion
|
|
- [ ] Verify APU handshake timing
|
|
- [ ] Add audio debugging tools to UI
|
|
- [ ] Test with music playback in ALTTP
|
|
|
|
**Success Criteria**: Audio plays correctly during emulation
|
|
|
|
---
|
|
|
|
### Milestone 2: SDL3 Migration (Weeks 3-8)
|
|
|
|
#### 2.1 Directory Restructure
|
|
**Agent**: `backend-infra-engineer`
|
|
**Status**: IN_PROGRESS
|
|
**Scope**: Move `src/lib/` + `third_party/` → `external/`
|
|
|
|
**Tasks**:
|
|
- [ ] Create `external/` directory structure
|
|
- [ ] Move SDL2 (to be replaced), imgui, etc.
|
|
- [ ] Update CMakeLists.txt references
|
|
- [ ] Update submodule paths
|
|
- [ ] Validate builds on all platforms
|
|
|
|
#### 2.2 SDL3 Backend Infrastructure
|
|
**Agent**: `imgui-frontend-engineer`
|
|
**Status**: ✅ COMPLETE (commit a5dc884612)
|
|
**Files**: `src/app/platform/`, `src/app/emu/audio/`, `src/app/emu/input/`, `src/app/gfx/backend/`
|
|
|
|
**Tasks**:
|
|
- [x] Create `IWindowBackend` abstraction interface
|
|
- [x] Create `IAudioBackend` abstraction interface
|
|
- [x] Create `IInputBackend` abstraction interface
|
|
- [x] Create `IRenderer` abstraction interface
|
|
- [x] 17 new abstraction files for backend system
|
|
- [ ] Implement SDL3 concrete backend (next phase)
|
|
- [ ] Update ImGui to SDL3 backend
|
|
- [ ] Port window creation and event handling
|
|
|
|
#### 2.3 SDL3 Audio Backend
|
|
**Agent**: `snes-emulator-expert`
|
|
**Status**: PLANNED (after audio fix)
|
|
**Files**: `src/app/emu/audio/sdl3_audio_backend.h/cc`
|
|
|
|
**Tasks**:
|
|
- [ ] Implement `IAudioBackend` for SDL3
|
|
- [ ] Migrate audio initialization code
|
|
- [ ] Verify audio quality matches SDL2
|
|
|
|
#### 2.4 SDL3 Input Backend
|
|
**Agent**: `imgui-frontend-engineer`
|
|
**Status**: PLANNED
|
|
**Files**: `src/app/emu/ui/input_handler.cc`
|
|
|
|
**Tasks**:
|
|
- [ ] Implement SDL3 input backend
|
|
- [ ] Add gamepad support improvements
|
|
- [ ] Verify continuous key polling works
|
|
|
|
---
|
|
|
|
### Milestone 3: Editor Fixes (Weeks 2-4)
|
|
|
|
#### 3.1 Tile16 Palette System Fix
|
|
**Agent**: `zelda3-hacking-expert`
|
|
**Status**: PLANNED
|
|
**Files**: `src/app/editor/graphics/tile16_editor.cc`
|
|
|
|
**Tasks**:
|
|
- [ ] Fix Tile8 source canvas palette application
|
|
- [ ] Fix palette button 0-7 switching logic
|
|
- [ ] Ensure color alignment across canvases
|
|
- [ ] Add unit tests for palette operations
|
|
|
|
**Success Criteria**: Tile editing workflow fully functional
|
|
|
|
#### 3.2 Overworld Sprite Movement
|
|
**Agent**: `zelda3-hacking-expert`
|
|
**Status**: PLANNED
|
|
**Files**: `src/app/editor/overworld/overworld_editor.cc`
|
|
|
|
**Tasks**:
|
|
- [ ] Debug canvas interaction system
|
|
- [ ] Fix drag operation handling for sprites
|
|
- [ ] Test sprite placement workflow
|
|
|
|
**Success Criteria**: Sprites respond to drag operations
|
|
|
|
#### 3.3 Dungeon Sprite Save Integration
|
|
**Agent**: `zelda3-hacking-expert`
|
|
**Status**: IN_PROGRESS (uncommitted)
|
|
**Files**: `src/zelda3/dungeon/room.cc/h`
|
|
|
|
**Tasks**:
|
|
- [x] Implement `EncodeSprites()` method
|
|
- [x] Implement `SaveSprites()` method
|
|
- [ ] Integrate with dungeon editor UI
|
|
- [ ] Add unit tests
|
|
- [ ] Commit and verify CI
|
|
|
|
---
|
|
|
|
## Agent Assignments
|
|
|
|
| Agent | Primary Responsibilities | Workstream |
|
|
|-------|-------------------------|------------|
|
|
| `snes-emulator-expert` | PPU catch-up, audio fix, state injection, SDL3 audio | Stream 1 |
|
|
| `imgui-frontend-engineer` | SDL3 core, SDL3 input, UI updates | Stream 2 |
|
|
| `zelda3-hacking-expert` | Tile16 fix, sprite movement, dungeon save | Stream 3 |
|
|
| `ai-infra-architect` | Semantic API, multimodal context | Stream 4 |
|
|
| `backend-infra-engineer` | Directory restructure, CI updates | Stream 2 |
|
|
| `test-infrastructure-expert` | Test suite for new features | Support |
|
|
| `docs-janitor` | Documentation updates | Support |
|
|
|
|
---
|
|
|
|
## Parallel Workstreams
|
|
|
|
```
|
|
Week 1-2:
|
|
├── Stream 1: snes-emulator-expert → Complete PPU catch-up
|
|
├── Stream 3: zelda3-hacking-expert → Tile16 palette fix
|
|
└── Stream 4: ai-infra-architect → Semantic API design
|
|
|
|
Week 3-4:
|
|
├── Stream 1: snes-emulator-expert → Audio system fix
|
|
├── Stream 2: backend-infra-engineer → Directory restructure
|
|
├── Stream 3: zelda3-hacking-expert → Sprite movement fix
|
|
└── Stream 4: ai-infra-architect → Semantic API implementation
|
|
|
|
Week 5-6:
|
|
├── Stream 1: snes-emulator-expert → State injection API
|
|
├── Stream 2: imgui-frontend-engineer → SDL3 core integration
|
|
└── Stream 3: zelda3-hacking-expert → Dungeon sprite integration
|
|
|
|
Week 7-8:
|
|
├── Stream 1: snes-emulator-expert → SDL3 audio backend
|
|
├── Stream 2: imgui-frontend-engineer → SDL3 input backend
|
|
└── All: Integration testing and stabilization
|
|
```
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
### v0.4.0 Release Readiness
|
|
- [ ] PPU catch-up renders raster effects correctly
|
|
- [ ] Semantic API provides structured game state (Phase 1 ✅, Phase 2 pending)
|
|
- [ ] State injection enables "test sprite" workflow
|
|
- [ ] Audio system functional
|
|
- [ ] SDL3 builds pass on Windows, macOS, Linux
|
|
- [ ] No performance regression vs v0.3.x
|
|
- [ ] Critical editor bugs resolved (dungeon rendering, ZSOW v3 palettes)
|
|
- [ ] WASM release build stabilized
|
|
- [x] Documentation updated for v0.3.9 features (web app, format specs)
|
|
|
|
---
|
|
|
|
## Risk Mitigation
|
|
|
|
| Risk | Probability | Impact | Mitigation |
|
|
|------|-------------|--------|------------|
|
|
| SDL3 breaking changes | Medium | High | Maintain SDL2 fallback branch |
|
|
| Audio system complexity | High | Medium | Prioritize diagnosis before migration |
|
|
| Cross-platform issues | Medium | Medium | CI validation on all platforms |
|
|
| Agent coordination conflicts | Low | Medium | Strict coordination board protocol |
|
|
|
|
---
|
|
|
|
## Communication
|
|
|
|
- **Daily**: Coordination board updates
|
|
- **Weekly**: Progress sync via initiative status
|
|
- **Blockers**: Post `BLOCKER` tag on coordination board immediately
|
|
- **Handoffs**: Use `REQUEST →` format for task transitions
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- [Emulator Accuracy Report](emulator_accuracy_report.md)
|
|
- [Roadmap](../roadmaps/roadmap.md)
|
|
- [Feature Parity Analysis](../roadmaps/feature-parity-analysis.md)
|
|
- [Code Review Next Steps](../roadmaps/code-review-critical-next-steps.md)
|
|
- [Coordination Board](coordination-board.md)
|