===============================================================================

                      SSSS    tt          lll  lll
                     SS  SS   tt           ll   ll
                     SS     tttttt  eeee   ll   ll   aaaa
                      SSSS    tt   ee  ee  ll   ll      aa
                         SS   tt   eeeeee  ll   ll   aaaaa
                     SS  SS   tt   ee      ll   ll  aa  aa
                      SSSS     ttt  eeeee llll llll  aaaaa

                    A Multi-platform Atari 2600 VCS Emulator

                                  User Guide
===============================================================================
        A Bradford W. Mott production in association with Aaron Giles,
       Seunghee Lee, Jeff Miller, Darrell Spice Jr., and Keith Wilkins
===============================================================================

This is the Stella user guide please read it thoroughly before mailing 
anyone questions.  If after reading this document you still have questions
please check the FAQ on the Stella homepage.  If you have any suggestions 
for improvements to this document please send them to bwmott@eos.ncsu.edu.  

PLEASE DO NOT EMAIL ASKING FOR ROMS THEY ARE COPYRIGHTED AND WE WILL NOT 
SEND YOU ANY OR TELL YOU WHERE TO FIND THEM!


Stella License Information and Copyright Notice
===============================================

Stella is Copyright(c) 1995, 1996, 1997 by Bradford W. Mott.

Permission to use, copy, and distribute Stella in its entirety, for
non-commercial purposes, is hereby granted without fee, provided that
this license information and copyright notice appear in all copies.

If you redistribute Stella, the entire contents of this distribution
must be distributed.  The software may be modified for your own
purposes, but modified versions may NOT be distributed without prior
consent from the author.

This software is provided 'as-is', without any expressed or implied
warranty.  In no event will the author be held liable for any damages
arising from the use of this software.

If you would like to do something with Stella that this copyright
prohibits (such as distributing it with a commercial product, using
portions of the source in some other program, etc.), please contact
the author.

The author can be contacted via:

   email:    bwmott@eos.ncsu.edu

   mail:     Bradford Mott
             Graduate Student
             Department of Computer Science
             North Carolina State University
             Raleigh, NC 27695-8206, U.S.A.


TiaSound Library Copyright Notice
==================================

(Stella uses the TiaSound library written by Ron Fries.  It can be be 
downloaded from the Stella home page.)

TiaSound is Copyright(c) 1996 by Ron Fries

This library is free software; you can redistribute it and/or modify it under 
the terms of version 2 of the GNU Library General Public License as published 
by the Free Software Foundation.

This library is distributed in the hope that it will be useful, but WITHOUT 
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
FOR A PARTICULAR PURPOSE.  See the GNU Library General Public License for more 
details.

To obtain a copy of the GNU Library General Public License, write to the Free 
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Any permitted reproduction of these routines, in whole or in part, must bear 
this legend.  



Table of Contents
=================

  1.0 Introduction

  2.0 Installation
    2.1 Linux Binary Distribution
    2.2 MS-DOS Binary Distribution
    2.3 Power Mac Binary Distribution
    2.4 Windows 95 & NT Binary Distribution
    2.5 Unix Source Code Distribution

  3.0 ROM Images and Property Files

  4.0 Installing ROMS Images

  5.0 Playing a Game
    5.1 Unix and MS-DOS
    5.2 Power Macs
    5.3 Windows 95 & NT

  6.0 Keyboard Layout

  7.0 Mailing List

  8.0 Known problems with Cartridges

  9.0 Property files (.vcs files)

 10.0 Property Autodetection

 11.0 Acknowledgements

 12.0 Revision History

   
1.0 Introduction
================

Stella is a portable emulator of the old Atari 2600 video-game console
written in C++.  It is a work-in-progress, however, you can play most
Atari 2600 games with it.  You can get the latest Stella news, code,
and binaries from:

  http://www4.ncsu.edu/~bwmott/www/2600/

If you have problems with Stella please check the homepage to make
sure you're running the lastest release before sending mail.  There
are versions of Stella for Linux, MS-DOS, OS/2, Power Macs, Unix/X,
and Windows.  The maintainers are:

  Aaron Giles (agiles@sirius.com)           Power Macs
  Jeff Miller (milnak@msn.com)              Windows 95 & NT
  Bradford W. Mott (bwmott@eos.ncsu.edu)    Linux and Unix/X
  Darrell Spice Jr. (spice@ibm.net)         OS/2
  Keith Wilkins (wilki1k@nectech.co.uk)     MS-DOS

