yaze/docs/H1-changelog.md

Changelog

0.3.3 (October 2025)

Emulator: Audio System Infrastructure ✅ COMPLETE

Audio Backend Abstraction:

• IAudioBackend Interface: Clean abstraction layer for audio implementations, enabling easy migration between SDL2, SDL3, and custom backends
• SDL2AudioBackend: Complete implementation with volume control, status queries, and smart buffer management (2-6 frames)
• AudioBackendFactory: Factory pattern for creating backends with minimal coupling
• Benefits: Future-proof audio system, easy to add platform-native backends (CoreAudio, WASAPI, PulseAudio)

APU Debugging System:

• ApuHandshakeTracker: Monitors CPU-SPC700 communication in real-time
• Phase Tracking: Tracks handshake progression (RESET → IPL_BOOT → WAITING_BBAA → HANDSHAKE_CC → TRANSFER_ACTIVE → RUNNING)
• Port Activity Monitor: Records last 1000 port write events with PC addresses
• Visual Debugger UI: Real-time phase display, port activity log, transfer progress bars, force handshake testing
• Integration: Connected to both CPU (Snes::WriteBBus) and SPC700 (Apu::Write) port operations

Music Editor Integration:

• Live Playback: PlaySong(int song_id) triggers songs via $7E012C memory write
• Volume Control: SetVolume(float) controls backend volume at abstraction layer
• Playback Controls: Stop/pause/resume functionality ready for UI integration

Documentation:

• Created comprehensive audio system guides covering IPL ROM protocol, handshake debugging, and testing procedures

Emulator: Critical Performance Fixes

Console Logging Performance Killer Fixed:

• Issue: Console logging code was executing on EVERY instruction even when disabled, causing severe performance degradation (< 1 FPS)
• Impact: ~1,791,000 console writes per second with mutex locks and buffer flushes
• Fix: Removed 73 lines of console output from CPU instruction execution hot path
• Result: Emulator now runs at full 60 FPS

Instruction Logging Default Changed:

• Changed: kLogInstructions flag default from true to false
• Reason: Even without console spam, logging every instruction to DisassemblyViewer caused significant slowdown
• Impact: No logging overhead unless explicitly enabled by user

Instruction Log Unbounded Growth Fixed:

• Issue: Legacy instruction_log_ vector growing to 60+ million entries after 10 minutes, consuming 6GB+ RAM
• Fix: Added automatic trimming to 10,000 most recent instructions
• Result: Memory usage stays bounded at ~50MB

Audio Buffer Allocation Bug Fixed:

• Issue: Audio buffer allocated as single int16_t instead of array, causing immediate buffer overflow
• Fix: Properly allocate as array using new int16_t[size] with custom deleter
• Result: Audio system can now queue samples without corruption

Emulator: UI Organization & Input System

New UI Architecture:

• Created src/app/emu/ui/ directory for separation of concerns
• EmulatorUI Layer: Separated all ImGui rendering code from emulator logic
• Input Abstraction: IInputBackend interface with SDL2 implementation for future SDL3 migration
• InputHandler: Continuous polling system using SDL_GetKeyboardState() instead of event-based ImGui keys

Keyboard Input Fixed:

• Issue: Event-based ImGui::IsKeyPressed() only fires once per press, doesn't work for held buttons
• Fix: New InputHandler uses continuous SDL keyboard state polling every frame
• Result: Proper game controls with held button detection

DisassemblyViewer Enhancement:

• Sparse Address Map: Mesen-style storage of unique addresses only, not every execution
• Execution Counter: Increments on re-execution for hotspot analysis
• Performance: Tracks millions of instructions with ~5MB RAM vs 6GB+ with old system
• Always Active: No need for toggle flag, efficiently active by default

Feature Flags Cleanup:

• Removed deprecated kLogInstructions flag entirely
• DisassemblyViewer now always active with zero performance cost

Debugger: Breakpoint & Watchpoint Systems

BreakpointManager:

