Virtual GameBoy
version 2.1

by Marat Fayzullin

Contents

Disclaimers

New in This Version

History

New in VGB 2.0

New in VGB 1.7

New in VGB 1.6

New in VGB 1.5

New in VGB 1.4

New in VGB 1.3

New in VGB 1.2

New in VGB 1.1

Introduction

 Virtual GameBoy (VGB) is a portable emulator of the Nintendo GameBoy handheld videogame console. It allows to run most of GameBoy software on a personal computer, as well as debug this software. As VGB is written in a portable C programming language, it runs on many different platforms and operating systems. You can always get latest VGB binaries and support files from

http://www.komkon.org/fms/VGB/

I have always been a big fan of GameBoy and even wrote a USENET FAQ on it. In 1995, I have accidentally stumbled upon an information file on GameBoy hardware written by Pan of Anthrox, and started the VGB project. At the present time, VGB successfully runs overhelming majority of GameBoy games and supports such esoteric devices as GameShark, GameGenie, and Super GameBoy. It also has support for the latest Nintendo's additions to GameBoy family: GameBoy Pocket and GameBoy Color. Following is a list of features supported by VGB at this moment:

VGB Ports

 From the moment of its creation, VGB was intended to be a tool for people who like to figure out how things work. It is widely used to debug homebrewn GameBoy games and other hobbist projects involving GameBoy. Because of that, VGB's source code has been publicly distributable for a very long time. Unfortunately, it looks that for each person geniunely interested in hardware hacking, videogame programming, or revival of the old videogame experience, there are dozens of adolescent gremlins hungry for a quick fun of playing pirated GameBoy games on their PCs. Because of that, I decided to stop releasing VGB source code and terminate the development of a free version of VGB for MSDOS, formerly done by Marcel de Kogel and Hans de Goede. I am no longer willing to provide free entertainment for the vermin. I do feel it necessary to apologize for inconvinience created to all the intended users of VGB. The complete up-to-date list of VGB ports can be obtained from the VGB distribution site. Following are the major ports of VGB available at the moment:

Unix

VGB-Unix is available freely in binary form for various flavors of Unix from the VGB distribution site. I am always trying to compile it on as many different Unices as I have handy at the moment.

MacOS

The Macintosh version of VGB is being developed by John Stiles. It is available from him as a shareware and can be found at the VGB distribution site.

Windows CE

There were two versions of VGB-CE developed by Pascal Felber and Hayes Haugen, but the authors decided to merge them into a single one. This version, called PalmGB and maintained by Hayes Haugen, is a shareware and can be found at the VGB distribution site.

Windows 95/98/NT

The Windows version of VGB is available from me, Marat Fayzullin, for $35US. This fee ensures that you will get you the latest full version of VGB-Windows with sound and joystick support, saved preferences, GameGenie support, and free updates via email as long as VGB-Windows is being updated. For more information about it, take a look at

http://www.komkon.org/fms/VGB/VGBWindows.html

I do not feel very good about maintaining the Windows version because people pirate it a lot and most Windows users appear to be mentally underdeveloped (judging from their email, anyway). If you do want to see Windows version being developed, please, register it by one of the following methods:

ORDER BY MAIL
Send $35US in cash, money order, or a US bank check to: 
     Marat Fayzullin
     6304 Hampton Place
     Elkridge, MD 21075
     USA
Don't forget to include your email address and mention that you want VGB-Windows, as I'm selling several other products as well. The software will be emailed to you as soon as I receive the money.

ORDER BY PHONE
Call one of the following numbers in US: 
     1-800-242-4775 (extension 15245)
     1-713-524-6394 (extension 15245)
and refer to product #15245 (VGB-Windows). This service is provided by DigiBuy. You can pay them with a credit card. Don't forget to give them your email address. The software will be emailed to you as soon as I receive the notification from DigiBuy.

ORDER ON THE WEB
Tell your WWW browser to go to

http://www.digibuy.com/cgi-bin/order.html?296825+92971140557

and use the online form to register VGB-Windows. You can pay with a credit card. They take MasterCard, Visa, Amex, or Discover. The software will be emailed to you as soon as I receive the notification from DigiBuy.

MSDOS

You may find older versions of VGB (<=0.8) for MSDOS on the Net, but there are no newer versions currently available, neither freeware nor shareware. Please, do not mail me asking for it: I won't answer to you. I won't allow anyone to do an MSDOS port of VGB either. See above for the reasons why.

Linux

