BGB version 1.5.9

homepage: https://bgb.bircd.org/
email: bgb at bircd dot org

this is a gameboy/color emulator/debugger for win32 which will probably never be finished

disclaimer:

no warranty of any kind, use at your own risk. This program is guaranteed to do nothing but taking disk space. Don't blame me if it damages your computer, or erases your hard drive, etc. Using copyrighted roms with an emulator is illegal if you don't own the real cartridge or have explicit permission from the copyright holder. If you choose to do so, that is your responsibility.

table of contents

right click menu
default keys
features in this version
supported platforms/system requirements
accurate emulation and broken PD roms
known problems
SAV (battery) file format
options window
GameGenie/GameShark cheat
cheat searcher
debugger hotkeys
expressions, breakpoint conditions, and debug messages
Commandline parameters
Demo recording/playback
How to make bgb run faster if you have a slow computer
full screen mode
game link
AVI recorder
Note for speedrun or "race" use
version history

right click menu:

Click the right mouse button in the emulator window to get the popup menu, from which you can access the options and functions.

default keys:

numpad +fast forward
numpad *reset gameboy
numpad -cheat codes on/off
AB button
SA button
ShiftSelect button
EnterStart button
F2save state
F3select state
F4load state
Escdebugger
Alt+F4exit

features in this version:

supported platforms/system requirements

OS: supported/known to work on windows 98 up to windows 10, DirextX 7 or later. Wine on Linux and OS X.

soundcard and joystick/gamepad are optional. A videocard with 3D hardware acceleration is recommended. 200 MHz pentium or faster CPU. BGB runs perfectly on an atom netbook.

accurate emulation and broken PD roms:

by default, BGB emulates the real hardware very accurately, including behavior that some broken PD/unofficial roms may have problems with. These roms would also fail on real hardware, or on a real cartridge: they rely on an inaccurate emulator, or a flashcart. in the "except" tab, one can choose "Troubleshoot broken PD roms", and then set aspects of deliberately inaccurate emulation, to see which one a broken PD rom depends on. Choosing "Emulate as in reality" disables and locks out all inaccuracies and should be done if not trying to fix a problem with a bad rom.
one can also set "break on ..." settings to break (go to the debugger) if a rom misbehaves.
note that if you enable any "break on" settings, or set breakpoints of any kind, bgb will run in "debug mode", and will be about twice as slow because of extra checks. this is done to allow bgb to run as fast as possible if debug features are disabled.

known problems:

SAV (battery) file format

SAV files are raw battery ram images, except for MBC3 RTC games, where 48 bytes of RTC data is appended, in a way that is compatible with Visualboy Advance. Some emulators are unable to load such SAV files, for example 3ds VC. If you encounter this problem, you can disable "Save RTC in SAV file (VBA compatible)" in the settings, "misc" tab. To "fix" an existing SAV file, load the game and close it again.

options window:

Popup menu --> Options.
here you can change a lot of settings such as the joypad keys, configure a gamepad/jostick, change the colors of the gameboy screen, and graphics and sound options. Besides obvious "preference" settings, most settings are optimal as default and should not be changed unless trying to fix a problem.

GameGenie/GameShark cheat:

how to use a gamegenie/shark code: press F10, or use the rightclick menu and choose "cheat", to show the cheat window. click "Add". click in the "Code" field, and paste or type the code. optionally, click in the "Comment" field, and enter a description. click "OK". click on the newly added code in the list, and click "Enable".

the cheat window shows a list. you can add/edit/delete cheat entries, with a code and a description. you can load/save the cheats to a file.
meaning of the letters:

in the cheat edit window, you can either enter a code, and internal values will be displayed, or you can enter internal values, and the corresponding code will be displayed.

for a gameshark cheat, you can either use "enable" to make it work constantly, or "poke" to make it change the ram value once.

rightclick on a cheat to set an "access breakpoint" (for gameshark codes only), or go to this cheat's rom or ram address in the debugger.

cheat searcher:

with the cheat searcher and the debugger, you can make new gameshark and gamegenie cheats

Play the game to the point where you want to influence behavior (for example, the game action itself) press esc to enter debugger. menu: Window -> cheat searcher. select value type (normally 8 bits) and press start.

