- Rust 97.7%
- Python 2.3%
597b02881b
Add a dependency-free keypad state machine in gba-core, map KEYCNT, latch IF bit 12, and wake HALT through the existing interrupt gates. Sample complete CPU/DMA control writes once so transient byte values cannot create false requests. Document the mGBA-style polling policy and its unverified hardware retrigger limits. Cover every button-state/selection pair, register masks, repeated requests, byte/word writes, failed-store isolation, DMA priority, ARM/Thumb IRQ return, BIOS IntrWait, and retained BIOS reset state. Follow the restructured workspace and modular documentation. Validated on Darwin arm64: workspace and core/demo tests pass in debug and release, with Clippy, rustdoc, ten native window smoke tests, and terminal demos passing. |
||
|---|---|---|
| crates | ||
| docs | ||
| .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 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. ROM loading, audio, and saves are not implemented.
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 every demo and smoke test.
Documentation
| Document | Contents |
|---|---|
| docs/status.md | What works today, deliberate limits, and next steps |
| 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/architecture.md | Crate boundaries and a file-by-file map |
| docs/hardware/cpu.md | ARM/Thumb execution rules, modes, exceptions, and timing |
| docs/hardware/bios.md | The original BIOS replacement and each supported service |
| docs/hardware/timers-irq.md | Timers, interrupt registers, HALT, and power control |
| docs/hardware/dma.md | DMA channels, triggers, and timing |
| 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.