nivent/rgb

RGB (Rust Game Boy) is a simple emulator for the original game boy and the...

RGB (Rust Game Boy) is a simple emulator for the original game boy and the color game boy

RGB

.

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
cd 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.

Special Inputs

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 enable_development_keys and 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 Esc.

Debugging

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 infinite_loop_breakpoint and unimplemented_instruction_breakpoint flags in case the emulator enters a (detectable) infinite loop or encounters a nonexistent instruction.

Known Bugs/Issues

  • 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.

Information - Updated Feb 27, 2022

Stars: 17
Forks: 1
Issues: 0

Repositories & Extras

This is an example of a Rust server that functions as a remote schema for...

Rust + Hasura Rust server that functions as a Hasura

This is an example of a Rust server that functions as a remote schema for...

Newport Engine is a modular 2D and 3D game engine built in Rust for Rust

It is designed to be easily extendable and easy to use

Newport Engine is a modular 2D and 3D game engine built in Rust for Rust

Newport Engine is a modular 2D and 3D game engine built in Rust for Rust

It is designed to be easily extendable and easy to use

Newport Engine is a modular 2D and 3D game engine built in Rust for Rust

liboqs-rust: Rust bindings for liboqs

Qyantum Safe liboqs rust bindings

liboqs-rust: Rust bindings for liboqs

msgflo-rust: Rust participant support for MsgFlo

Flowhub visual programming IDE

msgflo-rust: Rust participant support for MsgFlo
Actix

1.0K

How to be a full stack Rust Developer

Read Rust the Rust blog posts at Steadylearner

How to be a full stack Rust Developer

Rust library translation (rust-src/rust-std/stdlib/rustlib translation)

This is the place to translate Having a documentation in your native language is essential if you don't speak English, and still enjoyable even if...

Rust library translation (rust-src/rust-std/stdlib/rustlib translation)

False Positive for rust-lang/rust#83583

The deprecation lint proc_macro_derive_resolution_fallback is intended to catch proc macro generated code that refers to items from parent modules that should not be in scope:

False Positive for rust-lang/rust#83583

A CHIP-8 & SuperChip interpreter written in Rust using rust-sdl2

If you're getting compile errors it may be because

A CHIP-8 & SuperChip interpreter written in Rust using rust-sdl2

Rust-Svelte-on-Rust

Starter template for Rocket backend server

Rust-Svelte-on-Rust

xbuild is a build tool for rust and rust/flutter projects with support for cross compiling...

xbuild is a build tool for rust and rust/flutter projects with support for cross compiling and

xbuild is a build tool for rust and rust/flutter projects with support for cross compiling...
Facebook Instagram Twitter GitHub Dribbble
Privacy