From caffe598004aaa10a32e272c5cf1c54a38790f63 Mon Sep 17 00:00:00 2001 From: scawful Date: Fri, 26 Sep 2025 15:00:57 -0400 Subject: [PATCH] Update README and build instructions for clarity and organization - Revised README to enhance feature descriptions and streamline sections for better readability. - Updated build instructions to clarify platform-specific setup and improve the overall structure. - Added new documentation files for platform compatibility and build presets, detailing native file dialog support and build configuration options. - Removed outdated documentation related to overworld expansion to maintain relevance. --- README.md | 143 +++++++++---------------- docs/02-build-instructions.md | 168 +++++++++++++++++++++++------- docs/B2-ci-cd-fixes.md | 55 ++++++++++ docs/B2-platform-compatibility.md | 55 ++++++++++ docs/B3-build-presets.md | 109 +++++++++++++++++++ docs/E5-dungeon-object-system.md | 4 +- docs/F2-overworld-expansion.md | 32 ------ docs/index.md | 126 +++------------------- 8 files changed, 410 insertions(+), 282 deletions(-) create mode 100644 docs/B2-ci-cd-fixes.md create mode 100644 docs/B2-platform-compatibility.md create mode 100644 docs/B3-build-presets.md delete mode 100644 docs/F2-overworld-expansion.md diff --git a/README.md b/README.md index be3f2e87..55478e71 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,7 @@ A modern, cross-platform editor for The Legend of Zelda: A Link to the Past ROM [![Build Status](https://github.com/scawful/yaze/workflows/CI/badge.svg)](https://github.com/scawful/yaze/actions) [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) -## 🚀 Version 0.3.0 - Major Release - -**Complete Asar Integration • Modern Build System • Enhanced CLI Tools • Professional CI/CD** - -### ✨ Key Features +## Version 0.3.0 - Stable Release #### Asar 65816 Assembler Integration - **Cross-platform ROM patching** with assembly code support @@ -36,12 +32,7 @@ A modern, cross-platform editor for The Legend of Zelda: A Link to the Past ROM - **Professional packaging**: NSIS, DMG, and DEB/RPM installers - **Enhanced testing**: ROM-dependent test separation for CI compatibility -## 🏗️ Quick Start - -### Prerequisites -- **CMake 3.16+** -- **C++23 Compiler** (GCC 13+, Clang 16+, MSVC 2022 17.8+) -- **Git** with submodule support +## Quick Start ### Build ```bash @@ -49,114 +40,76 @@ A modern, cross-platform editor for The Legend of Zelda: A Link to the Past ROM git clone --recursive https://github.com/scawful/yaze.git cd yaze -# Build with presets -cmake --preset dev -cmake --build --preset dev - -# Run tests -ctest --preset stable +# Build with CMake +cmake --preset debug # macOS +cmake -B build && cmake --build build # Linux/Windows ``` -### Targets -- **yaze**: GUI Editor Application with docking system -- **z3ed**: Enhanced CLI Tool with Asar integration and TUI -- **yaze_c**: C Library for extensions and custom tools -- **yaze_test**: Comprehensive test suite executable -- **yaze_emu**: Standalone SNES emulator application +### Applications +- **yaze**: Complete GUI editor for Zelda 3 ROM hacking +- **z3ed**: Command-line tool with interactive interface +- **yaze_test**: Comprehensive test suite for development -## 💻 Usage Examples +## Usage -### Asar Assembly Patching +### GUI Editor +Launch the main application to edit Zelda 3 ROMs: +- Load ROM files using native file dialogs +- Edit overworld maps, dungeons, sprites, and graphics +- Apply assembly patches with integrated Asar support +- Export modifications as patches or modified ROMs + +### Command Line Tool ```bash -# Apply assembly patch to ROM -z3ed asar my_patch.asm --rom=zelda3.sfc -✅ Asar patch applied successfully! -📁 Output: zelda3_patched.sfc -🏷️ Extracted 6 symbols: - main_routine @ $008000 - data_table @ $008020 +# Apply assembly patch +z3ed asar patch.asm --rom=zelda3.sfc -# Extract symbols without patching -z3ed extract my_patch.asm +# Extract symbols from assembly +z3ed extract patch.asm -# Validate assembly syntax -z3ed validate my_patch.asm -✅ Assembly file is valid - -# Launch interactive TUI +# Interactive mode z3ed --tui ``` -### C++ API Usage +### C++ API ```cpp -#include "app/core/asar_wrapper.h" +#include "yaze.h" -yaze::app::core::AsarWrapper wrapper; -wrapper.Initialize(); - -// Apply patch to ROM -auto result = wrapper.ApplyPatch("patch.asm", rom_data); -if (result.ok() && result->success) { - for (const auto& symbol : result->symbols) { - std::cout << symbol.name << " @ $" - << std::hex << symbol.address << std::endl; - } -} +// Load ROM and apply patch +yaze_project_t* project = yaze_load_project("zelda3.sfc"); +yaze_apply_asar_patch(project, "patch.asm"); +yaze_save_project(project, "modified.sfc"); ``` -## 📚 Documentation +## Documentation -### Core Documentation -- **[Getting Started](docs/01-getting-started.md)** - Basic setup and usage -- **[Build Instructions](docs/02-build-instructions.md)** - Detailed build guide -- **[Asar Integration](docs/03-asar-integration.md)** - Complete 65816 assembler guide -- **[API Reference](docs/04-api-reference.md)** - C/C++ API documentation +- [Getting Started](docs/01-getting-started.md) - Setup and basic usage +- [Build Instructions](docs/02-build-instructions.md) - Building from source +- [API Reference](docs/04-api-reference.md) - Programming interface +- [Contributing](docs/B1-contributing.md) - Development guidelines -### Development -- **[Testing Guide](docs/A1-testing-guide.md)** - Comprehensive testing framework -- **[Contributing](docs/B1-contributing.md)** - Development guidelines and standards -- **[Changelog](docs/C1-changelog.md)** - Version history and changes -- **[Roadmap](docs/D1-roadmap.md)** - Development plans and timeline +**[Complete Documentation](docs/index.md)** -### Technical Documentation -- **[Assembly Style Guide](docs/E1-asm-style-guide.md)** - 65816 assembly coding standards -- **[Dungeon Editor Guide](docs/E2-dungeon-editor-guide.md)** - Complete dungeon editing guide -- **[Overworld Loading](docs/F1-overworld-loading.md)** - ZSCustomOverworld v3 implementation +## Supported Platforms -**[Complete Documentation Index](docs/index.md)** +- **Windows** (MSVC 2019+, MinGW) +- **macOS** (Intel and Apple Silicon) +- **Linux** (GCC 13+, Clang 16+) +## ROM Compatibility -## 🔧 Supported Platforms +- Original Zelda 3 ROMs (US/Japan versions) +- ZSCustomOverworld v2/v3 enhanced overworld features +- Community ROM hacks and modifications -- **Windows**: Full support with MSVC and MinGW compilers -- **macOS**: Universal binaries supporting Intel and Apple Silicon -- **Linux**: GCC and Clang support with package management -- **Professional Packaging**: Native installers for all platforms +## Contributing -## 🎮 ROM Compatibility +See [Contributing Guide](docs/B1-contributing.md) for development guidelines. -- **Vanilla ROMs**: Original Zelda 3 ROMs (US/JP) -- **ZSCustomOverworld v2/v3**: Enhanced overworld features and compatibility -- **Custom Modifications**: Support for community ROM hacks and modifications +**Community**: [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk) -## 🤝 Contributing +## License -We welcome contributions! Please see our [Contributing Guide](docs/B1-contributing.md) for: - -- Code style and C++23 standards -- Testing requirements and ROM handling -- Pull request process and review guidelines -- Development setup with CMake presets - -### Community -- **Discord**: [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk) -- **GitHub Issues**: Report bugs and request features -- **Discussions**: Community discussions and support - -## 📄 License - -YAZE is distributed under the [GNU GPL v3](https://www.gnu.org/licenses/gpl-3.0) license. - -Third-party libraries (SDL2, ImGui, Abseil) are subject to their respective licenses. +GNU GPL v3 - See [LICENSE](LICENSE) for details. ## 🙏 Acknowledgments diff --git a/docs/02-build-instructions.md b/docs/02-build-instructions.md index df134e2c..eca41a33 100644 --- a/docs/02-build-instructions.md +++ b/docs/02-build-instructions.md @@ -4,62 +4,150 @@ YAZE uses CMake 3.16+ with modern target-based configuration. For VSCode users, - https://marketplace.visualstudio.com/items?itemName=twxs.cmake - https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools -## Quick Build +## Quick Start +### macOS (Apple Silicon) ```bash -# Development build -cmake --preset dev -cmake --build --preset dev +cmake --preset debug +cmake --build build +``` -# CI build (minimal dependencies) -cmake --preset ci -cmake --build --preset ci +### Linux / Windows +```bash +cmake -B build -DCMAKE_BUILD_TYPE=Debug +cmake --build build +``` + +### Minimal Build +```bash +cmake -B build -DYAZE_MINIMAL_BUILD=ON +cmake --build build ``` ## Dependencies -### Core Dependencies -- **SDL2**: Graphics and input library -- **ImGui**: Immediate mode GUI library with docking support -- **Abseil**: Modern C++ utilities library -- **libpng**: Image processing library +### Required +- CMake 3.16+ +- C++23 compiler (GCC 13+, Clang 16+, MSVC 2019+) +- Git with submodule support -### v0.3.0 Additions -- **Asar**: 65816 assembler for ROM patching -- **ftxui**: Terminal UI library for CLI -- **GoogleTest**: Comprehensive testing framework +### Bundled Libraries +- SDL2, ImGui, Abseil, Asar, GoogleTest +- Native File Dialog Extended (NFD) +- All dependencies included in repository -## Platform-Specific Setup - -### Windows - -#### vcpkg (Recommended) -```json -{ - "dependencies": [ - "abseil", "sdl2", "libpng" - ] -} -``` - -#### msys2 (Advanced) -Install packages: `mingw-w64-x86_64-gcc`, `mingw-w64-x86_64-cmake`, `mingw-w64-x86_64-sdl2`, `mingw-w64-x86_64-libpng`, `mingw-w64-x86_64-abseil-cpp` +## Platform Setup ### macOS ```bash -brew install cmake sdl2 zlib libpng abseil boost-python3 +# Install Xcode Command Line Tools +xcode-select --install + +# Optional: Install Homebrew dependencies (auto-detected) +brew install cmake pkg-config ``` -### Linux -Use your package manager to install the same dependencies as macOS. +### Linux (Ubuntu/Debian) +```bash +sudo apt-get update +sudo apt-get install -y build-essential cmake ninja-build pkg-config \ + libgtk-3-dev libdbus-1-dev +``` -### iOS -Xcode required. The xcodeproject file is in the `ios` directory. Link `SDL2.framework` and `libpng.a`. +### Windows +**Option 1 - Minimal (Recommended for CI):** +- Visual Studio 2019+ with C++ CMake tools +- No additional dependencies needed (all bundled) + +**Option 2 - Full Development:** +- Install vcpkg and dependencies from `vcpkg.json` ## Build Targets -- **yaze**: Desktop GUI application -- **z3ed**: Enhanced CLI tool -- **yaze_c**: C library for extensions -- **yaze_test**: Test suite executable +### Applications +- **yaze**: Main GUI editor application +- **z3ed**: Command-line interface tool + +### Libraries +- **yaze_c**: C API library for extensions +- **asar-static**: 65816 assembler library + +### Development (Debug Builds Only) - **yaze_emu**: Standalone SNES emulator +- **yaze_test**: Comprehensive test suite + +## Build Configurations + +### Debug (Full Features) +```bash +cmake --preset debug # macOS +# OR +cmake -B build -DCMAKE_BUILD_TYPE=Debug # All platforms +``` +**Includes**: NFD, ImGuiTestEngine, PNG support, emulator, all tools + +### Minimal (CI/Fast Builds) +```bash +cmake -B build -DYAZE_MINIMAL_BUILD=ON +``` +**Excludes**: Emulator, CLI tools, UI tests, optional dependencies + +### Release +```bash +cmake --preset release # macOS +# OR +cmake -B build -DCMAKE_BUILD_TYPE=Release # All platforms +``` + +## IDE Integration + +### VS Code +1. Install CMake Tools extension +2. Open project, select "Debug" preset +3. Language server uses `compile_commands.json` automatically + +### CLion +- Opens CMake projects directly +- Select Debug configuration + +### Xcode (macOS) +```bash +cmake --preset debug -G Xcode +open build/yaze.xcodeproj +``` + +## Features by Build Type + +| Feature | Debug | Release | Minimal (CI) | +|---------|-------|---------|--------------| +| GUI Editor | ✅ | ✅ | ✅ | +| Native File Dialogs | ✅ | ✅ | ❌ | +| PNG Support | ✅ | ✅ | ❌ | +| Emulator | ✅ | ✅ | ❌ | +| CLI Tools | ✅ | ✅ | ❌ | +| Test Suite | ✅ | ❌ | ✅ (limited) | +| UI Testing | ✅ | ❌ | ❌ | + +## Troubleshooting + +### Architecture Errors (macOS) +```bash +# Clean and use ARM64-only preset +rm -rf build +cmake --preset debug # Uses arm64 only +``` + +### Missing Headers (Language Server) +```bash +# Regenerate compile commands +cmake --preset debug +cp build/compile_commands.json . +# Restart VS Code +``` + +### CI Build Failures +Use minimal build configuration that matches CI: +```bash +cmake -B build -DYAZE_MINIMAL_BUILD=ON -DYAZE_ENABLE_UI_TESTS=OFF +cmake --build build +``` diff --git a/docs/B2-ci-cd-fixes.md b/docs/B2-ci-cd-fixes.md new file mode 100644 index 00000000..23725c2b --- /dev/null +++ b/docs/B2-ci-cd-fixes.md @@ -0,0 +1,55 @@ +# Platform Compatibility Improvements + +Recent improvements to ensure YAZE works reliably across all supported platforms. + +## Native File Dialog Support + +YAZE now features native file dialogs on all platforms: +- **macOS**: Cocoa-based file selection with proper sandboxing support +- **Windows**: Windows Explorer integration with COM APIs +- **Linux**: GTK3 dialogs that match system appearance +- **Fallback**: Bespoke implementation when native dialogs unavailable + +## Cross-Platform Build Reliability + +Enhanced build system ensures consistent compilation: +- **Windows**: Resolved MSVC compatibility issues and dependency conflicts +- **Linux**: Fixed standard library compatibility for older distributions +- **macOS**: Proper support for both Intel and Apple Silicon architectures +- **All Platforms**: Bundled dependencies eliminate external package requirements + +## Build Configuration Options + +YAZE supports different build configurations for various use cases: + +### Full Build (Development) +Includes all features: emulator, CLI tools, UI testing framework, and optional libraries. + +### Minimal Build +Streamlined build excluding complex components, optimized for automated testing and CI environments. + +## Implementation Details + +The build system automatically detects platform capabilities and adjusts feature sets accordingly: + +- **File Dialogs**: Uses native platform dialogs when available, with cross-platform fallbacks +- **Dependencies**: Bundles all required libraries to eliminate external package requirements +- **Testing**: Separates ROM-dependent tests from unit tests for CI compatibility +- **Architecture**: Supports both Intel and Apple Silicon on macOS without conflicts + +## Platform-Specific Adaptations + +### Windows +- Complete COM-based file dialog implementation +- MSVC compatibility improvements for modern C++ features +- Resource file handling for proper application integration + +### macOS +- Cocoa-based native file dialogs with sandboxing support +- Universal binary support for Intel and Apple Silicon +- Proper bundle configuration for macOS applications + +### Linux +- GTK3 integration for native file dialogs +- Package manager integration for system dependencies +- Support for multiple compiler toolchains (GCC, Clang) diff --git a/docs/B2-platform-compatibility.md b/docs/B2-platform-compatibility.md new file mode 100644 index 00000000..23725c2b --- /dev/null +++ b/docs/B2-platform-compatibility.md @@ -0,0 +1,55 @@ +# Platform Compatibility Improvements + +Recent improvements to ensure YAZE works reliably across all supported platforms. + +## Native File Dialog Support + +YAZE now features native file dialogs on all platforms: +- **macOS**: Cocoa-based file selection with proper sandboxing support +- **Windows**: Windows Explorer integration with COM APIs +- **Linux**: GTK3 dialogs that match system appearance +- **Fallback**: Bespoke implementation when native dialogs unavailable + +## Cross-Platform Build Reliability + +Enhanced build system ensures consistent compilation: +- **Windows**: Resolved MSVC compatibility issues and dependency conflicts +- **Linux**: Fixed standard library compatibility for older distributions +- **macOS**: Proper support for both Intel and Apple Silicon architectures +- **All Platforms**: Bundled dependencies eliminate external package requirements + +## Build Configuration Options + +YAZE supports different build configurations for various use cases: + +### Full Build (Development) +Includes all features: emulator, CLI tools, UI testing framework, and optional libraries. + +### Minimal Build +Streamlined build excluding complex components, optimized for automated testing and CI environments. + +## Implementation Details + +The build system automatically detects platform capabilities and adjusts feature sets accordingly: + +- **File Dialogs**: Uses native platform dialogs when available, with cross-platform fallbacks +- **Dependencies**: Bundles all required libraries to eliminate external package requirements +- **Testing**: Separates ROM-dependent tests from unit tests for CI compatibility +- **Architecture**: Supports both Intel and Apple Silicon on macOS without conflicts + +## Platform-Specific Adaptations + +### Windows +- Complete COM-based file dialog implementation +- MSVC compatibility improvements for modern C++ features +- Resource file handling for proper application integration + +### macOS +- Cocoa-based native file dialogs with sandboxing support +- Universal binary support for Intel and Apple Silicon +- Proper bundle configuration for macOS applications + +### Linux +- GTK3 integration for native file dialogs +- Package manager integration for system dependencies +- Support for multiple compiler toolchains (GCC, Clang) diff --git a/docs/B3-build-presets.md b/docs/B3-build-presets.md new file mode 100644 index 00000000..0d2e2589 --- /dev/null +++ b/docs/B3-build-presets.md @@ -0,0 +1,109 @@ +# Build Presets Guide + +CMake presets for development workflow and architecture-specific builds. + +## 🍎 macOS ARM64 Presets (Recommended for Apple Silicon) + +### For Development Work: +```bash +# ARM64-only development build with ROM testing +cmake --preset macos-dev +cmake --build --preset macos-dev + +# ARM64-only debug build +cmake --preset macos-debug +cmake --build --preset macos-debug + +# ARM64-only release build +cmake --preset macos-release +cmake --build --preset macos-release +``` + +### For Distribution: +```bash +# Universal binary (ARM64 + x86_64) - use only when needed for distribution +cmake --preset macos-debug-universal +cmake --build --preset macos-debug-universal + +cmake --preset macos-release-universal +cmake --build --preset macos-release-universal +``` + +## 🔧 Why This Fixes Architecture Errors + +**Problem**: The original presets used `CMAKE_OSX_ARCHITECTURES: "x86_64;arm64"` which forced CMake to build universal binaries. This caused issues because: +- Dependencies like Abseil tried to use x86 SSE instructions (`-msse4.1`) +- These instructions don't exist on ARM64 processors +- Build failed with "unsupported option '-msse4.1' for target 'arm64-apple-darwin'" + +**Solution**: The new ARM64-only presets use `CMAKE_OSX_ARCHITECTURES: "arm64"` which: +- ✅ Only targets ARM64 architecture +- ✅ Prevents x86-specific instruction usage +- ✅ Uses ARM64 optimizations instead +- ✅ Builds much faster (no cross-compilation) + +## 📋 Available Presets + +| Preset Name | Architecture | Purpose | ROM Tests | +|-------------|-------------|---------|-----------| +| `macos-dev` | ARM64 only | Development | ✅ Enabled | +| `macos-debug` | ARM64 only | Debug builds | ❌ Disabled | +| `macos-release` | ARM64 only | Release builds | ❌ Disabled | +| `macos-debug-universal` | Universal | Distribution debug | ❌ Disabled | +| `macos-release-universal` | Universal | Distribution release | ❌ Disabled | + +## 🚀 Quick Start + +For most development work on Apple Silicon: + +```bash +# Clean build +rm -rf build + +# Configure for ARM64 development +cmake --preset macos-dev + +# Build +cmake --build --preset macos-dev + +# Run tests +cmake --build --preset macos-dev --target test +``` + +## 🛠️ IDE Integration + +### VS Code with CMake Tools: +1. Open Command Palette (`Cmd+Shift+P`) +2. Run "CMake: Select Configure Preset" +3. Choose `macos-dev` or `macos-debug` + +### CLion: +1. Go to Settings → Build, Execution, Deployment → CMake +2. Add new profile with preset `macos-dev` + +### Xcode: +```bash +# Generate Xcode project +cmake --preset macos-debug -G Xcode +open build/yaze.xcodeproj +``` + +## 🔍 Troubleshooting + +If you still get architecture errors: +1. **Clean completely**: `rm -rf build` +2. **Check preset**: Ensure you're using an ARM64 preset (not universal) +3. **Verify configuration**: Check that `CMAKE_OSX_ARCHITECTURES` shows only `arm64` + +```bash +# Verify architecture setting +cmake --preset macos-debug +grep -A 5 -B 5 "CMAKE_OSX_ARCHITECTURES" build/CMakeCache.txt +``` + +## 📝 Notes + +- **ARM64 presets**: Fast builds, no architecture conflicts +- **Universal presets**: Slower builds, for distribution only +- **Deployment target**: ARM64 presets use macOS 11.0+ (when Apple Silicon was introduced) +- **Universal presets**: Still support macOS 10.15+ for backward compatibility diff --git a/docs/E5-dungeon-object-system.md b/docs/E5-dungeon-object-system.md index b0029d73..b45065a5 100644 --- a/docs/E5-dungeon-object-system.md +++ b/docs/E5-dungeon-object-system.md @@ -1,8 +1,8 @@ -# YAZE Dungeon Object System +# Dungeon Object System ## Overview -The YAZE Dungeon Object System provides a comprehensive framework for editing and managing dungeon rooms, objects, and layouts in The Legend of Zelda: A Link to the Past. This system combines real-time visual editing with precise data manipulation to create a powerful dungeon creation and modification toolkit. +The Dungeon Object System provides a comprehensive framework for editing and managing dungeon rooms, objects, and layouts in The Legend of Zelda: A Link to the Past. This system combines real-time visual editing with precise data manipulation to create a powerful dungeon creation and modification toolkit. ## Architecture diff --git a/docs/F2-overworld-expansion.md b/docs/F2-overworld-expansion.md deleted file mode 100644 index 29166cd9..00000000 --- a/docs/F2-overworld-expansion.md +++ /dev/null @@ -1,32 +0,0 @@ - -Module09_21 -Module08_02_LoadAndAdvance -Credits_LoadScene_Overworld_LoadMap - - Overworld_LoadAndBuildScreen: - #_02ED59: - - Overworld_DrawQuadrantsAndOverlays: - #_02EEC5: - - Overworld_DecompressAndDrawAllQuadrants: - #_02F54A: - - OverworldLoad_Map32HPointers/LPointers: - #_02F94D - OverworldMap32_Screens - Banks $0B and $0C - - -public void fill(int x, int y, byte indextoreplace) -{ - if (indextoreplace == (byte)colorIndex) { return; } - if (sheetPtr[x, y] == indextoreplace) - { - sheetPtr[x, y] = (byte)colorIndex; - fill(x - 1, y, indextoreplace); - fill(x + 1, y, indextoreplace); - fill(x, y - 1, indextoreplace); - fill(x, y + 1, indextoreplace); - } -} \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 5988cbee..95bde98f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,20 +1,20 @@ # YAZE Documentation -Cross-platform Zelda 3 ROM editor built with modern C++23, SDL2, ImGui, and integrated Asar 65816 assembler support. +Yet Another Zelda3 Editor - A comprehensive ROM editor for The Legend of Zelda: A Link to the Past. ## Quick Start - [Getting Started](01-getting-started.md) - Basic setup and usage -- [Build Instructions](02-build-instructions.md) - How to build from source -- [Asar Integration](03-asar-integration.md) - Complete 65816 assembler guide +- [Build Instructions](02-build-instructions.md) - Cross-platform build guide +- [Asar Integration](03-asar-integration.md) - 65816 assembler usage - [API Reference](04-api-reference.md) - C/C++ API documentation ## Development -- [Testing Guide](A1-testing-guide.md) - Comprehensive testing framework -- [Contributing](B1-contributing.md) - Development guidelines and standards -- [Changelog](C1-changelog.md) - Version history and changes -- [Roadmap](D1-roadmap.md) - Development plans and timeline +- [Testing Guide](A1-testing-guide.md) - Testing framework and best practices +- [Contributing](B1-contributing.md) - Development guidelines and standards +- [Platform Compatibility](B2-platform-compatibility.md) - Cross-platform support details +- [Build Presets](B3-build-presets.md) - CMake preset usage guide ## Technical Documentation @@ -29,115 +29,15 @@ Cross-platform Zelda 3 ROM editor built with modern C++23, SDL2, ImGui, and inte ### Overworld System - [Overworld Loading](F1-overworld-loading.md) - ZSCustomOverworld v3 implementation -- [Overworld Expansion](F2-overworld-expansion.md) - Advanced overworld features - -## Current Version: 0.3.0 (January 2025) - -### ✅ Major Features - -#### Asar 65816 Assembler Integration -- **Cross-platform ROM patching** with assembly code support -- **Symbol extraction** with addresses and opcodes -- **Assembly validation** and comprehensive error reporting -- **Modern C++ API** with safe memory management -- **Enhanced CLI tools** with improved UX - -#### ZSCustomOverworld v3 -- **Enhanced overworld editing** capabilities -- **Advanced map properties** and metadata -- **Custom graphics support** and tile management -- **Improved compatibility** with existing projects - -#### Advanced Message Editing -- **Enhanced text editing interface** with improved parsing -- **Real-time preview** of message formatting -- **Better error handling** for message validation -- **Improved workflow** for text-based ROM hacking - -#### GUI Docking System -- **Improved workspace management** with flexible layouts -- **Better window organization** for complex editing tasks -- **Enhanced user workflow** with customizable interfaces -- **Modern UI improvements** throughout the application - -#### Technical Improvements -- **Modern CMake 3.16+**: Target-based configuration and build system -- **CMakePresets**: Development workflow presets for better productivity -- **Cross-platform CI/CD**: Automated builds and testing for all platforms -- **Professional packaging**: NSIS, DMG, and DEB/RPM installers -- **Enhanced testing**: ROM-dependent test separation for CI compatibility - -### 🔄 In Progress -- **Sprite Builder System**: Custom sprite creation and editing tools -- **Emulator Subsystem**: SNES emulation for testing modifications -- **Music Editor**: Enhanced music data editing interface - -### ⏳ Planned for 0.4.X -- **Overworld Sprites**: Complete sprite editing with add/remove functionality -- **Enhanced Dungeon Editing**: Advanced room object editing and manipulation -- **Tile16 Editing**: Enhanced editor for creating and modifying tile16 data -- **Plugin Architecture**: Framework for community extensions and custom tools ## Key Features -### ROM Editing Capabilities -- **Asar 65816 Assembly**: Apply assembly patches with symbol extraction -- **Overworld Editing**: ZSCustomOverworld v3 with enhanced features -- **Message Editing**: Advanced text editing with real-time preview -- **Palette Management**: Comprehensive color and palette editing -- **Graphics Editing**: SNES graphics manipulation and preview -- **Hex Editing**: Direct ROM data editing with validation - -### Development Tools -- **Enhanced CLI**: Modern z3ed with subcommands and interactive TUI -- **Symbol Analysis**: Extract and analyze assembly symbols -- **ROM Validation**: Comprehensive ROM integrity checking -- **Project Management**: Save and load complete ROM hacking projects - -### Cross-Platform Support -- **Windows**: Full support with MSVC and MinGW compilers -- **macOS**: Universal binaries supporting Intel and Apple Silicon -- **Linux**: GCC and Clang support with package management -- **Professional Packaging**: Native installers for all platforms - -## Compatibility - -### ROM Support -- **Vanilla ROMs**: Original Zelda 3 ROMs (US/JP) -- **ZSCustomOverworld v2/v3**: Enhanced overworld features and compatibility -- **Custom Modifications**: Support for community ROM hacks and modifications - -### File Format Support -- **Assembly Files**: .asm files with Asar 65816 assembler -- **BPS Patches**: Standard ROM patching format -- **Graphics Files**: PNG, BMP, and SNES-specific formats -- **Project Files**: .yaze project format for complete editing sessions - -## Development & Community - -### Architecture -- **Modern C++23**: Latest language features for performance and safety -- **Modular Design**: Component-based architecture for maintainability -- **Cross-Platform**: Consistent experience across all supported platforms -- **Comprehensive Testing**: Unit tests, integration tests, and ROM validation - -### Contributing -See [Contributing](B1-contributing.md) for guidelines on: -- Code style and C++23 standards -- Testing requirements and ROM handling -- Pull request process and review -- Development setup with CMake presets - -### Community -- **Discord**: [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk) -- **GitHub**: [YAZE Repository](https://github.com/scawful/yaze) -- **Issues**: Report bugs and request features on GitHub -- **Discussions**: Community discussions and support - -## License - -This project is licensed under the terms specified in the [LICENSE](../LICENSE) file. +- Complete GUI editor for all aspects of Zelda 3 ROM hacking +- Integrated Asar 65816 assembler for custom code patches +- ZSCustomOverworld v3 support for enhanced overworld editing +- Cross-platform support (Windows, macOS, Linux) +- Modern C++23 codebase with comprehensive testing --- -*Last updated: January 2025 - Version 0.3.0* \ No newline at end of file +*Last updated: September 2025 - Version 0.3.0* \ No newline at end of file