*************************************************************************
   **                                                                     **
   **   MM   MM                    WW        WW                           **
   **   MMM MMM                    WW        WW                           **
   **   MMMMMMM  oooo rr rrr eeee   WW  WW  WW  oooo rr rrr mm mmm mmm    **
   **   MM M MM oo  oo rrr  ee  ee  WW  WW  WW oo  oo rrr    mmm mmm mm   **
   **   MM   MM oo  oo rr   eeee     WWWWWWWW  oo  oo rr     mm  mm  mm   **
   **   MM   MM  oooo  rr    eeeee    WW  WW    oooo  rr     mm  mm  mm   **
   **                                                                     **
   *************************************************************************


MoreWorm        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 :-) .
- can be used for playing with a higher number of wormholes. It can also be
  used for allowing a wormhole travel only when the player has a starbase
  near the end of the wormhole. In addition, it features some additional
  friendly codes for instance "WTB" when a ship should not end up in open
  space after the wormhole travel, but is dragged to the base.
- is supposed to be used with PHost Version 3.x (or higher?) only.

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: MoreWorm can be operated from any directory. It needs the
Match directory as parameter and also a switch that tells the program what
to do. Run
'MoreWorm /s <Dir>' immediately before PHost,
'MoreWorm /b <Dir>' immediately before the PHost movement phase.
'MoreWorm /a <Dir>' immediately after the PHost movement phase.
MoreWorm operates a cummulative log file, MoreWorm.Log. If it is getting
too long, run '/sd' instead of '/s'. If you want to know why, read more
from this doc file :-) .

Moreover: MoreWorm supports program exit codes. On successful operation it
exits with exit code 0.

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

Contents                       Update!
~~~~~~~~
1.  Why MoreWorm?
2.  How it works
3.  Where to put it, command line parameters
4.  The file MoreWorm.Log
5.  Exit codes and run-time errors
6.  No warranties
7.  History
8.  Future plans
9.  Please hand on
10. Contact
11. Wormhole configuration

1. Why MoreWorm?
~~~~~~~~~~~~~~~~
If you play Planets with more than 100 Planets it can take quite a while
until you ships reach the battle front. Those ships want to be supplies
with fuel and thus take your time while you are working on your TRN, but
they are not part of the fun. They are supposed to fight, not to travel.
In addition, ships that travel, occupy ship slots which are released only
when they fight. Ship slots are scarce and that's another reason why ships
should fight and not travel. This is why I strongly argue that Planets
needs some kind of Rapid Transport System. Existing systems did not satisfy
me, so I wrote MoreWorm which is a slight, but efficient extension of the
existing wormhole feature.

My main problem with the usual idea is that they tend to dissolve the
battle front. You can't keep your country free of enemies when they can
come out of a wormhole around every corner - especially when the wormholes
are big, but you do want big and relyable wormholes if they are supposed to
be a transport system for your fleet. So one main goal of MoreWorm was to
make sure that wormholes can be used as a fast transport system in your own
part of the galaxy, but cannot be used in order to get behind the enemy's
battle lines. This is secured by the condition that a wormhole can only be
used if you have one of your own starbases near the wormhole exit point.

Another problem was that after traveling through a wormhole a ship ends up
in open space. This is not a useful place to be for a ship, which means,
it costs time it is supposed to save. And in addition your opponents may
see you - or you may not want to use a wormhole if you think your opponent
may watch your steps. That's why I introduced an additional friendly code
WTB (Worm Travel Base). Ships using this FC will not end up in open space
but at the base near the wormhole exit.

When I started a new game using wormholes with this design, I wanted all
home bases to be close to a wormhole exit so that all players can make
equal use of the feature. So I designed a net of wormholes. This net would
have knots, and from each knot four wormholes would go into each direction,
vertically and horizontally, to the neighboring knots. I soon found out
that in order to distribute the home bases homogeniously over this net,
I needed at least 64 knots, 8 by 8, making each wormhole 250 LJs long.
But PHost supports only 100 wormholes. This is why MoreWorm also extends
the number of wormholes that can be used for the match.

The two features, Wormhole number extension and movement restriction,
are independent from each other. They can be used separately.

