https://github.com/scawful/yaze
Yet Another Zelda3 Editor
https://github.com/scawful/yaze
romhacking zelda
Last synced: 4 months ago
JSON representation
Yet Another Zelda3 Editor
- Host: GitHub
- URL: https://github.com/scawful/yaze
- Owner: scawful
- License: other
- Created: 2022-06-09T03:29:05.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2026-02-14T08:58:44.000Z (4 months ago)
- Last Synced: 2026-02-14T09:24:12.099Z (4 months ago)
- Topics: romhacking, zelda
- Language: C++
- Homepage:
- Size: 19.9 MB
- Stars: 42
- Watchers: 2
- Forks: 6
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# YAZE - Yet Another Zelda3 Editor
[](https://github.com/scawful/yaze/actions)
[](LICENSE)
A ROM editor for The Legend of Zelda: A Link to the Past.
Built in C++23 with ImGui, includes a built-in SNES emulator, the Asar 65816 assembler, and a CLI tool (`z3ed`) for scripted ROM operations. Runs on Windows, macOS, and Linux. There's also an experimental WASM build for browsers.
## What It Does
- **Overworld Editor** - Edit 160 overworld maps, tiles, entrances, exits
- **Dungeon Editor** - Edit 296 dungeon rooms, objects, sprites, palettes
- **Graphics Editor** - View and edit 223 graphics sheets, tilesets
- **Palette Editor** - Modify color palettes with live preview
- **Message Editor** - Edit in-game text and dialogue
- **Sprite Editor** - View sprite graphics and animations
- **Music Editor** - (Experimental) View and edit SPC700 music data
- **Built-in Emulator** - Test changes without leaving the editor
- **CLI (z3ed)** - Script ROM operations, integrate with AI agents (Ollama or cloud APIs)
## Apps
- **Desktop app (yaze)** - Full GUI editor + emulator. See `docs/public/build/quick-reference.md`.
- **CLI (z3ed)** - Scriptable ROM editing and AI workflows. See `docs/public/usage/z3ed-cli.md`.
- **Web/WASM preview** - Browser-based editor with a subset of features. See `docs/public/usage/web-app.md`.
## What It Needs
- A legally obtained ALttP ROM (US or JP)
- CMake 3.25+, C++23 compiler (Clang 16+, GCC 13+, or MSVC 2022+)
- For AI features: Ollama running locally or a cloud API key (Gemini/OpenAI/Anthropic)
## Project Status
v0.6.2 is the current release. See [`CHANGELOG.md`](CHANGELOG.md) for details.
| Component | Status | Notes |
|-----------|--------|-------|
| Overworld Editor | Beta | 160 maps, undo/redo, copy/paste; tile16 palette issues, sprite workflow incomplete |
| Dungeon Editor | Beta | 296 rooms, entity drag-drop, ROM safety; 12+ unknown object types, visual discrepancies |
| Graphics Editor | Beta | Sheet editing, undo/redo |
| Palette Editor | Beta | Live preview; JSON import/export not implemented |
| Message Editor | Stable | Text editing, bundle import/export |
| Assembly Editor | Beta | Symbol navigation, Asar integration; project file editor incomplete |
| Sprite Editor | Beta | Viewing works, editing limited |
| Music Editor | Beta | Playback and editing, no clipboard ops |
| Screen Editor | WIP | Core operations unimplemented |
| Memory Editor | WIP | Hex viewing only, search unimplemented |
| Emulator | Beta | Functional, save-state UI incomplete |
See [`docs/public/reference/feature-coverage-report.md`](docs/public/reference/feature-coverage-report.md)
for cross-app status, persistence notes, and test coverage.
## Quick Start
```bash
# Clone
git clone --recursive https://github.com/scawful/yaze.git
cd yaze
# Build (macOS, AI-enabled editor + CLI)
cmake --preset mac-ai
cmake --build build_ai --target yaze z3ed --parallel 8
# Run
./scripts/yaze zelda3.sfc
```
**Presets:** `mac-dbg`, `mac-rel`, `lin-dbg`, `lin-rel`, `win-dbg`, `win-rel`
For AI features, use `*-ai` presets (`mac-ai`, `win-ai`) which enable
Ollama/Gemini/OpenAI/Anthropic integration.
See [`docs/public/build/quick-reference.md`](docs/public/build/quick-reference.md) for full build instructions.
## Usage
```bash
# GUI editor
./scripts/yaze zelda3.sfc
# CLI - ROM info
./scripts/z3ed rom-info --rom=zelda3.sfc
# CLI - List dungeon sprites
./scripts/z3ed dungeon-list-sprites --room=1 --rom=zelda3.sfc
# CLI - Interactive TUI
./scripts/z3ed --tui
# Web version (experimental)
# https://scawful.github.io/yaze/
```
## Testing
```bash
# Fast local loop (quick labeled suites)
./scripts/test_fast.sh --quick
# Stable suites (label-filtered)
ctest --test-dir build_ai -C Debug -L unit
ctest --test-dir build_ai -C Debug -L integration
# Preset-based runs (see CMakePresets.json testPresets)
ctest --preset mac-ai-unit
ctest --preset mac-ai-quick-unit
ctest --preset mac-ai-quick-integration
```
Some tests require a ROM. Set `YAZE_TEST_ROM_VANILLA` or
`YAZE_TEST_ROM_VANILLA_PATH` (and optionally `YAZE_TEST_ROM_EXPANDED` or
`YAZE_TEST_ROM_EXPANDED_PATH`).
Web app smoke checks: load `src/web/tests/wasm_debug_api_tests.js` in the
browser console and run `await window.runWasmDebugApiTests()`.
## Documentation
- User docs: [`docs/public/`](docs/public/index.md)
- Developer docs: [`docs/internal/`](docs/internal/README.md)
- API reference: `doxygen Doxyfile` generates to `build/docs/`
## Contributing
See [`CONTRIBUTING.md`](CONTRIBUTING.md). Discussion on [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk).
## License
GPL v3. See [`LICENSE`](LICENSE).
## Screenshots
