Rust GameBoy emulator aiming for cycle accuracy
Go to file
EliseZeroTwo d60de54d89
fix: OBJ white/transparency confusion, implement interrupt dispatch TOCTTOU found in hardware
2024-01-26 09:10:52 -07:00
.forgejo/workflows fix: PPU timings are more accurate 2024-01-25 10:41:36 -07:00
.github/workflows fix: PPU timings are more accurate 2024-01-25 10:41:36 -07:00
meowgb fix: PPU timings are more accurate 2024-01-25 10:41:36 -07:00
meowgb-core fix: OBJ white/transparency confusion, implement interrupt dispatch TOCTTOU found in hardware 2024-01-26 09:10:52 -07:00
meowgb-opcode feat: timer works much better 2024-01-04 23:23:58 -07:00
meowgb-tests fix: PPU timings are more accurate 2024-01-25 10:41:36 -07:00
test-roms fix: PPU timings are more accurate 2024-01-25 10:41:36 -07:00
.gitignore test: add much more tests, fix up a few broken things 2024-01-04 02:02:23 -07:00
CODEOWNERS chore: add CODEOWNERS 2024-01-02 14:34:38 -07:00
Cargo.lock feat: better DMA, PPU, add more tests 2024-01-19 11:44:51 -07:00
Cargo.toml feat: switch from chrono to time 2024-01-02 14:09:33 -07:00
LICENSE.md docs: add README and LICENSE 2024-01-02 17:47:14 -07:00
README.md feat: visual overlay debugger 2024-01-03 12:13:29 -07:00
config.example.toml feat: visual overlay debugger 2024-01-03 12:13:29 -07:00
generate-action-and-tests.sh feat: better DMA, PPU, add more tests 2024-01-19 11:44:51 -07:00
run-test-roms.sh fix: PPU timings are more accurate 2024-01-25 10:41:36 -07:00
rust-toolchain multi: upgrade dependencies, fix a bug with interrupts, implement some missing opcodes 2023-12-30 09:08:15 -07:00
rustfmt.toml feat: basic ppu 2021-11-24 12:01:25 +01:00
tests.md fix: PPU timings are more accurate 2024-01-25 10:41:36 -07:00

README.md

MeowGB

A Gameboy (DMG) emulator written in Rust, aiming for cycle accuracy and conformance with weird hardware quirks.

To view what test ROMs are currently passed and part of CI, look at tests.md, test ROMs are stored in subfolders inside test-roms/ and each subfolder contains the original license of the test-roms.

Contents

Features

  • Mostly M-cycle accurate instructions (passes tests)
  • Memory bus emulation
  • Pipelined CPU (passes timing tests)
  • Partially working PPU (ticked at the correct speed, drawing pixel by pixel)

Future Features

  • Audio
  • Visual debugger/state inspector
  • T-cycle accurate PPU
  • Networked link-cable

Structure

There are currently 4 crates used in this project:

  • meowgb: A cross-platform frontend for the emulator
  • meowgb-core: The implementation of the emulator
  • meowgb-opcode: Procedural macro used in meowgb-core for defining opcodes
  • meowgb-tests: A frontend-less test-harness for running tests and comparing their output, used in CI for ensuring regressions are minimal and noticed as soon as possible

Usage

You will have to build it yourself as currently there are no premade builds available, once it is in a state I am happy with I will add release builds to CI.

  1. Ensure you have a Rust toolchain installed (docs)
  2. Run cargo install --git https://github.com/EliseZeroTwo/MeowGB.git
  3. To launch the emulator, run meowgb --rom PATH_TO_ROM.GB

Key Bindings

By default the keybindings are:

Gameboy Keyboard
A A
B S
Start W
Select Q
Up Arrow Up
Down Arrow Down
Left Arrow Left
Right Arrow Right

Configuration

Default keybindings are overridable by placing a config.toml either in the directory you are running the emulator from, or at ~/.meowgb/config.toml.

An example configuration file can be found in config.example.toml.

License

This software is currently licensed under the CNPLv7+, a summary of which can be found at here. The contents of the test-roms folder is excluded from this, and the original license of the test ROMs are placed in their respective subdirectory, they are not compiled into any of the software, they are included in the repository purely for intergration testing in CI.

Dependency Version Notice

The frontend uses old versions of winit and egui related libraries, this is due to incompatibility between more modern versions of the underlying crates with egui, pixels, and winit. In order to upgrade them, these compatibility issues need to be fixed by them.