Skip to content

kaplanz/gameboy

gameboy

A delayed game is eventually good, but a rushed game is forever bad. Shigeru Miyamoto


dependency status

A cycle accurate emulator of the original 1989 Nintendo Game Boy.

Important

Consider this to be pre-alpha software. I make no guarantee of the stability of any documented APIs until the first official release.

Goal

This project aims to provide high-accuracy emulation of all major components in the SM83-based Nintendo Game Boy family of consoles. (Note that at this time, there are no plans to support the later Game Boy Advance, which has an entirely different architecture.) Each component is modular, enabling them to be easily substituted for one another. In turn, this leads to emulator instances supporting multiple implementations of core components with different accuracy/performance margins.

Organization

In accordance with the preference for modularity outlined above, the project is partitioned into the core, and various emulator frontends. Useful supporting crates are independently available as well. Also packaged in this repository are several open-source ROMs. These are used internally for testing and to demo project functionality.

Workspace

Cargo — Rust's package manager — allows for a workspace of several crates to be specified within its manifest. Within this project, workspace crates are used with the structure as follows:

./
├── Cargo.lock       # cargo lockfile
├── Cargo.toml       # cargo manifest
├── Justfile         # useful development commands
├── README.md        # this document
├── ...
├── apps/            # frontend apps
├── core/            # emulation core
├── crates/          # support crates
├── docs/            # documentation
├── roms/            # open-source ROMs
├── src/             # emulation library
└── tests/           # integration tests

Tip

For downstream library users, I recommend using the top-level gameboy crate rather than directly using gameboy-core, as it better structured for end users and includes useful supporting modules.

Progress

Core

  • Implementation
    • Audio (APU)
    • Cartridges
      • Save RAM to disk
      • Support hardware
        • MBC1
        • MBC3
        • MBC5
    • Interrupts (PIC)
    • Graphics (PPU)
      • Functional correctness
        • Background drawing
        • Window overlay
        • Sprite rendering
      • Implementation accuracy
    • Joypad
    • Processor (CPU)
      • Functional correctness
      • Implementation accuracy
        • Multi-cycle instructions
        • Timed memory accesses
        • Timing precision
    • Timer
      • Functional correctness
      • Implementation accuracy
  • Performance enhancements
    • Real-time emulation
    • Benchmark tests
  • Testing
    • Blargg (17/45)
    • Mooneye (23/69)

Library

  • Color palette API
  • Debugger API
    • Breakpoints
      • Instruction address (PC)
      • Instruction opocode
      • I/O operation (read/write)
      • Softbreak (ld b, b)
      • Dynamic condition
    • Memory peek/poke
    • Register manipulation
      • APU
      • CPU
      • Interrupts
      • PPU
      • Serial
      • Timer
    • Peripheral control
      • Serial interface
  • Exposed core API
  • Frontend API

Frontend

  • Command-line
    • Configuration file
      • Re-mappable joypad
    • Debugging support
      • Interactive debugging
      • CPU logging
      • Memory rendering
      • Dynamic speed changing
  • Cross platform (SDL)
  • Native
    • iOS
    • macOS
  • Web (WASM)

References

This project would not have been possible without the countless Game Boy community resources. Of these, I would like to specifically recognize the Game Boy Development community.

See the list of resources (in no particular order) used as research for this project below.

Documentation

Hardware

Software

License

This project is dual-licensed under both MIT License and Apache License 2.0. You have permission to use this code under the conditions of either license pursuant to the rights granted by the chosen license.

About

Cycle-accurate Game Boy emulation

Resources

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published