drhelius / gearboy

Game Boy / Gameboy Color emulator for macOS, Windows, Linux, BSD and RetroArch.

Gearboy

Gearboy is a cross-platform Game Boy / Game Boy Color emulator written in C++ that runs on Windows, macOS, Linux, BSD and RetroArch.

This is an open source project with its ongoing development made possible thanks to the support by these awesome backers. If you find it useful, please, consider sponsoring.

Don't hesitate to report bugs or ask for new features by openning an issue.

---

Downloads

• Windows:
  • Gearboy-3.5.0-windows.zip
  • NOTE: If you have errors you may need to install:
    • Microsoft Visual C++ Redistributable
    • OpenGL Compatibility Pack
• macOS:
  • Gearboy-3.5.0-macos-arm.zip
  • Gearboy-3.5.0-macos-intel.zip
• Linux:
  • Gearboy-3.5.0-ubuntu-22.04.zip
  • Gearboy-3.5.0-ubuntu-20.04.zip
  • NOTE: You may need to install libsdl2 and libglew
• RetroArch: Libretro core documentation.

Features

• Accurate CPU emulation, passes cpu_instrs.gb from blargg's tests.
• Accurate instruction and memory timing, passes instr_timing.gb and mem_timing.gb from blargg's tests.
• Supported cartridges: ROM, ROM + RAM, MBC1, MBC2, MBC3 + RTC, MBC5, HuC-1 and MBC1M (multicart).
• Accurate LCD controller emulation with correct timings and priorities including mid-scanline effects.
• Game Boy Color support.
• LCD screen ghosting effect as seen in the original Game Boy.
• LCD dot matrix effect.
• Battery powered RAM save support.
• Save states.
• Compressed rom support (ZIP).
• Bootrom (BIOS) support.
• Game Genie and GameShark cheat support.
• Supported platforms (standalone): Windows, Linux, BSD and macOS.
• Supported platforms (libretro): Windows, Linux, macOS, Raspberry Pi, Android, iOS, tvOS, PlayStation Vita, PlayStation 3, Nintendo 3DS, Nintendo GameCube, Nintendo Wii, Nintendo WiiU, Nintendo Switch, Emscripten, Classic Mini systems (NES, SNES, C64, ...), OpenDingux, RetroFW and QNX.
• Full debugger with just-in-time disassembler, cpu breakpoints, memory access breakpoints, code navigation (goto address, JP JR and CALL double clicking), debug symbols, memory editor, IO inspector and VRAM viewer including tiles, sprites, backgrounds and palettes.
• Windows and Linux Portable Mode.
• Rom loading from the command line by adding the rom path as an argument.
• Support for modern game controllers through gamecontrollerdb.txt file located in the same directory as the application binary.

Tips

• Boot ROM: Gearboy can run with or without a Boot ROM. You can optionally load a Boot ROM and enable it.
• Mouse Cursor: Automatically hides when hovering main output window or when Main Menu is disabled.
• Portable Mode: Create an empty file named portable.ini in the same directory as the application binary to enable portable mode.
• Debug Symbols: The emulator always tries to load a symbol file at the same time a rom is being loaded. For example, for path_to_rom_file.gb it tries to load path_to_rom_file.sym. It is also possible to load a symbol file using the GUI or using the CLI.
• Command Line Usage: gearboy [rom_file] [symbol_file]

Build Instructions

Windows

• Install Microsoft Visual Studio Community 2022 or later.
• Open the Gearboy Visual Studio solution platforms/windows/Gearboy.sln and build.
• You may want to use the platforms/windows/Makefile to build the application using MinGW.

macOS

• Install Xcode and run xcode-select --install in the terminal for the compiler to be available on the command line.
• Run these commands to generate a Mac app bundle:

brew install sdl2
cd platforms/macos
make dist

Linux

• Ubuntu / Debian / Raspberry Pi (Raspbian):

sudo apt-get install build-essential libsdl2-dev libglew-dev libgtk-3-dev
cd platforms/linux
make

• Fedora:

sudo dnf install @development-tools gcc-c++ SDL2-devel glew-devel gtk3-devel
cd platforms/linux
make

BSD

• FreeBSD:

su root -c "pkg install -y git gmake pkgconf SDL2 glew lang/gcc gtk3"
cd platforms/bsd
gmake