2. How it works
~~~~~~~~~~~~~~~
MoreWorm is a program that is supposed to be run in several parts. The
first part is called with command line parameter /s (select). When MoreWorm
is called with this parameter, it first reads in a wormhole file called
'Wormhole.ori'. This is your original wormhole file containing all up to
128 wormholes. Then MoreWorm reads the ship FCs and positions, determines
which wormholes are needed for the current turn and writes those to a file
'Wormhole.txt' which will be used by PHost. PHost reads in this file
directly when it starts. Later changes are not taken into account. That
is why MoreWorm /s must be run before the start of PHost. Unfortunately at
that time the ship information in Ship.Hst is not yet up to date. FC and
waypoints changes can still be in the TRN files. So MoreWorm reads in not
only the Ship.Hst but also all TRN files it can find in the match directory.
Take care that all TRN files are available when you run MoreWorm /s. It may
be best to run MoreWorm immediately before PHost.

From all Wormholes available in Wormhole.Ori, those are chosen to be
represented in Wormhole.txt first, which are needed for wormhole travel.
Next, wormholes supposed to be scanned by Bohemians will be selected and
finally wormholes to be scanned by other ships. If there are too many
wormhole candidates in any of these three groups, MoreWorm starts selecting
at a random Wormhole ID and switches on in ascending order as long as
wormhole slots are available in Wormhole.Txt.

For Wormhole movement restriction, 'MoreWorm /b' must be run as close as
possible before the movement phase. MoreWorm then checks all ships set for
wormhole travel. In another FC than WRT is used for this purpose, it makes
a note (which is saved in a status file, MoreWorm.Sta) and sets the FC to
WRT. All ships that travel through wormholes travel in the normal way using
PHost routines. Formulas and other considerations given in the PHost document
files are valid. MoreWorm then checks which wormhole the ship is supposed
to travel (and in which way), and searches the closest base that the player
has at the wormhole exit. If the distance from the wormhole exit to this
base is <= 81 LJ, the ship is allowed to travel. Otherwise the ship FC is
set to WTN (Worm Travel No).

Follows the PHost movement phase.

After the movement, MoreWorm checks the position of the ships that traveled.
If the wormhole travel was successful and the FC WTB had been set by the
player, the ship is dragged to the starbase of this player which is closest
to the exit of the wormhole. This dragging is not part of the PHost movement.
It does not consume fuel, and the ship will not be disturbed by mines etc.
Consider the process as a twisting of the wormhole caused by a machine in
the star base. Note that if an intercepting ship made it through the wormhole
somehow, it will not usually make it to the same exit point unless it belongs
to the same player and the same special FC is set.

After the drag process, a player message is sent with a summary of all
successful wormhole travels and all attempts that failed. The following
failures are possible:
- An FC for wormhole travel was set, but there is no wormhole near the
  waypoint.
- An FC for wormhole travel was set, but the player doesn't own a star base
  at the wormhole exit.
- A ship was allowed to travel, but didn't arrive at the exit. Maybe it ran
  out of fuel and was destroyed or flung somewhere far into open space.

As I mentioned above, after phase /b, a status file is written that contains
ship information (former FC and desired wormhole number) for phase /b.
This status file is deleted after phase /a. If out of some reason phase /a
doesn't run, this file *must be deleted manually*! If the status file exists
at the start of phase /b, there may be an error! If the file is deleted
before phase /a, the special FCs will not work, and the player messages
will be empty.