• CRUD Operations: Add/Remove/Enable/Disable breakpoints with unique IDs
• Breakpoint Types: Execute, Read, Write, Access, and Conditional breakpoints
• Dual CPU Support: Separate tracking for 65816 CPU and SPC700
• Hit Counting: Tracks how many times each breakpoint is triggered
• CPU Integration: Connected to CPU execution via callback system

WatchpointManager:

• Memory Access Tracking: Monitor reads/writes to memory ranges
• Range-Based: Watch single addresses or memory regions ($7E0000-$7E00FF)
• Access History: Deque-based storage of last 1000 memory accesses
• Break-on-Access: Optional execution pause when watchpoint triggered
• Export: CSV export of access history for analysis

CPU Debugger UI Enhancements:

• Integrated Controls: Play/Pause/Step/Reset buttons directly in debugger window
• Breakpoint UI: Address input (hex), add/remove buttons, enable/disable checkboxes, hit count display
• Live Disassembly: DisassemblyViewer showing real-time execution
• Register Display: Real-time CPU state (A, X, Y, D, SP, PC, PB, DB, flags)

Build System Simplifications

Eliminated Conditional Compilation:

• Before: Optional flags for JSON (YAZE_WITH_JSON), gRPC (YAZE_WITH_GRPC), AI (Z3ED_AI)
• After: All features always enabled, no configuration required
• Benefits: Simpler development, easier onboarding, fewer ifdef-related bugs, consistent builds across all platforms
• Build Command: Just cmake -B build && cmake --build build - no flags needed!

DisassemblyViewer Performance Limits:

• Max 10,000 instructions stored (prevents memory bloat)
• Auto-trim to 8,000 when limit reached (keeps hottest code paths)
• Toggle recording on/off for performance testing
• Clear button to free memory

Build System: Windows Platform Improvements

gRPC v1.67.1 Upgrade:

• Issue: v1.62.0 had template instantiation errors on MSVC
• Fix: Upgraded to v1.67.1 with MSVC template fixes and better C++17/20 compatibility
• Result: Builds successfully on Visual Studio 2022

MSVC-Specific Compiler Flags:

• /bigobj - Allow large object files (gRPC generates many)
• /permissive- - Standards conformance mode
• /wd4267 /wd4244 - Suppress harmless conversion warnings
• /constexpr:depth2048 - Handle deep template instantiations

Cross-Platform Validation:

• All new audio and input code uses cross-platform SDL2 APIs
• No platform-specific code in audio backend or input abstraction
• Ready for SDL3 migration with minimal changes

GUI & UX Modernization

• Theme System: Implemented a comprehensive theme system (AgentUITheme) that centralizes all UI colors. All Agent UI components are now theme-aware, deriving colors from the main application theme.
• UI Helper Library: Created a library of 30+ reusable UI helper functions (AgentUI::* and gui::*) to standardize panel styles, section headers, status indicators, and buttons, reducing boilerplate code by over 50%.
• Visual Polish: Enhanced numerous UI panels (Agent Chat, Test Harness, Collaboration) with theme-aware colors, status badges (PASS/FAIL/RUN), connection indicators, and provider badges (Ollama/Gemini).

Overworld Editor Refactoring

• Modular Architecture: Refactored the 3,400-line OverworldEditor into smaller, focused modules, including OverworldEntityRenderer.
• Progressive Loading: Implemented a priority-based progressive loading system in the central gfx::Arena to prevent UI freezes during asset loading. This benefits all editors.
• Critical Graphics Fixes: Resolved major bugs related to graphics not refreshing immediately, multi-quadrant map updates, and incorrect feature visibility on vanilla ROMs.
• Multi-Area Map Configuration: Implemented a robust ConfigureMultiAreaMap() method to correctly handle parent/child relationships for all area sizes (Small, Large, Wide, Tall).

Build System & Stability

• Build Fixes: Resolved 7 critical build errors, including linker issues, missing virtual methods, and filesystem crashes.
• C API Separation: Decoupled the C API library from the main application to improve build modularity.