• NetBSD:

su root -c "pkgin install gmake pkgconf SDL2 glew lang/gcc gtk3"
cd platforms/bsd
gmake

Libretro

• Ubuntu / Debian / Raspberry Pi (Raspbian):

sudo apt-get install build-essential
cd platforms/libretro
make

• Fedora:

sudo dnf install @development-tools gcc-c++
cd platforms/libretro
make

Accuracy Tests

Compared to other emulators: see here.

Tests from blargg's test roms:

Screenshots

Contributors

Thank you to all the people who have already contributed to Gearboy!

License

Gearboy is licensed under the GNU General Public License v3.0 License, see LICENSE for more information.

gearboy's Issues

download

where the download button

Super Gameboy support

Hi there,

Just wondered if you have any plans for super gameboy support? Some older windows GB emulators I used back in day supported this, and games like Donkey Kong, earlier Pokemon etc look much nicer than the dreary monochrome.

Enable Saves to Network folder:

On iOS devices it would be nice to allow save files to go dropbox, googledrive, or other networked folders so that if apple shuts down the app you can quick pickup where your game dropped off.

Windows release missing Qt platform plugin

Libretro port of Gearboy

Gearboy 1.3 install for non-jailbroken iPad

Hi.

When you say: "Use your developer certificate to compile and install it, then use iTunes file sharing to transfer roms." Is there an easy tutorial to install it ?

I dont understand what i have to do. I really want this version to import/export my saves !

Thanks a lot

Pokemon Maize crashing Gameyob

I tried to play this game in SGB mode as the game is programmed to natively, and it crashes on loading to the title screen. The emulator crashes as a result and even disabling the SGB mode still gives an issue after I closed the rom. It has to have something to do with how it's made somehow but the creator of the hack says this isn't the case at all.

A strange big use of CPU when no game is loaded

Hi.

When I launch Gearboy, even when no game were loaded, it uses at least 30% of a CPU!

• OS: Trisquel GNU/Linux 7 (based on Ubuntu 14.04)
• CPU: Intel(R) Core(TM)2 Duo CPU P8600 @ 2.40GHz (cat /proc/cpuinfo | grep 'model name' | uniq)

Regards.

The sav is not loaded

Hi.

I have a game.gb and a game.sav. Emulators usually load the .sav, but Gearboy does not. o_O
I am running on Trisquel GNU/Linux 7.

Regards.

How can I get a save file from another emulator onto gearboy on my iphone?

Do you know if there's some way to do this? Would I have to include it in the assets of the xcode project somehow?

Minor patches aimed at Fedora packaging

Hi,

Thanks for writing Gearboy, it's a great emulator. I'm looking into packaging it for inclusion in Fedora. To package it, I've been applying a number of small patches that I wanted to share with you. Here's a draft of the package, if you're curious: https://copr.fedorainfracloud.org/coprs/dmoerner/Gearboy/

I welcome you to apply these patches if you'd like. All the patches are in the master branch of my forked repo (https://github.com/dmoerner/Gearboy), but I also include here links and extra descriptions.

1. Build against system miniz: Fedora, like most Linux distributions, prefers to build against system copies of libraries. The patch is trivial: dmoerner@c802ea9

2. Man page: I wrote a very simple man page. I included the note about using alsa to fix the sound: dmoerner@7c12d85

3. Fedora requires desktop files for GUI applications and recommends appdata.xml files. I wrote basic versions of each:
   dmoerner@d7b9d2e
   dmoerner@993bb72

4. Fedora includes extra -debuginfo packages. For these to work properly, it is preferred that some minor stylistic considerations be cleared up. I switched to UNIX-style file endings in two files, and removed the executable bit on 8 files: dmoerner@b661a2d

I totally understand that you might not want to include all these patches upstream. But #4 should be pretty trivial, and the man/desktop/appdata files could just be dropped in platforms/linux/Gearboy.

Daniel

PS: I'm not sure if you're aware, but the audio issue on Linux can be fixed by forcing SDL to use alsa: https://wiki.libsdl.org/SDL_AudioInit.

Toolbar all black until clicked and other problems

I built the source on Linux using the same commands listed in the readme
The toolbar appears as a black stripe, however the buttons are still click-able
It's also spamming the terminal with this warning:

