Skip to content

Latest commit

 

History

History
151 lines (108 loc) · 5.59 KB

README.md

File metadata and controls

151 lines (108 loc) · 5.59 KB
Raw

Rusty Boy

Rusty Boy is an open-source Game Boy emulator written in Rust for Linux, macOS and Playdate. Rusty Boy does not aim to be the most accurate Game Boy emulator, or the most feature complete. Instead, it is a simplistic implementation of the minimum set of features required to play most games. It focuses on performance on Playdate, often at the cost of emulation accuracy.

Motivation

I started this project because, even though several other emulators had been written and ported to the Playdate handheld console, I found they ran staggeringly slow, to the point that they were unplayable on a real device, specially in revision B of the Playdate.

Features

  • Emulates most of the DMG Game Boy features.
  • Achieves 70 % to 100 % of the framerate in the Playdate, depending on the game and the kind of load it requires.
  • Upscales the frame to the size of the Playdate screen, and applies dithering to emulate the gray shades of the original DMG Game Boy.
  • Emulates MBC1, rom-only and MBC3 cartridges. Adding support for other mappers should be easy to do.
  • Backs up cartridge RAM on exit (does not actually implement save states).
  • In order to avoid complexity, it does not support GBC games. And because the Playdate has a monochrome display, it wouldn't be that useful.
  • Does not implement sound emulation. I hope to work on this in the future, but I suspect it will be quite computationally intensive to run.
  • Passes all CPU, time and interrupt blargg tests.
  • Does not emulate the bootrom, goes straight into the game entrypoint.
  • Gives me a warm and fuzzy feeling every time I get nostalgic about Game Boy games! (Ok, this probably does not belong on this list, but it's pretty much why I wrote it in the first place).

How do I get it working?

Easy! You will need to follow a couple of steps, since I have not created any actual releases just yet.

Supported build systems

I have tested these instructions susccessfully in the following machines:

  • Macbook Air with M2 running macOS.
  • PC running Ubuntu 22.04 on an AMD CPU.
  • PC running Arch Linux on an AMD CPU.

Note that running the build on Asahi Linux is not really supported, since the Playdate SDK doesn't have aarch64 linux support.

The build will probably work in other systems, it just hasn't been tested. You're welcome to submit patches for your system if you find a problem.

Dependencies

In summary, we will need:

  • The Playdate SDK.
  • The crank tool to build the Playdate game.
  • A copy of the ARM GNU toolchain that is present in your path.
  • A nightly Rust compiler, which is required by crankstart.
  • The SDL2 libraries, used for the host builds of Rusty Boy.

Let's start by downloading the Playdate SDK and extracting it in a known location.

wget https://download.panic.com/playdate_sdk/Linux/PlaydateSDK-2.4.2.tar.gz
tar -xf PlaydateSDK-2.4.2.tar.gz

The processor in the playdate is an ARM Cortex-M7, so we also need to install a C toolchain for it. On Ubuntu 22.04 this can be done with:

sudo apt-get install gcc-arm-none-eabi

We will need to get a copy of a nightly Rust compiler. I suggest you use rustup.rs if you don't yet have it. We will also need the crank tool, which acts as a replacement for cargo when building for the Playdate.

rustup toolchain install nightly
cargo install --git=https://github.com/pd-rs/crank

Finally install SDL2. On Ubuntu 22.04 you can do this with:

sudo apt-get install libsdl2-dev

Building

Building for the host

Rusty Boy can be built for the host with:

# Run this command on the root directory of this repository
cargo build --release

You will find the executable in:

./target/release/rusty-boy-sdl

Now you can run games with:

./target/release/rusty-boy-sdl <ROM_PATH>

Building for the Playdate

The Playdate emulator is under the rusty-date subdirectory, since it uses its own toolchain that makes it incompatible with the rest of targets. Note that the playdate version of Rusty Boy for Playdate is called Rusty Date.

cd rusty-date
crank build --device --release

This command builds the Rusty Date.pdx game bundle under the target folder.

Running tests

You can run all unit tests by simply executing:

cargo test

Loading Rusty Date to your playdate

Follow the instructions for sideloading the game (Rusty Date.pdx) as described here.

Loading ROMs to the playdate

⚠️ Disclaimer ⚠️

Please, use this emulator responsibly and only use it with legally obtained ROMs. I do not condone the use of this software for piracy purposes. All responsibility for such actions will fall on the user. By using this software you accept these terms and conditions.

Ok, I will assume from this point onwards that you have legally obtained your cartridge dumps. If so, to upload them to the Playdate follow these instructions:

  • Connect your Playdate via USB to your computer. Navigate to Settings -> System -> Reboot to Data Disk on the Playdate and wait for the USB MSD device to show up as a disk on your compuer.
  • Once the disk is mounted, drag and drop the cartrige ROMs you want to play to the Data/Rusty Date directory. All ROMs must end with the .gb extension in order to be detected by Rusty Date.
  • Eject the disk and wait until the Playdate reboots.
  • You can now play your games! They should appear in a list when you first open the Rusty Date game.