

                   ******* Virtual GameBoy *******
                The Portable Nintendo GameBoy Emulator
                             version 0.3

                         by Marat Fayzullin
                      
                       email: fms@wam.umd.edu
                            IRC:  RST38h
               WWW:  http://www.cs.umd.edu/users/fms/

         (*) GameBoy is a registered trademark of Nintendo.






                          * INTRODUCTION *

  Virtual GameBoy [VGB] is a portable emulator of the Nintendo GameBoy 
portable videogame console written in C. Although it is an initial 
release of the emulator in which many things do not quite work yet, it 
was able to run about 85% of 80 games checked with it. You can always
get the latest VGB source code and support files from

    http://www.cs.umd.edu/users/fms/GameBoy/VGB.html

  There are two different VGB distributions which are both covered by 
this manual:

1. *** Source Code Distribution ***
  This distribution contains C sources of the emulator, and the 
screen/keyboard drivers for Unix/X. Virtual GameBoy has been tested on 
the following Unix systems:

  SunOS   Solaris   OSF/1   FreeBSD   HP/UX   Linux   AIX 3.2.5

  It was also successfully run on a Mac, Amiga, and Atari Falcon, 
although no decent ports are available for these platforms yet.
  If you would like to write new drivers, or port VGB to another platform, 
*please*, contact me by email or some other means. Feel free to look at 
existing drivers as well as at the other code.

2. *** VGB-Windows Distribution ***
  Due to the flood of requests from the people who use DOS/Windows 
running PCs and are unable to compile the emulator on their own, I have 
ported VGB under Microsoft Windows. This distribution contains an
executable of a limited version of VGB-Windows which doesn't allow you to 
reload a new game from a menu when emulation is already running, and has 
an annoying "Virtual GameBoy DEMO" message across its window. The 
uncrippled version of VGB-Windows is available for $35US from

  Marat Fayzullin
  6304 Hampton Place
  Elkridge, MD 21227
  USA

  VGB-Windows is a 32-bit application which runs under Windows 3.11, 
Windows 95, and Windows NT. It is compiled with Borland C++ and needs 
Microsoft WinG library which can be obtained from

  ftp://ftp.microsoft.com/Softlib/MSFILES/WING10.EXE




                      * NEW IN THIS VERSION *

o Windows version is made.
o Some heavy magic is done on the interrupts.
o Palette registers are writable now.
o Sprite display routine is changed.
o Sprites are now clipped properly at the top and bottom boundaries.
o -delay/-nodelay option is added.
o etc.



               * SHORT MANUAL FOR THE WINDOWS USERS *

  In order to use VGB-Windows, you will first have to install WinG
graphical library which can be obtained from Microsoft [see address
above]. Also, the VGB-WIndows distribution contains a file called
BWCC32.DLL which should be either kept in a directory from which
VGB runs, or copied into \WINDOWS\SYSTEM directory.
  VGB-Windows runs in a resizable window with the following menus:

o File
  o New
    This opton allows to run a new game. If you only have an unregistered
    version of VGB-Windows, it will be disabled so that you will only be
    able to choose a game when emulator starts.
  o Setup
    This option pops up a setup dialog allowing to change all 4 GameBoy's
    colors and some emulation parameters:
    o Palette
      Use this group of controls to select a color and change its RGB
      components. The palette controls may not work very well if you
      run Windows in 256-color mode. Use 16-bit or 24-bit graphical
      mode for best effect. 
    o VBlank Period
      This parameter determines how many CPU commands will be executed
      between vertical blanking interrupts. Setting it lower may speed
      up the emulation, but setting it too low will hang it.
    o Update Period
      This parameter determines how many vertical blanking interrupts
      will pass between window refreshes. It is usually set to 2, but
      you can increase it to make VGB work faster. The sprite
      movements become jerky at high update periods though, and some
      sprites may simply disappear.
    o Delay Line Interrupts
      If you see "dirty" horizontal lines in some games, you may turn
      this option on or off to remove them. There is no some universal
      state of this option which will work for all games though.  
  o Quit
o Size
  o 1:1  These options change the window size to be the same as in real
  o 2:1  GameBoy, or 2/3/4 times bigger. Please, note that you can change
  o 3:1  window size by simple dragging the bottom-right corner of a
  o 4:1  window with the mouse.
o Help
  o About
    This option will display a dialog box with copyright information
    and other legal stuff.



                   * FREQUENTLY ASKED QUESTIONS *

1. What is GameBoy?
  GameBoy is a handheld videogame machine produced by Nintendo. It is 
built around a custom CPU similar to Z80, but with some changes. GameBoy 
is frequently laughed at because of its reflective green-on-yellow LCD 
screen which in fact is its virtue. Due to the low power consumption of 
its LCD, GameBoy can work for 35 hours off 4 AA batteries. There is a lot 
of good games produced for GameBoy, both classics [Tetris, Pacman, 
Asteroids, etc.] and specific ones [Final Fantasy series for GB]. It 
excells in RPGs and classic games where gameplay is more important than 
graphics. More information about GameBoy is available from
 
                http://www.cs.umd.edu/users/fms/GameBoy/

