                      ASH - AStrowar Help program
                      ---------------------------

Introduction

ASH is a simple turn viewer for AstroWar.  It is designed to be used
with the text messages generated and accepted by AstroMail, the netmail
Interface to AstroWar.

IMPORTANT DISCLAIMER

PLEASE NOTE: ASH is NOT release-quality software.  It's purely a bodge
set up so that I could play my own games easily.  It has been released
to others so that they can gain benefit from it as well.  However, it
is not "supported" software.  Once it is released, no more work will
be done on it.

If it fails to work, wipes your AstroWar game files, causes the rise
and fall of your empire, formats your hard disk, demolishes your house
or destroys civilisation as we know it, I am not responsible.  Run ASH
at your own risk.

Installing

IMPORTANT: This is one of those programs which requires ANSI.SYS.
Why?  I've written it in ANSI standard C, which has no screen
formatting, in order that it can be easily ported.  For screen control
I've used a subset of ANSI screen codes, which should be suitable for
use on most ANSI or VT100-compatible terminals.  It may even work with
VT52, but I've never used a VT52 so I don't know for sure.

Make a directory for ASH and copy the distribution files into it.  Then
make a directory for each game you want to play using ASH.  Next,
copy into each directory the 'detail.data' file for that game.  This
should be available from the sysop running the game if you don't have it
already.

Finally, create a file in each game's directory called 'ash.data'
(MS-DOS will truncate and capitalise this; don't worry).  The contents
of this file are as follows:

        empire=Yourempirename
        planet=Yourhomeworld

Capitalisation is important here.  NOTE: ASH is confused by punctuation
in an empire name.  If your empire has punctuation in it, include only
the name BEFORE the punctuation mark.  Once you have prepared the
directory, you are ready to transfer your game to ASH. There are two
methods, described in the next section.

IMPORTANT: If you are hosting games, do not use the game host
directories for your games.  ASH uses the files 'planet.data' etc. to
store details of planets as you see them.  You don't want this to
overwrite the 'real' game data now, do you?  Note also that ASH is
unsuitable for use as a game viewer for hosts.

Starting to Play using ASH-- method one

This method requires that you have kept all the old messages AstroWar
sent you.  Export all these messages from your message editor into a
single text file called 'report-file'.  Don't worry about formatting,
but make sure that you only include the messages from that one game.

Run ASH with the directory the game files are in as a parameter.  NOTE:
you need to put a trailing slash or backslash on the directory name.
If everything has been done correctly, after a pause and a few
semi-informative messages, you should get a full screen display of your
homeworld.  This information is not wholly accurate; don't worry about
this.  Just type 'exit' at the ASH command prompt.

Now, export just the last message to the file 'report-file'. Run ASH
again, with the directory name as a parameter.  This time, the
information on your screen should be as accurate that which you could
put together yourself.  You are now ready to start using the more
advanced features of ASH.

Starting to Play using ASH-- method two

This second method requires that you take today's turn as normal, by
whatever method you currently use.  In addition to all your normal
orders, do the following: (1) issue a 'map' order for every planet you
own, and (2) scout every 'enemy' planet you know of.  You don't have to
scout planets you're not interested in, such as those of allies for
instance.

When you receive the report for this turn, you should have an extensive
set of maps, and in the following turns you should receive comprehensive
intelligence from the planets you have scouted.  It is important to
ensure that you continually scout active enemy planets if you are going
to rely on the data which ASH presents to you.  Simple forecasting from
previous turns' data is obviously not good enough to keep track of enemy
fleet movements.

Copy the report you receive (or rename it) as 'report-file', and run ASH
with the name of the game directory as a parameter (including trailing
slash or backslash).  After some messages and pauses, you will find
yourself at the ASH command line, and the program is ready for use.

A Note about 'report-file'

ASH takes the existence of 'report-file' to signal the start of a new
turn.  Planets are updated with the values of last turn's forecasts (if
any) before the report is read in, so that enemy planets which haven't
been scouted have some approximation of their real data.  Fleets are
also moved, and if they are due to arrive this turn, deleted from the
fleet file; the planet details will already have taken these arrivals
into account.

After 'report-file' has been read, it is deleted.  Since 'report-file'
signifies a new turn, it is important not to confuse ASH by providing it
with a 'report-file' more than once per turn.  Confusing ASH in this way
causes 'phantom' differences in expected and actual planetary detail,
and can cause incorrect reporting of enemy planet details.

Viewing your Planets

When you start ASH you are viewing your homeworld.  The screen is
arranged as follows:

        ========================================================
                  [1]
        +----------------------+               [4]
        |                      |
        |                      |
        |                      | -------------------------------
        |         [2]          |
        |                      |               [5]
        |                      |
        |                      |
        +----------------------+ -------------------------------

                   [3]                          [6]

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

[1] is the ASH command line 'window'.  All commands are typed into this
small space.

[2] is the map window.  This contains a map of planets centred upon the
planet you're currently viewing.

[3] is the 'obvious' planetary data, i.e. that which is directly given
in planet lists, scout intelligence and 'attack failed' reports.

