**************************************************************
    **                                                          **
    **   PPPPP   ll                 TTTTTTTT                    **
    **   PP  PP  ll                    TT                       **
    **   PPPPP   ll    aaaaa  nn nnn   TT   oooo   ww      ww   **
    **   PP      ll   aa  aa   nn  nn  TT  oo  oo  ww  ww  ww   **
    **   PP      ll   aa  aa   nn  nn  TT  oo  oo   ww ww ww    **
    **   PP       lll  aaa aa  nn  nn  TT   oooo     ww  ww     **
    **                                                          **
    **************************************************************


PlanTow         by Michael Herrmann
~~~~~~~
- is a tool for VGA Planets ((c) Tim Wisseman). If you don't know what
  that is, you don't need this program :-) .
- features a new tow model that is supposed to be more satisfactory than
  existing tow models.
- will cooperate with both TimHost and PHost.
- was created after the release of PHost 3, the new tow model of which
  heavily handicaps cloaker races and destroys the equilibrium of the
  races. The new PHost tow model was considered unusable; the alternative,
  TimHost-compatible model was okay, but somewhat unsatisfactory because
  of its heavy reliance on IDs and waypoints. The old PHost 2 model was
  also okay, but no longer available. So I wrote this program in order to
  get a simple and fair tow model that sums up the advantages of the other
  existing (or no longer existing) models.

What you should really know
~~~~~~~~~~~~~~~~~~~~~~~~~~~
You should really know that you should read or at least scan this manual at
least once :-) . But for those who really have to start quickly, here is a
short summary.

Installation: PlanTow feels comfortable in your main planets directory. In
that case call PlanTow with your match directory as a command line parameter.
This is a way of making sure that PlanTow finds the necessary files
(ship.hst and hullspec.dat). For alternatives, call 'PlanTow ?' or RTFM.
Run PlanTow immediately before the movement phase or in AuxHost1.Ini.

Features: In simple words, a simple tow will always succeed. A ship that is
being towed successfully, cannot tow another ship. In a conflict situation,
the stronger ship wins. Strength depends on tech level, number of engines,
warp speed, GravAx and travel distance. If you want to know more, RTFM :-) .

Moreover: PlanTow supports program exit codes and writes a PlanTow.Log file.

Warranties: Ths usual stuff. Anyway, by using this program you confirm that
you agree with the warranties section of this manual.

Contents
~~~~~~~~
1.  How it works
2.  Who's towing who?
3.  Where to put it, command line parameters
4.  How to use PlanTow
5.  The file PlanTow.Log
6.  Exit codes and run-time errors
7.  No warranties
8.  History
9.  Known problems
10. Please hand on
11. Contact

1. How it works
~~~~~~~~~~~~~~~
PlanTow does not replace the tow or the movement phase of the host program.
It is supposed to run before that phase. In order to force the host program
to behave as PlanTow wants, PlanTow switches off the Tow mission of a tower
if the ship is not supposed to tow. If a ship is supposed to be towed,
PlanTow reduces its warp speed or cuts the waypoint (whatever is needed
for your preferred host program).