0.3.2 (December 2025) - In Development

Tile16 Editor Improvements (In Progress)

Palette System Enhancements:

• Comprehensive Palette Coordination: Enhanced tile16 editor now properly coordinates with overworld palette system
• Sheet-Based Palette Mapping: Implemented sophisticated palette mapping where different graphics sheets use appropriate palette groups:
  • Sheets 0, 3-6: AUX palette group
  • Sheets 1-2: MAIN palette group
  • Sheet 7: ANIMATED palette group
• Enhanced UI Layout: Improved scrollable layout with better organization and visual clarity
• Right-Click Tile Picking: New feature to pick tiles directly from the tile16 canvas for quick editing
• Save/Discard Workflow: Implemented proper save/discard workflow that prevents ROM changes until explicit user confirmation

Known Issues:

• ⚠️ Palette display still has some errors with certain sheet configurations (work in progress)
• Some edge cases in palette group selection need refinement

Graphics System Optimizations

Performance Improvements:

• Segmentation Fault Resolution: Fixed critical crashes in tile16 editor caused by tile cache system using std::move() operations that invalidated Bitmap surface pointers
• Direct SDL Texture Updates: Disabled problematic tile cache and implemented direct texture update system for improved stability
• Comprehensive Bounds Checking: Added extensive bounds checking throughout graphics pipeline to prevent crashes and palette corruption
• Surface/Texture Pooling: Implemented graphics optimizations including surface/texture pooling while maintaining system stability
• Performance Profiling: Added performance monitoring and profiling capabilities for graphics operations

Windows Platform Stability

Build System Fixes:

• Stack Overflow Fix: Increased Windows stack size from 1MB to 8MB to match macOS/Linux defaults
  • Prevents crashes during EditorManager::LoadAssets() which loads 223 graphics sheets
  • Handles deep call stacks from multiple editor initializations
  • Applied to both yaze executable and yaze_test test suite
• Development Utility Fixes: Fixed linker errors in extract_vanilla_values and rom_patch_utility executables
  • Resolved multiple main() definition conflicts
  • Added proper yaze_core library linkage
  • Prevented CI/release builds from attempting to build development-only utilities
• File Dialog Fallback Implementation: Fixed non-functional file dialogs in minimal builds
  • Implemented proper Windows COM-based IFileOpenDialog/IFileSaveDialog fallback
  • Previously returned empty string when NFD (Native File Dialog) was unavailable
  • Now works in all Windows builds regardless of vcpkg/NFD availability
  • Supports file open, file save, and folder selection dialogs
• Consistent Cross-Platform Behavior: Windows builds now have equivalent stack resources and stability as Unix-like systems

Memory Safety & Stability

Critical Fixes:

• Bitmap Surface Invalidation: Root cause analysis and fix for segmentation faults in graphics rendering
• Tile Cache System: Disabled move semantics in tile cache that caused pointer invalidation
• Memory Management: Enhanced RAII patterns and smart pointer usage throughout graphics pipeline
• Bounds Verification: Added comprehensive bounds checking for tile and palette access

Testing & CI/CD Improvements

Test Infrastructure:

• Windows Test Reliability: Fixed test suite crashes by increasing stack size
• Development-Only Builds: Properly isolated development utilities from CI/release builds
• Better Error Reporting: Enhanced error messages for Windows build failures
• Cross-Platform Consistency: Ensured consistent test behavior across all platforms

Future Optimizations (Planned)

Graphics System:

• Lazy loading of graphics sheets (load on-demand rather than all at once)
• Heap-based allocation for large data structures instead of stack
• Streaming/chunked loading for large ROM assets
• Consider if all 223 sheets need to be in memory simultaneously

Build System:

• Further reduce CI build times
• Enhanced dependency caching strategies
• Improved vcpkg integration reliability

Technical Notes

Breaking Changes:

• None - this is a patch release focused on stability and fixes

Deprecations:

• None

Migration Guide:

