                                  VSS V0.77
                           (Virtual Super System)

           copyright 1996,1998 by Daniel Boris (dboris@erols.com)

---------------------------------------------------------------------------

Acknowledgments:

I would like to thank the following people for their help and encouragement:


        Keita Iida (Keita/Pooka/Fygar)
                for his enthusiasm for the 5200 beta testing and
                general encouragement.
        Markus Gietzen
                for ideas on improving the emulation.
        Bo Krogsgaard (Therion23)
                for his support of the project and his ASM coding and
                beta testing.
        Kevin Horton
                for figuring out the Bounty Bob bank switching.
        Ron Fries
                for his excellent pokey sound library.
        Jeffry Johnson (calamari), Lepper, and Conjurer.
                for help in beta testing
        Erica (unico)
                for putting up with me while I was working on this ;)

        and everyone on EFNET IRC channels #emulate and #rgvc.

---------------------------------------------------------------------------
Copyright:
VSS is copyright 1996-1998 by Daniel Boris.
POKEY Sound is copyright 1996 by Ron Fries.

VSS is free as long as it is not used in a commercial matter and not
altered in any way. The contents of this archive should not be
added to or changed in any way. 

I maintain the right to forbid the use of the emulator  at
any time. I am not responsible for any damage caused by the use
of this program. This program is distributed "as-is". I make no
guarantees as to it's accuracy, performance, or compatibility with
the users hardware.

VSS is not to be included in CD collections of any sort.
---------------------------------------------------------------------------    

Introduction
        
        Virtual Super System (VSS) is an Atari 5200 Super System emulator
for MSDOS. VSS needs a 486 or greater processor with 2 Meg of memory and
a standard VGA card to run. The emulator is still a little slow, so the
faster the processor the better. On my Cyrix 133Mhz machine with PCI video
card it runs at normal speed with sound and no frame skipping.

The current version of Virtual Super System can be found at:

    http://www.atarihq.com/danb

---------------------------------------------------------------------------

VSS was written using DJGPP a free 32bit C/C++ development system:

        http://www.delorie.com/djgpp/ 

VSS uses Allegro, an excellent game programming library for djgpp by Shawn
Hargreaves:

	http://www.talula.demon.co.uk/allegro/

POKEY sound emulation was done with POKEY sound V1.2 by Ron Fries.

----------------------------------------------------------------------------

Setup:

        Before you can run VSS you need a copy of the 5200 BIOS ROM. For
copyright reasons I am not including this ROM image in this archive, but
it can be found at:

        http://www.davesclassics.com/

Once you get the image rename it to 5200.bin and put it in the same directory
as the emulator.

If you are running under MSDOS you must copy the file CWSDPMI.EXE to your
root directory.

You will also need cartridge images, but again for copyright reasons I cannot
provide these. PLEASE DO NOT E-mail me asking for ROM images! All messages
asking for ROM images will be promptly deleted.

The following games run almost perfectly:
Pac-man,Ms. Pac-man, K-razy Shoot Out, Frogger, Frogger II, Jungle Hunt
Astrochase, Berzerk, Blue Print, Centipede, Defender, Gorf, Gremlins,
Kaboom, Missile Command, Pengo, Space Dungeon, Super Breakout, Bounty Bob

A note on bad images: If an image does not run on the emulator it is possible that the ROM 
image is bad. I had a working Q-Bert image, and got another one that worked OK, but the top
of the screen was messed up. If the Atari logo comes up, and the title of the game is 
corrupt or missing, then the image is probably bad. If an image crashes out to the debugger,
then the image is probably bad. 

------------------------------------------------------------------------------------

Sound Setup:

VSS works with Sound Blaster and compatible cards. Be sure to have you
BLASTER environment variable set (see your sound card manual for more info).
VSS should automatically detect your sound card, if it doesn't it will disable
sound emulation.

I have removed the Allegro sound setup utility from the zip because people
should not really need it, and it takes up a lot of space. If people have
problems getting the sound to work, I may make it available.