[4] is the planet list, which includes just the planets shown in the map
window [2].

[5] is the fleet list, showing just those fleets which are approaching
the planet you're currently viewing.

[6] is the forecast 'window'.  These forecasts are based on the
production of the planet you're viewing, any fleets which are
approaching, and (for your planet) ships which you are sending
elsewhere.  More on forecasts later.

Some Commands for Viewing

'view': the 'view' command allows you to view another planet for which
you have data.  It can be a planet of yours, or a neutral or enemy
planet.  The format is simply 'view Planetname'.

'more planets': Where there are more than eight planets on the visible
map, only eight are displayed at a time.  'more planets' is like a 'page
down' key for the planets window, and shows the next eight planets.

'first planets': After looking down the planet list, you can use 'first
planets' to return to the top of the planet list.

'more fleets': When there are more than eight fleets approaching the
currently viewed planet, 'more fleets' allows you to display the next
eight approaching fleets.

'first fleets': After using 'more fleets' to page down the approaching
fleet list, 'first fleets' returns you to the top of the fleet list.

'exit': quits from ASH.  After a brief pause, you are returned to the
DOS (or whatever) command line.

All of these commands can be abbreviated to their smallest unambiguous
form.  So 'view' can be entered as 'v', and 'more fleets' can be entered
as 'mo f' (see more commands later), for instance.

More about some of the Windows

The data in the planets window is the planet name, its position on the
map, its distance from the planet being viewed and the number of ships
currently in orbit.  You can use this to correctly identify the full
names of planets in the map window.  In the map window the planets are
just identified by the first two letters of their name, which can often
be ambiguous.

The 'approaching fleets' window contains the fleet number, planet of
origin, number of ships (followed by 's') and the distance left to
travel (followed by '+') of each fleet which is destined for the planet
being viewed.

The 'forecasts' window is the most interesting, and each line has a
slightly different meaning.  The 'this turn' line contains, on the far
right, last turn's forecast for the planet for this turn.  To the left
of this is the difference between the forecast, and the number of
planets actually in orbit; this figure is followed by a '-' if the
number of ships in orbit is less than expected, or a '+' if it is more.
The 'difference' figure can be used to ascertain enemy fleet movements,
or it can act as a reminder of unsuccessful attacks on your own planets.
A '*' to the right of the forecast means that the planet should have
been yours this turn.

The next three lines are the forecasts for this planet over the next
three turns.  They take into account approaching fleets, and the 'Next
turn' line also takes into account ships you are sending away from this
planet next turn (see later).  Scouts approaching enemy or neutral
planets are not counted as arrivals, as once they reach this planet they
will return to their planet of origin.  The first column contains the
numbers of ships arriving on each turn.  The middle column contains
ships being sent out next turn, and the last column contains the number
of ships expected to be in orbit on that turn.  A '*' after that last
figure means that the planet is expected to be yours that turn.

The 'Long Term' forecasts cover fleet arrivals 4 or more turns into the
future.  The ship arrival figure will be accurate, but the ships in
orbit will only take into account the production in 4 turns, whereas
some of the ships may be arriving 5 or more turns in the future.  This
'long term' figure is mainly of use where you have a target figure for
ships orbiting the planet; it tells you when you already have enough
ships approaching the planet to reach that target figure (eventually).

Writing Orders using ASH

ASH allows you to write two sorts of orders-- 'send' orders and 'map'
orders.  In order to send ships from one planet to another, first you
must view the planet using 'view'.  Once viewing the planet, type the
following command:

        send <ships> <dest>

where <ships> is the number of ships (1 for scout missions) and <dest>
is the destination planet.  When sending to planets with stupid long
names, you might want to use the 'more planets' command, if necessary,
to get the destination planet's full name in view.

When you enter a send order, there will be a slight pause as the
forecasts are updated.  Remember that you can include in your fleet any
ships arriving next turn, as well as ships already in orbit.  You can
even launch ships from planets you don't yet own, if you are reasonably
sure you will take the planet next turn.  The forecasts help you in both
of these instances.

In addition to launching scouting missions with 'send 1 <planet>', you
can also use the shorthand 'scout <planet>'.  This has a special
advantage that you can substitute an asterisk (*) for the planet name;
'scout *' scouts all known enemy/neutral/unscouted planets on the map.
Scouting this way is hardly ideal though, as the scouts will take a
quite while to reach the most distant planets, which would be better
scouted from a nearer friendly planet.

When you invade a planet you usually want to get a map of the planets
which surround it.  When viewing any planet, you can use the 'map'
command, which takes no parameters, to request a map.  Obviously
AstroWar will only honour map requests for planets which you own by the
time the order is processed.

Note that ASH automatically requests a planet and fleet list each time
you process a turn.

Orders are first saved to a binary 'orders.data' file, which is used to
calculate ship quantities in forecasting.  However, when you quit the
program, these orders are converted to text.  Next turn (i.e. when ASH
finds a new 'report-file'), the existing orders from this turn will be
used in forecasting, so don't delete the 'orders.data' between turns.
The text file, 'orders-file', is overwritten with the contents of
'orders.data' each time you exit gracefully from ASH.
