This is my attempt to write a GameBoy emulator in Rust, to add to the pile of existing ones.
Simply run cargo run --release -- path/to/rom.gb.
By default, the game starts straight away, as if the boot ROM had just run. To run an actual boot ROM first, pass it with --boot-rom path/to/dmg_boot.bin. The libretro core looks for dmg_boot.bin in the frontend's system directory.
Current keybindings:
- ↑, ↓, ←, →: Joypad
- A, B: A/B
- Enter: Start
- Space: Select
- ESC: Exit
- D: interrupt the program and start the command-line debugger
- S: Take a screenshot
- F5: Save the state of the game (to a
.statefile, see below) - F7: Load the saved state
- F: Toggle fullscreen
- P: Switch to the next palette (remembered for next time)
- L: Switch between plain pixels and the LCD shader (remembered for next time)
The palette or shader switched to, and whether a screenshot or save state worked, are shown in the bottom-left corner of the screen for a couple of seconds.
Gamepads work too, and can be plugged in while the emulator runs (you can also use the keyboard at the same time):
- D-pad or left stick: Joypad
- Right face button (B on Xbox pads, A on Nintendo ones): A
- Bottom face button (A on Xbox pads, B on Nintendo ones): B
- Start / Select (or Menu / View): Start / Select
Battery-backed cartridge RAM is saved to a .sav file named after the ROM in $XDG_DATA_HOME/gbrs/saves (~/.local/share/gbrs/saves by default), and quick save states to $XDG_STATE_HOME/gbrs/states (~/.local/state/gbrs/states). These are the XDG locations on macOS too. Saves used to be kept next to the ROM, and are still loaded from there if there isn't one in the saves directory yet.
The screen colours come from a palette: there are a few built-in ones (green, the default, dmg, pocket and grey), and you can add your own in the config file. Switching palettes with P saves your choice as palette in the config file (creating it if needed), leaving the rest of the file as it is.
In RetroArch, the libretro core has a "Palette" core option instead.
The libretro core also supports RetroAchievements: log in under Settings > Achievements in RetroArch, and they work as with other Game Boy cores.
The screen can also be drawn like the Game Boy's LCD, with a thin gap around each pixel and the shadows the pixels cast on the screen behind them. Switch to it with L, which saves your choice as shader in the config file. It shows best in a large window (or fullscreen), as the gaps fade out when each Game Boy pixel is only a few screen pixels wide.
These locations, the palette and the shader can be changed in $XDG_CONFIG_HOME/gbrs/config.toml (~/.config/gbrs/config.toml), or another file given with --config. Every setting is optional:
save-dir = "~/Games/gb/saves"
state-dir = "~/Games/gb/states"
# Defaults to the current directory
screenshot-dir = "~/Pictures"
# The palette to start with, updated when switching palettes with P
palette = "blue"
# How to draw the screen: "none" (plain pixels, the default) or "lcd", updated when switching with L
shader = "lcd"
# Extra palettes, from lightest to darkest shade. They come after the built-in ones when switching
# palettes with P, and one named like a built-in palette replaces it.
[palettes]
blue = ["#e0f0ff", "#80a8d0", "#305078", "#081828"]Seems to work fine with most MBC1+RAM games that I've tried. MBC1 multicarts, MBC2, MBC3 (including its real-time clock) and MBC5 are supported too.
- Allow building/running without the boot rom
- Support other MBCs (MBC1, MBC2, MBC3 and MBC5 are done)
- Sound
- Maybe compile to WASM?
