******* Virtual GameBoy ******* The Portable Nintendo GameBoy Emulator Ms-Dos version 0.88 Linux version 0.79 Core emulator code copyright (C) 1995,1996 Marat Fayzullin MS-DOS port copyright (C) 1996 Marcel de Kogel SVGA-lib code copyright (C) 1995 Thierry Lescot Additional Features (C) 1997 Hans de Goede GameBoy is a registered trademark of Nintendo. MS-DOS is a trademark of Microsoft Corp. Introduction ============ Please, *carefully* read this manual. Do not write me email with questions answered in here, as such letters are going to be ignored: I have too many other things to do to answer the same questions over and over again. Virtual GameBoy (VGB) is a portable emulator of the Nintendo GameBoy handheld videogame console written in C. Although many things do not work quite well yet, it was able to run about 85% of games checked with it. GameBoy-related archives with technical and other info are located at: http://www.freeflight.com/fms/GameBoy/ ftp://ftp.komkon.org/pub/GameBoy/ There are versions of VGB for Amiga, Macintosh, and IBM PC (both MeSsyDOS and Windoze). Following people are maintaining ports of VGB to these systems: Linux Svgalib, Enhanced X and MSDOS: Hans de Goede [j.w.r.degoede@et.tudelft.nl] http://www.et.tudelft.nl/~jdegoede/ Windows and Unix/X Marat Fayzullin [fms@wam.umd.edu] http://www.freeflight.com/fms/ Macintosh: John Stiles [jstiles@cello.gina.calstate.edu] This document covers the following versions: Ms-Dos Linux Svgalib Linux X enhanced Hardware Requirements ===================== A 486DX-33 (486DX2-66 recommended) A VGA compatible video card Adlib/Adlib Gold/SBPro/SB16 and joystick supported Software requirements: ====================== Ms-Dos: ------- VGB-DOS requires the presence of a DPMI server. If you don't run the program under a DPMI-hosted environment (Windows, OS/2, QPMI, ...), put the file CSDPMI.EXE included in CWSDPMI.ZIP somewhere in your path. Linux-Svgalib: -------------- The Linux Svgalib version requires svgalib, this version must run as root! The joystick module and the oss-lite sound drivers are also supported. Unix/x: ------- Requires an 8-bit depth x-server preferable with MIT-SHM extensions The linux/x version again supports the joystick module and OSS drivers. If you want sound run this one as root!, otherwise use "vgbx -sound 0" Files included in VGB-DOS.ZIP ============================== VGB-DOS.EXE The emulator VGB-DBG.EXE The emulator with intergrated debugger. VGB.TXT This file VGB.GIF A GIF file containing the title screen. You can replace this with your own. Make sure the file is in 256-color, 320x200, non-interlaced GIF87A format. The first 64 colors are reserved for use by the emulator KEYS.EXE Small utility to alter the key mappings CONVERT.EXE Small utility to convert old .cfg files to the new format CWSDMI.ZIP A DPMI server required by VGB-DOS.EXE Files included in vgb-linux.zip =============================== vgb The svgalib executable make this sui root! xvgb The X executable if you want to use sound also make this one sui root! Otherwise run with -sound 0. xvgb-dbg X executable with debugger. vgb.txt This file vgb.gif A GIF file containing the title screen. You can replace this with your own. Make sure the file is in 256-color, 320x200, non-interlaced GIF87A format. The first 64 colors are reserved for use by the emulator joy-patch.dif A patch to the linux joystick module 0.8.0 to allow use of 4 button joysticks. Aplly with "patch < joypatch.dif" in the directory where you unpacked the joystick module source. (the dir containing the joystick-0.8.0 dir that is) And recompile your joystick module as instructed in the docs. Default Key Mappings ==================== Cursor Keys - Movement Left Alt - Button A Left Ctrl - Button B Left Shift - Start Z - Select Special Keys ============ q,w,e,r - Toggle sound channels 1-4 on/off (dos version only) t - Toggle sound on/off (dos version only) y - Save current settings to .cfg o - Pause & Blank screen (toggle) (dos version only) p - Pause (toggle) grey - - Decrease volume. grey + - Increase volume ESC - Quit emulator F1 - F4 - Select Backgroundcolor 0 - 3 F5 - F8 - Select Spritecolor 0 - 3 F9 - F12 - Select Windowcolor 0 - 3 1 - Increase red for selected color 2 - Decrease red for selected color 3 - Increase green for selected color 4 - Decrease green for selected color 5 - Increase blue for selected color 6 - Decrease blue for selected color Special Keys in the debugger version only ========================================= A - Enter the debugger S - Display sprite information D - Display lcd state registers Command line options ==================== All commandline options are excepted by all versions covered by this doc. But when it says (version x only) this means they only do something in that version). This is to keep the .cfg files compatible along different versions. -help Print a help page describing all available command line options -ifreq Select interrupt frequency [60] If you want your games to run faster, increase the interrupt frequency. If you want them to run slower, decrease it. -verbose Select debugging messages [1] 0 - Silent 1 - Startup messages 2 - Illegal writes 4 - Illegal CPU ops 8 - Bank switching -vperiod Set VBlank interrupts period [69905 cycles] -uperiod Number of interrupts per screen update [-1] Selecting -1 will enable real-time refresh checking.If the emulation is chunky, try: -uperiod 2 or -uperiod 3 -autosave Save currents settings to .cfg on exit. -cheat Activate GameGenie cheat [none] -delay/-nodelay Delay/Don't delay screen refresh [-delay] -crc/-nocrc Check/Don't check cartridge CRC [-crc] -video Select video mode [0] (not available in X) 0 - 320x200 with title screen 1 - 320x200 without title screen 2 - 360x144 full screen mode 3 - 180x144 full screen mode 4 - 256x200 with title screen 5 - 256x200 without title screen Please note that modes 2-5 may not be compatible with your VGA card or monitor -background Select GIF file to use as background(Not under X) [vgb.gif] (Only works in video modes 0 and 4) -joystick Select joystick mode 0 - disabled 1 - autodetected -sound Select sound mode [1] 0 - No sound 1 - Adlib You may want to have the sound turned off by default for certain games, as the emulation isn't nearly perfect -stereo Select stereo mode [1] 0 - mono 1 - normal 2 - reversed -volume Select initial volume [10]. 0 is silent, 15 is maximum. In dos volume control only works on SBPro or SB16 compatible cards -bcolorX Changes the background/sprite/window colors. -spritecolorX The argument should be: -windowcolorX "#rrggbb", where r=red, b=blue an g =green. these are hex values!, colornames are no longer supported! -swapbuttons Select buttons to swap [0] (msdos only) 1 - Swap joystick fire-buttons 2 - Swap keyboard fire-buttons 3 - Swap both fire-buttons 4 - Remap buttons for gravis gamepad -autoa Select button A autofire mode [0] 0 - No autofire 1 - Autofire -autob Select button B autofire mode [0] 0 - No autofire 1 - Autofire -keys Alter key mappings (see note!) Note on -keys: ============== The string taken by -keys looks something like: "1122334455667788" where the numbers are hex-representation of the scancodes for: 1 : left 2 : right 3 : up 4 : down 5 : button a 6 : button b 7 : start 8 : select Due to the way the keyboard routines work this is the only option which is a bit different for the different versions so put it in vgb-.cfg . - For starters the x-windows version ignores option (still to come ?) - The svgalib version doesn't support extended keycodes but maps the grey cursor keys to the old numeric keypad. So the string for the default-keymapping are: Dos: "CBCDC8D0381D2A2C" ,this completly maches with the scan codes. Svgalib: "4B4D4850381D2A2C" ,note how the cursor keys have changed, because we now use the scancodes for the numeric keypad, cause ext-keys are not supported. But due to the remapping of svgalib the grey cursor keys also work. Configuration files =================== The emulator loads two configuration files (if present) before it loads a cartridge rom: "vgb-dos.cfg" or "vgb-unix.cfg" located in the CURRENT! directory. There is a seperate cfg for each version for some platform dependend options. (see the note above on -keys). cart.cfg (e.g. "dkong.cfg" if you load "dkong.gb") located in the cartridge dump's directory. These are plain text files containing optional commandline options. Options can be separated with spaces, tabs or returns. Troubleshooting =============== - If the emulator refuses to load your ROM images, check if it's CRC is correct and if it's size is a multiple of 8192 bytes. If it's CRC is incorrect, you might want to try using -nocrc, although getting a correct image is prefered. If it's size is incorrect, there might be a SmartCard header attached to the file. Try stripping the first 512 bytes - If a game doesn't run correctly, try increasing vperiod to about 100000 - If display is incorrect, try -delay or -uperiod 0 Note I'm starting a list of specific options needed to run certain games, please mail me any games you know need a specificoption to run. Game: Needed Option: Mario Land 2 -vperiod 75000 Version specific Comments: ========================== Ms-Dos: ------- There has changed a lot with this version, not visually but under the hood. Since I'm now also working on a linux version there has been a complete source tree merge between the Ms-dos and unix version. I now can specify which version I want to compile with one define in the makefile. This also means almost every commandline option has changed. (see above) For one the colorscheme support has disappeared! The same is possible with the -XcolorX options and the colorscheme code was a big mess. Also colornames are nolonger supported! I realise this is a bit inconvienient but this really needed to be done to get a clean code base at which some serious coding could (and has) been done. I've added a convert utility to the dos-distribution just run "convert *.cfg" to convert all your old cfg files to the new commandline options. Colorschemes and names will be converted to the -XcolorX option. So if you liked a specific colorscheme just make a vgb-dos.cfg file and run convert on it. I hope this eases the pain ,I just really needed to get things cleaned up including all those worthless commandline options. Version 0.88 is the latest dos-version, all the bugs I know of have been fixed. And keeping vgb-dos in sync with the linux version would mean breaking my agreement with Marat that I would only do bugfixes, since from now on a lott of new features will be introduced. From now on the DOS-port is officially discontinued as requested by Marat. Linux generic comments: ----------------------- If you want to play with joystick you need to have a loaded joystick module, you can always get the latest joystick module from: ftp://sunsite.unc.edu/pub/Linux/kernel/patches/console (At the time of writing the latest version is: 0.8.0) If you want to use a 4 button joystick you will need a slightly modified joystick module, just apply the patch and recompile*. This should be 100% backwards compatible. I'm working on getting this into the official joystick-module. * = Aplly with "patch < joypatch.dif" in the directory where you unpacked the joystick module source. (the dir containing the joystick-0.8.0 dir that is) And then recompile your joystick module as instructed in the docs. The linux version from now on uses the emulation core of vgb-dos mainly because the vgb-dos core is 20 - 30% faster ! this shouldn't hurt compatibility, but please notify me if any games stop working! The sound routines don't use the OSS-drivers. Instead they directly write to the opl registers. This is done cause the gb-sound hardware looks a lot like an adlib and otherwise it would be one hell of a job to emulate. This means vgb needs root! rights to get permission to directly write to the opl. Also don't run any other sound(midi) programs when running vgb. Your pc shouldn't crash on this but the sound it makes will be horrible. Although vgb doesn't use the OSS-lite drivers for the sound it still needs them. For one it needs them to detect wether there is an opl3. Oss-lite is also used for the mixer functions. Note: if you don't have an opl it won't be detected, so you don't have to run xvgb as root. Vgb-svgalib still needs root for the svgalib. Linux svgalib: -------------- First of all a very big thanks to Ulrich Hecht. He originally came with the idea to use Thierry Lescot's svga-lib code for vgb-linux. He also beat me to releasing a svgalib-version of vgb. Since that day we've been sharing sources. I've done my own adaptation of Thierry's sources to the newest vgb. I've done this mainly because I wanted a clean version whit cross-platform compability. I did however use Ulrich's code for the joystick support. Thanks for all the help Ulrich. I've given my vgb-linux version no 0.76 to clearly indicate that it superceeds Ulrich's version it does the same, plus somethings extra. History ======= Although al versions originaly came from marat. They've quite grown apart. So there's a different old-history for each version. From this release on all versions who are maintained by me will stay in sync, so they've a combined history. Version numbers will probably get matched in the future Current combined release: ------------------------- Dos 0.88 -DOS: This is the latest DOS-release as requested by Marat, Linux 0.79 The dos version now is officially discontinued. My work on the linux version will continue however. -Fixed bug in the opl2 routines, now opl2's are detected and used succesfully again. -Fixed a bug which only saved the first 8kb of battery-backed-ram even if there was more, Thanks go to Mogu for reporting this. Dos 0.87 -Changed the default -uperiod from 0 to -1, -1 now is realtime Linux 0.78 refresh-checking. This was done so that a frameskip of 0 could be manually forced. -Thanks to Paul Robson author of gb97 Donkey Kong 97 is fixed. If you're a dos user be sure to check out his great gb-emu at: http://members.aol.com/~autismuk/gameboy.htm -Added -swapbuttons 4 for gravis gamepad owners. -Linux: added realtime-refreshchecking. -Linux: framecount is corrected for pause. -Linux: sound is turned of when vgb isn't active. -Linux: added background gif support to svgalib version. -Linux: -swapbuttons is implemented -Linux: -support for 4 button joysticks, see linux notes -Linux: vgb doesn't dump core anymore when it can't get the io-permissions for the sound-output instead it issues a warning and continues with sound disabled. Dos 0.86 -Switched from the unix emulation core to marcel's dos-core Linux 0.77 Basicly both core's are the same but although marat's code is cleaner, marcel's is much faster. This means the dos-version is back up to speed. The linux version now is 20 - 30% faster! Thanks to the guy who told me how slow the new vgb-dos was. -I've also optimised the drawing routines a bit which also should speed things up a bit. -Fixed a bug which made the emulator crash when a cartridge file without extension was given on the commandline. -Dos: fixed the realtime syncing routine's. Realtime sync now is disabled when specifying a uperiod other as 0. Dos 0.85 -First combined release based one big merged source tree. Linux 0.76 This means lotts of changes especially for the dos-version So read this doc, even if you've read it for an old version. - -joystick added to en/disable joystick. -Svga-lib version added, with colorchanging and option saving. -Dos: -nodelay made default following the unix version. -Dos: keyboard handling cleaned up vgb should once again run under windows 311. -Unix: sound and joystick support added. -Unix: serial io interrupt emulated, taken from the dos-version. -Unix: changed keys to follow the dos-keys: cursor-keys :movement shift-key :start z-key :select left-alt :fire A left-crtl :fire B Prior Dos versions: ------------------- 0.84 - Added -autosave to the -help commandline parameter list - When saving options the gif-file used for the background is also saved - Fixed a nasty bug in the string parsing of the options-saving-routine, Strange enough this bug only showed at the compaq prolinea's we have at school. 0.83 - Last updated release, since Marat wants the dos-port discontinued, check Marat's vgb page for more info, coming soon. Maybe one more release to fix bugs, but no more update's. Still, if you find any port specific bugs, please mail. Please don't mail any this game won't run bugs. Only port specific bugs , your soundcard not being recognised, for example. - Source-code no longer available on request of Marat - Options and colors can now be saved by pressing Y - -autosave added to save options on exit - vgb-dbg.exe added to the distribution. This is vgb-dos with an integrated debugger, a tat slower though. Debugger information is now displayed readable and entering the debugger doen't crash the emu anymore. 0.82 I (Hans) took over the msdos-port since Marcel has dropped it, on the fly color-changing for easy creation of color-schemes. Quite Some keys changed do to the new color-scheme-changing. 0.8b1 Fixed LCD state and serial I/O emulation, implemented sprite priorities and improved sprite refreshing, added autofire options, soundtrack can now be saved into a file, key mappings can now be changed, increased speed 0.6.2 Fixed a major bug in the GB's timer interrupt scheme and a minor bug in the RAM page allocation scheme 0.6.1 Fixed lots of bugs, added sprite color control 0.5.2 Major speedup, added sync option, fixed some bugs, added color scheme support and a few other options 0.5.1 Initial release Prior Unix-versions: -------------------- Ulrich's vgb-linux releases: 0.7.5 - bugfix: SB volume control works now - autodetection of ports and joystick presence implemented - on-the-fly joystick calibration implemented 0.7.4 - fixed a bug that made it impossible to disable the Sound Blaster 0.7.3 - first public release Marat's original releases: 0.7 - CPU emulation is somewhat sped up - CPU cycles (not ops) are now used for synchronization - LCD controller's state changes are done correctly (which may slow things down somewhat) - Sprite priorities implemented (which may slow things down somewhat) - RAM size bug fixed - Separate autofire for buttons A and B - Saving soundtrack into a file - Separate colors for background, window, and sprites - -nodelay is made default now Whats Next ========== Dos: ---- Nothing, as asked by Marat. I just released this last few versions as a total clean-up so if there are any bugs yo fix or nice features to add I can do it easily. So keep the bug reports flowing, I'll still do bug-fixes. But please do not send any reports about not working games instead try the trouble shooting options. And mail me if you find a way to make a game work. Unix/Linux generic: ------------------- I'm working on gb link emulation for the unix version of vgb. I don't know wether I'll succeed. All info on the gb link and related stuff is appreciated. X-windows: ---------- - Add support for 16, 24 and 32 bpp servers. - Add color changing and palette saving. - Add window scaling Credits ======= - The real work for this emu was done by Marcel and Marat. Thanks for all the hard work Marcel and Marat. - Thanks to Thierry Lescot for the original svga-lib code - Thanks to Ulrich Hecht for his work on the svga-lib code and the joystick support for linux. - Thanks to Paul Robson author of gb97 for the donkey Kong fix and all the future help. If you're a dos user be sure to check out his great gb-emu at: http://members.aol.com/~autismuk/gameboy.htm - VGB-DOS was compiled using DJ Delorie's DJGPP v2.01 DJGPP is a 32 bit C compiler for MS-DOS. Source code and binaries of DJGPP are available at http://www.delorie.com. Please send your comments to me (Hans) at j.w.r.degoede@et.tudelft.nl -BUT PLEASE, do NOT ask for ROM IMAGES!, nor NAG about some games not working, instead try the trouble shooting hints, they work with most games.