If you would like to port Stella to another platform or would like to
help with something please take a look at the Todo.doc file for a list
of things that need to be done.   Please note that although the source code
for Stella is freely distributed the code is NOT public domain.


2.0 Installation
================

Once you've downloaded a Stella distribution you should follow the 
directions for the distribution you have.  

2.1 Linux Binary Distribution
-----------------------------

This distribution contains the ELF binaries for Linux.  The binaries were
built on a machine running Red Hat Linux 4.0 upgraded to Linux 2.0.27.
If these binaries don't work on your system then download the Unix/X source
code distribution and compile it yourself.  To install the distribution 
do the following:

  1) Untar the distribution: tar -zxvf stella-0.6-linux.tar.gz

  2) Login as root (or su) and cd to the distribution directory

  3) Copy the executables: cp stella xstella stella-sound /usr/local/bin

  4) Fix permissions: chmod u+s /usr/local/bin/stella

  5) You may also need to execute 'chmod a+rw /dev/ttyS0' to get the paddles
     to work under SVGALIB

The binaries were built with joystick support so if you have a joystick
module installed, such as joystick-0.8.0.tar.gz, you'll be able to use
your joysticks.  The stella-sound program must be in your PATH when you
run Stella if you want sound to work.

2.2 MS-DOS Binary Distribution
------------------------------

This distribution contains the binaries for MS-DOS.  To install the
distribution do the following:

  1) Change directories to the root directory: CD \

  2) Execute the self-extracting archive: STELLA06.EXE

  3) Copy the STELLA.EXE program to a directory in your path or
     add C:\STELLA to your path in the AUTOEXEC.BAT file

This version of Stella supports sound using a Sound Blaster card.  For
it to work correctly you should set the BLASTER environment variable in
your AUTOEXEC.BAT file.  If your card is at port 220, irq 5, and DMA 1 
then you shouldn't need to set the variable.

2.3 Power Mac Binary Distribution
---------------------------------

This distribution contains the binaries for Power Macs.  To install
the distribution do the following:

  1) Decode the .hqx file (if it hasn't already been done)

  2) Double-click the .sea file and extract the contents somewhere on
     your hard disk

The Power Macintosh version of Stella should work with most joysticks that
emulate the keyboard (i.e., most of them).  No configuration files are
provided, however.

2.4 Windows 95 & NT Binary Distribution
---------------------------------------

This distribution contains the binaries for Windows 95 & NT.  To install
the distribution do the following:

  1) Unzip the distribution stella-0.6-win32.zip

  2) Execute the setup.exe program

  3) Follow the on screen instructions to install Stella

The Windows version of Stella includes joystick support, however, it does
not support paddles.

2.5 Unix Source Code Distribution
---------------------------------

This distribution contains the source code for Stella.  It can be compiled
under most Unix operating systems and MS-DOS.  The Unix code has been
developed with GCC 2.7.2, however, it should compile with other C++ 
compilers.  You'll need SVGALIB 1.2.10 to compile the SVGALIB version of
Stella.  The MS-DOS port has been developed with DJGPP, however, it 
may compile with others.

  1) Change directories to the .../stella-0.6/src directory

  2) Edit the makefile to meet your needs

  3) Type 'make' and follow the on screen instructions to build Stella

  4) Install Stella in a directory that's in your path

  5) Change directories to the .../stella-0.6/src/sound directory

  6) Type 'make' and follow the on screen instructions to build stella-sound

  7) Install stella-sound in a directory that's in your path

At this time there is no support for sound under Unix except for Linux. If
you have some free time please try to port the stella-sound program to your
favorite Unix.


3.0 ROM Images and Property Files
=================================

Games for the Atari 2600, like many game systems, were stored on 
cartridges.  These cartridges usually contained a single ROM chip 
(Read Only Memory) which had the program for the game stored on it.  
When you plugged the cartridge into the 2600 it allowed the 2600's
microprocessor, a 6507 which is very similar to a 6502, to execute
the program on the cartridge.