-----------------------------------------------------------------------------

Basic Usage:

To start VSS simply type 5200 followed by the name of the rom file you want
to load. For example to load a file called pac-man.bin you would type:

5200 PAC-MAN.BIN

-----------------------------------------------------------------------------
Config file:

VSS now supports a default configuration file. This file (5200.cfg) will be
automatically created the first time you run the emulator. The config file
specifies all the default configurations that are to be used by the emulator.
The options in the [config] section of the file corresponds to the command line
options. For example "fr = 1" in the config file means to use a frame skip rate
of 1. Any command line options you use when running the emulator will override
the setting in the config file. So, for example, if you start the emulator with:

5200 pac-man.bin -frame=3

the emulator will use a frame skip rate of 3 instead of 1. If there is not config
file entry for an option and you don't specify a command line option for it, then
the emulator will use and internal default.

The only config option that does not correspond to a command line option is
the 'path' option. Path sets the directory to use when loading roms. So if
you have 'path = c:/vss/roms/' in the config file, and you type:

5200 pac-man.bin

the file: c:/vss/roms/pac-man.bin will be loaded. If you put a path in the
command line then it will override the config file:

5200 c:/vss/pac-man.bin

will load the file c:/vss/pac-man.bin.

-----------------------------------------------------------------------------
Command line options:

5200 file -[options]

        file - 5200 file to load. This must be a raw binary file, either
        16K or 32K long. If you supply a path name with the file name,
        for example: 5200 C:/VSS/ROMS/PAC-MAN.BIN then it will be loaded
        from that path, and the path option in the config file will be
        overridden.

        -frame=# - Sets frame skip rate. The emulator will display 1 out of
        every # frames. The higher the number, the faster the emulation, but
        more frames are skipped. I find that a frame rate of -frame=4 works
        good for most games. Some games display things every other frame,
        (e.g. Pengo, Wizard of Wor). In this case an even frame skip number will
        not work, but an odd number will. Please note that due to the way frame skipping
        is handled, the color scrolling Atari logo will appear to scroll at
        the same speed, but it will disappear faster.

        -top=# - sets the first scanline to display on the screen. Default
        is 24. The 5200 screen is only supposed to be 192 lines high, but
        some games stretch this beyond 200, thus the emulator will cut off
        the bottom of the image. The image can be shifted up and down with
        this setting.

        -modex - This makes the emulator use the VGA 320x240 Mode. This
         mode is slower the normal mode, but allows for a bigger display.
         This works good for games like Bounty Bob which need create a larger
         display them the normal graphics mode can handle.

        -pengo - Enables special keyboard joystick emulation for use in
        Pengo, Super Breakout, Missile Command and probably some others. 

        -control =
            This configures what type of control you wish to use. After the
        equals put one of the following options:

           key    - Disables all other controls and uses the keyboard.

           stickd - Enables a real joystick to be used in digital mode. This
                    mode works good for most games.
            
           sticka - Enables a real joystick to be used in analog mode. The
                    first time you use this option you will be prompted through
                    calibrating your joystick. Once you have done this once, it will
                    be saved in a file called 5200.cfg. If you ever need to
                    re-calibrate the stick start the emulator with the joystick
                    enabled and the -cal option.

           mouse -  Enables joystick emulation via the mouse.

         -cal - Forces re-calibration of the joystick. This must be used
          in conjunction with -control=sticka or -control=stickd.

         -nostick - Disables real joystick. This will override any other
          joystick command line options.

        -mouse=# - Sets the mouse sensitivity. This option should be 
         a value from from 1 to 10. A value around 2 seems to work OK.
         The 5200's joysticks are analog as opposed to digital. Most
         games treat them as digital sticks, and these games work fine
         with the keyboard controls. Some games like Missile Command,
         and Gorf, use the 'analogness' of the sticks and work better
         with the mouse.

        -nosound - Disables sound emulation.

        -limit - Enables the speed limiter. Use this if VSS runs too fast
         on your system. I neve thought this would be a problem :)

        -bb - Use this option to run Bounty Bob.  To run it you will need
         the following files:

         BB_A0_BF.bin   -   fixed bank at A000 to BFFF
         BB_40_4F.bin   -   4 banks at 4000 to 4FFF
         BB_50_5F.bin   -   4 banks at 5000 to 5FFF

         If you don't specify a pathname on the command line then these file
         will be loaded from the path specified in the config file. If you want
         to specify a path on the command line you can:

         5200 -bb c:/vss/roms/

         or

         5200 -bb c:/vss/roms/bb.bin  (the file name here will be ignored and
            just the path used)

        -debug  - Start emulator in debug mode.