Currently, VGB-Linux (ELF, GLIBC, X11) is compiled from the same source as all other Unix versions. You can get it for free from the VGB distribution site. Please, do not ask me for an SVGALib version though: I do not consider SVGALib as a viable standard and will not develop for it.

There is also an older version of VGB-Linux (<=0.8) for both XWindows and SVGALib, developed by Hans de Goede, but this version is now discontinued.

Registered Users

 If you registered VGB-Windows, please do not give your copy to anybody. And I do mean anybody. There was a couple of cases when registered users gave VGB away to their friends, relatives, or just "KeWl" guys on the Net, and then I found it pirated, put onto WWW pages, and even posted to USENET newsgroups. If I find your personalized copy of VGB being spread around, your registration gets automatically cancelled which means no support and no more updates.

I understand that the previous paragraph may sound threating to some people, but this kind of piracy really hurts my profits and feelings. I've put a lot of effort into VGB, and can only continue working on it if people do not try to cheat on me.

It may also be a good idea to buy a real cartridge for each GameBoy ROM image you use with the emulator. GameBoy software is copyrighted, but as long as you own the real cartridge, you are protected by the law allowing customers to backup bought software.

What is Included

 Following files are included into the distribution: 
  vgb         - VGB executable file (Unix. vgb -help for options)
  vgb-debug   - VGB with debugger (Unix. vgb-debug -help for options)
  vgb.exe     - VGB executable file (Windows)
  VGB.html    - This documentation
  CART.GB     - Sample ROM image
  demos/      - Directory with some homebrewn GameBoy games and
                demos

What is not Included

 Absolutely no ROM images of GameBoy games are included. GameBoy games are still copyrighted by the companies who produced them, and therefore, I can not distribute any of them. I'm also unable to tell you where to find these games, so do not send me email asking for them. You will have to look for them on your own.

The VGB WWW page contains some links to GameBoy cartridge copier info. Cartridge copiers can be used to dump GameBoy cartridges into files. I can not provide you with any additional information about these copiers, so do not send me email asking for this information. Use the copier-related links at the VGB WWW page.

I'm no longer distributing the GameBoy disassembler and GBLIST cartridge listing utility with this emulator. These programs are now distributed separately in the EMUTools package, also available at VGB WWW page.

Buttons

 
  [SPACE]    - A button (also: [LALT],A,S,D,F,G,H,J,K,L)
  [LCONTROL] - B button (also: Z,X,C,V,B,N,M)
  [TAB]      - SELECT button
  [ENTER]    - START button
  [F11]      - Reset GameBoy
  [ESC]      - Quit emulation (also: [F12])
  [F2]       - Toggle soundtrack log on/off
  [F3]       - Toggle FIRE-A autofire on/off
  [F4]       - Toggle FIRE-B autofire on/off
  [F5]       - Toggle GameGenie/GameShark cheats on/off
  [F6]       - Save emulation state (*.STA)
  [F7]       - Toggle color washout for CGB

  When compiled with #define SOUND:
  [1]-[4]    - Toggle sound channels on/off
  [0]        - Toggle all sound on/off
  [-]        - Decrease sound volume
  [+]        - Increase sound volume

  When compiled with #define DEBUG:
  [F1]       - Go into the built-in debugger

  When compiled with #define MSDOS:
  [F8]       - Toggle joystick on/off
  [F10]      - Make a screen snapshot (SNAPxxxx.GIF)