Just like a cartridge had to be plugged into the 2600 you must also
supply Stella with a copy of the cartridge you want to play.  This
is done by having a ROM image (.BIN file) of the cartridge.  ROM 
images are files which contain the actual data off the cartridge
(so it basically contains 6507 machine code).  There are several 
ways to get a ROM image:

  1) It's possible to build a device that plugs into the printer port
     of a PC and reads the data off the cartridge (See the Stella home 
     page for more information)

  2) Purchase any of the Activision Atari 2600 Action Packs and use the
     ROM images (.BIN files) from it

  3) Search around the net and find some ROM images (.BIN files) to download

WARNING: It is illegal to have ROM images of games that you do not
         actually own (i.e. you don't own the cartridge and you 
         didn't buy it from Activision)

In addition to the ROM image you may also need a property file (.VCS file)
for the game.  A property file informs Stella of the "best" settings for
a game.  Without a property file Stella tries to guess the settings for
the game and uses defaults for settings it can't guess.  For some games
you will not need a property file, however, for best results always use
a property file if it's available.  

Each Stella distribution contains a set of property files in the 'vcs'
directory.  An effort is underway to create an archive of property files.
This archive is located at ftp://2600.cow.net/2600 and maintained by
Jason Scott.  If you have any questions or contributions send them
to 2600@cow.net.


4.0 Installing ROMS Images
==========================

If you plan on using Stella with property files (.VCS files) you have
to install your ROM images (.BIN files) in a directory that's searched
by Stella.  Otherwise, you'll be unabled to play the game.  Stella 
searches for the ROM image, specified in the property file, as follows:

  1) in the directory where the property file is located

  2) in the 'ROMS' subdirectory of the directory where the property file 
     is located

  3) in the '2600' subdirectory of the directory where the property file
     is located

  4) in the 'ROMS' sibiling directory of the directory where the property
     file is located

  5) in the '2600' sibiling directory of the directory where the property 
     file is located

So the best thing to do is to create two directories.  One called 'VCS' 
and one called 'ROMS'.  Place all of your ROM images (.BIN files) in the 
'ROMS' directory and place all of your property files (.VCS files) in 
the 'VCS' directory.


5.0 Playing a Game
==================

Once you've installed Stella and have your ROM images in the correct
place you can play a game by following the directions for your system.

5.1 Unix and MS-DOS
-------------------

The Unix and MS-DOS versions of Stella expect you to pass the name
of the property file or ROM image as a command line argument.  For
example:

  stella filename.vcs (xstella filename.vcs for the X windows version)
  stella FILENAME.BIN (xstella FILENAME.BIN for the X windows version)

5.2 Windows 95 & NT
-------------------

After double-clicking on stella.exe a standard file dialog appears which
allows you to select the property file or ROM image to load.

5.3 Power Macs
--------------

After double-clicking on Stella a standard file dialog appears which
asks you to choose a property file or ROM image to load.  Or, if a property
file or ROM image has the proper creator type ('StLa'), you can simply
double-click that file to run the game directly.


6.0 Keyboard Layout
===================

The following keys are used:

  [q]             Quit (Unix, MS-DOS and Power Mac)

  [s]             Select Game
  [r]             Game Reset
  [c]             Color television
  [b]             Black and white television

  [1]             Left player difficulty B
  [2]             Left player difficulty A
  [3]             Right player difficulty B
  [4]             Right player difficulty A

  [Up Arrow]      Left joystick up
  [Down Arrow]    Left joystick down
  [Left Arrow]    Left joystick left
  [Right Arrow]   Left joystick right
  [Space]         Left joystick fire button 
  [Enter]         Left joystick fire button

  [y]             Right joystick up
  [h]             Right joystick down
  [g]             Right joystick left
  [l]             Right joystick right
  [z]             Right joystick fire button

  [=]             Change window size (X windows)


7.0 Mailing List
================

There is a mailing list for Stella.  The mailing list is for discussions
concerning Stella including bug reports, enhancements reports, and
general usage tips.  Anyone who uses Stella regularly should subscribe
to the mailing list.

To subscribe to the list send the following message to majordomo@csc.ncsu.edu:

  subscribe stella
  end

