65 lines
2.0 KiB
Markdown
65 lines
2.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
_Extends: ~/AGENTS.md, ~/CLAUDE.md_
|
|
|
|
C++23 ROM editor for Zelda: A Link to the Past. GUI editor + SNES emulator + AI CLI (`z3ed`).
|
|
|
|
## Build & Test
|
|
|
|
```bash
|
|
cmake --preset mac-dbg && cmake --build build -j8 # Build
|
|
ctest --test-dir build -L stable -j4 # Test
|
|
./yaze --rom_file=zelda3.sfc --editor=Dungeon # Run
|
|
```
|
|
|
|
Presets: `mac-dbg`/`lin-dbg`/`win-dbg`, `mac-ai`/`win-ai`, `*-rel`. See `docs/public/build/quick-reference.md`.
|
|
|
|
## Architecture
|
|
|
|
| Component | Location | Purpose |
|
|
|-----------|----------|---------|
|
|
| Rom | `src/app/rom.h` | ROM data access, transactions |
|
|
| Editors | `src/app/editor/` | Overworld, Dungeon, Graphics, Palette |
|
|
| Graphics | `src/app/gfx/` | Bitmap, Arena (async loading), Tiles |
|
|
| Zelda3 | `src/zelda3/` | Overworld (160 maps), Dungeon (296 rooms) |
|
|
| Canvas | `src/app/gui/canvas.h` | ImGui canvas with pan/zoom |
|
|
| CLI | `src/cli/z3ed.cc` | AI-powered ROM hacking tool |
|
|
|
|
## Key Patterns
|
|
|
|
**Graphics refresh**: Update model → `Load*()` → `Renderer::Get().RenderBitmap()`
|
|
|
|
**Async loading**: `Arena::Get().QueueDeferredTexture(bitmap, priority)` + process in `Update()`
|
|
|
|
**Bitmap sync**: Use `set_data()` for bulk updates (syncs `data_` and `surface_->pixels`)
|
|
|
|
**Theming**: Always use `AgentUI::GetTheme()`, never hardcoded colors
|
|
|
|
**Multi-area maps**: Always use `Overworld::ConfigureMultiAreaMap()`, never set `area_size` directly
|
|
|
|
## Naming
|
|
|
|
- **Load**: ROM → memory
|
|
- **Render**: Data → bitmap (CPU)
|
|
- **Draw**: Bitmap → screen (GPU)
|
|
|
|
## Pitfalls
|
|
|
|
1. Use `set_data()` not `mutable_data()` assignment for bitmap bulk updates
|
|
2. Call `ProcessTextureQueue()` every frame
|
|
3. Pass `0x800` to `DecompressV2`, never `0`
|
|
4. SMC header: `size % 1MB == 512`, not `size % 32KB`
|
|
5. Check `rom_->is_loaded()` before ROM operations
|
|
|
|
## Code Style
|
|
|
|
Google C++ Style. Use `absl::Status`/`StatusOr<T>` with `RETURN_IF_ERROR()`/`ASSIGN_OR_RETURN()`.
|
|
|
|
Format: `cmake --build build --target format`
|
|
|
|
## Docs
|
|
|
|
- Architecture: `docs/internal/architecture/`
|
|
- Build issues: `docs/BUILD-TROUBLESHOOTING.md`
|
|
- Tests: `test/README.md`
|