2. Who's towing who?
~~~~~~~~~~~~~~~~~~~~
The basic understanding of a tow beam in PlanTow is that a tow beam disables
its target's engines and tow beam (and maybe more). Consequently, any simple
tow (by which I mean ship A towing ship B, and no other ships interfering)
will always succeed. This closely matches Host and PHost 2 behavior because
in those programs a simple tow can always be made work by setting the tower's
warp speed to 9. (In TimHost, the tow target can actually escape by setting
a large waypoint, but you don't really like to set long waypoints because
you don't want to tell your opponent which planet you came from, right?)
In PHost 3, the number of engines plays an important role, e.g. a (fully
equipped and fast-moving) STF cannot be towed e.g. with a Resolute or Dark
Wing, and a Merlin, Golem or Rush cannot even be towed with a MCBR. I
wouldn't want to play any cloaker race (let alone Privateer) under these
circumstances.

Exceptions to the basic rule are ships without fuel, which cannot tow
because the tow beam doesn't get energy, and cloaking tow targets, in
which case the captain of the tower can't know where to direct the tow
beam. This also matches Host and PHost behavior. A self-tow is not possible
in PlanTow, because a Tow beam is straight and cannot be directed to one's
own ship.

You may want to know what happens in conflict situations as a mutual tow
or a multipe tow. Before I come to that, let me explain three structures.
Or, if you are not really interested in the details, you can skip the rest
of this section.

A tow chain is a structure as A tows B tows C tows D ...

A tow node is a structure as B tows A, C tows A, D tows A ...
One ship is tow targeted by several would-be towers. This is also called
a 'multiple tow' (e.g. by PHost). Tow chains can end in a tow node, and
one tow chain may come out of it.

A tow ring is a structure as A tows B tows C tows ... tows A.
Chains can end in a ring but never origin from a ring. A ring of length one
is a 'self-tow', a ring of length two is a 'mutual tow'.

PlanTow deals with these structures by breaking them down into simple tows
(or 'tow pairs') starting with the chains from top to bottom. For a
chain A tows B tows C tows D ..., A will tow B. Since B's tow beam is
then disabled, C is free to move and can tow D, etc. A ship will never
tow two ships at the same time (compatible with TimHost and PHost).

After all chains are broken down as far as possible, only nodes and rings
remain. For a node (or multiple tow), the strongest ship wins. This
agrees with PHost, but not with TimHost (in which case the ship with the
lower ID wins).

To determine the tow strength, the new PHost 3 formula is used with one change:
Strength = (Enging_TL^2 * (No_of_engines + GravAx) * Speed * 163) + Distance.
GravAx equals the maximum number of engines for any ship found in the
Hullspec.dat for a ship with gravitonic accelerators, or 0 for all other
ships. This makes sure that a Transwarp GravAx ship will win a tow competition
agains any other ship. The ships with the IDs 44, 45, 46 are considered
GravAx ships. Distance is the distance that the ship can travel in one turn.
In case two ships have equal tow strength, the lower ID ship wins (in
agreement with PHost 3).

In a tow ring, the strongest ship will win, too. The ring is thus broken up
into a chain and treated correspondingly.

The shortest ring is a ring of length one, i.e. a ship towing itself. Since
the ship is the strongest of the ring :-) , the tow (from itself) is broken,
and the ship can move.

The next shortest ring is a ring of length two. This means that two ships
are trying to tow each other. As in the more general case, the strongest
ship will win this tow. This agrees with PHost 3, but does not agree with
PHost 2 (in which case both ships won't move) or with TimHost (in which
case the ship with the lower ID wins).

As a last complex case consider the following situation: A tows B tows C
tows B. B and C form a tow ring with which A interferes. The situation is
handeled as follows. While the tow beams of B and C struggle with each other,
A's tow beam operates. This shuts down B's tow beam, so that C's tow beam
can also work. Thus B will be towed by the stronger ship of A and C.

3. Where to put it, command line parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PlanTow can be operated from any directory. However, it needs to find the
match files, more specific the ship.hst and the hullspec.dat. The ship.hst
is always found in the match directory, and the hullspec.dat usually resides
in the main planets directory (in the following called 'game directory'). You
can tell PlanTow about these two directories using command line parameters:

Usage: PlanTow [/no1] [/tcs] [/bfX] [[game_directory] match_directory]');

A '?' in any of the command line parameters will call the info function and
abort the program.

If the game directory is not supplied, it is supposed to be the parent
directory of the match directory. If the match directory is not supplied,
it is supposed to be the current directory. All files (i.e. also the
hullspec.dat) are first searched for in the match directory. If not found
there, they will be searched for in the game directory and, finally, also
in the current directory.

Examples:

1. To make things easy, you would probably install PlanTow in your game
directory and call 'PlanTow <match_directory>' which will work even if
the match directory is not a subdirectory of the (current) game directory.

2. If your match directories are subdirectories of your game directory, you
can go to your match directory and from there call PlanTow without
command line parameters.

The parameter '/no1' (or '-no1' or '/NO1' etc.) switches OneEngineTow off.
(If your game or match directory happens to be called '-no1', write './-no1'
if you mean your directory.) OneEngineTow must be switched on both in PlanTow
and Host in order to work! If it is switched on in one of them and off in the
other, the result will be strange. PlanTow does *not* read the PConfig.src!

With '/tcs' (or '-TCS' or '/TcS' etc.) set, ships are allowed to tow cloaked
ships even if they belong to a different race. When '/tcs' is not set,
players can only tow their own cloaked ships. TimHost uses '/tcs' set, the
default for PHost is '/tcs' not set. Please note that PlanTow does not read
the PHost alliance status. Thus, if '/tcs' is not set, you can't tow your
ally's cloaked ships even if the ship level of alliance is set.

