                      ******* Virtual GameBoy *******
                   The Portable Nintendo GameBoy Emulator
                             Ms-Dos version 0.8.8
                             Linux version 0.7.11

        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.

                   DO NOT DISTRIBUTE WITH ROM IMAGES!!


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 90% of games checked with it. 

To use VGB you will need rom-dumps of actual cartridges, please do not
ask me for such cartidges since distribution of these is illegal you may
only make a copy of such cartridge for use with vgb if you own them.

Also please do not distribute VGB with rom-images since this could get me,
and others working on VGB in to trouble with Nintendo and others.

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.
This version also requires you have libz installed.

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 "xvgb -sound 0"
This version also requires you have libz installed.


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
============
y            -  Save current settings to <cart-name>.cfg 
o            -  Pause & Blank screen (toggle)    (dos version only)
p            -  Pause (toggle)
grey -       -  Decrease volume.
grey +       -  Increase volume
ESC          -  Quit emulator
F1           -  Select background palette
F2           -  Select sprite palette 0
F3           -  Select sprite palette 1
F4           -  Select window palette
F5 - F8      -  Select color 0 - 3
F9           -  Instant save to slot 0
F10          -  Instant save to slot 1
F11          -  Restore slot 0
F12          -  Restore slot 1
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


Usage
=====
To start up the emulator just type:
"vgb <cartname> <options>"

The options are optional and are desribed below.

You'll need a romdump of a gb-cartidge in .gb format. Gb format is a 
raw-format, without any headers. There's a utility available on the
webpage to strip the 512 bytes headers some cart-readers add.
Do not! mail me for ROM-images they're copyrighted so I can't provide 
you with any, also do not distrubte any rom images with VGB.
 

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 <frequency>             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 <level>               Select debugging messages [1]
                               0 - Silent           1 - Startup messages
                               2 - Illegal writes   4 - Illegal CPU ops
                               8 - Bank switching
-vperiod <period>              Set VBlank interrupts period [69905 cycles]
-uperiod <period>              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
-ifreq <period>                selects h-blanks / second (framerate) [60]
-autosave                      Save currents settings to <cart-name>.cfg
                               on exit.
-cheat <GG code>               Activate GameGenie cheat [none]
-delay/-nodelay                Delay/Don't delay screen refresh [-delay]
-crc/-nocrc                    Check/Don't check cartridge CRC [-crc]
-video <mode>                  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
                               (Under Svgalib this option only selects the use
                               of a title screen !)
-background <filename>         Select GIF file to use as background [vgb.gif]
                               (Not available under X, Only works in video 
                               modes 0 and 4)
-joystick <mode>               Select joystick mode
                               0 - disabled
                               1 - autodetected
-sound <mode>                  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 <mode>                 Select stereo mode [1]
                               0 - mono
                               1 - normal
                               2 - reversed
-volume <value>                Select initial volume [10]. 0 is silent, 15
                               is maximum. In dos volume control only works on
                               SBPro or SB16 compatible cards
-bcolorX <color> (X=0-3)       Changes the background/sprite/window colors.
-scolorX <color> (X=0-7)       The <color> argument should be:
-wcolorX <color> (X=0-3)       "#rrggbb", where r=red, b=blue an g =green.
                               these are hex values!, colornames are no
                               longer supported!
-swapbuttons <flags>           Select buttons to swap [0] (not under X)
                               1 - Swap joystick fire-buttons
                               2 - Swap keyboard fire-buttons
                               3 - Swap both fire-buttons
                               4 - Remap buttons for gravis gamepad
-autoa <mode>                  Select button A autofire mode [0] 0 - No
                               autofire 1 - Autofire
-autob <mode>                  Select button B autofire mode [0] 0 - No
                               autofire 1 - Autofire
-keys <string>                 Alter key mappings (see note!)
-shm/-noshm                    Use/don't use MIT SHM extensions (X only)
-saver/-nosaver                Suspend/don't suspend vgb when out of focus (X)
-scale <x>                     Scale window x times (X only)

Options available only in versions with debugger:
-trap <address>                Trap execution when PC reaches address [0xFFFF]
-trace                         Startup in the debugger

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-<version>.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:

Dos:  "vgb-dos.cfg" located in the CURRENT! directory.
      cart.cfg (e.g. "dkong.cfg" if you load "dkong.gb") located in the 
      cartridge dump's directory.

Unix: $HOME/.vgb.cfg if it can't find this file it also checks for:
      /usr/local/etc/vgb.cfg.
      After this file it also tries to load:
      $HOME/.vgb-saves/<cartname>.cfg

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
Zelda                     -delay



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.8.8 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 hopefully get matched in the future.
 
Current combined release:
-------------------------
Linux 0.7.11 -Since Marat has been insulted too many times by lamers 
              flaming him for roms, and by pirats robbing his hard work, 
              he now refuses to release his source code to anyone.
              So I'm continuing work based on vgb 0.7.
              This version is mostly up with 1.0 but misses the sgb part,
              and has a totally different sound engine.
              Don't forget to try out Marat's version of vgb for linux though,
              the sgb part is really cool with Donkey Kong for example.
              I'm still maintaining this one,
              since it has a few advantages too. ;)
             -Fixed silly bug which saved cheatcodes twice in .cfg files
             -Fixed a bug in the sound length implementation now pacman and
              others sound ok again.
             -Fixed a stupid bug in the LCD-controller introduced in 0.7.10
             -More fixes to the LCD-controller
             -Fixed sio emulation (fixes alleway)
             -Fixed cpu timing bug which made the windfish hang in zelda
             -Correctly emulated sound registers according the the amazing 
              Paul Robson this fixes Bart Simpson at Camp Deadly
             -Implemented undocumented MBC2 behaviour

             -.cfg, .sav and instantsaves (.sv?) are now all located in 
              $HOME/.vgb-saves/<cartname>.xxx
             -compiled with zlib support, now you can load gzipped cart's,
              you do need zlib handy to run vgb now though. (Get it from
              your favorite linux ftp-site)
             -added 512 bytes header detection, 512 bytes headers are skipped
              automatic if detected.
             -more accurate speed regulation alghorithm, fixes slowdowns in X
             -No longer uses mastervolume as volume control, so now you can
              all listen to your favorite mp3's while playing vgb ;)
             -Better signal handling for svgalib version
             -16, 24 and 32 bpp support for X!
             -scaling support for X try -scale 2!

Linux 0.7.10 -Made sprite palettes 0 and 1 configurable seperatly.
             -Added instant save and restore with 2 slots.
             -F-keys changed to free keys for save / restore, see above.
             -Implement sound-lenght byte for all sound channels, for one this
              means the sword sound in zelda is fixed, Thanks go to 
              Paul Robson for the info on this.
             -Corrected the speed at which sound sweeps where done.
             -Fixed the chrgen for the window, this fixes lemmings 2 and more.
              again Thanks to Paul Robson for this. 
             -Corrected the clockcycle count for a few instructions,
              Thanks to someone who didn't want his name mentioned ;)

Dos   0.8.8 -DOS: This is the latest DOS-release as requested by Marat,
Linux 0.7.9  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.8.7 -Changed the default -uperiod from 0 to -1, -1 now is realtime 
Linux 0.7.8  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.8.6 -Switched from the unix emulation core to marcel's dos-core
Linux 0.7.7  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.8.5 -First combined release based one big merged source tree. 
Linux 0.7.6  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.8.4 - 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.8.3 - 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.8.2	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.8.1   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.
- Many thanks to Paul Robson author of gb97 for the donkey Kong fix ,the lemmings 
  2 window fix ,the sound lenght byte hint. 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.
