7d396fea35
Move the README's hardware notes, demo controls, environment setup, test notes, file map, and references into docs/ and docs/hardware/. The README is now an overview with a docs index. AGENTS.md gives coding agents a short map of crates, commands, and where to read and write documentation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
59 lines
3.4 KiB
Markdown
59 lines
3.4 KiB
Markdown
# AGENTS.md
|
|
|
|
Orientation for coding agents. This is a map, not a rulebook: use your judgment, and read the linked doc for the area you are touching rather than everything.
|
|
|
|
## What this is
|
|
|
|
`gameboy-rust` is a from-scratch Game Boy family emulator in Rust. The Game Boy Advance comes first; other systems (GB, GBC) may follow as separate cores.
|
|
It cannot run commercial games yet. See [docs/status.md](docs/status.md) for what works, what is deliberately missing, and what is next.
|
|
|
|
## Crates
|
|
|
|
- `crates/gba-core`: the emulator (CPU, memory bus, I/O, timers, DMA, video, BIOS replacement). Keep it free of external dependencies and of window, audio, clock, and file-system code, so it stays portable to WebAssembly.
|
|
- `crates/gba-demos`: original ARM test programs and frame runners that drive the core.
|
|
- `crates/desktop`: minifb frontend and the `gameboy-rust` binary. Host-specific code belongs here.
|
|
|
|
[docs/architecture.md](docs/architecture.md) has a file-by-file map.
|
|
|
|
## Commands
|
|
|
|
Run through direnv so the Nix toolchain and macOS build flags apply:
|
|
|
|
```sh
|
|
direnv exec . cargo test --locked # everything
|
|
direnv exec . cargo test --locked -p gba-core -p gba-demos # skip the window dependency
|
|
direnv exec . cargo clippy --locked --all-targets -- -D warnings
|
|
direnv exec . cargo fmt --all
|
|
direnv exec . cargo run --locked --release -- --tile-demo # --help lists all modes
|
|
```
|
|
|
|
Window smoke tests (`--*-smoke-test`) need a logged-in desktop session. Details are in [docs/testing.md](docs/testing.md).
|
|
|
|
## Where to read
|
|
|
|
| Working on | Read |
|
|
| --- | --- |
|
|
| ARM/Thumb instructions, modes, exceptions, timing | [docs/hardware/cpu.md](docs/hardware/cpu.md) |
|
|
| BIOS services (SWI) | [docs/hardware/bios.md](docs/hardware/bios.md) |
|
|
| Timers, IE/IF/IME, HALT | [docs/hardware/timers-irq.md](docs/hardware/timers-irq.md) |
|
|
| DMA | [docs/hardware/dma.md](docs/hardware/dma.md) |
|
|
| VCOUNT/DISPSTAT, HBlank/VBlank, row capture | [docs/hardware/display-timing.md](docs/hardware/display-timing.md) |
|
|
| Backgrounds, sprites, mosaic, windows, blending, input | [docs/hardware/video.md](docs/hardware/video.md) |
|
|
| Demos and key mapping | [docs/demos.md](docs/demos.md) |
|
|
| Build environment, minifb workarounds | [docs/development.md](docs/development.md) |
|
|
|
|
## Where to write
|
|
|
|
- Behavior notes for a subsystem go in its `docs/hardware/*.md` file. Add a new file there when a new subsystem arrives (audio, cartridge, saves).
|
|
- Sources you consulted, including web searches, go in [docs/references.md](docs/references.md), or in a "References" section of the subsystem doc when the link explains one specific behavior.
|
|
- Update [docs/status.md](docs/status.md) when a feature lands or a limit goes away.
|
|
- Keep `README.md` short: overview, quick start, and the docs index.
|
|
- Avoid hard-coded test counts in prose; they go stale with every change.
|
|
|
|
## Conventions
|
|
|
|
- Version control is jj (colocated with git). History is a linear stack with one bookmark per change, named `feature/<topic>` or `refactor/<topic>`.
|
|
- Commit messages follow Conventional Commits, for example `feat(bios): implement SoftReset restart service`.
|
|
- New behavior comes with tests. Core integration tests live in `crates/gba-core/tests/`.
|
|
- The core currently reports unsupported hardware behavior as explicit errors rather than guessing. Prefer that to silent approximations, and note the gap in the docs.
|
|
- Everything in the repo is original. Do not add Nintendo BIOS code, game ROMs, or game assets.
|