The parameter '/bfX' (or '-bfX' or '/BFX' etc.) with X = 0 .. 6 determines
what PlanTow does with ships that are supposed to be towed. The default is
X = 0. PlanTow then sets the warp speed of the ship to zero and also cancels
the waypoint. This means that a towed ship can never break free from a tow
if the tower runs out of fuel or is hit by a mine. If you want your ships
to break free in such an incident, you have to set X = 1 .. 5 depending on
your host program. If you don't want ships to break free, the default is
the safest choice.

X = 1 .. 3 are for use with TimHost or the TimHost compatible mode of
PHost 3. X = 1 will cut the waypoint to a distance the towed ship can
travel within one turn. X = 2 will reduce the warp speed to less that
the towing ship's speed. Each of those should be sufficient to enable
breaking free. If you want to make sure, use X = 3 which does both.

X = 4 limits the towed ship's warp speed to the towing ship's warp speed.
This is for PHost 2. Note that X = 4 differs a little from X = 2 also in
respect to GravAx ships. X = 5 is for PHost 3.

X = 6 does nothing whatsoever to the speed or waypoint of the towed ship
and leaves the action to the host program. Be warned that the result of this
may be inconsistent. For instance, if ship A is set to tow B and B is set
to tow C with no other ships interfering, PlanTow will disable the tow from
B to C. But with X = 6 the host program may decide that A is not allowed
to tow B. Now B should tow C, but it can't because PlanTow already disabled
it. I don't recommend using X = 6. But if you still think, it makes sense
for your case, feel free to use it - eh, and please drop me a note :-) .

4. How to use PlanTow
~~~~~~~~~~~~~~~~~~~~~
The most suitable time to run PlanTow is immediately before the movement
phase of your host program (i.e. PHost 3). If you can't do that, you can
also run it from AuxHost1.Ini or before phase 2 of PHost 2.x.

5. The file PlanTow.Log
~~~~~~~~~~~~~~~~~~~~~~~
PlanTow writes all its actions to the screen and also to a file called
'PlanTow.Log' which is located in the match directory. If an old file with
this name exists, it will be overwritten.

6. Exit codes and runtime errors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On successful execution, PlanTow quits with exit code 0. Command line
errors (esp. also any '?' in the command line) call the info function and
cause exit code 255 (or -1). Exit codes from 10 through 19 indicate a file
read or write error. Exit codes from 20 to 29 mean that the program
encountered a situation which it could not handle (which actually should
never happen). In case of an error, the program beeps and waits for any
key to be pressed. When a key is pressed or if no key is pressed after
30 seconds (or maybe less), the program exits.

7. No warranties
~~~~~~~~~~~~~~~~
I wrote this program very carefully and tested it thoroughly. However, to
err is human, and you know that no useful program is really free of bugs of
every kind. By using this program you accept that the risk is completely on
your side and that I cannot be made responsible for problems of any kind
including (but not limited to) loss of data, hardware destruction etc.
(By the way, you *do* make backups of your planets matches, don't you?)

8. History
~~~~~~~~~~
PlanTow 1.1:
- Bug corrected: GravAx ships had been treated as in PHost 3.
- Bug corrected: Multiple tows had not been resolved correctly.

PlanTow 1.0:
- first public release

9. Known problems
~~~~~~~~~~~~~~~~~
- PlanTow doesn't check the PHost alliance status. Thus a player can't
  tow an ally's cloaked ships unless the command line parameter '/tcs'
  is set which enables towing all cloaked ships. In addition, for
  determining if a ship is cloaked or not, its mission is checked.
  Although this seems to be a proper indicator of a valid cloak status,
  I am not completely sure. If you run into a problem (and esp. if you
  know a way out of it :-) ) please write me a mail.

10. Please hand on
~~~~~~~~~~~~~~~~~~
PlanTow is Freeware. Please feel free to give it to anyone else and/or
upload it to mailboxes or servers if
- you distribute it free of charge (and only free of charge) and
- you distribute it together with this documentation.
You are not allowed to make any changes to the program or the documentation.

11. Contact
~~~~~~~~~~~
For questions, comments, bug reports etc. please contact
Michael_Herrmann@m2.maus.de  or  herrmann@crl.go.jp. If both doesn't work,
someone in the newsgroup maus.spiele.planets probably knows how to find me.