From a1429a8199faff0db75be14dc1402eadfb7f3e29 Mon Sep 17 00:00:00 2001 From: scawful Date: Thu, 25 Sep 2025 09:28:46 -0400 Subject: [PATCH] Update README and documentation for v0.3.0 release - Revamped README.md to provide a clearer overview of the project, including updated platform support, key features, and installation instructions. - Added a new asar-integration.md file detailing the Asar 65816 assembler integration, including usage examples and API references. - Updated changelog.md to reflect new features and improvements in version 0.3.0, including Asar integration, ZSCustomOverworld v3, and enhanced message editing. - Revised getting-started.md to indicate the completion of Asar patching features and updated CLI command statuses. - Enhanced index.md to include new documentation links and a summary of major new features in the latest release. - Improved infrastructure.md to reflect the transition to C++23 and modern CMake practices. --- README.md | 76 ++++---- docs/asar-integration.md | 404 +++++++++++++++++++++++++++++++++++++++ docs/changelog.md | 14 ++ docs/getting-started.md | 11 +- docs/index.md | 152 +++++++++------ docs/infrastructure.md | 32 +++- docs/roadmap.md | 25 ++- 7 files changed, 593 insertions(+), 121 deletions(-) create mode 100644 docs/asar-integration.md diff --git a/README.md b/README.md index 05bc9692..8618e4c3 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,58 @@ # Yet Another Zelda3 Editor -- Platform: Windows, macOS, iOS, GNU/Linux -- Dependencies: SDL2, ImGui, abseil-cpp +A modern, cross-platform editor for The Legend of Zelda: A Link to the Past ROM hacking. -## Description +- **Platform**: Windows, macOS, Linux +- **Language**: C++23 with modern CMake build system +- **Features**: ROM editing, Asar 65816 assembly patching, ZSCustomOverworld v3, GUI docking -General purpose editor for The Legend of Zelda: A Link to the Past for the Super Nintendo. +## Key Features -Provides bindings in C and Python for building custom tools and utilities. +- **Asar Integration**: Apply 65816 assembly patches and extract symbols +- **ZSCustomOverworld v3**: Enhanced overworld editing capabilities +- **Message Editing**: Advanced text editing with real-time preview +- **GUI Docking**: Flexible workspace management +- **Modern CLI**: Enhanced z3ed tool with interactive TUI -Takes heavy inspiration from ALTTP community efforts such as [Hyrule Magic](https://www.romhacking.net/utilities/200/) and [ZScream](https://github.com/Zarby89/ZScreamDungeon) +Takes inspiration from [Hyrule Magic](https://www.romhacking.net/utilities/200/) and [ZScream](https://github.com/Zarby89/ZScreamDungeon) -Building and installation -------------------------- -[CMake](http://www.cmake.org "CMake") is required to build yaze +## Building and Installation -1. Clone the repository -2. Create the build directory and configuration -3. Build and run the application -4. (Optional) Run the tests - -``` - git clone --recurse-submodules https://github.com/scawful/yaze.git - cmake -S . -B build - cmake --build build +### Quick Build +```bash +git clone --recurse-submodules https://github.com/scawful/yaze.git +cd yaze +cmake --preset default +cmake --build --preset default ``` -By default this will build all targets. +### Targets +- **yaze**: GUI Editor Application +- **z3ed**: Command Line Interface with Asar support +- **yaze_c**: C Library +- **yaze_test**: Unit Tests -- **yaze**: Editor Application -- **yaze_c**: C Library -- **yaze_emu**: SNES Emulator -- **yaze_py**: Python Module -- **yaze_test**: Unit Tests -- **z3ed**: Command Line Interface +### Asar Examples +```bash +# Apply assembly patch +z3ed asar patch.asm --rom=zelda3.sfc -Dependencies are included as submodules and will be built automatically. For those who want to reduce compile times, consider installing the dependencies on your system. See [build-instructions.md](docs/build-instructions.md) for more information. +# Extract symbols +z3ed extract patch.asm + +# Interactive TUI +z3ed --tui +``` + +See [build-instructions.md](docs/build-instructions.md) for detailed setup information. ## Documentation -- **[Getting Started](docs/getting-started.md)** - Basic setup and usage guide -- **[Build Instructions](docs/build-instructions.md)** - Detailed build and installation guide +- **[Getting Started](docs/getting-started.md)** - Setup and basic usage +- **[Asar Integration](docs/asar-integration.md)** - Assembly patching and symbol extraction +- **[Build Instructions](docs/build-instructions.md)** - Detailed build guide +- **[Contributing](docs/contributing.md)** - How to contribute - **[Documentation Index](docs/index.md)** - Complete documentation overview -- **[Contributing](docs/contributing.md)** - How to contribute to the project - -### Key Documentation -- **[Dungeon Editor Guide](docs/dungeon-editor-comprehensive-guide.md)** - Complete dungeon editing guide -- **[Overworld Loading Guide](docs/overworld_loading_guide.md)** - ZSCustomOverworld implementation -- **[Canvas Interface](docs/canvas-refactor-summary.md)** - Graphics system architecture -- **[Integration Tests](docs/integration_test_guide.md)** - Testing framework - -For developers, see the [documentation index](docs/index.md) for a complete overview of all available documentation. License -------- diff --git a/docs/asar-integration.md b/docs/asar-integration.md new file mode 100644 index 00000000..10a71e16 --- /dev/null +++ b/docs/asar-integration.md @@ -0,0 +1,404 @@ +# Asar 65816 Assembler Integration Guide + +Yaze v0.3.0 includes complete integration with the Asar 65816 assembler, enabling cross-platform ROM patching, symbol extraction, and assembly validation for SNES development. + +## Overview + +The Asar integration provides: +- **ROM Patching**: Apply 65816 assembly patches directly to SNES ROMs +- **Symbol Extraction**: Extract labels, addresses, and opcodes from assembly files +- **Assembly Validation**: Comprehensive syntax checking and error reporting +- **Cross-Platform**: Full support for Windows, macOS, and Linux +- **Modern APIs**: Both CLI tools and C++ programming interface + +## Quick Examples + +### Command Line Usage + +```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 + +# Extract symbols without patching +z3ed extract my_patch.asm + +# Validate assembly syntax +z3ed validate my_patch.asm +✅ Assembly file is valid + +# Launch interactive TUI +z3ed --tui +``` + +### C++ API Usage + +```cpp +#include "app/core/asar_wrapper.h" + +// Initialize Asar +yaze::app::core::AsarWrapper wrapper; +wrapper.Initialize(); + +// Apply patch to ROM +std::vector rom_data = LoadRom("zelda3.sfc"); +auto result = wrapper.ApplyPatch("patch.asm", rom_data); + +if (result.ok() && result->success) { + std::cout << "Found " << result->symbols.size() << " symbols:" << std::endl; + for (const auto& symbol : result->symbols) { + std::cout << " " << symbol.name << " @ $" + << std::hex << symbol.address << std::endl; + } +} + +// Extract symbols independently +auto symbols = wrapper.ExtractSymbols("source.asm"); +auto main_symbol = wrapper.FindSymbol("main_routine"); +``` + +## Assembly Patch Examples + +### Basic Hook + +```assembly +; Simple code hook +org $008000 +custom_hook: + sei ; Disable interrupts + rep #$30 ; 16-bit A and X/Y + + ; Your custom code + lda #$1234 + sta $7E0000 + + rts + +; Data section +custom_data: + db "YAZE", $00 + dw $1234, $5678 +``` + +### Advanced Features + +```assembly +; Constants and macros +!player_health = $7EF36C +!custom_ram = $7E2000 + +macro save_context() + pha : phx : phy +endmacro + +macro restore_context() + ply : plx : pla +endmacro + +; Main code +org $008000 +advanced_hook: + %save_context() + + ; Modify gameplay + sep #$20 + lda #$A0 ; Full health + sta !player_health + + %restore_context() + rtl +``` + +## Testing Infrastructure + +### ROM-Dependent Tests + +Yaze includes comprehensive testing that handles ROM files properly: + +```cpp +// ROM tests are automatically skipped in CI +YAZE_ROM_TEST(AsarIntegration, RealRomPatching) { + auto rom_data = TestRomManager::LoadTestRom(); + AsarWrapper wrapper; + wrapper.Initialize(); + + auto result = wrapper.ApplyPatch("test.asm", rom_data); + EXPECT_TRUE(result.ok()); +} +``` + +### CI/CD Compatibility + +- ROM-dependent tests are labeled with `ROM_DEPENDENT` +- CI automatically excludes these tests: `--label-exclude ROM_DEPENDENT` +- Development builds can enable ROM testing with `YAZE_ENABLE_ROM_TESTS=ON` + +## Cross-Platform Support + +### Build Configuration + +The Asar integration works across all supported platforms: + +```cmake +# Modern CMake target +target_link_libraries(my_target PRIVATE yaze::asar) + +# Cross-platform definitions automatically handled +# Windows: _CRT_SECURE_NO_WARNINGS, strcasecmp=_stricmp +# Linux: linux, stricmp=strcasecmp +# macOS: MACOS, stricmp=strcasecmp +``` + +### Platform-Specific Notes + +- **Windows**: Uses static linking with proper MSVC runtime +- **macOS**: Universal binaries support both Intel and Apple Silicon +- **Linux**: Compatible with both GCC and Clang compilers + +## API Reference + +### AsarWrapper Class + +```cpp +namespace yaze::app::core { + +class AsarWrapper { +public: + // Initialization + absl::Status Initialize(); + void Shutdown(); + bool IsInitialized() const; + + // Core functionality + absl::StatusOr ApplyPatch( + const std::string& patch_path, + std::vector& rom_data, + const std::vector& include_paths = {}); + + absl::StatusOr> ExtractSymbols( + const std::string& asm_path, + const std::vector& include_paths = {}); + + // Symbol management + std::optional FindSymbol(const std::string& name); + std::vector GetSymbolsAtAddress(uint32_t address); + std::map GetSymbolTable(); + + // Utility functions + absl::Status ValidateAssembly(const std::string& asm_path); + std::string GetVersion(); + void Reset(); +}; + +} +``` + +### Data Structures + +```cpp +struct AsarSymbol { + std::string name; // Symbol name + uint32_t address; // Memory address + std::string opcode; // Associated opcode + std::string file; // Source file + int line; // Line number + std::string comment; // Optional comment +}; + +struct AsarPatchResult { + bool success; // Whether patch succeeded + std::vector errors; // Error messages + std::vector warnings; // Warning messages + std::vector symbols; // Extracted symbols + uint32_t rom_size; // Final ROM size + uint32_t crc32; // CRC32 checksum +}; +``` + +## Error Handling + +### Common Errors and Solutions + +| Error | Cause | Solution | +|-------|-------|----------| +| `Unknown command` | Invalid opcode | Check 65816 instruction reference | +| `Label not found` | Undefined label | Define the label or check spelling | +| `Invalid hex value` | Bad hex format | Use `$1234` format, not `$GOOD` | +| `Buffer too small` | ROM needs expansion | Check if ROM needs to be larger | + +### Error Handling Pattern + +```cpp +auto result = wrapper.ApplyPatch("patch.asm", rom_data); +if (!result.ok()) { + std::cerr << "Patch failed: " << result.status().message() << std::endl; + return; +} + +if (!result->success) { + std::cerr << "Assembly errors:" << std::endl; + for (const auto& error : result->errors) { + std::cerr << " " << error << std::endl; + } +} +``` + +## Development Workflow + +### CMake Presets + +```bash +# Development build with ROM testing +cmake --preset dev +cmake --build --preset dev +ctest --preset dev + +# CI-compatible build (no ROM tests) +cmake --preset ci +cmake --build --preset ci +ctest --preset ci + +# Release build with packaging +cmake --preset macos-release +cmake --build --preset macos-release +cmake --build --preset macos-release --target package +``` + +### Testing Workflow + +1. **Write assembly patch** +2. **Validate syntax**: `z3ed validate patch.asm` +3. **Extract symbols**: `z3ed extract patch.asm` +4. **Apply to test ROM**: `z3ed asar patch.asm --rom=test.sfc` +5. **Test in emulator** + +## Integration with Yaze Editor + +The Asar integration is built into the main yaze editor: + +- **Assembly Editor**: Real-time syntax validation +- **Project System**: Save/load assembly patches with projects +- **Symbol Browser**: Navigate symbols with address lookup +- **Patch Management**: Apply and manage multiple patches + +## Performance and Memory + +- **Large ROM Support**: Handles ROMs up to 16MB +- **Efficient Symbol Storage**: Hash-based symbol lookup +- **Memory Safety**: RAII and smart pointer usage +- **Cross-Platform Optimization**: Platform-specific optimizations + +## Future Enhancements + +Planned improvements for future versions: + +- **Real-time Assembly**: Live compilation and testing +- **Visual Debugging**: Assembly debugging tools +- **Patch Management**: GUI for managing multiple patches +- **Symbol Navigation**: Enhanced symbol browser with search + +## Assembly Patch Templates + +### Basic Assembly Structure + +```assembly +; Header comment explaining the patch +; Author: Your Name +; Purpose: Brief description + +; Constants section +!player_health = $7EF36C +!custom_ram = $7E2000 + +; Code section +org $008000 +main_hook: + ; Save context + pha : phx : phy + + ; Your custom code here + sep #$20 ; 8-bit A + lda #$A0 ; Full health + sta !player_health + + ; Restore context + ply : plx : pla + rts + +; Data section +data_table: + dw $1234, $5678, $9ABC +``` + +### Advanced Features + +```assembly +; Macro definitions +macro save_registers() + pha : phx : phy +endmacro + +macro restore_registers() + ply : plx : pla +endmacro + +; Conditional assembly +if !version == 3 + ; ZSCustomOverworld v3 specific code + org $C08000 +else + ; Vanilla ROM code + org $008000 +endif + +advanced_routine: + %save_registers() + + ; Complex logic here + + %restore_registers() + rtl +``` + +## Testing Your Patches + +### Development Workflow + +1. **Write Assembly**: Create your `.asm` patch file +2. **Validate**: `z3ed validate patch.asm` +3. **Extract Symbols**: `z3ed extract patch.asm` +4. **Apply Patch**: `z3ed asar patch.asm --rom=test.sfc` +5. **Test in Emulator**: Verify functionality + +### Best Practices + +- Always backup ROMs before patching +- Use test ROMs for development +- Validate assembly before applying +- Start with simple patches and build complexity +- Document your patches with clear comments + +## Troubleshooting + +### Common Issues + +| Issue | Solution | +|-------|----------| +| "Unknown command" | Check 65816 instruction reference | +| "Label not found" | Define the label or check spelling | +| "Invalid hex value" | Use `$1234` format, not `$GOOD` | +| "Buffer too small" | ROM may need expansion | + +### Getting Help + +- **CLI Help**: `z3ed help asar` +- **Community**: [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk) +- **Documentation**: [Complete guide](docs/index.md) + +--- + +For complete API reference and advanced usage, see the [documentation index](index.md). \ No newline at end of file diff --git a/docs/changelog.md b/docs/changelog.md index 94b1f30c..5b943846 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,5 +1,19 @@ # Changelog +## 0.3.0 (01-2025) +- **Asar 65816 Assembler Integration**: Complete cross-platform support for 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 +- **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 +- **Professional Packaging**: NSIS, DMG, and DEB/RPM installers +- **ROM-Dependent Testing**: Separated testing infrastructure for CI compatibility +- **Comprehensive Documentation**: Updated guides and API documentation + ## 0.2.2 (12-31-2024) - DungeonMap editing improvements - ZSCustomOverworld support diff --git a/docs/getting-started.md b/docs/getting-started.md index 34300b3c..a32211fe 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -37,7 +37,7 @@ This feature is still in development and is not yet fully documented. | Dungeon Maps | Todo | Edit dungeon maps. | | Scad Format | Done-ish | Open and view scad files (SCR, CGX, COL) | | Hex Editing | Done | View and edit ROM data in hex. | -| Asar Patching | In Progress | Apply Asar patches to your ROM or Project. | +| Asar Patching | Complete | Apply Asar 65816 assembly patches to ROM. | ## Command Line Interface @@ -45,9 +45,12 @@ Included with the editor is a command line interface (CLI) that allows you to pe | Command | Arg | Params | Status | |--------------------|-------|--------------------------------------|-------------| -| Apply BPS Patch | -a | rom_file bps_file | In progress | -| Create BPS Patch | -c | bps_file src_file modified_file | Not started | -| Asar Patch | -asar | asm_file rom_file | In progress | +| Apply Asar Patch | asar | patch.asm [--rom=file] | Complete | +| Extract Symbols | extract | patch.asm | Complete | +| Validate Assembly | validate | patch.asm | Complete | +| Apply BPS Patch | patch | patch.bps [--rom=file] | Complete | +| Create BPS Patch | create | src_file modified_file | In progress | +| Asar Patch (legacy) | -asar | asm_file rom_file | Complete | | Open ROM | -o | rom_file | Complete | | Backup ROM | -b | rom_file [new_file] | In progress | | Expand ROM | -x | rom_file file_size | Not started | diff --git a/docs/index.md b/docs/index.md index 3ae5131f..35cc17a9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,115 +1,145 @@ # Yaze Documentation -Welcome to the Yaze documentation. This cross-platform Zelda 3 ROM editor is built with C++20, SDL2, and ImGui, designed to be compatible with ZScream projects. +Welcome to the Yaze documentation. This cross-platform Zelda 3 ROM editor is built with modern C++23, SDL2, ImGui, and integrated Asar 65816 assembler support. ## Quick Start - [Getting Started](getting-started.md) - Basic setup and usage -- [Build Instructions](build-instructions.md) - How to build yaze +- [Build Instructions](build-instructions.md) - How to build yaze from source - [Contributing](contributing.md) - How to contribute to the project +## New in v0.3.0 + +- [Asar Integration Guide](asar-integration.md) - Complete 65816 assembler integration +- [Roadmap](roadmap.md) - Updated development plans and release timeline +- [Changelog](changelog.md) - Complete version history and changes + ## Core Documentation ### Architecture & Infrastructure -- [Infrastructure](infrastructure.md) - Project structure and architecture +- [Infrastructure](infrastructure.md) - Project structure and modern build system - [Assembly Style Guide](asm-style-guide.md) - 65816 assembly coding standards ### Editors -#### Dungeon Editor +#### Overworld Editor +- [Overworld Loading Guide](overworld_loading_guide.md) - ZSCustomOverworld v3 implementation +- [Overworld Expansion](overworld-expansion.md) - Advanced overworld features + +#### Dungeon Editor - [Dungeon Editor Guide](dungeon-editor-comprehensive-guide.md) - Complete dungeon editing guide - [Dungeon Editor Design Plan](dungeon-editor-design-plan.md) - Architecture and development guide - [Dungeon Integration Tests](dungeon-integration-tests.md) - Testing framework -#### Overworld Editor -- [Overworld Loading Guide](overworld_loading_guide.md) - ZScream vs Yaze implementation -- [Overworld Expansion](overworld-expansion.md) - ZSCustomOverworld features - ### Graphics & UI - [Canvas Interface Refactoring](canvas-refactor-summary.md) - Canvas system architecture - [Canvas Migration](canvas-migration.md) - Migration guide for canvas changes -### Testing +### Testing & Development - [Integration Test Guide](integration_test_guide.md) - Comprehensive testing framework -## Project Status +## Current Version: 0.3.0 (January 2025) -### Current Version: 0.2.2 (12-31-2024) +### ✅ Major New Features -#### ✅ Completed Features -- **Dungeon Editor**: Full dungeon editing with object rendering, sprite management, and room editing -- **Overworld Editor**: Complete overworld editing with ZSCustomOverworld v2/v3 support -- **Canvas System**: Refactored pure function interface with backward compatibility -- **Graphics System**: Optimized rendering with caching and performance monitoring -- **Integration Tests**: Comprehensive test suite for all major components +#### 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 -#### 🔄 In Progress -- **Sprite Builder System**: Custom sprite creation and editing +#### 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**: Music data editing interface +- **Music Editor**: Enhanced music data editing interface -#### ⏳ Planned -- **Advanced Object Editing**: Multi-object selection and manipulation -- **Plugin System**: Modular architecture for community extensions -- **Performance Optimizations**: Further rendering and memory optimizations +### ⏳ 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 -### Dungeon Editing -- Room object editing with real-time rendering -- Sprite management (enemies, NPCs, interactive objects) -- Item placement (keys, hearts, rupees, etc.) -- Entrance/exit management and room connections -- Door management with key requirements -- Chest management with treasure placement -- Undo/redo system with comprehensive state management +### 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 -### Overworld Editing -- ZSCustomOverworld v2/v3 compatibility -- Custom background colors and overlays -- Map properties and metadata editing -- Sprite positioning and management -- Tile16 editing and graphics management +### 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 -### Graphics System -- High-performance object rendering with caching -- SNES palette support and color management -- Graphics sheet editing and management -- Real-time preview and coordinate system management +### 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**: Enhanced overworld features -- **ZSCustomOverworld v3**: Advanced features with overlays and custom graphics +- **ZSCustomOverworld v2/v3**: Enhanced overworld features and compatibility +- **Custom Modifications**: Support for community ROM hacks and modifications -### Platform Support -- **Windows**: Full support with native builds -- **macOS**: Full support with native builds -- **Linux**: Full support with native builds -- **iOS**: Basic support (work in progress) +### 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 +## Development & Community ### Architecture +- **Modern C++23**: Latest language features for performance and safety - **Modular Design**: Component-based architecture for maintainability -- **Cross-Platform**: SDL2 and ImGui for consistent UI across platforms -- **Modern C++**: C++20 features for performance and safety -- **Testing**: Comprehensive integration test suite +- **Cross-Platform**: Consistent experience across all supported platforms +- **Comprehensive Testing**: Unit tests, integration tests, and ROM validation ### Contributing See [Contributing](contributing.md) for guidelines on: -- Code style and standards -- Testing requirements -- Pull request process -- Development setup - -## Community +- 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 @@ -117,4 +147,4 @@ This project is licensed under the terms specified in the [LICENSE](../LICENSE) --- -*Last updated: December 2024* +*Last updated: January 2025 - Version 0.3.0* \ No newline at end of file diff --git a/docs/infrastructure.md b/docs/infrastructure.md index b6300433..3a8f9621 100644 --- a/docs/infrastructure.md +++ b/docs/infrastructure.md @@ -2,15 +2,16 @@ For developers to reference. -The goal of yaze is to build a cross platform editor for the Legend of Zelda: A Link to the Past. The project is built using C++20, SDL2, and ImGui. The project is built using CMake and is designed to be modular and extensible. The project is designed to be built on Windows, macOS, iOS, and Linux. +The goal of yaze is to build a cross platform editor for the Legend of Zelda: A Link to the Past. The project is built using C++23, SDL2, ImGui, and Asar 65816 assembler. The project uses modern CMake 3.16+ and is designed to be modular and extensible. The project supports Windows, macOS, and Linux with professional packaging and CI/CD. ## Targets -- **yaze**: Desktop application for Windows/macOS/Linux -- **z3ed**: Command Line Interface -- **yaze_c**: C Library -- **yaze_test**: Unit test executable -- **yaze_ios**: iOS application +- **yaze**: Desktop application with GUI docking system (Windows/macOS/Linux) +- **z3ed**: Enhanced command line interface with Asar integration and TUI +- **yaze_c**: C Library for custom tools and extensions +- **yaze_test**: Comprehensive unit test executable with ROM-dependent test separation +- **yaze_emu**: Standalone SNES emulator application +- **yaze_ios**: iOS application (coming in future release) ## Directory Structure @@ -31,10 +32,21 @@ The goal of yaze is to build a cross platform editor for the Legend of Zelda: A See [build-instructions.md](docs/build-instructions.md) for more information. -- **SDL2**: Graphics library -- **ImGui**: GUI library -- **Abseil**: C++ library -- **libpng**: Image library +### Core Dependencies +- **SDL2**: Graphics and input library +- **ImGui**: Immediate mode GUI library with docking support +- **Abseil**: Modern C++ utilities library +- **libpng**: Image processing library + +### New in v0.3.0 +- **Asar**: 65816 assembler for ROM patching and symbol extraction +- **ftxui**: Terminal UI library for enhanced CLI experience +- **GoogleTest/GoogleMock**: Comprehensive testing framework + +### Build System +- **CMake 3.16+**: Modern build system with target-based configuration +- **CMakePresets**: Development workflow presets +- **Cross-platform CI/CD**: GitHub Actions for automated builds and testing ## Flow of Control diff --git a/docs/roadmap.md b/docs/roadmap.md index de1e2ab0..36d488a0 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,15 +1,22 @@ # Roadmap -## 0.2.X (Current) -- Overworld Editing Features -- Palette Editing Features -- Hex Editing +## 0.3.0 (Current - Released January 2025) +- **Asar 65816 Assembler Integration**: Complete cross-platform ROM patching with assembly code +- **ZSCustomOverworld v3**: Complete integration with enhanced overworld editing capabilities +- **Advanced Message Editing**: Enhanced text editing interface with improved parsing +- **GUI Docking System**: Improved docking and workspace management for better workflow +- **Symbol Extraction**: Extract and analyze assembly symbols with addresses +- **Enhanced CLI Tools**: Modern z3ed command-line interface with improved UX +- **Modernized Build System**: CMake 3.16+ with professional packaging and CI/CD +- **Testing Infrastructure**: Comprehensive test suite with ROM-dependent test separation -## 0.3.X -- Overworld Sprites: Complete sprite editing, add/remove functionality. -- Tile16 Editing: Implement the core editor to create, modify, and store tile16 data. -- Palette Editing: Finalize palette editor UI and saving of palette groups. -- Dungeon Maps: Introduce map layouts and tile-based editing for dungeons. +## 0.4.X (Next Major Release) +- **Overworld Sprites**: Complete sprite editing, add/remove functionality +- **Enhanced Dungeon Editing**: Advanced room object draw and edit functionality +- **Tile16 Editing**: Enhanced editor for creating and modifying tile16 data +- **Plugin Architecture**: Framework for community extensions and custom tools +- **Graphics Sheets**: Complete editing, saving, and re-importing of sheets +- **Project Refactoring**: Clean up resource loading and memory usage ## 0.4.X - Dungeon: Implement room object draw and edit functionality.