• No migration required - this release is fully backward compatible with 0.3.1

0.3.1 (September 2025)

Major Features

• Complete Tile16 Editor Overhaul: Professional-grade tile editing with modern UI and advanced capabilities
• Advanced Palette Management: Full access to all SNES palette groups with configurable normalization
• Comprehensive Undo/Redo System: 50-state history with intelligent time-based throttling
• ZSCustomOverworld v3 Full Support: Complete implementation of ZScream Save.cs functionality with complex transition calculations
• ZEML System Removal: Converted overworld editor from markup to pure ImGui for better performance and maintainability
• OverworldEditorManager: New management system to handle complex v3 overworld features

Tile16 Editor Enhancements

• Modern UI Layout: Fully resizable 3-column interface (Tile8 Source, Editor, Preview & Controls)
• Multi-Palette Group Support: Access to Overworld Main/Aux1/Aux2, Dungeon Main, Global Sprites, Armors, and Swords palettes
• Advanced Transform Operations: Flip horizontal/vertical, rotate 90°, fill with tile8, clear operations
• Professional Workflow: Copy/paste, 4-slot scratch space, live preview with auto-commit
• Pixel Normalization Settings: Configurable pixel value masks (0x01-0xFF) for handling corrupted graphics sheets

ZSCustomOverworld v3 Implementation

• SaveLargeMapsExpanded(): Complex neighbor-aware transition calculations for all area sizes (Small, Large, Wide, Tall)
• Interactive Overlay System: Full SaveMapOverlays() with ASM code generation for revealing holes and changing map elements
• SaveCustomOverworldASM(): Complete custom overworld ASM application with feature toggles and data tables
• Expanded Memory Support: Automatic detection and use of v3 expanded memory locations (0x140xxx)
• Area-Specific Features: Background colors, main palettes, mosaic transitions, GFX groups, subscreen overlays, animated tiles
• Transition Logic: Sophisticated camera transition calculations based on neighboring area types and quadrants
• Version Compatibility: Maintains vanilla/v2 compatibility while adding full v3+ feature support

Technical Improvements

• SNES Data Accuracy: Proper 4-bit palette index handling with configurable normalization
• Bitmap Pipeline Fixes: Corrected tile16 extraction using GetTilemapData() with manual fallback
• Real-time Updates: Immediate visual feedback for all editing operations
• Memory Safety: Enhanced bounds checking and error handling throughout
• ASM Version Detection: Automatic detection of custom overworld ASM version for feature availability
• Conditional Save Logic: Different save paths for vanilla, v2, and v3+ ROMs

User Interface

• Keyboard Shortcuts: Comprehensive shortcuts for all operations (H/V/R for transforms, Q/E for palette cycling, 1-8 for direct palette selection)
• Visual Feedback: Hover preview restoration, current palette highlighting, texture status indicators
• Compact Controls: Streamlined property panel with essential tools easily accessible
• Settings Dialog: Advanced palette normalization controls with real-time application
• Pure ImGui Layout: Removed ZEML markup system in favor of native ImGui tabs and tables for better performance
• v3 Settings Panel: Dedicated UI for ZSCustomOverworld v3 features with ASM version detection and feature toggles

Bug Fixes

• Tile16 Bitmap Display: Fixed blank/white tile issue caused by unnormalized pixel values
• Hover Preview: Restored tile8 preview when hovering over tile16 canvas
• Canvas Scaling: Corrected coordinate scaling for 8x magnification factor
• Palette Corruption: Fixed high-bit contamination in graphics sheets
• UI Layout: Proper column sizing and resizing behavior
• Linux CI/CD Build: Fixed undefined reference errors for ShowSaveFileDialog method
• ZSCustomOverworld v3: Fixed complex area transition calculations and neighbor-aware tilemap adjustments
• ZEML Performance: Eliminated markup parsing overhead by converting to native ImGui components

ZScream Compatibility Improvements