2. Where do I get GameBoy games?
  You buy the cartridges. GameBoy software is copyrighted and still sold. 
Therefore, its distribution is an act of piracy. Nothing prohibits you 
from backing up a cartridge you own and playing it on the emulator though.
To back up a GameBoy cartridge, you can use either SmartCard copier [about
$100 for a standalone version], or a self-built copier, description of
which will hopefully be available at the WWW page soon.

3. Is it legal to spread GameBoy cartridge snapshots?
  NO. Be aware of the fact that by using commercial software you haven't 
bought, you are commencing an act of piracy. Not that I care, anyway...

4. What are the keys used in VGB?
  VGB Unix/X keys:

  [SPACE] - A button
  [LALT]  - B button                        ([CONTROL] in Windows)
  [TAB]   - SELECT button
  [ENTER] - START button
  [ESC]   - Quit emulation
  [F1]    - Turn tracing on/off             (Not implemented in Windows)
  [F2]    - Show LCD controller registers   (Not implemented in Windows)

5. Where is the complete list of command line options of VGB?
  Use -help option. It will tell VGB to display all options available in 
your version. Following are the options available in VGB-Unix/X:

  -verbose <level>    - Select debugging messages [5]
                        0 - Silent           1 - Startup messages
                        2 - Illegal writes   4 - Illegal CPU ops
                        8 - Bank switching
  -vperiod <period>   - Set VBlank interrupts period [10000ops]
  -uperiod <period>   - Number of interrupts per screen update [2]
  -help               - Print this help page
  -cheat <GG code>    - Activate a GameGenie cheat [not supported yet]
  -shm/-noshm         - Use/don't use MIT SHM extensions for X [-shm]
  -trap <address>     - Trap execution when PC reaches address [FFFFh]
  -delay/nodelay      - Delay/don't delay coincidence int-s [-nodelay]
  -saver/-nosaver     - Save/don't save CPU when inactive [-saver]
  -color0 <name>      - Change color#0 [black]
  -color1 <name>      - Change color#1 [#585858]
  -color2 <name>      - Change color#2 [#989898]
  -color3 <name>      - Change color#3 [white]

6. Why some games do not run with VGB?
  As it was said before, VGB emulation is not completely accurate yet.
Also, some games will probably never run on VGB.

o If a game refuses to work, try changing -vperiod value from 2000 to
  15000, or moving a "VBlank Period" knob in the VGB-Windows setup
  window.
o If you see a group of "dirty" lines on VGB screen, or a game behaves
  strangely, try -delay/-nodelay options, or check/clear the "Delay
  Line Interrupts" checkbox in the VGB-Windows setup window. 
o If some sprites blink or do not appear at all, try changing -uperiod
  value from 1 to 10 [1 will give you the best picture, but the slowest
  emulation], or moving an "Update Period" knob in the VGB-Windows
  setup window.

7. Palette controls in VGB-Windows do not work.
  This probably means that you are running Windows in the 256-color
mode. In this mode, not all of 256 possible colors are available, and
you will be able to choose only from the available colors. Switch
Windows into 16-bit or 24-bit graphics and palette will start working.

8. I start VGB-WIndows, but it tells me that WING.DLL is not found.
  This means that you haven't installed WinG library necessary to run
VGB. Check the information in the beginning of this manual on how to
obtain WinG.

9. I start VGB-WIndows, but it tells me that BWCC32.DLL is not found.
  VGB-Windows comes with a file called BWCC32.DLL. This file should
be either kept in the directory from which VGB runs, or put into
\WINDOWS\SYSTEM directory.

10. Why is VGB so slow on my computer?
  Because your computer is too slow to run VGB. VGB is written entirely in
C language and therefore is quite slow. Although it works on 486/33 and even 
386/33 PCs, it runs best on a Pentium/90 or a DEC Alpha/150. You can try to 
speed it up by increasing -uperiod value controlling the number of vertical
blanking impulses between screen updates to 3-6, and by decreasing -vperiod
value controlling the number of CPU cycles between vertical blanking
impulses to 3000-6000. Please, DO NOT SEND ME MAIL about VGB speed.

11. Can I compile VGB with my Borland/Turbo C compiler?
  You can, given that your compiler creates executables using flat 32bit 
memory model. Two PC compilers which do that are WATCOM [using DOS4GW DOS 
extender] and GCC [using DJPP extender]. The only Borland/Turbo C 32-bit 
compiler that I'm aware of is for Windows.

12. When compiling VGB under Unix, I get "undefined name" errors.
  This means that your linker can not find the libraries necessary
for VGB [namely, libX11.a and libXext.a]. Find these libraries in
your system and modify the Makefile so that the final invocation
of the C compiler has "-L<path_to_libs>" options. If the errors
persist, try #undefining MITSHM option.

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

14. VGB starts under Unix, but then I get X_PutImage error.
  Unix/X version of VGB currently needs 256-color X. Neither 2-color 
nor TrueColor Xterminals will work with the drivers included into 
"official" VGB distribution.

15. I start VGB-Unix/X but the window stays black.
  Some other X application took over all available colors so that VGB 
could not allocate any for itself. Check if you run XV, Netscape, or 
something similar.

---------------
Marat Fayzullin
