Rustual Boy - A Virtual Boy emulator.
Clone or download

README.md

Rustual Boy

Build Status Build status rustualboy.com Compabitility Chat on discord License

Rustual Boy

Description

Rustual Boy is a Virtual Boy emulator. It can be used to play existing Virtual Boy games, as well as be a helpful development/debugging tool for homebrew for this platform.

The name "Rustual Boy" is a portmanteau of the words "Rust" and "Virtual Boy". Ok, the "Virtual Boy" part was obvious, but why "Rust"? In fact, Rustual Boy is written in the Rust programming language - a "systems programming language that runs blazingly fast, prevents segfaults, and guarantees thread safety." Rust is a wonderful language with a thriving community, and as such provides a fantastic platform for an emulation project!

Status

Rustual Boy is currently able to emulate the majority of commercial Virtual Boy titles, as well as many homebrew ones. It supports basic video/audio output and keyboard input, and also a simple CLI debugger. It runs on Windows, MacOS, Linux, and likely some other platforms Rust supports.

While Rustual Boy's core emulation is nearly complete compatibility-wise, and in some respects is already one of the more accurate VB emulators available, the project is still young, and needs some time to mature. Particularly, its user interface is lacking (read: virtually non-existent), and there are some known (and probably unknown) stability/compatibility issues. Also, performance isn't fantastic yet, but the emulator should be playable at least.

That said, these things are bound to improve with time, and everyone is encouraged to grab a build or build the emulator, give it a shot, and report any bugs/feature requests!

Screenshots

screenie screenie screenie screenie

Known game compatibility

Key:

  • πŸ’–: Fully compatible. The game is fully playable with no known bugs (to our knowledge).
  • πŸ’”: Playable. The game can be played, but has some minor known glitches (described in the notes field).
  • 🚫: Incompatible. The reason is described in the notes field.
  • N/A: Game does not exist for this region.

Games marked πŸ’– and πŸ’” are all included in the compatibility metric.

Game USA JP Notes
3-D Tetris πŸ’– N/A
Bound High! πŸ’– N/A ROM is both USA+JP
Galactic Pinball πŸ’” πŸ’” Vocal samples throughout the game play at the wrong rate, likely related to CPU clock cycle inaccuracy
Golf πŸ’” πŸ’” Game transitions to demo mode WAY too fast, sometimes softlocks when transitioning to/from demo mode
Insmouse No Yakata N/A πŸ’–
Jack Bros. πŸ’– πŸ’–
Mario Clash πŸ’– πŸ’–
Mario's Tennis πŸ’– πŸ’–
Nester's Funky Bowling πŸ’– N/A
Panic Bomber πŸ’– πŸ’–
Red Alarm πŸ’– πŸ’–
SD Gundam Dimension War N/A πŸ’–
Space Invaders Virtual Collection N/A 🚫 Lazers aren't visible on most of the screen in "Virtual 3D" mode
Space Squash N/A πŸ’–
Teleroboxer πŸ’” πŸ’” Small audio glitches during screen transitions after demo mode wins games
V-Tetris N/A πŸ’–
Vertical Force πŸ’– πŸ’–
Virtual Bowling N/A πŸ’” Samples play at the wrong rate
Virtual Boy Wario Land πŸ’” πŸ’” Game is fully playable, but some parts of the intro cutscene are too dark, due to inaccurate emulation of the physical LED periods used in the display
Virtual Fishing N/A πŸ’–
Virtual Lab N/A πŸ’–
Virtual League Baseball πŸ’– πŸ’–
Waterworld πŸ’– N/A

Building and running

Currently, the only dependency for building is Rust itself, which can be downloaded here. Once that's installed, you can clone the repo, and simply cargo build/cargo run your way to victory! It's recommended to use the --release flag as well, as emulation can require a lot of CPU power, so we'll want all the compiler help we can get.

Note: If you're new to using Cargo (Rust's build system), it's recommended to give the Cargo Guide a quick skim.

Rustual Boy has a very simple CLI interface:

$ rustual-boy-cli --help
Rustual Boy 0.2.0
ferris <yupferris@gmail.com>, The Rustual Boy contributors
A CLI frontend to the Rustual Boy emulator

USAGE:
    rustual-boy-cli.exe [FLAGS] <ROM>

FLAGS:
    -s, --sram       Path to an SRAM
    -h, --help       Prints help information
    -V, --version    Prints version information

ARGS:
    <ROM>    The name of the ROM to load

The easiest way to run a game is to supply a single file argument:

rustual-boy-cli bound-high.vb

Input keymap

The Virtual Boy game pad consists of two d-pads, 4 buttons, and two shoulder buttons. These are mapped to the following keyboard keys:

Button Key
Left D-Pad Up W
Left D-Pad Down S
Left D-Pad Left A
Left D-Pad Right D
Right D-Pad Up I
Right D-Pad Down K
Right D-Pad Left J
Right D-Pad Right L
Select space
Start enter/return
A F
B H
Left bumper E
Right bumper U

For game pad layout reference, refer to this image. This key map is currently non-configurable.

Contributing

Rustual Boy aims to be an open project where anyone can contribute. If you're interested, check CONTRIBUTING.md!

License

Licensed under either of

at your option.