----------------------------------------------------------------------------

Controls:

	Arrow keys = Joystick 1
    E,S,X,F    = Joystick 2
    Alt        = Fire A Stick 1
    Ctrl       = Fire B Stick 1
    Space      = Fire A Stick 2

    1-9,0      = keypad number keys
    F6         = # key
    F5         = * key
    Q          = Leave the emulator
    F1         = Start key
    F2         = Pause key
    F3         = Reset key
    F4         = Enter debugger

----------------------------------------------------------------------------
Debugger

The debugger in VSS is provided "as-is". I don't make an effort to test it
completely with each release so I can guarantee whether it will work
entirely.

H = display help

----------------------------------------------------------------------------

Limitations
         - no GTIA graphics modes 17
         - no ANTIC mode 3 (I have never seen it used)
         - vertical fine scrolling not implemented in every mode
         - no mode 15 alizing

Version History:

v0.77  04/12/98
        - Added GTIA modes 9,11 (Fractalus and Ballblazer)
        - Fixed DLI handling in mode 2 (fixed little quirk in pac-man)
        - Cleaned up the startup and shutdown routines. This should help
          prevent memory leaks that may have caused people problems.
       -  Added -nostick option. This was requested for use with frontends.
       -  Improved speed limiter so games run smoother on high speed machines.
       -  Fixed color handling of ANTIC modes 2,4,5.
       -  Tweaked color palette.
       -  Enemies in Wizard of Wor are visible again. (I have no idea why!)
       -  Fixed DLI bug in mode ANTIC mode 15, Galaxian now runs.
       -  Added support for a default configuration file.
       -  Made command line options for selecting controllers a little simpler.
       -  Added better support for pathname handling.
       -  Added support for VGA modex.

v0.75  12/25/97
        - Added speed limiter, enable with -limit.
        - Fixed ANTIC address decoding, Bounty Bob now works.
        - Adjusted keyboard joystick values, Bounty Bob fix.
        - Bounty bob can now be run with just the -BB option.
          Filename and first_line are set automatically.
        - Now using Allegro 3.0 game library.
        - Switched to Allegro streaming audio functions, which
          increased the sound quality.

v0.71: 3/5/97
        - Fixed a major bug in the sound card initialization
        - Fixed a bug in the trigger handling with the mouse
        - Fixed bugs in Debugger. Program can now be stopped and
          restarted more the once.
        - Added some error handling to the debugger commands.

v0.70: 2/18/97
        - Added horizontal fine scrolling
        - Added vertical fine scrolling to mode 4 and 5
        - Added support for Bounty Bob bankswitching
        - Added sound support
        - Size of cart images is now checked
        - Many speed optimizations
        - Fixed handling of bit 6 in SKSTAT
        - ANTIC writes are now fully decoded
        - The random number generator is now seeded properly

v0.60: 10/15/96
        - Ported to DJGPP for increased speed.
        - Fixed problems with frame skip mode.
        - Replaced interactive debugger with a new one with more features
        - Added joystick emulation.
        - Added second joystick emulation keyboard.
        - Fixed bug that locked up Star Raiders.

v0.50: 9/03/96 First Public Release