Once you've subscribed you can send messages to everyone on the list
by mailing them to stella@csc.ncsu.edu.  Anything you mail to 
stella@csc.ncsu.edu goes to everyone on the mailing list.  

Make sure you really mean to send your message to stella@csc.ncsu.edu and
not majordomo@csc.ncsu.edu (i.e. if it's a mailing list server command it
should be sent to majordomo@csc.ncsu.edu not stella@csc.ncsu.edu).

For more information on using the majordomo mailing list server send the
following message to majordomo@csc.ncsu.edu:

  help
  end


8.0 Known problems with Cartridges
==================================

This section contains information about problems I know about 
with some cartridges:

  * Defender II     - This cartridge is really an F8SC cartridge, 8K with
                      128 bytes of RAM, not an F6SC cartridge.  There is
                      a 16K image of this cartridge floating around that
                      has the right code in it, however, it's the second
                      8K that's needed.  If you're running Unix you can 
                      fix it with the command: 

                        tail --bytes=8192 DEFENDR2.BIN > tmp
                        mv tmp DEFENDR2.BIN

                      If you're running MS-DOS you can fix it by
                      typing what's in <>s below:

                        <DEBUG DEFENDR2.BIN>
                        -<RCX>
                        CX 4000
                        : <2000>
                        -<W2100>
                        Writing 02000 bytes
                        -<Q>

                      (provided by plord@mail.pacificnet.net)
  
  * Stargate        - Same as Defender II above


9.0 Stella Property Files (.vcs files)
======================================

A property file informs Stella of the "best" settings for a game.  A 
property file is just an ASCII text file that has the form:

  Stella96

  ## Set cartridge properties (this is a comment)
  Cartridge.Name = Demon Attack
  Cartridge.Image = DEMONATK.BIN
  Cartridge.Type = 4K

  etc..

Every line except the very first one, which must be "Stella96", is
either a comment, a blank line, or has the form:

  Property = Value

The valid properties and values are listed below:

  Cartridge.Name          Full name of the game

  Cartridge.Image         Filename of the game's ROM image

  Cartridge.Type          Bankswitching method for the cartridge:

                            2K   for 2K cartridges
                            4K   for 4K cartridges
                            E0   for 8K parker bother cartridges
                            E7   for 16K M-Network cartridges
                            F4SC for 32K cartridges that have 128 bytes of RAM
                            F6   for most 16K cartridges
                            F6SC for 16K cartridges that have 128 bytes of RAM
                            F8   for most 8K cartridges
                            F8SC for Defender II or Stargate
                            FASC for 12K CBS RAM+ cartridges
 
                          For more information on the correct value to use
                          see the bankswitching document on the Stella homepage                          
  Display.FrameRate       How many frames should be display per second:
                          10, 15, 20, 30, or 60 (Some games will not
                          work unless this is set to 60)

  Display.YStart          Scanline to start displaying at:
                          0 < YStart < 100

  Display.Height          Number of scanlines to display:
                          0 < Height < 220

  Display.XStart          Pixel to start displaying a scanline at:
                          0 < XStart < 80, XStart mod 4 = 0

  Display.Width           Number of pixels to display on a scanline:
                          0 < Width < 160, Width mod 4 = 0

  Console.LeftDifficulty  Default value for left difficulty: A or B

  Console.RightDifficulty Default value for right difficulty: A or B

  Console.TelevisionType  Default television type: Color or Mono

  Controller.Paddle0      Physical paddle to use: 0, 1, 2, 3, or None
                          (Only 0 or None is really usable at this point)

  Controller.Paddle1      Physical paddle to use: 0, 1, 2, 3, or None

  Controller.Paddle2      Physical paddle to use: 0, 1, 2, 3, or None

  Controller.Paddle3      Physical paddle to use: 0, 1, 2, 3, or None

  Controller.Joystick0    Physical joystick to use: 0, 1, or None

  Controller.Joystick1    Physical joystick to use: 0, 1, or None

  Timer.Adjustment        Adjustment value for the PIA timer.  This
                          can be used to fix the screen from jittering
                          on some game: 0 < Adjustment < 64  

                          Hopefully, the PIA emulation will be improved
                          and this will not be needed.


10.0 Property Autodetection
===========================