A log file is written that tracks all events. This log file is available
at any time, especially at the end of the host phase after running PHost.
You can then have a look at the log file in order to check if everything
ran smoothly (or just in order to get an idea who in this turn made use of
this wonderful program's features ;-) ). As a default, the log file is
written cummulatively over as many turns as you like. If it doesn't exist
at any time MoreWorm is started, it is created. It is deleted when MoreWorm
starts with command line switch /d. Thus if you call MoreWorm /sd at the
beginning of each turn, the log file adds up the information of the current
turn only.

3. Where to put it, command line parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MoreWorm can be operated from any directory. However, it needs to find the
match files, more specific the ship.hst, xyplan.dat, bdata.hst, the message
and TRN files. These files are found in the match directory or should be
found there. If xyplan.dat is not there, put a copy there. Take care to
put the TRN files into the match directory before you run MoreWorm. If a
TRN file is not found, a note is left in the log file, but MoreWorm will
operate. However, if the TRN file is supplied later, a player may not be
able to travel through a wormhole because the wormhole was not selected into
the Wormhole.Txt! You can tell MoreWorm about the match directory using
command line parameters:

Usage: MoreWorm [options [more_options [...]]] [match_directory]');

An option parameter starts with '/' or '-' followed by one or more of the
option characters d, s, b, and a.

A '?' in any of the command line parameters will call the info function and
abort the program. The same happens if the program is called without any
parameters.

At least one option is needed for MoreWorm to take any action.

If the match directory is not supplied, the current directory is supposed
to be the match directory.

The option characters have the following meaning:
-d: delete log file at the start of this phase.
-s: select wormholes phase.
-b: before movement: check if ships are allowed to travel.
-a: after movement: drag ships to plants, write messages, delete status file.

Advice for execution:
Movement              = Execute MoreMrmB.Ini              Explain!
GloryDevices          = Execute MoreWrmA.Ini
Run 'MoreWorm /s' or 'MoreWorm /sd' or 'MoreWorm /s /d' immediately before
PHost. Run 'MoreWorm /b' in a PHost 3 INI batch file immediately before the
PHost movement phase. Run 'MoreWorm /a' in a PHost 3 INI batch file
immediately after the PHost movement phase. Don't forget to add the match
directory to the above commands unless you are sure that the match directory
is your current directory in all phases.

4. The file MoreWorm.Log
~~~~~~~~~~~~~~~~~~~~~~~~
A log file is written that tracks all events. This log file is available
at any time, especially at the end of the host phase after running PHost.
You can then have a look at the log file in order to check if everything
ran smoothly (or just in order to get an idea who in this turn made use of
this wonderful program's features ;-) ). As a default, the log file is
written cummulatively over as many turns as you like. If it doesn't exist
at any time MoreWorm is started, it is created. It is deleted when MoreWorm
starts with command line switch /d. Thus if you call MoreWorm /sd at the
beginning of each turn, the log file adds up the information of the current
turn only.

(This is the same as above ...)

5. Exit codes and runtime errors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On successful execution, MoreWorm quits with exit code 0. Command line
errors (esp. also any '?' in the command line) call the info function and
cause an exit code < 10 (or -1). Exit codes from 10 through 99 indicate a
file read or write error. Other errors should not occur. 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.

6. 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?)

7. History
~~~~~~~~~~
MoreWorm 1.0:
- First public release after several months of testing 0.9, no changes.

MoreWorm 0.9:
- Unnecessary player messages switched off.
- Scan radius reduced from 431 LJ to 200 LJ.

Moreworm 0.1:
- First version used in a game.

8. Future plans:
~~~~~~~~~~~~~~~~
I wrote this program while I didn't have much time. There is a lot I may
want to add or improve or which I may not want to improve but which have
to be taken into account by the user anyway. This is what I'm thinking of:
- Wormholes now are always considered bidirectional by MoreWorm. (May not
  really matter so much.)
- Parameters as the base-to-wormhole-exit distance are fixed now. They
  should be read in using command line parameters.
- I would like to add more friendly codes 'WT1', 'WT2' etc. for dragging
  ships to the n-th closest planet next to a wormhole exit. It may be
  desired to restrict this to a player's own planets.
- PConfig.Src is not read in, so the Wormhole entry radius is not known
  by MoreWorm. MoreWorm assumes that there is only one wormhole for each
  ship that wants to travel. Once it found a wormhole, it doesn't check for
  alternatives. Thus, the wormhole entry radius should be set small in the
  PConfic.Src. The entry radius is now fixed to 1.2~ LJ in agreement with a
  wormhole entry power of 0.1 and a fixed wormhole mass of 9999 kT. We
  should have a command line switch for this.
- Wormhole displacement can't be used because MoreWorm will not write the
  displacement to the Wormhole.Txt. It may not be a good idea anyway because
  the displacement would take place between phase /s and phase /b, so it
  would disturb the wormhole selection process. In addition it would confront
  with the small wormhole entry radius.
- Scan radius for wormhole selection (phase /s) is now fixed to 200 LJ and
  may have to be readjusted. A more apropriate way would be to always
  select the 100 wormholes closest to scanning ships. Scan radius would
  thus vary from turn to turn and could be published in the player messages.
- Due to wormhole numbers varying from turn to turn, frontends may get
  confused. It would be desirable to keep wormhole numbers as unchanged as
  possible. Preferably on a per player basis.

9. Please hand on
~~~~~~~~~~~~~~~~~
MoreWorm 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.

10. 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.

11. Wormhole configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~
In the following I add the PHost setting which I prefer to use with
MoreWorm, and I also add the Wormhole.Ori which I used for my first
MoreWorm game. Some notes in advance.

- My conception is that this is supposed to be a rapid transport system, but
  not one that is supposed to solve your fuel problems. Fuel logistics IMHO
  is an important part of this game that I don't want to get rid of. This is
  why I set the WrmTravelDistDivisor to 2. That is much more than the default
  and half of what be used without wormholes. Since most ships that use
  wormholes would probably fly a littly detour, I consider this factor
  adequate.

- Since wormholes are only for the players' own use, I switched on
  WrmTravelCloaked.

- Wormhole displacement can't be used because MoreWorm will not write the
  displacement to the Wormhole.Txt. It may not be a good idea anyway because
  the displacement would take place between phase /s and phase /b, so it
  would disturb the wormhole selection process. In addition it would confront
  with the small wormhole entry radius. (This is the same as above.)

  AllowWormholes		 = Yes
  WrmDisplacement		 = 1
  WrmRandDisplacement		 = 0
  WrmStabilityAddX10		 = 0
  WrmRandStability		 = 0
  WrmMassAdd			 = 0
  WrmRandMass			 = 0
  WrmVoluntaryTravel		 = Yes
  WrmTravelDistDivisor		 = 2
  WrmTravelWarpSpeed		 = 1
  WrmTravelCloaked		 = Yes
  WrmEntryPowerX100 		 = 10

# More Wormholes for MoreWorm

# horizontal
 1015 1005 1245 1005 9999    0
 1265 1005 1495 1005 9999    0
 1515 1005 1745 1005 9999    0
 1765 1005 1995 1005 9999    0
 2015 1005 2245 1005 9999    0
 2265 1005 2495 1005 9999    0
 2515 1005 2745 1005 9999    0
 2765 1005 2995 1005 9999    0

 1015 1255 1245 1255 9999    0
 1265 1255 1495 1255 9999    0
 1515 1255 1745 1255 9999    0
 1765 1255 1995 1255 9999    0
 2015 1255 2245 1255 9999    0
 2265 1255 2495 1255 9999    0
 2515 1255 2745 1255 9999    0
 2765 1255 2995 1255 9999    0

 1015 1505 1245 1505 9999    0
 1265 1505 1495 1505 9999    0
 1515 1505 1745 1505 9999    0
 1765 1505 1995 1505 9999    0
 2015 1505 2245 1505 9999    0
 2265 1505 2495 1505 9999    0
 2515 1505 2745 1505 9999    0
 2765 1505 2995 1505 9999    0

 1015 1755 1245 1755 9999    0
 1265 1755 1495 1755 9999    0
 1515 1755 1745 1755 9999    0
 1765 1755 1995 1755 9999    0
 2015 1755 2245 1755 9999    0
 2265 1755 2495 1755 9999    0
 2515 1755 2745 1755 9999    0
 2765 1755 2995 1755 9999    0

 1015 2005 1245 2005 9999    0
 1265 2005 1495 2005 9999    0
 1515 2005 1745 2005 9999    0
 1765 2005 1995 2005 9999    0
 2015 2005 2245 2005 9999    0
 2265 2005 2495 2005 9999    0
 2515 2005 2745 2005 9999    0
 2765 2005 2995 2005 9999    0

 1015 2255 1245 2255 9999    0
 1265 2255 1495 2255 9999    0
 1515 2255 1745 2255 9999    0
 1765 2255 1995 2255 9999    0
 2015 2255 2245 2255 9999    0
 2265 2255 2495 2255 9999    0
 2515 2255 2745 2255 9999    0
 2765 2255 2995 2255 9999    0

 1015 2505 1245 2505 9999    0
 1265 2505 1495 2505 9999    0
 1515 2505 1745 2505 9999    0
 1765 2505 1995 2505 9999    0
 2015 2505 2245 2505 9999    0
 2265 2505 2495 2505 9999    0
 2515 2505 2745 2505 9999    0
 2765 2505 2995 2505 9999    0

 1015 2755 1245 2755 9999    0
 1265 2755 1495 2755 9999    0
 1515 2755 1745 2755 9999    0
 1765 2755 1995 2755 9999    0
 2015 2755 2245 2755 9999    0
 2265 2755 2495 2755 9999    0
 2515 2755 2745 2755 9999    0
 2765 2755 2995 2755 9999    0

# vertical
 1005 1015 1005 1245 9999    0
 1255 1015 1255 1245 9999    0
 1505 1015 1505 1245 9999    0
 1755 1015 1755 1245 9999    0
 2005 1015 2005 1245 9999    0
 2255 1015 2255 1245 9999    0
 2505 1015 2505 1245 9999    0
 2755 1015 2755 1245 9999    0

 1005 1265 1005 1495 9999    0
 1255 1265 1255 1495 9999    0
 1505 1265 1505 1495 9999    0
 1755 1265 1755 1495 9999    0
 2005 1265 2005 1495 9999    0
 2255 1265 2255 1495 9999    0
 2505 1265 2505 1495 9999    0
 2755 1265 2755 1495 9999    0

 1005 1515 1005 1745 9999    0
 1255 1515 1255 1745 9999    0
 1505 1515 1505 1745 9999    0
 1755 1515 1755 1745 9999    0
 2005 1515 2005 1745 9999    0
 2255 1515 2255 1745 9999    0
 2505 1515 2505 1745 9999    0
 2755 1515 2755 1745 9999    0

 1005 1765 1005 1995 9999    0
 1255 1765 1255 1995 9999    0
 1505 1765 1505 1995 9999    0
 1755 1765 1755 1995 9999    0
 2005 1765 2005 1995 9999    0
 2255 1765 2255 1995 9999    0
 2505 1765 2505 1995 9999    0
 2755 1765 2755 1995 9999    0

 1005 2015 1005 2245 9999    0
 1255 2015 1255 2245 9999    0
 1505 2015 1505 2245 9999    0
 1755 2015 1755 2245 9999    0
 2005 2015 2005 2245 9999    0
 2255 2015 2255 2245 9999    0
 2505 2015 2505 2245 9999    0
 2755 2015 2755 2245 9999    0

 1005 2265 1005 2495 9999    0
 1255 2265 1255 2495 9999    0
 1505 2265 1505 2495 9999    0
 1755 2265 1755 2495 9999    0
 2005 2265 2005 2495 9999    0
 2255 2265 2255 2495 9999    0
 2505 2265 2505 2495 9999    0
 2755 2265 2755 2495 9999    0

 1005 2515 1005 2745 9999    0
 1255 2515 1255 2745 9999    0
 1505 2515 1505 2745 9999    0
 1755 2515 1755 2745 9999    0
 2005 2515 2005 2745 9999    0
 2255 2515 2255 2745 9999    0
 2505 2515 2505 2745 9999    0
 2755 2515 2755 2745 9999    0

 1005 2765 1005 2995 9999    0
 1255 2765 1255 2995 9999    0
 1505 2765 1505 2995 9999    0
 1755 2765 1755 2995 9999    0
 2005 2765 2005 2995 9999    0
 2255 2765 2255 2995 9999    0
 2505 2765 2505 2995 9999    0
 2755 2765 2755 2995 9999    0

 


  Last Modified: 25-Feb-2000
<URL:http://www.blutmagie.de/vagabond/addons/moreworm/moreworm.html>