scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README and build instructions for clarity and organization

Browse Source 
- 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.
This commit is contained in:
scawful
2025-09-26 15:00:57 -04:00
parent 78579d2934
commit caffe59800
8 changed files with 410 additions and 282 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
README.md
View File

@@ -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) [![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) [![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 ## Version 0.3.0 - Stable Release
**Complete Asar Integration • Modern Build System • Enhanced CLI Tools • Professional CI/CD**
### ✨ Key Features
#### Asar 65816 Assembler Integration #### Asar 65816 Assembler Integration
- **Cross-platform ROM patching** with assembly code support - **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 - **Professional packaging**: NSIS, DMG, and DEB/RPM installers
- **Enhanced testing**: ROM-dependent test separation for CI compatibility - **Enhanced testing**: ROM-dependent test separation for CI compatibility
## 🏗️ Quick Start ## Quick Start
### Prerequisites
- **CMake 3.16+**
- **C++23 Compiler** (GCC 13+, Clang 16+, MSVC 2022 17.8+)
- **Git** with submodule support
### Build ### Build
```bash ```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 git clone --recursive https://github.com/scawful/yaze.git
cd yaze cd yaze
# Build with presets # Build with CMake
cmake --preset dev cmake --preset debug # macOS
cmake --build --preset dev cmake -B build && cmake --build build # Linux/Windows
# Run tests
ctest --preset stable
``` ```
### Targets ### Applications
- **yaze**: GUI Editor Application with docking system - **yaze**: Complete GUI editor for Zelda 3 ROM hacking
- **z3ed**: Enhanced CLI Tool with Asar integration and TUI - **z3ed**: Command-line tool with interactive interface
- **yaze_c**: C Library for extensions and custom tools - **yaze_test**: Comprehensive test suite for development
- **yaze_test**: Comprehensive test suite executable
- **yaze_emu**: Standalone SNES emulator application
## 💻 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 ```bash
# Apply assembly patch to ROM # Apply assembly patch
z3ed asar my_patch.asm --rom=zelda3.sfc z3ed asar 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 # Extract symbols from assembly
z3ed extract my_patch.asm z3ed extract patch.asm
# Validate assembly syntax # Interactive mode
z3ed validate my_patch.asm
✅ Assembly file is valid
# Launch interactive TUI
z3ed --tui z3ed --tui
``` ```
### C++ API Usage ### C++ API
```cpp ```cpp
#include "app/core/asar_wrapper.h" #include "yaze.h"
yaze::app::core::AsarWrapper wrapper; // Load ROM and apply patch
wrapper.Initialize(); yaze_project_t* project = yaze_load_project("zelda3.sfc");
yaze_apply_asar_patch(project, "patch.asm");
// Apply patch to ROM yaze_save_project(project, "modified.sfc");
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;
}
}
``` ```
## 📚 Documentation ## Documentation
### Core Documentation - [Getting Started](docs/01-getting-started.md) - Setup and basic usage
- **[Getting Started](docs/01-getting-started.md)** - Basic setup and usage - [Build Instructions](docs/02-build-instructions.md) - Building from source
- **[Build Instructions](docs/02-build-instructions.md)** - Detailed build guide - [API Reference](docs/04-api-reference.md) - Programming interface
- **[Asar Integration](docs/03-asar-integration.md)** - Complete 65816 assembler guide - [Contributing](docs/B1-contributing.md) - Development guidelines
- **[API Reference](docs/04-api-reference.md)** - C/C++ API documentation
### Development **[Complete Documentation](docs/index.md)**
- **[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
### Technical Documentation ## Supported Platforms
- **[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
**[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 ## Contributing
- **macOS**: Universal binaries supporting Intel and Apple Silicon
- **Linux**: GCC and Clang support with package management
- **Professional Packaging**: Native installers for all platforms
## 🎮 ROM Compatibility See [Contributing Guide](docs/B1-contributing.md) for development guidelines.
- **Vanilla ROMs**: Original Zelda 3 ROMs (US/JP) **Community**: [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk)
- **ZSCustomOverworld v2/v3**: Enhanced overworld features and compatibility
- **Custom Modifications**: Support for community ROM hacks and modifications
## 🤝 Contributing ## License
We welcome contributions! Please see our [Contributing Guide](docs/B1-contributing.md) for: GNU GPL v3 - See [LICENSE](LICENSE) for details.
- 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.
## 🙏 Acknowledgments ## 🙏 Acknowledgments

168
docs/02-build-instructions.md
View File

@@ -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=twxs.cmake
- https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools - https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
## Quick Build ## Quick Start
### macOS (Apple Silicon)
```bash ```bash
# Development build cmake --preset debug
cmake --preset dev cmake --build build
cmake --build --preset dev ```
# CI build (minimal dependencies) ### Linux / Windows
cmake --preset ci ```bash
cmake --build --preset ci cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
```
### Minimal Build
```bash
cmake -B build -DYAZE_MINIMAL_BUILD=ON
cmake --build build
``` ```
## Dependencies ## Dependencies
### Core Dependencies ### Required
- **SDL2**: Graphics and input library - CMake 3.16+
- **ImGui**: Immediate mode GUI library with docking support - C++23 compiler (GCC 13+, Clang 16+, MSVC 2019+)
- **Abseil**: Modern C++ utilities library - Git with submodule support
- **libpng**: Image processing library
### v0.3.0 Additions ### Bundled Libraries
- **Asar**: 65816 assembler for ROM patching - SDL2, ImGui, Abseil, Asar, GoogleTest
- **ftxui**: Terminal UI library for CLI - Native File Dialog Extended (NFD)
- **GoogleTest**: Comprehensive testing framework - All dependencies included in repository
## Platform-Specific Setup ## Platform 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`
### macOS ### macOS
```bash ```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 ### Linux (Ubuntu/Debian)
Use your package manager to install the same dependencies as macOS. ```bash
sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build pkg-config \
libgtk-3-dev libdbus-1-dev
```
### iOS ### Windows
Xcode required. The xcodeproject file is in the `ios` directory. Link `SDL2.framework` and `libpng.a`. **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 ## Build Targets
- **yaze**: Desktop GUI application ### Applications
- **z3ed**: Enhanced CLI tool - **yaze**: Main GUI editor application
- **yaze_c**: C library for extensions - **z3ed**: Command-line interface tool
- **yaze_test**: Test suite executable
### Libraries
- **yaze_c**: C API library for extensions
- **asar-static**: 65816 assembler library
### Development (Debug Builds Only)
- **yaze_emu**: Standalone SNES emulator - **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
```

55
docs/B2-ci-cd-fixes.md Normal file
View File

@@ -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)

55
docs/B2-platform-compatibility.md Normal file
View File

@@ -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)

109
docs/B3-build-presets.md Normal file
View File

@@ -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

4
docs/E5-dungeon-object-system.md
View File

@@ -1,8 +1,8 @@
# YAZE Dungeon Object System # Dungeon Object System
## Overview ## 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 ## Architecture

32
docs/F2-overworld-expansion.md
View File

@@ -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);
}
}

126
docs/index.md
View File

@@ -1,20 +1,20 @@
# YAZE Documentation # 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 ## Quick Start
- [Getting Started](01-getting-started.md) - Basic setup and usage - [Getting Started](01-getting-started.md) - Basic setup and usage
- [Build Instructions](02-build-instructions.md) - How to build from source - [Build Instructions](02-build-instructions.md) - Cross-platform build guide
- [Asar Integration](03-asar-integration.md) - Complete 65816 assembler guide - [Asar Integration](03-asar-integration.md) - 65816 assembler usage
- [API Reference](04-api-reference.md) - C/C++ API documentation - [API Reference](04-api-reference.md) - C/C++ API documentation
## Development ## Development
- [Testing Guide](A1-testing-guide.md) - Comprehensive testing framework - [Testing Guide](A1-testing-guide.md) - Testing framework and best practices
- [Contributing](B1-contributing.md) - Development guidelines and standards - [Contributing](B1-contributing.md) - Development guidelines and standards
- [Changelog](C1-changelog.md) - Version history and changes - [Platform Compatibility](B2-platform-compatibility.md) - Cross-platform support details
- [Roadmap](D1-roadmap.md) - Development plans and timeline - [Build Presets](B3-build-presets.md) - CMake preset usage guide
## Technical Documentation ## Technical Documentation
@@ -29,115 +29,15 @@ Cross-platform Zelda 3 ROM editor built with modern C++23, SDL2, ImGui, and inte
### Overworld System ### Overworld System
- [Overworld Loading](F1-overworld-loading.md) - ZSCustomOverworld v3 implementation - [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 ## Key Features
### ROM Editing Capabilities - Complete GUI editor for all aspects of Zelda 3 ROM hacking
- **Asar 65816 Assembly**: Apply assembly patches with symbol extraction - Integrated Asar 65816 assembler for custom code patches
- **Overworld Editing**: ZSCustomOverworld v3 with enhanced features - ZSCustomOverworld v3 support for enhanced overworld editing
- **Message Editing**: Advanced text editing with real-time preview - Cross-platform support (Windows, macOS, Linux)
- **Palette Management**: Comprehensive color and palette editing - Modern C++23 codebase with comprehensive testing
- **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.
--- ---
*Last updated: January 2025 - Version 0.3.0* *Last updated: September 2025 - Version 0.3.0*