================================================
               |                                            |
               |    T h e   P l a n g i n e e r    1 . 0    |
               |                                            |
              ================================================






The Plangineer         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 :-) .
- If you know Planets and don't know HostHack, you do need this program.
- If you know HostHack, but you think it could be more powerful or more
  comfortable, you also need this program. :-)

What is the Plangineer?
~~~~~~~~~~~~~~~~~~~~~~~
The Plangineer is a powerful tool for manipulating VGA Planets host data.
- If you want to test some feature of Planets and need to rearrange a
  match for this purpose, use the Plangineer.
- If a tool or CPlayer meddled with some player's data and you have to
  correct this, use the Plangineer.
- If a player cheated and you have to punish him, use the Plangineer.
- If you are playing against a CPlayer and always loose, upgrade your
  ships and bases with the Plangineer. If you always win, upgrade the
  CPlayer's. ;-)
- If you have used HostHack for the above, but you don't like that it
  refuses to upgrade base tech levels, move ships, edit mines etc, or
  you just don't like that you can't figure out every time how many
  digits to enter or which keys to press, from now on use the Plangineer.
- If you want to view or change the engine or weapon data or even make a
  new shiplist, also use the Plangineer.
- The Plangineer allows you to view and change *all* data in the following
  files:
  - ship.hst     (ship data, also create/delete ships)
  - pdata.hst    (planet data)
  - bdata.hst    (base data, also create/destroy bases)
  - mines.hst    (mine data)
  - race.nm      (race names)
  - xyplan.dat   (planet coordinates)
  - planet.nm    (planet names)
  - truehull.dat (hull-to-race assignment)
  - hullspec.dat (hull data)
  - engspec.dat  (engine data)
  - beamspec.dat (beam data)
  - torpspec.dat (torp data)


Quick start
~~~~~~~~~~~
If you hate reading manuals and think you can handle it without, that's fine
with me. It's only your data ;-) . Read this section for a quick start.

First you will be looking for a directory to put the program in. Your main
planets directory will be fine, but any other directory is also okay. Call
'Plangnr ?' and read the usage hints. Start the Plangineer, press <F1> (or
choose the help function from the menu) and read the help screen. Get working.

Remember that your host data are only one copy of the game. The players have
another one, and if these data don't match, the player may get into trouble.
To prevent this, it may be a good idea to run the Plangineer from an Auxhost.

If you run into trouble with the file checksums, you should have read the
corresponding section of this manual. :-)

No warranty: By using this program you confirm that you agree with the
no-warranty section of this manual.

Contents
~~~~~~~~
1. Operation Instructions
2. No warranties
3. Checksums
4. History
5. Known problems
6. Please hand on
7. Contact

1. Operating Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~
The Plangineer can be operated from any directory. However it needs to find
at least those files which it is supposed to change, and finding some others
may make the operation more comfortable. (For instance, in the base menu
you can see the type of the stored hulls as strings only if the Plangineer
can locate both hullspec.dat and truehull.dat.) The Plangineer will search
for all files in the match directory (i.e. the directory with your match
data) first, then in the game directory (the main planets directory) and
finally in the current directory. Use command line parameters to tell the
Plangineer about the location of your match and game directory. Call
'Plangnr ?' (or with any other command line parameter that contains a '?')
to get the details about the command line parameters. To make things easy,
if the Plangineer resides in the game directory, 'Plangnr <matchdir>' will do.

After starting the program, you enter a main menu from which you choose
one of several submenus (ships, planets etc.). Choose a line in a menu
with <cursor up> and <cursor down>. To speed things up, press the cursor
OBtogether with <ctrl> (may also be called <strg>). If your computer doesn't
support <ctrl><cursor up/down>, use <Tab> and <Shift><Tab> instead. There
is no mouse support. If you can type text fast, you will find cursor
operation faster than mouse operation.

