mvdnes / rboy

A Gameboy Emulator in Rust

RBoy

A Gameboy Color Emulator written in Rust

QuickStart

You can clone this repository and build it using either the make command or cargo build --release. Running the emulator can be done either via cargo run --release, or by running the generated binary found in target/release. You can copy the executable named rboy or rboy.exe to some sort of binary directory such as ~/.local/bin/ in linux or something under the PATH in windows.

Then you can explore the ability of the emulator by rboy --help. Which outputs

A Gameboy Colour emulator written in Rust

Usage: rboy [OPTIONS] <filename>

Arguments:
  <filename>  Sets the ROM file to load

Options:
  -s, --serial         Prints the data from the serial port to stdout
  -p, --printer        Emulates a gameboy printer
  -c, --classic        Forces the emulator to run in classic Gameboy mode
  -x, --scale <scale>  Sets the scale of the interface. Default: 2
  -a, --audio          Enables audio
      --skip-checksum  Skips verification of the cartridge checksum
      --test-mode      Starts the emulator in a special test mode
  -h, --help           Print help
  -V, --version        Print version

Now you can look below for the Keybindings section below.

Keybindings

Gameplay Keybindings

Key on Keyboard	Emulator Key
Z	A
X	B
Up/Down/Left/Right	Up/Down/Left/Right
Space	Select
Return/Enter	Start

General Keybindings

Key on Keyboard	Emulator Action
1	Switch to 1:1 scale
R	Restore scale given on command line
Left Shift (Hold)	Unrestricted Speed Mode
T	Change pixel interpolation

Implemented

• CPU
  • All instructions correct
  • All timings correct
  • Double speed mode
• GPU
  • Normal mode
  • Color mode
• Keypad
• Timer
• Audio
• MMU
  • MBC-less
  • MBC1
  • MBC3 (with RTC)
  • MBC5
  • save games
• Printing

Test mode

The test mode, activated with the --test-mode flag, provides some functionality for running GBEmulatorShootout. This is still under development.

Special thanks to

• http://imrannazar.com/GameBoy-Emulation-in-JavaScript:-The-CPU
• http://bgb.bircd.org/pandocs.htm
• https://github.com/alexcrichton/jba (The Rust branch)
• https://gbdev.io/pandocs/

rboy's Issues

Clarify buttons to press

Could you please add some kind of documentation which keyboard keys are responsible for which gameboy keys? Thanks! I love this emulator, but this makes it hard to recommend it to others. :)

Question about renderscan implementation

I've been using your emulator as a reference while learning how to write an emulator. Thanks for sharing it!

I had a question about how you implement the GPU's cycle.

In do_cycle https://github.com/mvdnes/rboy/blob/master/src/gpu.rs#L110 it seems like you're emulating the advancement of the GPU's timing fairly accurately. I was expecting to see a mechanism for incrementally drawing graphics into a buffer (later to be output to the host's screen), pixel by pixel. But instead, it seems like you just draw it all at once at the beginning of switching to mode 1, calling self.renderscan() once.

Could you confirm that is indeed what you're doing, and if you had any feedback on it? Was that for performance reasons? Is it because it doesn't affect some, most, or all games? My sense is that some games might want to do clever things depending on what column you're currently drawing to, but that's not possible if you draw it all in one shot and then emulate no-op cycles past that.

Thank you!

Get an explanation

Hey,

I'm trying learn more about emulators and how the things works on low level... I find this function on your code...

fn alu_add16imm(&mut self, a: u16) -> u16 {
  let b = self.fetchbyte() as i8 as i16 as u16;
  self.reg.flag(N, false);
  self.reg.flag(Z, false);
  self.reg.flag(H, (a & 0x000F) + (b & 0x000F) > 0x000F);
  self.reg.flag(C, (a & 0x00FF) + (b & 0x00FF) > 0x00FF);
  return a.wrapping_add(b)
}

Why this can't add the b directly to a? Without make 3 casts to i8 -> i16 and finally u16?

Thank you in advance 😉

Testing: Pokemon Green

It seems as if the input and sound is not working, any plans to impliment it soon?

Noise length parameter not respected

In sound.rs

 0xFF23 => {
                self.length_enabled = v & 0x40 == 0x40;
                if v & 0x80 == 0x80 {

The self.length_enabled statement is missing. Adding this fixes annoying noise in a number of games including Zelda: Link's Awakening.

Additionally, the enabled flag on the wave channel should be set like this:

   0xFF1A => {
                self.enabled_flag = (v & 0x80) == 0x80;

The Zelda: Oracle games needs this but seem to have other issues too.

Just stuff I noticed when messing around with it :) (I've been using parts of the code to play with upscaling shaders).

Document the build instructions

write a remote gdb server

Hello.

I am looking for an accurate emulator for gameboy color with gdbserver feature. I want to implement it to rboy with gdbstub: https://github.com/daniel5151/gdbstub.

Assign me to this issue please.

Cartridge checksum is invalid

This is what I get after compiling it in release mode.

Allow Device to attach Serial/Link Cable

I'd like to be able to connect Serial/Link Cables.

I'm imagining something like syncing this similarly to how the audio system works (you impl SerialConnection for LinkCable {?)

I can imagine if you don't have both of the Device's do_cycle's in sync this can cause some problems, since there doesn't seem to be a "buffer" system in the system.

At minimum, I'd like to make the printer output data buffers instead of to files. Device->Device connections might be too hard to be worth the time.

Allow Device to load rom data

Allow Device to load by buffer instead of by rom path.

let data = fs::read(rom_name).unwrap(); //this will come from an external source
let a = Device::new_cgb_from_buffer(data,true);

I'd also like to extract the save data via Device.

I'm using rboy as a library and I want to have more control over where files save, etc.