• Complete Save.cs Implementation: All major methods from ZScream's Save.cs now implemented in YAZE
• Area Size Support: Full support for Small, Large, Wide, and Tall area types with proper transitions
• Interactive Overlays: Complete overlay save system matching ZScream's functionality
• Custom ASM Integration: Proper handling of ZSCustomOverworld ASM versions 1-3+
• Memory Layout: Correct usage of expanded vs vanilla memory locations based on ROM type

0.3.0 (September 2025)

Major Features

• Complete Theme Management System: 5+ built-in themes with custom theme creation and editing
• Multi-Session Workspace: Work with multiple ROMs simultaneously in enhanced docked interface
• Enhanced Welcome Screen: Themed interface with quick access to all editors and features
• Asar 65816 Assembler Integration: Complete cross-platform ROM patching with assembly code
• ZSCustomOverworld v3: Full integration with enhanced overworld editing capabilities
• Advanced Message Editing: Enhanced text editing interface with improved parsing and real-time preview
• GUI Docking System: Improved docking and workspace management for better user workflow
• Symbol Extraction: Extract symbol names and opcodes from assembly files
• Modernized Build System: Upgraded to CMake 3.16+ with target-based configuration

User Interface & Theming

• Built-in Themes: Classic YAZE, YAZE Tre, Cyberpunk, Sunset, Forest, and Midnight themes
• Theme Editor: Complete custom theme creation with save-to-file functionality
• Animated Background Grid: Optional moving grid with color breathing effects
• Theme Import/Export: Share custom themes with the community
• Responsive UI: All UI elements properly adapt to selected themes

Enhancements

• Enhanced CLI Tools: Improved z3ed with modern command line interface and TUI
• CMakePresets: Added development workflow presets for better productivity
• Cross-Platform CI/CD: Multi-platform automated builds and testing with lenient code quality checks
• Professional Packaging: NSIS, DMG, and DEB/RPM installers
• ROM-Dependent Testing: Separated testing infrastructure for CI compatibility with 46+ core tests
• Comprehensive Documentation: Updated guides, help menus, and API documentation

Technical Improvements

• Modern C++23: Latest language features for performance and safety
• Memory Safety: Enhanced memory management with RAII and smart pointers
• Error Handling: Improved error handling using absl::Status throughout
• Cross-Platform: Consistent experience across Windows, macOS, and Linux
• Performance: Optimized rendering and data processing

Bug Fixes

• Graphics Arena Crash: Fixed double-free error during Arena singleton destruction
• SNES Tile Format: Corrected tile unpacking algorithm based on SnesLab documentation
• Palette System: Fixed color conversion functions (ImVec4 float to uint8_t conversion)
• CI/CD: Fixed missing cstring include for Ubuntu compilation
• ROM Loading: Fixed file path issues in tests

0.2.2 (December 2024)

• DungeonMap editing improvements
• ZSCustomOverworld support
• Cross platform file handling

0.2.1 (August 2024)

• Improved MessageEditor parsing
• Added integration test window
• Bitmap bug fixes

0.2.0 (July 2024)

• iOS app support
• Graphics Sheet Browser
• Project Files

0.1.0 (May 2024)

• Bitmap bug fixes
• Error handling improvements

0.0.9 (April 2024)

• Documentation updates
• Entrance tile types
• Emulator subsystem overhaul

0.0.8 (February 2024)

• Hyrule Magic Compression
• Dungeon Room Entrances
• PNG Export

0.0.7 (January 2024)

• OverworldEntities
  • Entrances
  • Exits
  • Items
  • Sprites

0.0.6 (November 2023)

• ScreenEditor DungeonMap
• Tile16 Editor
• Canvas updates

0.0.5 (November 2023)

• DungeonEditor
• DungeonObjectRenderer

0.0.4 (November 2023)

• Tile16Editor
• GfxGroupEditor
• Add GfxGroups functions to Rom
• Add Tile16Editor and GfxGroupEditor to OverworldEditor

0.0.3 (October 2023)

• Emulator subsystem
  • SNES PPU and PPURegisters