Use <cursor left/right> to change between ships/planets etc. Don't forget
to use the <ctrl> key for efficient work. To find the next ship/planet/
base/hull of race N, press <Alt><N>, where <N> stands for a number on the
letter block of your keyboard. <0> should work for the Rebels, the key to
the right of <0> (whatever printed on it) should work for the Colonies. The
key to the right of this or the key to the left of <1>, or <Esc>, (each
pressed together with <Alt> should work for a ship/planet/base that belongs
to none of the races. (Note that some of these possibilities may not work
on your computer because there are a lot of keyboard layouts esp. in foreign
countries. However, I hope I included something for everybody. At least there
is a straight line of working keys on those American, German and Japanese
keyboards which I tested. You can also use <Alt><A> for the Rebels and
<Alt><B> for the Colonies.)

There are three more hotkeys:
<F1> for help,
<F2> for save,
<F10> for save-and-exit.

For changing an entry, if it is a number or a string, just type. If you
want to change a name only slightly, try to start the edit mode with the
<Backspace> key. After typing press <Enter> or, if you changed your mind,
press <Esc> to quit. For entering coordinates, write both numbers separated
by a comma or anything suitable. Brackets and other stuff before and after
the numbers is optional and will be ignored. A single positive (negative)
number from 1 to 500 will be replaced by the coordinates of the planet (ship)
with this number. 0 is interpreted as (0,0).

For changing the race of a ship, its mission, a native government type etc,
press '+' and '-' to go through the possible choices. (There is a big '+' and
a conveniently placed '-' key on the number block of your keyboard. ;-) )
Ship hulls in a choice of all 105 hulls, or ship missions can also be
changed by pressing <Enter> and choosing a hull or mission from a submenu.

If you find that you cannot change something, for instance the number of
engines of a ship in a ship menu, there may be some reason for it :-) .
All ships with a certain hull have the same number of engines. To change
this number, go to the hull menu. You can't change the number of engines
of a single ship. You can, however, change its number of weapons. Note, that
your host program may or may not support e.g. Small Deep Space Freighters
with 5 or with 15 beams and bays :-) .

If a race, mission, hull type etc. is not shown as a name, but only as a
number, the likely reason is that the Plangineer couldn't locate a file
needed for this. In principle, any of the files is allowed to be missing,
the Plangineer will still work. The Plangineer will also work if no files
are found at all. In that case, however, your changes will also be written
to no files at all ... :-) At the start, the Plangineer will inform you
about missing files.

When you save the data, only those files are written to which you made
changes. If you leave the program without saving, nothing at all will be
written or saved. If you save some data with <F2> or from the main menu,
then make additional changes and then quit the program (with <Esc> or using
the quit function from the main menu), the saved data will remain saved,
but the additional data will not be saved.

2. Checksums
~~~~~~~~~~~~
There is a checksum on some of the files:
1. The sum of the x coordinates of all planets must be 998681.
2. The sum of all bytes in the *spec.dat files must be 338817.
If these checksums don't match, most current frontends don't care, but
Planets.exe, for instance, will refuse to work.

When writing files, the Plangineer will check these checksums, if possible.
If all four *spec.dat files are supplied, the Plangineer will use some
unnecessary space in the torpspec.dat to supply the proper checksum.
(This feature is switched off if you shortened your files.) This doesn't
work for the xyplan.dat because there is no unnecessary space in this
file. If you change the x position of a planet by N, you must also
change the x position of another planet by -N if you want to use this
xyplan.dat with Planets.exe. The plangineer will not change planet
coordinates, but it will check the sum for you and display the result.

3. 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
any 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.
If you haven't made a backup of your game and match data before using the
Plangineer, do make a backup! If you did make a backup, make another one :-) .

4. History
~~~~~~~~~~
Plangnr 1.0:
- first public release

5. Known problems
~~~~~~~~~~~~~~~~~
Problems? What problems?  ;-)

6. Please hand on
~~~~~~~~~~~~~~~~~
The Plangineer is freeware. If you like it, I'm happy. Please feel free to
give the Plangineer 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.
If you want a change, please contact me.

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