BGB version 1.4.1

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

disclaimer:

right click menu:

default keys:

features in this version:

• emulation of the GameBoy, GameBoy Color, and Super Gameboy
• accurate emulation of the hardware, based on research with lots of test roms, useful for debugging/rom development. some highlights:
  • clock exact timing of LCD behavior/state changes
  • realistic initial ram values - random but with specific bit patterns, and simulated values left by bootroms (for example "nibbler (pd)" depends on this)
  • accurate emulation of LCD register writes during scanline (prehistorik man, demotronic demo)
  • emulation of inaccessible VRAM and OAM as on real hardware
  • 10 sprites per line limit
  • clock exact emulation of sprites causing mode 3 to take longer
  • correct memory access timing (access happening at the last/second to last clock of an opcode)
  • accurate emulation of the differences between DMG and GBC, including timing differences, differences in hardware behavior, initial state, etc.
  • can run a GBC rom as on a DMG, and a DMG rom as on a GBC
• powerful debugger:
  • disassembler
  • assembler (change code and ability to save modified rom)
  • symbols (SYM file) support
  • "inline" editing in code, data, and stack viewer
  • breakpoints
  • break on access
  • conditional breakpoints
  • "on jump" access breakpoints for breaking before a jump into a range is taken.
  • source code breakpoints (ld b,b)
  • singlestepping/tracing/animating/step out/step over
  • vram viewer: BG map, tiles, OAM, palette.
  • IO registers viewer
  • live display of data during emulation and freezing of ram values
  • break on exceptions (accessing inaccessible VRAM, read unitialized RAM, echo ram access, access locked external ram, disable lcd outside vblank)
  • ability to modify all registers and state at any time
  • joypad window allows simulating button presses at any time while debugging
• SGB multiplayer with up to 4 gamepads
• graphics output: GDI, DirectDraw, Direct3D, OpenGL, null output
• graphics doubler: HQ2X, Scale2x, scanlines filter, blocky
• sound output: waveout, directsound, null, and disk writer supported. support for writing the 4 channels to separate wav files
• screenshot animation recording that is synchronized with the wav writer and can be converted to a video using avisynth
• runs almost all roms perfectly, compatibility comparable with the best GB/C emulators
• Accurate/high quality sound emulation, bandlimited synthesis
• accurate video emulation including "high color" graphics, correct sprite/background priorities, 10 sprites/line limit, and mid-scanline register changes.
• This emulator is fast.
• Joystick/Gamepad support, everything mappable to every button
• some user interface keys are configurable and can be mapped to joystick/gamepad buttons
• MBC3 Real Time Clock emulation. RTC is saved/loaded in the .sav file, compatible with VBA
• Auto delay/frameskip, emulation runs at 100% real speed and full 60 fps
• GameGenie and GameShark cheat, load/save cheats (auto and manual), "cheat searcher", easy creation of new cheat codes
• save/load state with quick (zsnes style) keys.
• Load from ZIP and GZIP files
• good OS/platform compatibility/low requirements
• support for optional border bitmap and pseudo and real fullscreen modes.
• TCP/IP game link support

supported platforms/system requirements

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

soundcard and joystick/gamepad are optional. A videocard with 3D hardware acceleration is recommended. The minimum CPU is probably in the order of a 200 MHz pentium. BGB runs perfectly on an atom netbook.

accurate emulation and broken PD roms:

known problems:

• pinball fantasies/deluxe: crashes in game
• bgb 0.x will hang/crash when attempting to open bgb 1.0 save states because the old save state format had no version information.

options window:

• Sound:

  • Soundcard (auto) enable sound output to soundcard API. if this and WAV writer are disabled, sound rendering is disabled completely.
  • disable events: (off) do not time sound output on callback events. can be used with null output for performance testing.
  • 8 bits output: (off) enable this if 16 bits audio is not supported or gives problems.
  • High quality sound rendering: (on) bandlimited synthesis. disable this if you're on a very slow PC and you're trying to speed up emulation.
  • Latency: (50) setting this higher means lower latency. setting it too high causes sound to skip.
  • WAV file writer: (off) writes wav file. each time it is re-inited, a new WAV with a different timestamp is created
  • animation recording: (off) saves a BMP screenshot for every 1 or 2 frames (as desired), with timestamp prefix matching the WAV file and a frame number.
  • Save individual channels: (off) write 4 wav files for the individual hardware channels. this works in addition to/independently of "WAV file writer"

• Joypad:

  • click on "configure keyboard" or "configure game controller", to show the wizard. press the desired keys/buttons for the hilighted buttons. to change keys for user interface functions (load/save state, fast forward, reset, etc), check "configure extra buttons", then click on "configure ..."

