------------------------------------------------------------------------
                      VCSMAKER.EXE  -  Version 0.2a
------------------------------------------------------------------------
                              USER'S GUIDE
                     Written by Pixelboy (Luc Miron)
                          pixelboy@lanzen.net
------------------------------------------------------------------------
                    Last modified : Febuary 10th 1997
------------------------------------------------------------------------


1. What is VCSMAKER.EXE?
------------------------
 This program generates VCS files compatible with the Stella emulator.
 The filename required as parameter must be the name of an Atari 2600
 binary ROM file ("BIN file" for short). Since the .BIN extension is
 assumed, you do not have to specify it within the filename parameter.

 If the filename specified is defined in the VCSMAKER.CFG file (which
 must lie in the same directory as VCSMAKER.EXE), the VCS file associated
 with the BIN file is created using the data found in the VCSMAKER.CFG
 file. If there is no such data for the filename specified, the program
 creates a default VCS file, which you can edit to your liking.

 This program was created to enable you to store all your VCS file data
 into a single file (the VCSMAKER.CFG file), so you won't have to put up
 with all those awefully redundant VCS files.

 Note that this program is made available "AS-IS", with no warranties.
 The programmer of this MS-DOS program cannot be held accountable
 for anything wrong that happens as a result of using it.


2. How to use VCSMAKER.EXE
--------------------------
 Go to the directory where VCSMAKER is located,
 and at the DOS prompt, simply type:

     VCSMAKER <name of BIN file>   (and press the RETURN KEY)

 Examples: VCSMAKER ADVNTURE
           VCSMAKER ASTEROID
           VCSMAKER MSPACMAN

 Remember that you can get a quick user's reminder by typing:

     VCSMAKER -h

 And if you want to generate ALL the VCS files defined in the
 VCSMAKER.CFG file (in the current directory), simply type this:

     VCSMAKER -a



3. How to configure the VCSMAKER.CFG file
-----------------------------------------
VCSMAKER.EXE needs the VCSMAKER.CFG file to run properly. This file
contains configuration information for each BIN file. This configuration
information will be used to created a VCS file compatible with the Stella
emulator. In normal circumstances, you'll find a sample VCSMAKER.CFG file
packed with the software, which you can edit using any ASCII editor.

While VCSMAKER.EXE allows for some flexibility in the VCSMAKER.CFG file,
some basic rules must be followed to the letter, or VCSMAKER.EXE will
not decode the configuration information properly:


1) Each configuration parameter you specify in the VCSMAKER.CFG file
   must end with a ";" character, INCLUDING the last parameter of the line.

2) The configuration data for each game MUST be written on two
   consecutive lines of text: On the first line you must specify the
   name of the BIN file INCLUDING the .BIN extension (ex: RAIDERS.BIN),
   followed by the full name of the game (ex: Raiders of the Lost Ark).
   Do NOT put any quotes in the lines. The second line of text must
   contain the remaining parameter values:

     Cartridge Type     : 2K, 4K, E0, E7, F6, F8, FE, F4SC, F6SC, F8SC or FASC
     Display Frame Rate : 10, 15, 20, 30 or 60
     Display Y Start    : any number between 0 and 100
     Display Height     : any number between 0 and 220, in respect to Y Start
     Display X Start    : Numbers between 0 and 80, with (XStart mod 4 = 0)
     Display Width      : Numbers between 0 and 160, with (Width mod 4 = 0)
     Left Difficulty    : A or B
     Right Difficulty   : A or B
     Television Type    : Color or Mono
     Paddle0            : None, 0, 1, 2 or 3
     Paddle1            : None, 0, 1, 2 or 3
     Paddle2            : None, 0, 1, 2 or 3
     Paddle3            : None, 0, 1, 2 or 3
     Joystick0          : None, 0 or 1
     Joystick1          : None, 0 or 1
     Timer Adjustment   : Any number between 0 and 63 (0 = default)

   Here is an example of a configuration definition for Barnstorming:

      BARNSTRM.BIN; Barnstorming;
      4K; 30; 46; 190; 8; 152; B; B; Color; None; None; None; None; 0; None; 0;

   Refer to the Stella documentation for more details about the
   configuration parameters.

3) You can insert comments in the VCSMAKER.CFG file by putting a "#"
   character at the beginning of the lines where the comments are.
   VCSMAKER.EXE will skip those lines.

4) Do not put quotes (") ANYWHERE except in comment lines.

5) You cannot insert comments in between configuration parameters.

6) You can insert blank (empty) lines anywhere you want. They will be skipped.



4. Error messages
-----------------

"You must not specify any kind of path with the filename."

      Like the message says, all you need to mention is the name of the
      BIN file, and nothing else. You don't even have to include the
      .BIN extension when you type the name of the BIN file.


"Error: Unexpected end of line!"

      There's a problem in your VCSMAKER.CFG file: Either there are
      configuration parameters missing, or there is a missing ";" at
      the end of the line where the data is written. Simply correct
      any typo in the VCSMAKER.CFG file, and try again. Remember that
      EACH parameter you write must end with a ";" character, even
      the last one of the line.


"Error: End of VCSMAKER.CFG file reached prematurely!"

      VCSMAKER.EXE reached the end of the VCSMAKER.CFG file before
      it could read all the configuration information. You should
      look the VCSMAKER.CFG file over to detect any errors near the
      end of the file.


"VCSMAKER.CFG was not found in current directory."

      The VCSMAKER.CFG file must always be in the current directory,
      or VCSMAKER.EXE will not be able to find it and read it.


"WARNING: No data found in VCSMAKER.CFG, so default VCS file will be generated.
          Please verify that cartridge Name, Image, and Type are correct."

      VCSMAKER.EXE could not find any configuration information in the
      VCSMAKER.CFG file for the BIN file you specified, so the program
      wrote a default VCS file. It's important that you review the new
      VCS file after it has been created, because some of the configuration
      parameters might not be correct. Refer to the Stella documentation
      for more details about how to customize your VCS files, once they
      have been created by VCSMAKER.EXE.



5. Notes
--------
Each time a new version of the Stella emulator is released, you should
check if the current version of VCSMAKER.EXE that you have is still
100% compatible with it. More precisely, if the emulator has been
changed to process new configuration parameters in the VCS files, then
you should immediately look for a new version of VCSMAKER.EXE that will
match these changes.

Of course, a new version of VCSMAKER.EXE could be released at any time,
before or after the release of a new version of Stella.

This program was made specifically for MS-DOS. It can be compiled on
other platforms, but the distributed source code does NOT support long
.BIN filenames properly if there is more than one dot (.) in the filename.



6. History
----------
0.1 - First release

0.2 - 1) Added support for (Timer.Adjustment) parameter
      2) Added special comment in the generated VCS file, in the
         case that two players take turns, and use the same
         joystick or the same paddle.
      3) All the VCS files can now be generated by running
         VCSMAKER.EXE just once, by specifying the "-a"
         switch instead of a specific BIN filename.

0.2a - Fixed a couple of typos and added notes for the F4SC and E7 modes.
       Also reworked the VCSMAKER.CFG file to match the VCS files given
       with the 0.6 distributions.



Send questions and comments to pixelboy@lanzen.net

