RealBoy is a Free, Fast and Accurate, Game Boy/Game Boy Color/Super Game Boy Emulator for Linux/Unix. It has both technical as well as educational goals. Technically, it aims for the following: 1) Accuracy. Perhaps the most important technical goal, as seen in the best closed-sourced emulators, such as KiGB and BGB, and some free emulators, such as Gambatte and MESS. 2) Performance. Show that it is possible to implement a very fast emulator without sacrificing accuracy. 3) Feature-rich. Implement advanced features such as a flexible internal debugger. Besides the technical goals, RealBoy pretends to serve as an education tools; it includes a set of documentation files describing the design and implementation issues found while developing the emulator. This can be found on RealBoy's official website (realboyemulator.wordpress.com). We hope the documentation can be useful to individuals that would like to learn about how emulators work in general, and the type of problems you face when implementing a fully-functional emulator project. Features -------- RealBoy is a work in progress; current features include: - Accuracy: Pass various test ROMS designed to evaluate the accuracy of a Game Boy emulator, including: CPU Instructions, Instructions' Timings and Memory Access Timings. - Performance: For 64-bit versions of the x86 architecture (a.k.a x86_64, a.k.a amd64), an Assembly Language version of the emulator's core is provided, significantly faster than the C version. - Experimental Support for the Super Game Boy (disabled by default; see "Super Game Boy Support" below) - Support for MBC1, MBC3 and MBC5. - Support for RTC (Real Time Clock) in MBC3. - Support for executing the original boot ROMS (files not included for legal reasons). - Internal Debugger: Basic functionality such as adding breakpoints, printing registers, etc. - FPS: User control over framerate (default is 60fps). - Sound: Implemented channels 1, 2 and 4. - Video: Scaling to 2x, 3x and 4x, with or without fullscreen. - Video: Antialiasing. - RealBoy Internals: Design and implementation documentation. Compiling the sources --------------------- RealBoy is distributed with Autotools-derived scripts, so compiling is just a matter of the well-known ./configure && make process. There are some RealBoy-specific arguments you can pass to configure: ./configure --disable-asm (Force compiling the C instead of Assembly code for x86_64 architectures. By default, the configure script chooses the Assembly sources automatically on these processors.) System requirements ------------------- - POSIX-compliant Operating System (Linux, *BSD, Mac OS X, Solaris, etc) - SDL library (Generally installed from your packet manager, or download and compile from source from http://www.libsdl.org) Key combinations during emulation --------------------------------- The following is the default, configurable, key bindings (you can change key bindings on-the-fly pressing key '8', or make changes permanently configuring the Configuration File (see below)): - Key 'Enter': Start - Key 'a': Select - Key 'd': A - Key 's': B The following is the default, non-configurable, key bindings: - Key '1': Video scale 1x - Key '2': Video scale 2x - Key '3': Video scale 3x - Key '4': Video scale 4x - Key '5': Enable/disable antialiasing - Key '6': Enable/disable fullscreen - Key '7': Stop execution and launch GDDB debugger - Key '8': Change configurable key bindings (to make changes permanent, change the Configuration File instead (see below)) - Key '.': Speedup emulation - Key 'Esc': Quit RealBoy Configuration Directory ------- When executed for the first time, RealBoy will create the Configuration Directory '.realboy' in the user's home directory. In it, RealBoy creates the Saves Directory 'saves'; RealBoy creates and maintains save files here. Finally, RealBoy creates a default and customizable Configuration File 'RealBoy.conf'. Configuration File and Command-Line Arguments ------- The Command-Line Arguments will override temporarily (for the duration of RealBoy's execution) options set in RealBoy.conf. Permanent changes are possible only through the Configuration File RealBoy.conf. Boot ROMS ------- Both Game Boy and Game Boy Color execute a small program at startup (the moment when you power on the console). RealBoy is able to start emulation from here but, for legal reasons, don't include the boot files and skip their execution by default. If you are feeling nostalgic and want to use the boot ROMS, first you must get them somewhere (they can easily be found by googling). Next you must go to the Configuration Directory created by RealBoy in your home directory ('.realboy'), create a directory named 'boot_roms' and copy the files over there (Game Boy boot ROM must be called 'dmg_boot.bin'; Game Boy Color boot ROM must be called 'gbc_boot.bin'. Finally, when executing RealBoy, the parameter '-b' must be passed in order to tell RealBoy to attempt executing the boot ROM. RealBoy's Operation Modes ------- RealBoy automatically detects the features supported by the executing ROM; it sets its Operation Mode according to these features. Possible Operation Modes are (Original)Game Boy, Color Game Boy and Super Game Boy. The user can force RealBoy to execute in any ot these modes. For example, if a ROM supports both Color Game Boy and Super Game Boy, RealBoy will automatically select the Color Game Boy mode; the user can, therefore, force the execution mode to Super Game Boy mode. If the executing ROM does NOT support the forced mode, RealBoy will just ignore it and fallback to a supported mode. Color Game Boy Support ------- RealBoy fully supports emulating the Color Game Boy console. ROMS that do not explicitly support CGB mode can nontheless execute in this mode; the Color Game Boy is backwards-compatible with Game Boy ROMS. However, if you force CGB mode on a ROM that does not explicitly support it, you must supply the Game Boy Color boot ROM. ROMS supporting the Game Boy Color mode will work normally without the Game Boy Color boot ROM. Super Game Boy Support ------- Experimental support for the most common features of Super Game Boy has been added to version 0.2. It is disabled by default. To enable Super Game Boy mode, either pass the appropriate argument to RealBoy when executing (-S), or set the appropriate variable in RealBoy.conf (gboy_mode). Any ot these will force RealBoy to execute under Super Game Boy mode. If a ROM not supporting Super Game Boy is used, RealBoy will fallback to either Color Game Boy or Game Boy mode, depending on whether the ROM supports Color Game Boy or not. Multiplayer is currently not implemented. Contact ------- Any question, suggestion or bug report can be sent to Sergio.G.DelReal@gmail.com. People are welcome to join the project and help meet the goals established at the beginning of this README. Visit http://realboyemulator.wordpress.com for more information. Special Thanks -------------- Mathieu Peponas from gngb for kindly answering an email. Special thanks goes to the 'gngb' project; great deal of the graphics system and SGB support has been borrowed from it. Also, from 'gngb', 'VisualBoyAdvance' and 'MESS', I learned (and keep learning) a lot to make ReaBoy possible.