c256bf8ccd
Load read-only raw ROM files with bounded size checks and original BIOS boot. Require a machine-step budget and report CPU state, STOP, and explicit diagnostics without opening a window. Keep file access in the desktop crate. Cover argument parsing, Darwin paths, file boundaries, ARM/Thumb execution, DMA/IRQ budgets, HALT/STOP, and error reports. Document limits and usage. Verified on native Darwin arm64: debug/release workspace tests, core-only tests, Clippy, rustdoc, all ten window smoke tests, and a release raw-ROM run.
57 lines
3 KiB
Markdown
57 lines
3 KiB
Markdown
# 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 bounded terminal sessions. ROM windows, 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:
|
||
|
||
```sh
|
||
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 --steps 100000`.
|
||
See [cartridge loading](docs/hardware/cartridge.md) for limits and report meanings.
|
||
|
||
## Documentation
|
||
|
||
| Document | Contents |
|
||
| --- | --- |
|
||
| [docs/status.md](docs/status.md) | What works today, deliberate limits, and next steps |
|
||
| [docs/demos.md](docs/demos.md) | Every demo, its command, and its controls |
|
||
| [docs/development.md](docs/development.md) | Nix, direnv, and macOS build notes |
|
||
| [docs/testing.md](docs/testing.md) | Validation commands and what the test suites cover |
|
||
| [docs/architecture.md](docs/architecture.md) | Crate boundaries and a file-by-file map |
|
||
| [docs/hardware/cpu.md](docs/hardware/cpu.md) | ARM/Thumb execution rules, modes, exceptions, and timing |
|
||
| [docs/hardware/cartridge.md](docs/hardware/cartridge.md) | Raw ROM loading, bounded terminal execution, and diagnostics |
|
||
| [docs/hardware/bios.md](docs/hardware/bios.md) | The original BIOS replacement and each supported service |
|
||
| [docs/hardware/timers-irq.md](docs/hardware/timers-irq.md) | Timers, interrupt registers, HALT/STOP, and power control |
|
||
| [docs/hardware/dma.md](docs/hardware/dma.md) | DMA channels, triggers, and timing |
|
||
| [docs/hardware/display-timing.md](docs/hardware/display-timing.md) | Display clock, status, IRQs, and scanline capture |
|
||
| [docs/hardware/video.md](docs/hardware/video.md) | Backgrounds, sprites, mosaic, windows, color effects, and input |
|
||
| [docs/references.md](docs/references.md) | External hardware references and emulator sources consulted |
|
||
|
||
Coding agents should start with [AGENTS.md](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.
|