If you tell Stella to open a ROM image (.BIN file) instead of a
property file (.VCS file) it tries to guess the properties for the
game.  The guessing works as follows:

  1) Uses the following default values:

     Display.FrameRate = 60
     Display.YStart    = 38
     Display.Height    = 210
     Display.XStart    = 0
     Display.Width     = 160

     Console.LeftDifficulty  = B 
     Console.RightDifficulty = B
     Console.TelevisionType  = Color

     Controller.Paddle0 = None
     Controller.Paddle1 = None
     Controller.Paddle2 = None
     Controller.Paddle3 = None

     Controller.Joystick0 = 0
     Controller.Joystick1 = 1

     Timer.Adjustment = 0

  2) Determines Cartridge.Type as follows:

     a) If the name of the file matches any of the known 8K Parker Brother
        games then set the type to E0

     b) Use the "real" size of the ROM image to set the type to either
        2K, 4K, F8, F6 or F6SC

        NOTE: The type is set to F6SC if the size is 16K and the first
              256 bytes are all the same value
       
You can see that the guessing isn't all that smart and we can hopefully 
make it better in later releases.  You should also noticed that it doesn't
guess if the cartridge uses joysticks or paddles (it assumes joysticks).


11.0 Acknowledgements
=====================

The following people have had a part in bringing Stella to you:

  Bob Colbert       - Allowed "Okie Dokie" to be included in the Stella
                      distribution (rcolbert@novia.net)

  Ron Fries         - Author of the TiaSound library

  Aaron Giles       - Maintained the Power Mac version

  Mark R. Hahn      - Allowed "Elk Attack" to be included in the Stella
                      distribution

  Kevin Horton      - Author of the 2600 bankswitching methods paper 

  Daniel Marks      - Provided code to improve the keyboard joystick support

  Jeff Miller       - Maintained the Windows version

  Bradford Mott     - Maintained the core code, Linux SVGA version and X version

  Jason Scott       - Organizer of the property file archive

  Raul Silva        - Helped with the the design and graphics on the home page 

  Darrell Spice Jr. - Maintained the OS/2 version

  Keith Wilkins     - Maintained the MS-DOS version

  Jeff Wisnia       - Provided technical data sheet for the 6532

Thanks to all the 2600 fans who've kept encouraging us to continue.


12.0 Revision History
=====================

The following is a list of changes to Stella:

  0.5 to 0.6: (January 18,1996)

    * Fixed collision detection problem (Freeway works)

    * Changed PIA timing code to fix screen jitters

    * Added new bank switching methods: F4SC (Fatal Run), E7 (Burgertime)

    * Fixed some code in the TIA emulation that caused SEGFAULTS

    * Improved frame rate throttling code to work better on fast machines

    * Improved TIA emulation (missle graphics are fully emulated now)

    * Included Bob Colbert's "Okie Dokie" game

    * Uses version 1.1 of the TIA Sound library by Ron Fries

  0.4 to 0.5: (November 17, 1996)

    * Added sound support

    * Added new bank switching methods: F8SC (Defender II), FASC (CBS RAM+)

    * Changed TIA so peeking $E and $F return $F not $0 for Haunted House

    * Changed PIA timing code to fix screen jitters in Frogger

    * Addressing scheme rewritten

    * Optimized 6507 memory accesses

    * Randomized memory in PIA upon startup

    * Removed auto-disabling of objects at the start of a frame 
      so you can't walk through walls in Adventure

    * Changed the X windows terminal update method to make it faster and
      easier to understand

  0.3 to 0.4 (August 28, 1996):

    * TIA code has been optimized some

    * Some games can be played with just a ROM image

    * New search method for ROM images (no more STELLA_PATH)

    * Delta screen update supported

    * Better error handling added to the "core"

  0.2 to 0.3 (July 12, 1996):
  
    * Keyboard joystick support is much better (Daniel Marks)

    * Paddles are now supported via the mouse (Bradford Mott)

    * Many portability issues have been resolved (Keith Wilkins)

    * Fixed a problem with the 6507 ADC and SBC instructions that caused
      some games (Enduro) not to work correctly (Bradford Mott)

    * Power Macintosh port (Aaron Giles)

    * Windows 95 & NT port (Jeff Miller)