you may be looking for a value such as "3 lives", in that case, the value in RAM may be 3 as well, but it's not guaranteed.

continue the game, walking around, killing enemies, etc, but making the value you're looking for *not* change (not dying, not getting hurt, etc), use the criteria "equal to the previous value" and search. the number of addresses displayed goes down. you can repeat this a few times. now run the game, but make the value you are looking for change, for example by dying or getting hurt in the game. now search for values which are, for example, "lower than the previous value". the number of matching addresses in the list become smaller each time you run the game and do a search, and you should end up with only one address.

Now, rightclick on the address, and choose "go here in debugger". this will select the address in the ram viewer (on the bottom of the window). then rightclick on that address, and choose "freeze ram value", and enter the desired value. This will create a gameshark code. You can open the cheat window to see the code listed.

if you want to create a gamegenie code, rightclick on the gameshark code, and choose "set access breakpoint". Run the game until the value is changed (for example, die in the game), and it should stop and show the code line on which the value is changed. interpret how the code changes the value, and use game genie codes to change bytes in the code - such as changing an instruction to a nop, or change a "number to decrease" (value 01 to 00), in the cheat window, add new code, enter the address, existing and desired values, and a gamegenie code is produced automatically.

debugger hotkeys

A list of shortcut keys that work in the debugger:

F2Toggle breakpoint
F3Step Over
F4Run to cursor
F5VRAM viewer
F6Jump to cursor
F7Trace (step into)
F8Step out
F9Run
Shift+F9Run and ignore all breakpoint types
Ctrl+F9Run and ignore the last tripped breakpoint type
F10IO Map
F11Options
F12Load Rom
Ctrl+SSave ROM as
Alt+AAnimate
Ctrl+GGo to address
Ctrl+AGo to PC
Ctrl+Shift+numbercreate bookmark
Ctrl+numbergo to bookmark
Ctrl+Bgo to previous bookmark or breakpoint
Ctrl+Ngo to next bookmark or breakpoint
Ctrl+Hbreakpoints
Ctrl+Jaccess breakpoints
Right arrowfollow jump or address dereference
Left arrowundo follow or go to address
Tabtoggle symbols view
Ctrl+Tabgo to next viewer area
Ctrl+Shift+Tabgo to previous viewer area
letter or numberModify code/data
Ctrl+ZUndo modify code/data
Ctrl+Alt+ZRedo

expressions, breakpoint conditions, and debug messages

In the "condition" field of a breakpoint, one can enter an expression. for example ($ff44)=$90, to trip on the start of each vblank. the condition will only trip once every time when it becomes true. besides constant values and addresses, one can use the following:

CPU registers: AF, BC, DE, HL, SP, PC, B, C, D, E, H, L, A, ZERO, ZF, Z, CARRY, CY, IME, ALLREGS
other state values: ROMBANK, XRAMBANK, SRAMBANK, WRAMBANK, VRAMBANK, TOTALCLKS, LASTCLKS, CLKS2VBLANK

These values can also be evaluated by using the menu, "Debug", "Evaluate expression".

The unit of all "clocks" values is 1 nop in doublespeed mode, or about 0.5 microseconds. Clocks values are, like all other numerical values, in hexadecimal. The expression "ZEROCLKS" will reset the counter for LASTCLKS. TOTALCLKS is the same value as the clocks counter ("internal divider") in the IO map.

To add "ld d,d" debug messages into the code, assemble an opcode in the form: .msg 'message' where message is the message content. debug messages can contain expressions between %%. When enabled in the settings, whenever a debug message is encountered in the code, it will be logged to the debug messages window or log file.

Debug messages also support ternary operators in the form: "%boolean expression%text if true;text if false;".

The internal code that makes up a debug message is as follows: ld d,d; jr @end; dw $6464; dw $0000; db "message"; @end

One can also create debug messages that point to a null terminated text string elsewhere: ld d,d; jr @end; dw $6464; dw $0001; dw address; dw bank; @end

Commandline parameters

