<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>bgb readme</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<h2>BGB version 1.5.7</h2>
<b>homepage: </b><a href="http://bgb.bircd.org/">http://bgb.bircd.org/</a><br>
<b>email: </b>bgb at bircd dot org
<p>
this is a gameboy/color emulator/debugger for win32 which will probably never be finished
<p>
<h3>disclaimer:</h3>
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.
<p>
<h3>table of contents</h3>
<a href="#rightclick">right click menu</a><br>
<a href="#defaultkeys">default keys</a><br>
<a href="#features">features in this version</a><br>
<a href="#requirements">supported platforms/system requirements</a><br>
<a href="#pdroms">accurate emulation and broken PD roms</a><br>
<a href="#knownproblems">known problems</a><br>
<a href="#options">options window</a><br>
<a href="#cheats">GameGenie/GameShark cheat</a><br>
<a href="#cheatsearcher">cheat searcher</a><br>
<a href="#expressions">expressions, breakpoint conditions, and debug messages</a><br>
<a href="#commandlineparams">Commandline parameters</a><br>
<a href="#demorec">Demo recording/playback</a><br>
<a href="#slowpc">How to make bgb run faster if you have a slow computer</a><br>
<a href="#fullscreenmode">full screen mode</a><br>
<a href="#gamelink">game link</a><br>
<a href="#avirecorder">AVI recorder</a><br>
<a href="#speedruns">Note for speedrun or "race" use</a><br>
<a href="#history">version history</a><br>
<h3 id="rightclick">right click menu:</h3>
Click the right mouse button in the emulator window to get the popup menu, from which you can access the options and functions.
<p>
<h3 id="defaultkeys">default keys:</h3>
<table border="0">
<tr><td width="50%">numpad +</td><td>fast forward</tr>
<tr><td>numpad *</td><td>reset gameboy</tr>
<tr><td>numpad -</td><td>cheat codes on/off</tr>
<tr><td>A</td><td>B button</tr>
<tr><td>S</td><td>A button</tr>
<tr><td>Shift</td><td>Select button</tr>
<tr><td>Enter</td><td>Start button</tr>
<tr><td>F2</td><td>save state</tr>
<tr><td>F3</td><td>select state</tr>
<tr><td>F4</td><td>load state</tr>
<tr><td>Esc</td><td>debugger</tr>
<tr><td>Alt+F4</td><td>exit</tr>
</table>
<p>
<h3 id="features">features in this version:</h3>
<ul>
<li>emulation of the GameBoy, GameBoy Color, and Super Gameboy</li>
<li>accurate emulation of the hardware, based on research with lots of test roms, useful for debugging/rom development. some highlights:
<ul>
<li>clock exact timing of LCD behavior/state changes</li>
<li>realistic initial ram values - random but with specific bit patterns, and simulated values left by bootroms (for example "nibbler (pd)" depends on this)</li>
<li>accurate emulation of LCD register writes during scanline (prehistorik man, demotronic demo)</li>
<li>emulation of inaccessible VRAM and OAM as on real hardware</li>
<li>10 sprites per line limit</li>
<li>clock exact emulation of sprites causing mode 3 to take longer</li>
<li>correct memory access timing (access happening at the last/second to last clock of an opcode)</li>
<li>accurate emulation of the differences between DMG and GBC, including timing differences, differences in hardware behavior, initial state, etc.</li>
<li>can run a GBC rom as on a DMG, and a DMG rom as on a GBC</li>
</ul></li>
<li>powerful debugger:
<ul>
<li>disassembler</li>
<li>assembler (change code and ability to save modified rom)</li>
<li>symbols (SYM file) support</li>
<li>"inline" editing in code, data, and stack viewer</li>
<li>breakpoints</li>
<li>break on access</li>
<li>conditional breakpoints</li>
<li>"on jump" access breakpoints for breaking before a jump into a range is taken.</li>
<li>source code breakpoints (ld b,b)</li>
<li>singlestepping/tracing/animating/step out/step over</li>
<li>vram viewer: BG map, tiles, OAM, palette.</li>
<li>IO registers viewer</li>
<li>live display of data during emulation and freezing of ram values</li>
<li>break on exceptions (accessing inaccessible VRAM, read unitialized RAM, echo ram access, access locked external ram, disable lcd outside vblank)</li>
<li>ability to modify all registers and state at any time</li>
<li>joypad window allows simulating button presses at any time while debugging</li>
</ul></li>
<li>SGB multiplayer with up to 4 gamepads</li>
<li>graphics output: GDI, DirectDraw, Direct3D, OpenGL, null output</li>
<li>graphics doubler: HQ2X, Scale2x, scanlines filter, blocky</li>
<li>sound output: waveout, directsound, null, and disk writer supported. support for writing the 4 channels to separate wav files</li>
<li>AVI recording, to installed system codec of choice. No sound included but is in sync and conveniently named with recorded wav file.</li>
<li>runs almost all roms perfectly, compatibility comparable with the best GB/C emulators</li>
<li>Accurate/high quality sound emulation, bandlimited synthesis</li>
<li>accurate video emulation including "high color" graphics, correct sprite/background priorities, 10 sprites/line limit, and mid-scanline register changes.</li>
<li>This emulator is fast.</li>
<li>Joystick/Gamepad support, everything mappable to every button</li>
<li>some user interface keys are configurable and can be mapped to joystick/gamepad buttons</li>
<li>MBC3 Real Time Clock emulation. RTC is saved/loaded in the .sav file, compatible with VBA</li>
<li>Auto delay/frameskip, emulation runs at 100% real speed and full 60 fps</li>
<li>GameGenie and GameShark cheat, load/save cheats (auto and manual), "cheat searcher", easy creation of new cheat codes</li>
<li>save/load state with quick (zsnes style, and mappable) keys, and preview screenshots for slots in select window.</li>
<li>Load from ZIP and GZIP files</li>
<li>good OS/platform compatibility/low requirements (works well on wine, windows 98, and on slow/old PCs)</li>
<li>support for optional border bitmap and pseudo and real fullscreen modes.</li>
<li>TCP/IP game link support</li>
</ul>
<p>
<h3 id="requirements">supported platforms/system requirements</h3>
<p>OS: supported/known to work on windows 98 up to windows 10, DirextX 7 or later. Wine on Linux and OS X.
<p>
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.<p>
<h3 id="pdroms">accurate emulation and broken PD roms:</h3>
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 <i>"Troubleshoot broken PD roms"</i>, and then set aspects of deliberately inaccurate emulation, to see which one a broken PD rom depends on. Choosing <i>"Emulate as in reality"</i> disables and locks out all inaccuracies and should be done if not trying to fix a problem with a bad rom.<br>
one can also set "break on ..." settings to break (go to the debugger) if a rom misbehaves.<br>
note that if you enable any <i>"break on"</i> 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.
<p>
<h3 id="knownproblems">known problems:</h3>
<ul>
<li>bgb 0.x will hang/crash when attempting to open bgb 1.0 save states