It's also using 100% CPU power (even while paused):

(that shows before and after killing Gearboy)

Link cable support

It would be so cool to fight my friends on Pokemon Red/Blue without buying a ton of ancient hardware.

Would it be possible to support this at all? Either between two emulator instances, or a cable to an actual Game Boy. There might be some issues with timing on multitasking OSes.

As I understand it, it's basically an SPI cable where the the master is the first to start clocking. At least on the Raspi, it could maybe actually talk to a Game Boy using SPI over the GPIO pins.

I have no idea how it's done in software on the real Game Boy. I suspect you can write a byte to some register? Or do you manually clock the lines? Does the clock signal have any effect on the internal clock?

If it is at all possible, and given some hand-holding, I would like to look into this.

Add quit option to menu

Would it be possible to add a quit option in the Game Boy menu, perhaps below Load State? My tiling window manager does not offer any window decorations so the only way I have to close Gearboy is the esc keybind and force killing it.

launch issues

same problem applies also to Gearsystem:

I got the builds from Emucr

while the older versions based on Qt4 run fine, the newer version gives me the following error:

"this application failed to start because it could not load or find the Qt platform plugin "windows"

reinstalling the application may fix the problem"

is there any library missing I need to add to the folder or any package I need to install?
Qt5 libraries take up a lot of space when installed.

thanks

Raspberry Pi + PiTFT screen