All -params also work as --param. BGB will exit with an exit code of 1 in case of an error, and 0 for normal termination. Sadly, console output is not currently possible (console can't be programmatically enabled or disabled).

Demo recording/playback

There is minimal support for recording and playing back a demo. The support must be considered "experimental", and it may change in the future. It is only intended to be used from the commandline, where the rom to run is also given on the commandline (and not through the menus). One should start from a save state to ensure an exact identical starting state for recording and playback.

The following commandline loads a rom, saves a state, and exits:

bgb -hf -br any -rom game.gb -stateonexit game.sna
To record a demo:
bgb -rom game.sna -demorec game.dem
To play back a demo:
bgb -rom game.sna -demoplay game.dem
One can still load a rom directly (without using a save state) but with a risk that the playback differs from the recording.

Demo recording of linked bgb's works, but only on the same machine, not over lan. This is done because it's the only way that both instances will run at the exact same timing, to allow the demo to be played back. To do this, also link listen or connect using commandline parameters (not the menu). Use commandlines such as the following to start the two instances:

bgb -rom red.sna -demorec red.dem -setting winx=300 -listen 127.0.0.1:8765
bgb -rom blue.sna -demorec blue.dem -setting winx=800 -connect 127.0.0.1:8765
The demo file format is very simple, with 1 byte per frame for joypad buttons pressed, at the start of each vblank, and before emulation, so it could be handled easily with external tools. If LCD is disabled, no bytes are added to the demo, this was done to keep the demo format deterministic (consistent).

Note: i changed the nibble order around from what it was in 1.5.2, to make it conform to the standard used everywhere: the d-pad should be in the high bits, the other buttons in the low bits. To change existing demo files between the new and old format, use the following command:

bgb -demo152conv filename.dem
If you need it, there is support for the old format. use the parameter -demo152format (in addition to -demoplay or -demorec), but the old format must be considered deprecated.

How to make bgb run faster if you have a slow computer

This should not be necessary on any PC later than ~1998. if you have choppy graphics on a modern PC, the problem is something else.

full screen mode:

select window size -> full screen, to go to a "pseudo full screen" mode (borderless). the GB screen will be at the center of the screen and has the same size which the window had before going to fullscreen mode. "full screen stretched" is a pseudo fullscreen mode where the GB screen covers the whole screen.

real (pageflipped) fullscreen modes are also available in the graphics tab of the settings.

for bgb game link to work at all, you need a modern PC (around 1-2 GHz) and <1ms lag (fast LAN, or localhost). it does not work with all games. on one bgb, you select "listen", on the other you select "connect". it should then show "linked" in the titlebar. there is also an option "remotejoy" so joypad 2 of one bgb controls the other bgb (which does not have keyboard focus, for example).

As of 1.5.2, link in most games should work, and pokemon should work without any glitches (before, pokemon had occasional glitches). one can link between different games, for example pokemon red and blue. Also, a new feature was added: automatic connecting/reconnecting and re-listening: if the link is broken, it will connect or listen again. Also, it will keep trying to connect until it succeeded. This makes the link feature easier to use, and potentially enables unattended use. If the behavior causes problems, it can be disabled in the ini with "LinkAutoListen" and "LinkAutoConnect".

AVI recorder

As of 1.5, one can record to AVI, in addition to recording to BMP screenshots. this allows for greatly improved efficiency while recording, and allow for longer recordings. Sound is still not included in the AVI; enable WAV file writing too, to record sound. The AVI and WAV will have the same filename (and then .avi and .wav), will be perfectly in sync, and can easily be combined in video editing/transcoding software. "media player classic" will automatically use the WAV accompanying the AVI file, allowing for quick preview.

I recommend getting and installing the "camstudio lossless codec". I tested version 1.5. then in bgb, set the codec field to "cscd" to choose the codec. click "Config" to open the configure dialog, and choose "gzip compression" (this will produce smaller AVI files still). Turn off "record half framerate" to record full ~60 fps, which will still not produce too big AVI files, if desired.

The codec can be uploaded as is to youtube, which supports it, or be edited and transcoded to another codec afterwards.

To stitch together multiple recordings (for example if interrupted by the debugger), it is recommended to first combine the video pieces, and the audio pieces, and then mux the audio and video together.

Note for speedrun or "race" use

Speedruns, also known as "races", refer to playing games fast, competitively. Speedrun communities may or may not allow the use of emulators, but if they allow them, requirements may be imposed on them, only some emulators may be allowed, etc.

bgb will, by default, run at the real speed (~59.727 fps). When using bgb for speedruns, and one is not sure whether the settings are default, make sure of the following settings, to ensure running at the real speed:

BGB has a "speedrun mode" which changes a lot of behavior. Restart bgb after changing the speedrun mode setting:
BGB as of 1.5.7 has correct TID (trainer ID) in pokemon games, on GBC and GBA, with and without bootroms.

As of 1.5.8, hard resets (pressing the reset key, * by default), will be recorded and played back in demos. A demo can be recorded during a speedrun, and played back later in non-speedrun mode, as long as all platform settings are the same (choice of platform, GBA, GB player, bootroms), and the BGB version is the same.

version history:

1.5.9 (2021-04-23) 1.5.8 (2020-03-17) - Added mode where RTC stays at real time. Accuracy improvements. improved speedrun mode. Fixed graphics not showing on some wine setups. Improved fullscreen pageflipped mode. Improvements to debugger. Fixed many bugs.

1.5.7 (2018-09-14)

1.5.6 (2017-12-06) - Fixed regression: choppy framerate and sound glitches after pause.

1.5.5 (2017-11-27) - Added support for GUI display scaling. Improved input lag on 120 Hz display mode. Improvements to debug messages. A number of bug fixes and small improvements.

1.5.4 (2017-07-17) - Fixed regression: pokemon yellow broken in SGB mode. Fixed a number of bugs.

1.5.3 (2017-03-04) - Accuracy improvements, including: pokemon (all versions) now has correct TID for speedruns. Fixed a large number of bugs and problems, including: "uncoverable direct3d error" on some Optimus laptops. Added improved support for automation/commandline use. Significant performance/efficiency improvement with most roms. Added support for loading RTC .sav files where a timestamp in the future does not (incorrectly) advance time.

1.5.2 (2015-08-17) - Fixed a large number of bugs and problems, including: glitches in pokemon linking. Screensaver now doesn't start if you play with gamepad. Crash/stability fixes. Many small improvements, including efficiency improvements. Added support for more joypad axes (xbox 360 controller). Various debugger GUI improvements including local symbols.

1.5.1 (2014-11-14) - Fixed a number of bugs, including Donkey Kong Land and possibly other roms being broken, and a bug that caused it to sometimes not work on a secondary monitor.

1.5 (2014-10-18)

1.4.3 (2013-07-01) - fixed: loading/saving save files for roms with unicode filenames was broken if a save dir is not set. this was broken in 1.4.2.

1.4.2 (2013-06-30) - fixed a large number of small problems and bugs including: direct3d now works on secondary monitors, some accuracy fixes (including sagaia problem), added some features including: mono sound output and an exception break if making bad accesses during an OAM DMA transfer. tested to work on windows 8.

1.4.1 (2012-08-27) - fixed time keeping problems (hiccups) on windows 7. fixed inaccuracy in mid-scanline change of LCDC bits (gejmboj). fixed a condition that would cause inaccurate timing of interrupt (final fantasy adventure). added "gameboy or GBC" system mode setting. fixed searching any opcode with a space giving "IO error 105". added field in IO map to view/edit the "low" bank of multicart emulation. fixed "remotejoy" being broken. screen window can now init on secondary monitor. fixed failure of GUI elements initing on secondary monitor. fixed wrong field in wav file written.

1.4 (2012-05-25)

1.3.2 (2011-04-10) - more accurate SGB color scheme. improved detection of non-working vsync. fixed: bootroms don't load if read only. fixed: "load rom dialog on startup" not working. fixed: "game controller works only if focus" not working. fixed: setting borderless window, and switching to fullscreen, if using directdraw, the "window" can still move, and cause graphical glitches and crash. fixed: GBC accurate initial WRAM values as left by bootrom (fixes the menu in baby felix - halloween). fixed: a sprite on X = 0 uses more time in mode 3, too. fixed: inconsistent timing if resetting in the debugger.

1.3.1 (2011-02-09) - fixed: a DMG rom with GBC bootrom would show a white background instead of colorized palette. fixed: header checksum suggestion showed only one hex digit. fixed: menu->reset did not correctly reset emulation.

1.3 (2011-02-07)

1.12 (2006-01-05) - Fixed bug in graphics introduced in 1.1, affecting legend of zelda oracle of ages/seasons, and alfred chicken. Added separate settings for DMG and GBC border bitmaps. various fixes.

1.11 (2005-11-08) - fixed problem with saving color schemes. show ram values in cheat searcher. analog joystick can be used with mbc7. cpu registers can be changed in debugger. various fixes.

1.1 (2005-06-27) - rewritten graphics output to allow 24 bits accurate color reproduction. added support for directdraw pageflipped fullscreen mode (can be faster on old pc's). added support for loading the DMG bootrom (available elsewhere). some emulation accuracy fixes. pop 'n music GB (all versions) now work. added support for "POV hat" (fixed a possible cause for gamepads/joysticks d-pad to not work properly with BGB).

1.03 (2005-04-01) - Emulating hardware behavior for "gin & tonic trick" in the "mental respirator" demo by Phantasy. Fixed the "on blt2: action not supported" problem which happens on some videocards - if it still happens for you, please contact me. Added 24 bpp directdraw support. Made joypad wizard better support "broken" controllers with things like flickering buttons (must press button for 0.5 secs). Added optional screen on startup to tell the user what to do. Added "cpu idle" wait for vblank routine - if it's not smooth on your pc, disable "reduce cpu usage". Added support for up to 32 joypad buttons.

1.02 (2004-10-29) - fixed a bug in the emulation core which may have broken roms. added japanese documentation (thanks, translator). show error if trying to add duplicate cheat code. allow saving disassembler output to text file.

1.01 (2004-10-18) - fixed "Cannot change Visible in OnShow or OnHide" bug. fixed bugs related to gamegenie cheats and cheats GUI. fixed problems/bug with window/fullscreen behavior.

1.0 (2004-10-11)

0.9 (2003-08-10) - Color schemes can be edited. Increased precision of frequencies in sound code (alone in the dark intro interference effect). Centralized/wrapped sound output (waveout, disk writer) code. Fixed AV if showing registers w/o rom loaded.

0.88 (2003-05-08) - fixed: save file name gets corrupted if loading a rom causes a warning, making load/save impossible. added: you can now change the current save name, by changing the save dir in the options, without reloading the rom.

0.87c (2003-04-24) - fixed: the info screen still showed my old email adres...

0.87b (2003-03-15) - fixed: linkspeed was not initialized, causing problems when not linked, such as breaking alleyway

0.87 (2002-12-19) - added experimental TCP game link support.

0.86 (2002-11-27) - added support for japanese pokemon crystal. fixed: accessing a word on address $ffff caused AccessViolation. fixed saving of joystick buttons config. Redone code which searches GB screen rectangle in border bitmap.

0.85 (2002-10-30) - emulation of 2 joypads for SGB multiplayer. fixed memory leak when loading a rom fails. added support for gzipped roms. fixed some bugs in zip header code, bgb is less likely to hang on corrupt zips. new time synchronization code. sound bugfixes and accuracy improvements. Added option to use GB colors in SGB mode.

0.84 (2002-09-29) - Fixed pokemon crystal (HDMA behavior guesswork). Option for generating high quality anti aliased rectangular waves (CH1 and CH2).

0.83 (2002-09-09) - fixed some sound bugs introduced in 0.82. CH4 anti aliasing, especially CH4 high pitch tones sound better. Fixed a resize problem in wine.

0.82 (2002-08-28) - fixed "magical drop" and "miahamm soccer shootout". fixed "little mermaid ii pinball frenzy", speculation about HDMA behavior. rewritten sound code, improved sound. CH4 (noise) is more like real gb now. implemented anti emulator detection.

0.81 (2002-08-11) - redone STAT/timing/interrupts core, more accurate now (?), fixed *many* known problem roms. implemented DI+HALT hardware bug now, needed to fix smurfs/thunderbirds again (thanks no$gmb history text). "little mermaid ii pinball frenzy" graphics will be broken until i have exact HDMA timing. added "no visible window" mode (doubleclick in bgb window to toggle). GB screen can now be off-center in the border bitmap. SGB border can now overlap main screen in 16 bits gfx mode (alfred chicken). minor fixes/changes.

0.8 (2002-08-03) - Added SGB support. renamed "snapshot" to "state" to prevent confusion with "screenshot". changed I/O register behavior, it should be more like the real hardware, i might break something. fixed bugs. added options.

0.71b (2002-07-21) - i removed the hide taskbar code for fullscreen, i think its not needed. added support for "the smurfs" and "pocket puyo sun" (i didn't HALT if ints disabled)

0.71 (2007-07-21) - Added support for HuC1 and HuC3. Improved control panel GUI. The 4 sound channels can be enabled/disabled independently. Colors of background, window and sprites can be set. Improved full screen support. Bugfixes. Changed DMA behavior, "little mermaid II pinball frenzy" and "le mans 24h" both have correct GFX. fixed nintendo logo screen (ishido)

0.7 (2002-06-22) - improved compatibility, a number of problems fixed; tested: "legend of zerd", "magical chase", "elmo in grouchland", "faceball 2000" (framerate), "dragon slayer" (music). Emulation speed can be adjusted. added "delay" option so bgb doesnt have to use 100% cpu. emulation of absence of external ram (reads $ff). more cleanup.

0.66b (2002-01-27) - Saving zero length .sav files problem is fixed. save-filenames were truncated at first dot, fixed. problem with pressing U+D or L+R key simultaneously is fixed. Fixed problem of "Mr. do!" hanging at hi-scores screen.

0.66 (2001-11-25) - You can drag and drop files to the BGB window. BGB can start with no rom loaded - you don't get the load rom dialog.

0.65b (2001-11-04) - i did the changes from 0.64 to 0.65 again... this time i did yet another gfx engine, i didnt like 0.65 being 5 fps slower on my pc.

0.65 (2001-10-30) - Support for bilinear filter. removed the vram viewer; i didn't use it, and it was not stable. Fixed problems with "Mr. Do!". fix in gfx engine: dirty statusbar-split in "fortress of fear". small sound fix (broken in 0.64)

0.64 (2001-09-15) - minor update+bugfix. based on diagnose roms. Fixed speed of envelope sweep, it is now 1/64 sec per unit as in reality. sound registers now behave more like on real gb. OAM is now zero filled on reset, sprites were flipped incorrectly.

0.63 (2001-09-09) - minor update. Fixed (reversed) sound stereo. Added option for GBC "LCD colors", similar to the "real colors" option in no$gmb. Joystick buttons up to #16 can now be used. Fixed problem with puzzle road.

0.62 (2001-08-25) - Added support for joystick/gamepad. Added support for rumble carts. Cleaned up the LCD/STAT/interrupts code; a few rom problems solved, runs pinball deluxe/fantasies. Fixed sound volume rounding, better sound. Fixed the in 0.61 introduced sound problem with Cannon Fodder.

0.61 (2001-08-13) - Added support for zip files. Added 16 bits gfx engine for old GB (faster if window is big/maximized).

0.6 (2001-08-09) - Added GameShark support. Fixed many bugs. Great sound improvements (also fixed a bug which messed up the sound in GBC mode). Sprite priority as on real gb.

0.52 (2001-08-05) - Added a setting which automaticly switches between the faster 8 bits gfx and the 16 bits gfx when needed. Changed window behavior again, it should be correct by now (alfred's adventure). WAV writer didn't work if soundcard disabled... minor fixes. Fixed problem with Hook.

0.51 (2001-08-02) - fixed problems, even more roms supported, check out the screenshots page. Added "Tiles viewer". Fixed a problem with the filename of the wav-writer.

0.5 (2001-07-29) - Added hicolor GBC graphics engine. Added background priority support. Added MBC3 timer emulation. Problems solved, more roms run correctly. Wait-loop detection, some games run faster. Maximum frameskip option. BackGround map vram viewer. Minor changes.

0.4 (2001-07-24) - Added GBC support. Fixed bug in auto-frameskip code, it is now smoother. Minor change in video engine, "the addams family" and "starfight" now run.

0.32 (2001-07-08) - Added icon. Fixed serial transfer; Mortal Kombat and Alleyway now run. CPU optimized with assembler. Emulated behavior of window (startrek briefing screen). minor changes.

0.31 (2001-07-02) - Added support for MBC5 (games like warioland 2). Added gamegenie on/off key. Changed behavior of select snapshot window.

0.3 (2001-06-29) - First released version

feedback:

If you have comments, questions, hints or problems/bugs which are not described here, send me mail.