0xrsydn/gameboy-rust
1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
gameboy-rust/AGENTS.md
0xrsydn 661f00d682 test(memory): integrate pinned public memory compatibility suite 
Add --suite memory with verified source hashes, ARM eval checkpoint 0x08000350, and the r12 result assertion. Keep default ARM and explicit Thumb preparation unchanged. Extend offline adapter and CLI tests; retain public binaries outside tracked files.

The unmodified memory ROM passes in debug and release after 174 steps and 1478 nominal cycles, without changing core behavior. Document weak byte-write assertions and mode-selection caveats. Add original CPU-driven tests with exact sentinels, mode/mirror boundaries, byte lanes, forced blank, readback, and nominal device timing.

Validated on Darwin arm64: 851 workspace tests in debug and release; 782 core/demo tests separately; 30 Python tests; all three pinned public suites in both profiles; native ROM windows; all ten demo smoke tests; fmt, clippy, rustdoc, and local documentation links.
2026-10-05 21:19:32 +07:00

3.9 KiB
Raw Blame History

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 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 has a file-by-file map.

Commands

Run through direnv so the Nix toolchain and macOS build flags apply:

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.

Where to read

Working on Read
ARM/Thumb instructions, modes, exceptions, timing docs/hardware/cpu.md
Pinned public ARM/Thumb tests and compatibility results docs/public-arm-tests.md, docs/public-thumb-tests.md
Pinned public memory tests and video-byte coverage limits docs/public-memory-tests.md
ROM test suites, assertions, and JSON reports docs/rom-tests.md
ROM files, window execution, and terminal diagnostics docs/hardware/cartridge.md
BIOS services (SWI) docs/hardware/bios.md
Timers, IE/IF/IME, HALT/STOP docs/hardware/timers-irq.md
DMA docs/hardware/dma.md
VCOUNT/DISPSTAT, HBlank/VBlank, row capture docs/hardware/display-timing.md
Backgrounds, sprites, mosaic, windows, blending, input docs/hardware/video.md
Demos and key mapping docs/demos.md
Build environment, minifb workarounds 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, or in a "References" section of the subsystem doc when the link explains one specific behavior.
  • Update 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.