Command Line Options

 These options only work in VGB-Unix and other VGB ports with the command line interface. VGB-Windows takes no command line options, just a file name. 
  -verbose <level>    - Select debugging messages [5]
                         0 - Silent            1 - Startup messages
                         2 - Illegal writes    4 - Illegal CPU ops
                         8 - Bank switching   16 - SuperGB commands
                        32 - Printer commands
  -vperiod <period>   - Number of CPU cycles per VBlank [69000]
  -uperiod <period>   - Number of interrupts per screen update [3]
  -help               - Print this help page
  -cheat <code>       - Activate a GameGenie/GameShark cheat
  -sgb/-cgb/-mgb/-gb  - Use Super/Color/Pocket GB extensions [-gb]
  -printer/-noprinter - Pocket Printer emulation [-noprinter]
  -washout/-nowashout - Washed out CGB palette [-nowashout]
  -delay/-nodelay     - Delay line interrupts [-nodelay]
  -crc/-nocrc         - Check cartridge CRC [-crc]
  -autoa/-noautoa     - Autofire for button A [-noautoa]
  -autob/-noautob     - Autofire for button B [-noautob]
  -drums/-nodrums     - Emulate noise with MIDI drums [-nodrums]
  -logsnd <filename>  - Write soundtrack to a MIDI file [LOG.MID]
  -colorN <name>      - Set color #N [#FFFFFF,#989898,#585858,#000000]
  -bcolorN <name>     - Set background color #N [same]
  -scolorN <name>     - Set sprite color #N [same]
  -wcolorN <name>     - Set window color #N [same]

  When compiled with #define DEBUG:
  -trap <address>     - Trap execution when PC reaches address [FFFFh]
                        When a keyword 'now' is used in place of the
                        <address>, execution will trap immediately.

  When compiled with #define SOUND:
  -sound [<quality>]  - Sound emulation quality [0]
                        0 - Off                1 - Adlib (MSDOS)
                        Values >8191 are treated as wave synthesis
                        frequencies. Default frequency is 22kHz.
  -nosound            - Same as '-sound 0'

  When compiled with #define UNIX:
  -shm/-noshm         - Use MIT SHM extensions for X [-shm]
  -saver/-nosaver     - Save CPU when inactive [-saver]
  -static/-nostatic   - Static color palette [-nostatic]
  -sync <frequency>   - Sync screen updates to <frequency> [0]
  -nosync             - Same as '-sync 0'
  -scale <factor>     - Scale window by <factor> [1]
  -connect <host:prt> - Establish GameLink to <host:port> via TCP/IP

  When compiled with #define MSDOS:
  -back <filename>    - Use <filename> as background picture [VGB.GIF]
  -static/-nostatic   - Static color palette [-nostatic]
  -vsync/-novsync     - Sync screen updates [-novsync]
  -240/-200           - Non-standard 320x240 screen mode [-200]

