.-+-                                               -+-.
           |=====================================================|
             |                                                 |
             |    V G A S c o r e   A v e r a g e r   1 . 0    |
             |                                                 |
           |=====================================================|
           `-+-                                               -+-'



What ist VGAScAve?
==================

A few weeks ago, we decided to hold a little Planets team tournament
in the MAUS computer net. We chose VGAScore as scoring tool. The matches
were to have a fixed number of turns, but wanted to avoid that a race
would win just because of some action taken for the last turn (e.g. by
Lizard ground-attacking some planets that would be reconquered within
a few turns). So we decided to average the score over several turns.
The result is this score average tool.

VGAScAve does not write its own score. It just reads other score
boards, stores them in a file from turn to turn and outputs a score
average over an eligible number of turns.

VGAScAve can generate team scores even if the basic scoring tool doesn't.


Which score utilities can be used in combination?
=================================================

VGAScAve was written for use with VGAScore 2.2, but it will work
with all score boards it can recognize. This is how VGAScAve recognizes
a score board:

Before the score lines, there must be a line consisting of the string
'TURN XY' in which XY is the turn number (any number of digits).
The 'T' of 'TURN' (or 'Turn') must be the first 'T' in this line.

VGAScAve ignores the next line until it reaches a line starting with ' 1'.
VGAScAve then expects the score lines in the following format:

- first two characters: consecutive numbers
- next two characters: (ignored)
- next 30 characters: race name
- characters 35 to 40: score
- characters 41 to 48: bases
- characters 49 to 56: planets
- characters 57 to 64: capital ships
- characters 65 to 72: freighters

VGAScAve reads up to 11 score lines and ignores the rest of the score board.
 

Team Scoring
============

VGAScAve calculates its own team scores. To identify which race belongs
to which team, it uses a team file TEAMS.VGA as described in the
documentation of VGAScore. It is a text file with one line for each
team. At the beginning of each line, there is a list of the race numbers
separated by spaces. The team name follows.


Installing VGAScAve
===================

Install VGAScAve in any directory on your hard disk, but call VGAScAve
from your Planets main game directory. VGAScAve expects up to two
command line parameters:

- A game path. This can be omitted if your game data are in the main
  Planets directory.
- A number of turns for averaging, from 1 to 100. Obligatory.

The number of turns for averaging is a maximum number. At the beginning,
as long as there is not yet enough information, VGAScAve will sum up over
fewer turns, as many as it can find.

VGAScAve wants a file RACE.NM in the game directory or (if not found there)
in the Planets main directory. VGAScAve expects an input score file called
VGASCORE.BLT (in the game directory). The output is written to VGASCAVE.BLT.
VGAScAve also writes a file called VGASCAVE.SUM in which the score
information of all turns is collected. Selected scores of this file may
be deleted if this is desired out of some strange reason.


Changing Race Names
===================

VGAScAve holds the race names in RACE.NM to be the true race names.
It will not work if a false race name is found in VGASCORE.BLT. It
cannot add up over turns which have a false race name in the score
board. If you change the name of a race, you must also change the
respective race names in the file VGAScAve.SUM. If you don't, VGAScAve
will ignore all older turns.


Errors
======

On using inapropriate command line options, VGAScAve exits with an
error level 1, printing a little help and info screen. On a run time
error, VGAScAve exits with a double beep and a higher error level.
Without an error, VGAScAve exits with error level 0. For automatization,
catch the error code with a batch file.


The usual ***warning***
=======================

VGAScAve might damage your hard- or software, your body, or anything else.
The author of this program cannot be made responsible for any kind of
damage caused by using this program.


Copyright?
==========

You may not change this program, but you may copy it as often as you wish,
and you may give it to other persons free of charge.


Credits
=======

VGA Planets is an off-line computer game by Tim Wisseman.
VGAScore is a scoring utility by Martin Scolaro.


Comments?
=========

Contact: Michael_Herrmann@m2.maus.de