• Misc:

  • show framerate: (off) shows framerate in the window title bar, 2 numbers: drawed frames/sec, executed frames/sec.
  • increase timer resolution: (on) sets system clock to 1000 Hz to allow for a smooth framerate and reduced cpu usage.
  • reduce CPU usage: (on) causes bgb to use the minimum possible cpu by issuing sleep calls when waiting
  • reduce input latency: (auto) use an algorithm that, if vsync is used, delays input polling and emulation to reduce input-to-screen latency.
  • pause if losing focus: (off) pauses/stops bgb if switching to another app.
  • use fast open files dialog: (off) uses bgb's builtin open/save files dialog instead of the default windows one which can be very slow in windows XP.
  • framerate: (0) can be used to make bgb run slower or faster than real speed, at a desired framerate. 0 runs at the real ~59.72 fps
  • adjust sound speed: (off) change the sound's pitch to match the alternative emulation speed (like a real GB does if you change the clock signal).
  • undelayed speed: (10) how fast to run if pressing the "fast forward" button, 1 is equal to real speed. can also be used to turn the key into a "slow down" key if desired.

• Graphics:

  • Mix current and last frame: (off) can be used to make games show correctly which use "flickering" to mix colors (for example "ballistic")
  • doubler: (off) applies a screen filter effect, also doubles the size in pixels (useful for fullscreen pageflipped mode if you can't use 320x240)
  the "auto" settings are defaults and are recommended settings. other settings may sometimes have specific benefits or uses.
  • bpp: (auto) override bits per pixel selection
  • output: (auto) override choice of output method. use GDI if other methods have problems. null can be used for speed testing (does render, but not output. to disable graphics rendering *and* outputting, change the window's height to 0 instead). to force use of windowed directdraw in vista/7, find and set "DDrawForceNT6=1" in the ini file.
  • vsync: (auto) override choice of vertical synchronization method. vsync eliminates tearing in the animation. one can disable vsync, or set 1 frame/vblank (instead of synchronizing to real speed)
  • stretch: (blocky) instruct the graphics output to use "blocky" (point sampling) or "blurry" (bilinear filter) stretching
  • fullscreen pageflipped: (off) run in a real double/triple buffered fullscreen mode. may have benefits for performance or smooth animation
  • GBC LCD colors: (on) make GBC colors look as on real GBC. disable to use RGB values directly without conversion.
  • border BMP file: (only SGB border) you can use a BMP file as border for BGB (it will show if enabled, and there is no SGB border). use a 160x144 pixels plain, one color rectangle to define the location of the GB screen. You can also drag and drop a bitmap file to use it as background.

• System:

  • Gameboy: runs any rom as on a DMG (original gameboy)
  • Gameboy Color: runs any rom as on a GBC (gameboy color). this also emulates a DMG rom as on a real GBC in DMG mode, to allow testing/debugging this (for example, legend of zerd breaks as in reality)
  • Super Gameboy: runs any rom with SGB support as on a SGB, any other rom as on a DMG.
  • automatic, prefer GBC: (default) runs DMG, SGB, and GBC roms on the proper system. runs GBC+SGB roms as on a GBC.
  • automatic, prefer SGB: runs DMG, SGB, and GBC roms on the proper system. runs GBC+SGB roms as on a SGB.
  • SGB + GBC: emulates both SGB and GBC features at the same time. because this system does not exist, roms may have problems/unpredictable behavior.
  • GBC + initial SGB border: starts SGB+GBC roms in SGB mode, until they transferred a border, then resets in GBC mode. this is required for some GBC+SGB roms to show a border.
  • detect GB pocket/SGB2: (off) when in DMG mode, make roms detect a gameboy pocket, possibly unlocking features.
  • detect GBC on GBA: (off) when in GBC mode, make roms detect a gameboy advance, possibly unlocking features (example: "legend of zelda oracle of ages/seasons")
  • fast SGB transfers: (off) run at unlimited speed during SGB VRAM transfers (inaccurate and can cause problems).
  • Waitloop detection: (on) detect and shortcut waitloops (which most roms use), speeding up emulation. this is done without compromise on accuracy and has no known problems so it should be left enabled.
  • boot roms: (off) run the DMG/SGB and GBC bootrom (rom images must be obtained elsewhere). if used with the "gameboy color" system setting, this lets the GBC bootrom colorize DMG roms. The bootroms are not necessary for normal emulation.

• Exceptions:

  Controls emulation relevant for debugging roms.

  For playing games, the defaults are recommended: "Emulate as in reality", and disabling all "break on" settings. Enabling any "break on" setting will enable "debug mode" and cause emulation to use at least twice as much CPU.

  If developing a rom, keep "Emulate as in reality" and enable the "break on" settings to help catch common problems. If your rom works in bgb with "Emulate as in reality" then it is likely to work on real hardware, but you should still test that too.

  To make a 3rd party PD (unofficial) rom work which doesn't work, you can enable deliberate inaccuracies with with "Troubleshoot broken PD roms" and then enable individual inaccuracies, effectively emulating a poor emulator or a generic flash cart. This can help to pinpoint the cause of problems. Such roms will not work on a real gameboy, or on the real cart they report in the header. Do not rely on this when developing a rom.

GameGenie/GameShark cheat:

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:

• G = game genie
• S = game shark
• P = patched. means a gamegenie code changed values in the rom. if it does not show, the gamegenie code does not work for the used rom.
• E = enabled (toggled with enable/disable buttons)

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

cheat searcher:

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.

open the cheats window, "add", and enter address and desired value in the "internal values", press OK. you can now see the gameshark code in the list.

if you want to create a gamegenie code, in the debugger, menu -> debug -> "access breakpoints", enter the address, make sure only "on write" is checked, and click "add". run the game, and it should stop and show the code line on which the value is changed by the game (for example number of lives decreased). 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.

Commandline parameters

• [-rom] <filename of rom or state> load a rom or save state
• -setting name=value load bgb with a custom setting. this is useful for running multiple (linked) instances on a different position (with winx setting).
• -listen [[addr:]port] start bgb listening for game link. if addr/port is omitted, take from settings
• -connect [addr:port] start bgb connecting for game link. if addr/port is omitted, take from settings

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

• disable high quality sound rendering, set the sound samplerate to 22KHz, or turn sound off.
• make sure "debug mode" is not active (menu, "other", "debug mode")
• disable "mix current and last frame" and set "doubler" to "off"
• Set the desktop resolution to 16 bpp, set emulation to 16 or 8 bpp
• try "fullscreen pageflipped" mode, especially combined with 8 bpp.

full screen mode:

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

game link:

As of 1.4, game link accuracy has been greatly improved and almost all games should work without or with minimal glitches. in particular i have tested pokemon linking (trading and battle) to work without glitches now, and trading beteen blue and gold works too.

version history:

1.4

• greatly improved game link accuracy, most games should now work perfectly.
• added optional HQ2X and Scale2x graphics filters
• various accuracy improvements including sound registers, joypad timing, and lcd/interrupt timing
• Performance/efficiency improvements including waitloop detection and more efficient high quality sound rendering and others
• Major debugger improvements: Supports SYM files containing debug symbols. "on jump" access breakpoints. immideate entry of data into assembler, data, and stack viewer. improved assembler flexibility. Multiline code/data entry window. Keyboard shortcut for navigation to previous/next breakpoint, label etc. Live update memory mode. edit IO map registers. Fixed causes of accidental running while debugging.
• Sound quality improvements: CH3 and CH4 are now bandlimited in high quality mode. Improved DC offset accuracy. fixed sound timing inaccuracies.
• Improved WAV writer + screenshot recording. Fixed audio/video desync problems. Exported files are now better named.
• fixed windows 98 compatibility problem. eliminated requirement for DX9. improved wine support.
• New truecolor/hi-res icon.
• Many small bug fixes and improvements.

1.3.2 - 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 - 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

• added direct3D and OpenGL output, giving accelerated graphics on windows vista/7.
• greatly improved emulation accuracy based on lots of test roms/research, also fixing a number of remaining rom compatibility problems.
• added VBA compatible RTC loading/saving (in the .sav file).
• added support for the GBC bootrom.
• fixed lots of bugs.
• improved debugger functionality.
• redone cheat searcher.
• various performance improvements.
• various gameplay experience related improvements.

1.12 - 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 - 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 - 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 - 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 - 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 - 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

• added debugger
• added cheat searcher
• added optional directdraw and directsound support.
• greatly improved accuracy/compatibility/rom support, fixed many known problem roms.
• added "GBC + initial SGB border" support, allowing a number of GBC roms to show a border.
• added experimental support for sub-scanline timing graphics, "demotronic demo" works perfectly.
• new, more accurate, extendable, save state format. Old states are automatically converted/resaved by default.
• made bgb faster by optimizing/rewriting parts
• added support for 4 gamepads.
• redone joypad config, easy to use GUI
• new GBC LCD colors, more like the real GBC
• lots of minor changes

0.9 - 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 - 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 - fixed: the info screen still showed my old email adres...

0.87b - fixed: linkspeed was not initialized, causing problems when not linked, such as breaking alleyway

0.87 - added experimental TCP game link support.

0.86 - 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 - 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 - Fixed pokemon crystal (HDMA behavior guesswork). Option for generating high quality anti aliased rectangular waves (CH1 and CH2).

0.83 - 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 - 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 - 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 - 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 - 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 - 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 - 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 - 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 - You can drag & drop files to the BGB window. BGB can start with no rom loaded - you don't get the load rom dialog.

0.65b - 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 - 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 - 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 - 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 - 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 - Added support for zip files. Added 16 bits gfx engine for old GB (faster if window is big/maximized).

0.6 - 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 - 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 - 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 - 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 - 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 - 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 - Added support for MBC5 (games like warioland 2). Added gamegenie on/off key. Changed behavior of select snapshot window.

0.3 - First released version

feedback: