101 lines
6.0 KiB
Markdown
101 lines
6.0 KiB
Markdown
# YAZE - Yet Another Zelda3 Editor
|
||
|
||
[](https://github.com/scawful/yaze/actions)
|
||
[](https://github.com/scawful/yaze/actions)
|
||
[](https://github.com/scawful/yaze/actions)
|
||
[](https://github.com/scawful/yaze/actions)
|
||
[](LICENSE)
|
||
|
||
A cross-platform Zelda 3 ROM editor with a modern C++ GUI, Asar 65816 assembler integration, and an automation-friendly CLI (`z3ed`). YAZE bundles its toolchain, offers AI-assisted editing flows, and targets reproducible builds on Windows, macOS, and Linux. A preview web version is also available for browser-based editing.
|
||
|
||
## Highlights
|
||
- **All-in-one editing**: Overworld, dungeon, sprite, palette, and messaging tools with live previews.
|
||
- **Assembler-first workflow**: Built-in Asar integration, symbol extraction, and patch validation.
|
||
- **Automation & AI**: `z3ed` exposes CLI/TUI automation, proposal workflows, and optional AI agents.
|
||
- **Web preview**: Experimental browser-based editor (WASM) - see [Web App Guide](docs/public/usage/web-app.md).
|
||
- **Testing & CI hooks**: CMake presets, ROM-less test fixtures, and gRPC-based GUI automation support.
|
||
- **Cross-platform toolchains**: Single source tree targeting MSVC, Clang, and GCC with identical presets.
|
||
- **Modular AI stack**: Toggle agent UI (`YAZE_BUILD_AGENT_UI`), remote automation/gRPC (`YAZE_ENABLE_REMOTE_AUTOMATION`), and AI runtimes (`YAZE_ENABLE_AI_RUNTIME`) per preset.
|
||
|
||
## Project Status
|
||
v0.5.0 is the current release. New to YAZE? Start with a clean, legally obtained ALttP (USA) ROM and the Quick Start steps below. See [`docs/public/release-notes.md`](docs/public/release-notes.md) for details.
|
||
|
||
## Quick Start
|
||
|
||
### Clone & Bootstrap
|
||
```bash
|
||
git clone --recursive https://github.com/scawful/yaze.git
|
||
cd yaze
|
||
```
|
||
|
||
Run the environment verifier once per machine:
|
||
```bash
|
||
# macOS / Linux
|
||
./scripts/verify-build-environment.sh --fix
|
||
|
||
# Windows (PowerShell)
|
||
.\scripts\verify-build-environment.ps1 -FixIssues
|
||
```
|
||
|
||
### Configure & Build
|
||
- Use the CMake preset that matches your platform (`mac-dbg`, `lin-dbg`, `win-dbg`, etc.).
|
||
- Build with `cmake --build --preset <name> [--target …]`.
|
||
- See [`docs/public/build/quick-reference.md`](docs/public/build/quick-reference.md) for the canonical
|
||
list of presets, AI build policy, and testing commands.
|
||
|
||
### Agent Feature Flags
|
||
|
||
| Option | Default | Effect |
|
||
| --- | --- | --- |
|
||
| `YAZE_BUILD_AGENT_UI` | `ON` when GUI builds are enabled | Compiles the chat/dialog widgets so the editor can host agent sessions. Turn this `OFF` when you want a lean GUI-only build. |
|
||
| `YAZE_ENABLE_REMOTE_AUTOMATION` | `ON` for `*-ai` presets | Builds the gRPC servers/clients and protobufs that power GUI automation. |
|
||
| `YAZE_ENABLE_AI_RUNTIME` | `ON` for `*-ai` presets | Enables Gemini/Ollama transports, proposal planning, and advanced routing logic. |
|
||
| `YAZE_ENABLE_AGENT_CLI` | `ON` when CLI builds are enabled | Compiles the conversational agent stack consumed by `z3ed`. Disable to skip the CLI entirely. |
|
||
|
||
Windows `win-*` presets keep every switch `OFF` by default (`win-dbg`, `win-rel`, `ci-windows`) so MSVC builds stay fast. Use `win-ai`, `win-vs-ai`, or the new `ci-windows-ai` preset whenever you need remote automation or AI runtime features.
|
||
|
||
All bundled third-party code (SDL, ImGui, ImGui Test Engine, Asar, nlohmann/json, cpp-httplib, nativefiledialog-extended) now lives under `ext/` for easier vendoring and cleaner include paths.
|
||
|
||
## Applications & Workflows
|
||
- **`./build/bin/yaze`** – full GUI editor with multi-session dockspace, theming, and ROM patching.
|
||
- **Web App (Preview)** – browser-based editor at your deployed instance; see [`docs/public/usage/web-app.md`](docs/public/usage/web-app.md) for details and limitations.
|
||
- **`./build/bin/z3ed --tui`** – CLI/TUI companion for scripting, AI-assisted edits, and Asar workflows.
|
||
- **`ctest --test-dir build -L unit|integration|e2e`** – structured test runner for quick regression checks.
|
||
- **`z3ed` + macOS automation** – pair the CLI with sketchybar/yabai/skhd or Emacs/Spacemacs to drive ROM workflows without opening the GUI.
|
||
|
||
Typical commands:
|
||
```bash
|
||
# Launch GUI with a ROM
|
||
./build/bin/yaze roms/alttp_vanilla.sfc
|
||
|
||
# Apply a patch via CLI
|
||
./build/bin/z3ed asar patch.asm --rom roms/alttp_vanilla.sfc
|
||
|
||
# Run focused tests
|
||
cmake --build --preset mac-ai --target yaze_test
|
||
ctest --test-dir build -L unit
|
||
```
|
||
|
||
## Testing
|
||
- `ctest --test-dir build -L unit` for fast checks; add `-L integration` or `-L e2e --output-on-failure` for broader coverage.
|
||
- `ctest --preset dev` mirrors CI’s stable set; `ctest --preset all` runs the full matrix.
|
||
- Set `YAZE_TEST_ROM_VANILLA` or pass `--rom-vanilla` when a test needs a real ROM image (legacy `--rom-path` still works).
|
||
|
||
## Documentation
|
||
- Human-readable docs live under `docs/public/` with an entry point at [`docs/public/index.md`](docs/public/index.md).
|
||
- Run `doxygen Doxyfile` to generate API + guide pages (`build/docs/html` and `build/docs/latex`).
|
||
- Agent playbooks, architecture notes, and testing recipes now live in [`docs/internal/`](docs/internal/README.md).
|
||
|
||
## Contributing & Community
|
||
- Review [`CONTRIBUTING.md`](CONTRIBUTING.md) and the build/test guides in `docs/public/`.
|
||
- Conventional commit messages (`feat:`, `fix:`, etc.) keep history clean; use topic branches for larger work.
|
||
- Chat with the team on [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk).
|
||
|
||
## License
|
||
YAZE is licensed under the GNU GPL v3. See [`LICENSE`](LICENSE) for details and third-party notices.
|
||
|
||
## Screenshots
|
||
|
||
|
||
|