Hi,
Gearboy run perfectly on my Raspberry pi. But ... I have a PiTFT screen and application start always on HDMI TV :(

Gearboy ROMs not installing

When I install ROMs, it doesn't recognize Gearboy as some thing to install to. It says "safari cannot download this file." Help please?

Funny enough, same bug as the one for Gearsystem: black screen.

Funnily enough, I just reported this same bug for Gearsystem over here.

I built then installed the app and the first thing that happened when I "Opened In..." a game was get a black screen with the audio going. Just like on Gearsystem, closing and opening the app fixed this. Odd how the same thing happened in two different emulators.

Hope you find the issue!

converting .sav file

hi, just recently started playing Pokemon crystal, now i'm using a non jailbroken iphone 4, latest IOS version, and got your gearboy app from emu4ios unsure if thats where you get it officially? but anyways i really wanted to get the .sav file off my device so i could edit it using pikasav, which only supports .sav, anyways i got iExplorer and has a search for the .sav file and all ive found is .gearboy, i figured that must be the one, although thats not supported for pikasav, or any other emulator which is slightly disapointing if i want to play it on the computer, is there any way i could convert it to a .sav file?

Define ROM as argument at startup

I use Gearboy for development and it would be really useful if I could specify the ROM to be loaded upon startup, e.g.:

./Gearboy /PATH_TO_ROM.gb

Where is the certificate to get gearboy on ios 7 non jailbroken phone

The .zip for the windows version contains the readme from the Gearsystem emulator

std::bad_alloc on raspberry pi

Hey,
I installed the SDL libraries and whatnot, and compiled Gearboy. It seemed to go just fine, but whenever I try to start it, the screen flickers and it says:

terminate called after throwing an instance of 'std::bad_alloc'
  what():  std::bad_alloc
Aborted

i'm guessing i did something wrong, but i can't for the life of me figure out what? any help would be greatly appreciated.

Landscape Controls

Add the possibility to use Gearboy in landscape mode.

Clang error when compiling on OS X (Mavericks)

I followed the guide from README.md for installing on Mac OS X. Netbeans, Xcode, Qt 4 and SDL installed correctly and i added qmake to PATH.
But when i try to compile it using:
make -f nbproject/Makefile-Release.mk SUBPROJECTS= .build-conf

I get the following error:
ld: library not found for -lSDLmain
clang: error: linker command failed with exit code 1 (use -v to see invocation)
make[1]: *** [dist/Release/CLang-MacOSX/Gearboy] Error 1
make: *** [.build-conf] Error 2

(Sorry I can't make a code-block, I'm new at GitHub)

Games not appearing in list

Hi,
There appears to be a slight problem with my newly installed Gearboy 1.4 from Cydia; the games are not appearing in the list as they should if I opened a downloaded ROM file with Gearboy on IOS, rendering it impossible to play games on it.

Is there a solution for this?

Gearboy 1.4 save files

I recently jailbroke my ipod to get Gearboy 1.4 but when I try to transfer my old .gearboy pokemon crystal file there is no previous save so the only menu option it gives me is to start a new game.

Using saves from previous devices?

I recently upgraded to an iPhone 4, and was wondering how I would go about transferring my saves.

Non-jailbroken iPhone 4, using iFunBox to transfer files.

Random crashes in Pokemon Silver

Hello, thanks for making this emulator.

I've tried to play Pokemon Silver and it works as it should until it crashes. (It does every 5 minutes or so.) My machine runs Lubuntu 14.04 64-bit. Here's the terminal output:

joel@joel-laptop:~/Desktop/emulation$ Gearboy/platforms/linux/Gearboy/dist/Release/GNU-Linux-x86/Gearboy
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
Gearboy: ../../../src/audio/Gb_Apu.cpp:242: void Gb_Apu::run_until(blip_time_t): Assertion `time >= last_time' failed.
Aborted (core dumped)

I modified the source code slightly to be able to read time=4, last_time=12 when it crashed the third time.

Have you played this game without crashes?

Saves Compatibility Request

This may seem like a pretty lame comment, but I was wondering if there's any way to convert .zip.gearboy saves that are generated by the iOS (Non-Jailbroken) version of this application to the .sav files generated by VisualBoyAdvance, and visa verse.

Thanks for the great application. Works like a charm!

.sav and .gearboy

I want to be able to convert my .gearboy to .sav to play on vba with changeable speed and then convert it back to .gearboy when I am not able to use a computer, but i can't convert .gearboy to .sav.... I haven't tried converting .sav to .gearboy though. Any help?

How do I update Gearboy on ios? (I have an Apple Dev Account)

I don't understand how I put the file onto my ios device. I know you need the Apple Developer Account (which I have) but I'm not sure as to what to do now? Please help me.

Thanks in advance

CPU usage under Windows 10

While playing a game the emulator uses <= 1% of my CPU. When I do other stuff while the emulator is still open the CPU usage goes up to 15%. Probably not a big problem for most of the peope but it seems strange.

Clarify status of src/boot_roms.h

Hi,

src/boot_roms.h has the appropriate GPLv3+ license header. But it mainly contains a series of bytes with the comment "// From GameBoy-Online emulator". But I was wondering if you could follow up with more information about the contents of this file and where it came from.

Thanks

QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined

When opening the qt5 Gearboy frontend this is printed several times. The only possible symptom I see is that Gearboy's window does not scale well in the tiling wm I am using (Spectrwm). I'm not sure the full implications of this, but thought it would be good to point out.

$ Gearboy 
qt5ct: using qt5ct plugin
qt5ct: D-Bus global menu: no
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined
QOpenGLContext::swapBuffers() called with non-exposed window, behavior is undefined

converting .gearboy to .sav

I've been wanting to do this because I have been playing Pokemon Yellow edition on the gearboy, and now that I got the gba4ios app which also works with gbc games and gba games. I want to keep my save on the gearboy app but I want to put my save into the gba4ios app. So what do I do? also my ios device is non jailbroken.

File paths

Hi,

Is it possible that Gearboy could be made to not create gearboy.ini and game.gb.gearboy in the current directory?

With the Qt version on linux it should use a path like ~/.config/gearboy/ or ~/.local/share/gearboy/. I am not sure which is preferable?

For the libetro core it should respect the System/Bios directory for gearboy.ini and the Save directory for game.gb.gearboy. In RetroArch these directories default to the content directory but the use can change them to whatever they want.

Save file corrupted after swiping right

I was using the ios version and, in the middle of a game, swiped right to get to the tableview of games. Now the save file is corrupted. The game doesn't have the "Continue" option, only "New game". I know it's the save file because it doesn't work in other emulators either. Have you seen this behavior before? Any idea what's causing it? A quick fix may be to just make it so that you cant swipe right to get to the tableview controller, but I can't figure out how to do that.

Arrow key problem

When I hold down an arrow key to walk (in Pokemon Silver) there seems to be a bug caused by automatic key repetition made by the operating system: I don't walk continuously but stop every step or the other.

This can be worked around by using letter keys like ijkl instead.

Gearboy Roms

How can you download roms to play this with an iPhone 5?

Where does Gearboy (newest version from Cydia) keep its save files?

First of all, I want to say I love Gearboy. You did a great job making it.

Anyways, as for the save files, it's definitely not in ROMs/GAMEBOY, I figured out. I want to take a save file from my computer and put it on my phone, but I don't know where Gearboy keeps its save files. Could you please tell me?

Thanks.

sound problem?

The music is really bad, I'm playing pokemon silver and that was ok, after I actualized my Iphone 4S for ios 7... any tips?

Problem with converting save files

This is driving me absolutely insane. I downloaded Gearboy 1.4 off of Cydia and I've been playing pokemon crystal. I wanted to trade pokemon, so I downloaded VBALink. After converting the save file from .gbc.gearboy to .SAV, I was able to load my saved game on VBALink fine. However after saving on VBALink, the file becomes corrupt and when I place it back in the Gearboy files and change the name back to .gbc.gearboy, the in-game saving no longer works. Any idea what I'm doing wrong?

Rom emulation bugs

Action Man - Search for Base X
game over screen graphics are a bit messed up

4x4 World Trophy (Europe)
Runs really slow

Warriors of Might and Magic (USA)
No input.

Defender Joust
Hangs when starting a Joust game.

Foreman for Real
Music is messed up, input not working in game.

Zerd no Densetsu
Crash.

Ken Griffey Jr.'s Slugfest (USA)
graphics are messed up during the game and there is a glitch near the ball on the menu screen

Feel free to add any game not working properly.

How do I download latest Gearboy version form this Github onto the iphone 5 ios7?

I downloaded my version of Gearboy from emu4ios. How do I get the lastest version from here on my iphone?

Enable 32 and 64-bit builds for Raspbery Pi 3

As far as I can see, the current Makefile only builds the RPi3 binary for 64-bit OSes. This wouldn't work in a 32-bit OS.

In my RPi3, the target architecture for 32 bit is called armv7l. It should be possible to compile this emulator for both architectures. It could be a build option that defaults to 64 bit so that the code keeps working the same way it is working right now. Another option would be to detect it with a command.

How to?

Ok ive searched my issue and came to this sight, read a thread, but im not sure its entirely the same issue, I have the weebie download of the gearboy... My idea was to change my pokemon gold save file to a .sav file. Use virtual boy to cheat and get pokemon from the first gen. then change it back. now on the gearboy for windows... the transfer works fine, and i can play my saved file on gear boy... but when i try to put it on my iphone4... It wont let me continue... ive tried changing the sav file to .gearboy, .gbc.gearboy, ive opened it up on gearboy for windows, saved it, then tried to transfer it... what im trying to find out is... am i doing something wrong? Do I HAVE to have the cydia jailbroken version of gearboy to do what im trying to do? or is there a way to cheat on gearboy emulator? either or... I just want charmander and mewtwo on my game on my iphone :( and ive spent 3-4 hours trying to do so... lol

Debug menus?

What are they supposed to do? When I press them (for example Disassembler...) nothing happens.

Black Screen

Hi.
I am used to using bgb on Windows for its powerful debugger, and I was looking for a good Mac alternative so I was excited when I came across this.

I cloned the repo and used brew install homebrew/games/gearboy and then brew linkapps gearboy

Here is the output:
http://pastebin.com/59wLSBry

When I launch Gearboy.app it seems to open fine, but when I Game Boy->Load ROM... the game window remains black.

And when I click the red circle to close the window, the app seems to freeze.

Any suggestions as to what might be the problem?

I am on Mac OS X 10.11.1

Won't compile on newest rapberry pi firmware due to missing include.

Hello,
Due to some changes on the raspberry pi firmware compilation on raspberry pi fails with the following message:

In file included from /opt/vc/include/bcm_host.h:50:0,
                 from main.cpp:27:
/opt/vc/include/interface/vmcs_host/vcgencmd.h:33:27: fatal error: vchost_config.h: No such file or directory
compilation terminated.

This can be fixed by changing INCLUDES at the file "Makefile.include", to the following:

INCLUDES+=-I$(SDKSTAGE)/opt/vc/include/ -I$(SDKSTAGE)/opt/vc/include/interface/vcos/pthreads -I/opt/vc/include/interface/vmcs_host/linux  -I../../../src/ -I./