RGB (Rust Game Boy) is a simple emulator for the original game boy and the color game boy.
Warning: This no longer compiles in the latest versions of rust; use version 1.20.0 instead. At the moment, fixing things for newer versions is not high on my priorites list
How to Build
Install Rust and run the following commands in a terminal
git clone https://github.com/NivenT/RGB
cargo build --release
In order for it to build, you must have SDL2 installed. On Ubuntu, run
sudo apt-get install libsdl2-dev
If that doesn't work, try running
sudo add-apt-repository ppa:zoogie/sdl2-snapshots
sudo apt-get update
sudo apt-get install libsdl2-dev
How to Use
Before running the program, make sure to setup the settings.ini file. This is where you supply a path to the game to be loaded, tell the emulator which keyboard keys map to which gameboy buttons, and specify what hex colors the emulator should use for graphics. You can also supply a path to a binary file containg the gameboy BIOS. Even if you do not have a copy of the gameboy's BIOS (you supply a path to a nonexistent file), the emulator will still run. If you supply a CGB BIOS file, the emulator will run as a gameboy color, but if you supply a monochrome gameboy BIOS file, the emulator will run as a monochrome gameboy. If no BIOS file is supplied, it will decide which to run as depending on if the loaded game was made for monochrome of color gameboys. RGB uses SDL2 for window management and input handling, so check here for the values of each key.
Once settings.ini has been set up, start the program by running the following command from the project's main directory
cargo run --release
Once the program starts, it behaves like a gameboy with the keys you specified as the buttons.
Certain keys are special, and the emulator has built in responses for when they are pressed.
- P - Toggles whether or not emulation is paused
- D - Toggles whether or not the emulator displays debug information
- R - Toggles whether or not register values should be included in the debug information
- Up/Down - When paused, scrolls through the displayed debug information
- F - Emulates a single CPU instruction if paused
- M - Prompts for a starting and ending memory address. Emulator then prints the values stored in memory between those addresses (inclusive on starting and exclusive on ending)
- Esc - Exits program
- 1..0 - Runs the emulator at normal (double, triple, ..., up to 10x) speed
Since this list has been growing, and since I often accidentially press these when testing, you can disable these special keys. In the
settings.ini file, there are two flags named
only_gameboy_buttons. If the first one is false, then the only special inputs will be P, Esc, and the numbers. If the second one is
true, then the only special input will be
For helping with development, I've built some debugging features into the emulator.
- The main one is what happens when you press D. The emulator displays the opcodes it's executing (along with their inputs) in real time, and you can scroll through this output via up/down arrows if emulation is paused.
Another source of debugging information is the
disassembly.txt file. Whenever a game is first loaded, the emulator (attempts to) disassemble its source code and print the results into this file for later viewing.
settings.ini contains a
bios_breakpoint flag. When this is set to
true, the emulator will automaticallyy pause once the BIOS has finished running. This makes it easier to step through a game from the moment it begins. There are also
unimplemented_instruction_breakpoint flags in case the emulator enters a (detectable) infinite loop or encounters a nonexistent instruction.
- Gameboy Color games may have slight graphical bugs
- There is no sound
- The emulator seems to have issues with certain CGB Games
- Originally thought this was related to cartridge type, but that seems to not probably be the issue after all
- When you press
D to enter debug mode, it's common for the gameboy screen to stop being displayed; it usually comes back if you just pause and wait a while though.
If you find any other problems (including any way it fails on specific games), please open an issue.