Frequently Asked Questions
  1. I WANNA PLAY GAMES!!!! WHERE DO I GET GAMES???????
    I do not know. I can't give you any due to both legal and moral reasons. Please, do not mail me asking for games. I will delete your mail right away, and you won't get an answer.

  2. How do I copy games from cartridges to a computer?
    You can use a special device called cartridge copier. There are several different copiers available, both factory-made and homebrewn. The easiest to use copier appears to be the Bung GB Xchanger. You can buy it from Upstate Games .

  3. What is GameBoy? How its hardware works?
    GameBoy is a handheld videogame machine produced by Nintendo. It is built around a custom CPU similar to Z80, but with some changes. An FAQ on GameBoy programming, games, and other stuff is located at

    http://www.komkon.org/fms/GameBoy/

  4. There is no version of VGB for my Unix!
    I am trying to compile Unix binaries for as many flavors of Unix as possible, but as I do not have access to many machines, do not expect immediate support for every Unix flavor out there. Don't mail me asking for the source either: VGB source code is no longer publicly distrbutable, as much as I regret to say this :(.

  5. Where do I get VGB for MSDOS?
    This is explained in the beginning of this document.

  6. My favorite game doesn't work on VGB. What do I do?
    There may be several reasons why a game has problems running on VGB or does not run at all. Some of the problems are easy to catch by checking ROM images with GBLIST and replacing corrupted ROMs with correct ones. Others require some tweaking.

  7. Why is VGB so slow on my machine?
    Because your machine is too slow to run VGB. My experience shows that you need at least a Pentium/90 machine with fast video to run VGB at a reasonable speed. Following are the ways to speeds thing up:

  8. VGB is too fast on my machine! How do I slow it down?
    Frankly, when I started writing VGB, I never expected that it will be too fast on any machine :). But times change...

  9. What is GBLIST?
    GBLIST is a small utility which will list, verify, and possibly fix GameBoy ROM images for you. It is highly recommended to all VGB users and has been a part of the VGB distribution for a long time. It is now distributed as a part of the EMUTools package.

  10. What is EMUTools package and where can I get it?
    EMUTools is a set of utilities which may be useful for both emulator authors and users. They allow to list and verify diferent ROM images, convert music files, disassemble and compare ROMs. EMUTools can be obtained from the VGB WWW site.

  11. Do I need to unpack GZIPped ROM images to run them on VGB?
    No, unless your copy of VGB has been compiled without #define ZLIB. VGB-Windows and most versions of VGB-Unix are compiled with this option. It allows VGB to recognize and automatically unpack GZIPped and singular PKZIPped files. To find out whether your VGB-Unix supports this feature, run it with -help option and see if there is anything said about GZIP support.

  12. When starting VGB-Unix, ld says that libz library isn't found.
    Some VGB-Unix binaries are compiled with #define ZLIB option to make them automatically recognize and unpack GZIPped files. This option requires ZLib library which can be obtained from

    http://www.cdrom.com/pub/infozip/zlib/zlib.html

  13. I entered registration code into VGB-MacOS and now it says I pirated it!
    VGB-MacOS will lock up if you try to "register" it without paying for registration and using the correct registration code. It will then refuse to work on your computer. If you think that you have been mistreated for a simple typing error, contact John Stiles for help.

  14. When starting VGB-Unix, ld says that some library isn't found.
    This may happen if the versions of your shared libraries are older than the ones for which VGB has been compiled. A decent way to deal with this is to upgrade your Unix. A quick and dirty way is to make a symbolic link from the existing library to a name required by VGB.

  15. When starting VGB-Unix, I get X_ShmAttach error.
    You are probably trying to run VGB-Unix on a remote Xterminal while it attempts to use shared memory for interfacing with X. Use -noshm option to tell it not to use shared memory.

  16. When starting VGB-Unix, I get X_PutImage error.
    VGB-Unix version currently needs 8bit, 16bit, or 32bit X. Neither 2-color nor 16-color Xterminals will work. 24bit Xterminals may work, but don't count on it.

  17. When starting VGB-Unix, the window stays black.
    Some other X application took over all available colors so that the emulation could not allocate any for itself. Check if you run XV, Netscape, or something similar.

  18. The sound is distorted in the VGB-Windows. How do I fix it?
    The wave-synthetized sound in VGB may become distorted on slow or highly loaded machines (no graphics acceleration, for example). There are several ways you can improve sound:

  19. Does VGB-Windows support joystick? My joystick doesn't work!
    VGB-Windows supports joystick. If your joystick does not work, go into Windows Control Panel to see if it is configured and calibrated properly. Also, some new joysticks working in esoteric standards (like GRiP) are known to have problems.

  20. VGB-Windows starts, but then quits immediately!
    Check the pathname to wherever your VGB is located. It should not contain spaces. For example, "C:\Program Files\VGB" is a bad place for VGB, while "C:\VGB" will work. This bug is caused by an old version of C compiler I am using. I hope to get rid of it when I switch to a new compiler.

  21. Colors are all screwed up in VGB-Windows!
    When running Windows in 256-color mode, it will try to approximate colors to existing ones, but it won't always get an exact match. I'm working on fixing this. For now, switch Windows into 16bit or better graphics to get perfect colors.

  22. Black window in VGB-Windows!
    If you are running Windows in 256-color mode, then this is most likely the cause of a problem. Try switching Windows into 16bit or better screen mode.

  23. Command line options don't work in VGB-Windows!
    They shouldn't. The demo version of VGB-Windows supports no command line interface at all. The full version will only accept the .GB file name at the command line, but no options. All configuration is done via Setup Panel and VGB.INI file.

  24. Volume control works strangely in VGB-Windows!
    It is a result of the volume control being shared between VGB and other Windows applications. You can usually restore normal volume by leaving VGB window and then activating it again.

  25. Will VGB-Windows work on Windows 3.xx?
    It may, but I can't guarantee it. VGB-Windows has never been tested on Windows 3.xx. Maybe it is time to upgrade.

  26. I'm a registered VGB-Windows user and some games no longer run!
    It is quite possible that your VGB.INI file no longer works with the new version of VGB. It is my suggestion to delete VGB.INI every time you get a new version of VGB. You can still use some ASCII editor (Notepad or DOS Editor) to migrate some of your old settings into new VGB.INI.

  27. How do I use Pocket Printer emulation?
    Anything you print on a Pocket Printer will be printed in the ASCII art form. VGB-Unix will use standard ASCII characters and print to the standard output. VGB-Windows will use IBM PC pseudographics and print to a file called PRINTER.OUT in the current directory. Keep in mind that the Pocket Printer emulation is not perfect yet, so some games may not print properly.

  28. How do I save and load the GameBoy state during the game?
    The GameBoy state can be saved by pressing [F6] button. The resulting data file will have the same name as your .GB file, but its extension is going to be .STA. This state file will be loaded automatically next time you start VGB. The same state file is not guaranteed to work for versions of VGB running on a different hardware. State saving is not perfect yet, so for some games state may not be correctly saved.
© Copyright by Marat Fayzullin (fms@cs.umd.edu)