- Rust 97.7%
- Python 2.3%
32eaffa0fe
Select it with --save-type sram (SaveDevice::Sram). The array is byte-wide, starts erased, and repeats every 32 KiB through the 0x0e00xxxx save window. A CPU byte store is staged and committed when its step completes, so failed steps roll back and reads later in the step see the byte. Unlike Flash, SRAM can be read from ROM code. Halfword/word access and DMA stay diagnostic until the 8-bit bus behavior for those widths is verified. SRAM shares the save-image API, host save files, and save states. Its device code is new, so existing save states keep loading. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HhfHfHEuzv2AUTd6erW1gU |
||
|---|---|---|
| .pi | ||
| crates | ||
| docs | ||
| tools | ||
| .envrc | ||
| .gitignore | ||
| AGENTS.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CLAUDE.md | ||
| flake.lock | ||
| flake.nix | ||
| README.md | ||
gameboy-rust
Game Boy family emulation in Rust, written from scratch. The Game Boy Advance (GBA) is the first and currently only system.
This cannot run Pokémon Emerald or other commercial games yet. It is an emulator foundation: an ARM7TDMI interpreter, memory bus, timers, DMA, Mode 0–5 video, and an original BIOS replacement. The included demos run original ARM test programs through the emulated hardware. Raw ROM files can run in terminal sessions or a window with keyboard input. Audio and saves are not implemented. A pinned Pong homebrew passes scripted menu, ball-motion, and paddle-input checks.
Layout
| Crate | Purpose |
|---|---|
crates/gba-core |
Platform-independent GBA emulator. No external Rust dependencies. |
crates/gba-demos |
Original test programs that drive the core. |
crates/desktop |
Native window frontend on minifb. Builds the gameboy-rust executable. |
Quick start
macOS on Apple Silicon is the verified platform. Install Nix (with flakes) and direnv, then:
direnv allow .
direnv exec . cargo run --locked --release -- --tile-demo
direnv exec . cargo test --locked
Arrows scroll, Q rotates, W zooms, Z flips, X changes priority, Enter resets, and Escape exits.
Run direnv exec . cargo run --locked -- --help to list all modes.
For original ROM files, use --rom path/to/original.gba --window, or --steps 100000 instead of --window for terminal diagnostics.
See cartridge loading for limits and report meanings.
Use --test-suite suite.json for repeatable headless ROM assertions.
Documentation
| Document | Contents |
|---|---|
| docs/status.md | What works today, deliberate limits, and next steps |
| docs/usability-roadmap.md | General GBA usability criteria and feature priorities |
| docs/demos.md | Every demo, its command, and its controls |
| docs/development.md | Nix, direnv, and macOS build notes |
| docs/testing.md | Validation commands and what the test suites cover |
| docs/rom-tests.md | Headless ROM suites, completion checks, assertions, and JSON reports |
| docs/jev-debugging.md | Optional /jev-gb-debug workflow, evidence review, and local evaluation records |
| docs/public-arm-tests.md | Pinned public ARM test, preparation command, results, and limits |
| docs/public-thumb-tests.md | Pinned public Thumb test, result protocol, and compatibility baseline |
| docs/public-memory-tests.md | Pinned public memory test, results, and video-byte coverage limits |
| docs/public-bios-tests.md | Pinned BIOS read-protection result and firmware limits |
| docs/public-pong.md | Playable homebrew setup, scripted gameplay baseline, and limits |
| docs/architecture.md | Crate boundaries and a file-by-file map |
| docs/hardware/cpu.md | ARM/Thumb execution rules, modes, exceptions, and timing |
| docs/hardware/cartridge.md | ROM loading, window/input controls, original ROM generator, and diagnostics |
| docs/hardware/save-states.md | Whole-machine save states, F5/F9 hotkeys, format, and limits |
| docs/hardware/bios.md | The original BIOS replacement and each supported service |
| docs/hardware/timers-irq.md | Timers, interrupt registers, HALT/STOP, and power control |
| docs/hardware/dma.md | DMA channels, triggers, and timing |
| docs/hardware/audio.md | Sound devices, stereo capture, optional Darwin output, and limits |
| docs/hardware/serial.md | Disconnected serial initialization and transfer limits |
| docs/hardware/display-timing.md | Display clock, status, IRQs, and scanline capture |
| docs/hardware/video.md | Backgrounds, sprites, mosaic, windows, color effects, and input |
| docs/references.md | External hardware references and emulator sources consulted |
Coding agents should start with AGENTS.md.
Legal
All demo content and the BIOS replacement are original. No Nintendo code or assets are included. Only use game ROMs that you may lawfully use. Do not commit game ROMs, BIOS files, or game assets.