Update README and documentation for YAZE v0.3.0 release
- Revamped README to reflect the new branding and major features of YAZE, including complete Asar 65816 assembler integration and enhanced CLI tools. - Added new documentation files for getting started, build instructions, Asar integration, and comprehensive testing guides. - Removed outdated documentation and streamlined the structure for better navigation. - Introduced a changelog to track version history and significant updates. - Updated API reference and added detailed guides for dungeon and overworld editing functionalities.
This commit is contained in:
scawful
193
README.md
193
README.md
@@ -1,71 +1,178 @@
|
||||
# Yet Another Zelda3 Editor
|
||||
# YAZE - Yet Another Zelda3 Editor
|
||||
|
||||
A modern, cross-platform editor for The Legend of Zelda: A Link to the Past ROM hacking.
|
||||
A modern, cross-platform editor for The Legend of Zelda: A Link to the Past ROM hacking, built with C++23 and featuring complete Asar 65816 assembler integration.
|
||||
|
||||
- **Platform**: Windows, macOS, Linux
|
||||
- **Language**: C++23 with modern CMake build system
|
||||
- **Features**: ROM editing, Asar 65816 assembly patching, ZSCustomOverworld v3, GUI docking
|
||||
[](https://github.com/scawful/yaze/actions)
|
||||
[](https://www.gnu.org/licenses/gpl-3.0)
|
||||
|
||||
## Key Features
|
||||
## 🚀 Version 0.3.0 - Major Release
|
||||
|
||||
- **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
|
||||
**Complete Asar Integration • Modern Build System • Enhanced CLI Tools • Professional CI/CD**
|
||||
|
||||
Takes inspiration from [Hyrule Magic](https://www.romhacking.net/utilities/200/) and [ZScream](https://github.com/Zarby89/ZScreamDungeon)
|
||||
### ✨ Key Features
|
||||
|
||||
## Building and Installation
|
||||
#### Asar 65816 Assembler Integration
|
||||
- **Cross-platform ROM patching** with assembly code support
|
||||
- **Symbol extraction** with addresses and opcodes from assembly files
|
||||
- **Assembly validation** with comprehensive error reporting
|
||||
- **Modern C++ API** with safe memory management
|
||||
|
||||
### Quick Build
|
||||
#### ZSCustomOverworld v3
|
||||
- **Enhanced overworld editing** capabilities
|
||||
- **Advanced map properties** and metadata support
|
||||
- **Custom graphics support** and tile management
|
||||
- **Improved compatibility** with existing projects
|
||||
|
||||
#### Advanced Features
|
||||
- **Message Editing**: Enhanced text editing interface with real-time preview
|
||||
- **GUI Docking**: Flexible workspace management with customizable layouts
|
||||
- **Modern CLI**: Enhanced z3ed tool with interactive TUI and subcommands
|
||||
- **Cross-Platform**: Full support for Windows, macOS, and Linux
|
||||
|
||||
### 🛠️ 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
|
||||
|
||||
## 🏗️ Quick Start
|
||||
|
||||
### Prerequisites
|
||||
- **CMake 3.16+**
|
||||
- **C++23 Compiler** (GCC 13+, Clang 16+, MSVC 2022 17.8+)
|
||||
- **Git** with submodule support
|
||||
|
||||
### Build
|
||||
```bash
|
||||
git clone --recurse-submodules https://github.com/scawful/yaze.git
|
||||
# Clone with submodules
|
||||
git clone --recursive https://github.com/scawful/yaze.git
|
||||
cd yaze
|
||||
cmake --preset default
|
||||
cmake --build --preset default
|
||||
|
||||
# Build with presets
|
||||
cmake --preset dev
|
||||
cmake --build --preset dev
|
||||
|
||||
# Run tests
|
||||
ctest --preset stable
|
||||
```
|
||||
|
||||
### Targets
|
||||
- **yaze**: GUI Editor Application
|
||||
- **z3ed**: Command Line Interface with Asar support
|
||||
- **yaze_c**: C Library
|
||||
- **yaze_test**: Unit Tests
|
||||
- **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
|
||||
|
||||
### Asar Examples
|
||||
## 💻 Usage Examples
|
||||
|
||||
### Asar Assembly Patching
|
||||
```bash
|
||||
# Apply assembly patch
|
||||
z3ed asar patch.asm --rom=zelda3.sfc
|
||||
# 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
|
||||
z3ed extract patch.asm
|
||||
# Extract symbols without patching
|
||||
z3ed extract my_patch.asm
|
||||
|
||||
# Interactive TUI
|
||||
# Validate assembly syntax
|
||||
z3ed validate my_patch.asm
|
||||
✅ Assembly file is valid
|
||||
|
||||
# Launch interactive TUI
|
||||
z3ed --tui
|
||||
```
|
||||
|
||||
See [build-instructions.md](docs/build-instructions.md) for detailed setup information.
|
||||
### C++ API Usage
|
||||
```cpp
|
||||
#include "app/core/asar_wrapper.h"
|
||||
|
||||
## Documentation
|
||||
yaze::app::core::AsarWrapper wrapper;
|
||||
wrapper.Initialize();
|
||||
|
||||
- **[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
|
||||
// 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;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
License
|
||||
--------
|
||||
YAZE is distributed under the [GNU GPLv3](https://www.gnu.org/licenses/gpl-3.0.txt) license.
|
||||
## 📚 Documentation
|
||||
|
||||
SDL2, ImGui and Abseil are subject to respective licenses.
|
||||
### 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
|
||||
|
||||
Screenshots
|
||||
--------
|
||||
|
||||
### 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
|
||||
|
||||
|
||||
### 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
|
||||
|
||||
|
||||
**[Complete Documentation Index](docs/index.md)**
|
||||
|
||||
## 🔧 Supported Platforms
|
||||
|
||||
- **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
|
||||
|
||||
## 🎮 ROM Compatibility
|
||||
|
||||
- **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
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
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.
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
Takes inspiration from:
|
||||
- [Hyrule Magic](https://www.romhacking.net/utilities/200/) - Original Zelda 3 editor
|
||||
- [ZScream](https://github.com/Zarby89/ZScreamDungeon) - Dungeon editing capabilities
|
||||
- [Asar](https://github.com/RPGHacker/asar) - 65816 assembler integration
|
||||
|
||||
## 📸 Screenshots
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
**Ready to hack Zelda 3? [Get started now!](docs/01-getting-started.md)**
|
||||
Reference in New Issue
Block a user