***************************
                     *   P l a n e t s S p y   *
                     ***************************


PlanSpy is a tool for the off-line net game VGA Planets, (c) Tim Wisseman.
PlanSpy is installed as a background tool in the memory of your computer
and can be activated by pressing a hotkey. It extracts some useful data
out of planets.exe and displays this data while planets.exe is running.
Playing with planets.exe, you can now get the exact planet temperature
and happyness (incl. a forecast for the next turn), the exact mining rate
etc. PlanSpy also offers a fuel consumption calculator, a construction
menu for factories etc. which can be comfortably operated from the
planets.exe planet main menu and converts supplies to credits automatically
(if needed). Finally there are some tables with information on details of
VGA Planets.


Contents

 1. Everybody should read this
 2. Main information table
 3. Construction menu
 4. Yellow pages
 5. Fuel consuption calculator
 6. Command line options
 7. Initialisation
 8. Compulsory note
 9. Credits
10. History
11. Problems


1. Everybody should read this

Certainly, everybody should read the whole doc. But I'm realistic enough
to see that I won't get everybody to do this. Those who don't should at
least read this short section. It may help them to enjoy Planets Spy and
will save them some time later on.

Firstly a hint on the installation and usage of PlanSpy. PlanSpy can be
stored in any directory on your computer's hard disk and be started from
there. It installs in the background. Called when there is already an
installed copy in the computer's memory, it deinstalls, if possible.
PlanSpy is activated with a hotkey (default: <space>) in combination with
a special key (Control or Alt). Depending on the special key, various
functions are activated. In some cases, it is possible to scroll through
several pages by keeping the special key pressed and pressing the hotkey
several times. The main functions of PlanSpy can only be accessed after
planets.exe has been started and a race has been chosen. In the beginning,
it should be tested, if the numbers given by PlanSpy for some planets are
plausible. If this is obviously not the case, PlanSpy should be called
with the command line option /i2. If that doesn't help, I recommend a
glance through the section on initialization.

As a background tool, PlanSpy can conflict with other hard- or software
more easily than other programs. It is stable on my computer and several
others, but I can't give a guaratee for every one. Since unfortunately
planets.exe reacts aggressively on crashes if data are changed since
the start of the program, I recommend for the first use of PlanSpy,
to call and use the functions of PlanSpy several times before any data
in Planets are changed.

In this manual, there is one section for any of the four functions of the
Planets Spy. These sections can be read (not only) if required ;-) .
Especially the construction menu may not be self-explanatory, I'm afraid.
In this menu, factories etc. are built using the same keys as in the
construction menu of planets.exe. When the keys are pressed in combination
with the Alt-key, the construction will be undone (maybe) :-) . For details
see the said section.

I also don't warn against glancing through the sections `compulsory note'
and `problems' :-) , but I don't want to delay the hasty ones.


2. The main information table

The main function of the Planets Spy consists of spying out information
from planets.exe which that program won't yield voluntarily. This
information is esp. the exact planet temperature, mining rate and
happyness. At the same time, the increase of minerals, clans, credits
and happyness up to next turn is forecast.

These data are displayed on pressing left-alt + hotkey (default hotkey
is <space>) in the top left of the planets planet main menu. There they
overwrite the little planet picture. When the menu is changed in
planets.exe, the data are overwritten in return. They reappear when
left-alt + hotkey are pressed again. The data always refer to the last
planet active in plants.exe.

The main information table consists of the following data:

* Line 1: planet number and temperature.
* Lines 2 to 5: For each of the four minerals the mass in the planet's core,
  mass mined, mass being mined up to next turn (with the present number of
  mines) and mining rate.
* Lines 6 and 7: For colonists and natives the *increase* of clans
  (invalid for crystallines and in case of overpopulation), happyness of
  this and next turn (present tax rate, number of mines and factories
  provided; avians taken into consideration) and the taxes taken up to
  next turn (insectoids taken into considerations, but not supplies by
  bovinoids nor double taxes by the Federation).

The formulas for the forcasts are taken from the PHost documentation.
According to experience, most of these formulas are identical with the
formulas of the original host (`TimHost'). In case of deviations, these
tend to be small (rounding errors). For instance, colonists are somewhat
more busy in TimHost than in PHost. Due to different rounding, 1 kT more
minerals are extracted in TimHost than in PHost in 50 % of the cases.
PlanSpy will then show the lower value and mark with a `^' behind the
number that TimHost will yield another kT.

When the left alt key is kept pressed and the hotkey is pressed for a
second time, another information table is presented showing the armament
of the planet for the present number of defences and the changes in the
armament for higher numbers of defences. When a certain number of defences
is not mentioned, this means that this number does not improve the planet's
armament. When the hotkey is pressed again without releasing the left alt
key, the armament for further increasing number of defences is given. The
number of torpedo launchers in the right column of these tables is valid
for `planets have tubes' in PHost only. TimHost players can ignore this
column.


3. Construction menu

With Planets Spy, buildings can now be comfortably constructed from the
planet main menu of planets.exe. On pressing right-alt + hotkey a small
menu is activated which offers the same functions as the construction menu
of planets.exe, namely the construction of factories, mines and defences
with `f', `m' and `d' as well as the conversion of supplies to MCrs
with `5', `6' and `7'. The manual conversion of supplies will not be
needed as often as before, as supplies are automatically converted to MCrs
if this is needed for the construction of the buildings. When the above
keys are pressed in combination with the right alt key, the conversion
or construction is cancelled. However, the cancellation is only possible
as long as the construction menu is active. When the construction menu
is left, the new state is transmitted to planets.exe. MCrs or buildings
that have been build by then cannot be reconverted next time. When the
construction of a building is cancelled, it is always converted into
1 kT of supplies and the corresponding number of MCrs. After that, if
for the construction of the building more than 1 kT of supplies were used,
it is possible to reconvert MCrs to supplies pressing right-alt + 5 to
right-alt + 7.

The construction menu of Planets Spy makes the construction menu of
planets.exe obsolete. The tax rates can also be set using the `r' key
from the planet main menu of planets. With left-alt hotkey, PlanSpy
adds the new taxes, happyness change and clan growth for the present
tax rates.

The construction menu can be operated from a ship menu of planets.exe,
but then it has no effect!


4. The Yellow Pages

On the `Yellow Pages' (which are not yellow, BTW) of Planets Spy you find
a few tables with general information on planets, namely the classification
of the happyness (in numbers) to the happyness levels, and the same for
the planet temperature, mineral density and mining rate. There ist also
a (tight) memo table for the PHost extended missions. These pages are
activated pressing left-ctrl + hotkey. Scrolling through the pages is
possible by pressing the hotkey several times before releasing the control
key. When the control key is released, the menu will start with the first
page next time.

The Yellow Pages can also be activated when planets.exe is not present
in RAM. When the Yellow pages are activated from a text screen, there is
a final menu table that restores the screen background.


5. Fuel Consumption Calculator

Pressing right-ctrl + hotkey activates a routine that calculates the
fuel consumption of ships. A window opens, in the left part of which
the ship mass and distance must be entered. In the right part, several
parameters can be chosen, i.e. the drive and speed, if the drive
has a gravitonic accelerator (GravAx) and which fuel consumption model
is to be used. (PHost offers an alternative fuel consumption model.)

Toggle with the cursor keys between the active part of the window or the
lines. The values are changed with `+' or `-' (hopefully on international
keyboards, too :-/ if not, try the gray keys). Alternatively, other keys
can be used, which also change the active line. See the bottom line of
the window for these keys. To change the number fields, numbers can be
entered. The number fields can be cleared with the <space> key. <Backspace>
will delete the last character. The consumption field is updated on pressing
any key.

Unfortionately with the standard fuel consumption model, TimHost as well
as PHost use formulas with cannot be followed exactly by other programs
and result in errors of 1 kT fuel in 50 % of the cases. PHost and TimHost
aggree in 50 % of the cases, and in the other cases are half 1 kT too
high, half 1 kT too low. The Planets Spy fuel consumption calculator
agrees with both of them in 50 % of the cases and gives a by 1 kT higher
result in the other cases. So it should not happen that a ship runs out
of fuel due to rounding errors by the calculator. This problem (almost)
only applies to drives of tech level 1, 2 and 10 at any speed and the
movement with warp 1 with any drive.

Further errors in the calculation can occur when the distance cannot be
traveled in one turn. The consumption calculator cannot divide a distance
in several parts and consider the mass loss between the steps.

The fuel consumption calculator is exited with <Esc>. By the way, it can
also be used when planets.exe ist not present in RAM. When the calculator
is called from a text screen, the background is restored on leaving.


6. Command line options

PlanSpy can be used with the following command line options (where
captial letters can but needn't be used, and the `/' can be replaced
by `-'):

PLANSPY [/Rn] [/Hn] [/S] [/In] [/O[n]] [/B[s]]

 /Rn,  n = 0:         Scroll lock key ignored (default)
       n = 1, 2:      Planets Spy active when scroll lock on/off
       n = 3:         Planets Spy inactive
 /Hn,  n = 1 ... 127: Hotkey scan code (default is 57, space key)
 /S:                  Show scan codes for parameter /H
 /In:  n = 0:         Installation check for Planets.exe rigid
       n = 1:         Offset for planet table flexible (default)
       n = 2:         Reference code for planets.exe base adress reduced
 /O[n]:               Offset for planet table in Planets.exe
                      (Default is 251298. See below.)
 /B[s]:               Code for base adress. See below.

Description of the parameters:

When Planets Spy is installed it can be activated by pressing a hotkey
in combination with a special key (Alt or Ctrl). Default hotkey is the
<space> key, but other keys can be chosen as hotkey using the command
line parameter /H followed by the scan code of the key. The scan code
of any key is given when PlanSpy is called with the parameter /S. In
this case, PlanSpy is not loaded in the background, but instead gives
the scan code of the keys pressed thereafter. This mode is exited with
<Esc>.

Exclusively in Planets Spy there is also another simple possibility of
deactivating the hotkey. To make use of this, call Planets Spy with the
parameter /R2 (/R1). Then the hotkey is only active when the `Scroll Lock'
function of your keyboard is switched on (or off in case of /R1). In the
normal operation (corresponding to /R0), the Scroll Lock function is
not supported. With /R3, PlanSpy is inactive when Scroll Lock is on *or* off
:-) , that is, PlanSpy is totally inactive. This can be used to deactivate
PlanSpy when in cannot be removed from memory. PlanSpy can then be
reactivated with an other call with /Rn.

When Planets Spy is called for the first time, it installs in the background.
From the second time on, if command line parameters are given, they are
written to the installed background copy of PlanSpy. When PlanSpy is
called without command line parameters another time, the program removes
itself from memory, if that is possible.

The other parameters should only be used when problems occur during the
installation or initialization of Planets Spy. In this case see the section
on initialization.


7. Initialisation

Planets Spy reads information from the program planets.exe and also writes
information to it. To do that, Planets Spy must know where the information
is (or should be written to). Therefore Planets Spy goes through an
initialisation which consists of two steps. In the first step, Planets Spy
searches for a code (a character string) in the memory to find planets.exe
at all. Next, Planets Spy tries to locate the planet table within
planets.exe.

The default initialization procedure corresponds to the command line
parameters /i1 /o /b. In this procedure, the planets base adress code is
fixed and is 16 bytes long. The offset for the planet table is also fixed
at first, but if the table is not found at that offset, the offset is
varied by up to 21767 up and down. This procedure should work with by
far most versions of planets.exe. This means that by far most readers
are allowed to skip the rest of this section :-) .

The reason for a failure should normally be that the base adress code
is too rigid and doesn't match the planets.exe version in hand. In these
cases PlanSpy reports `planets.exe not found in RAM'. If you get this
message, try the command line parameter /i2. The base adress code is then
reduced to 6 bytes which consist of the string `PLANET'. With this string
planets.exe can hardly escape identification. The problem with it is that
other Planets tools might now respond to this code if they are in the
computer's memory at the same time (e.g. VPLRead). PlanSpy may report
`planet table not found' in this case, but there may as well be no error
messagy, but PlanSpy will then report obviously wrong data. This is why
/i2 should only be used if there are no alternatives. Before testing this
parameter for the first time you should reboot your computer and shouldn't
have any other tools in RAM in order not to puzzle PlanSpy. You can try
later on, if your favorite tools are compatible with /i2. If they aren't,
there are two further variants of getting PlanSpy to work, a systematic one
and a simple one.

The simple variant consists of accepting the wrong base adress, yet
making PlanSpy search for the planet table at the right place (using
parameter /O<offset>). You can either guess the offset starting with
251300 and increasing this value in steps of 64000, or you can
calculate it approximately. To calculate it, first write down the
base adress at which the wrong code was found. (The base adress is
reported by PlanSpy during the initialization.) Then leave Planets
and determine with the DOS command `mem /d' or `mem /p' at which
position planets.exe had been in the memory. (It is the same position
at which the program `mem' begins now.) The new offset is approximately:
offset  =  251500  +  start adress of PLANETS or MEM  -  faulty base adress.
Naturally, this offset may change when you change the number or order of
your background planets tools.

The systematic variant consists of loading planets.exe to a high
position in RAM where it is not overwritten when you leave it and
start the DOS DEBUGger. With the debugger you search the memory at the
position where planets.exe still exists, and seek there for an unequivocal
code which you tell PlanSpy with the parameter /bn (see below). This
will solve your problem for as long as you don't change your version of
planets.exe.

I can think of two further possibilities, when the initialization of
PlanSpy may fail. When a version of planets.exe is much smaller or larger
then the usual versions, the planet table may be at a totally different
position. PlanSpy then reports `Planet table not found'. In this case,
you have to tell PlanSpy a better offset with /On. A good starting value
is: n = NewOffset = 251298 + file size - 298194. When the initialization
mode is /i1 or /i2, this value needn't hit exactly, you may be up to
32767 wrong. With /O (that is without any number) PlanSpy returns to
the default offset.

The other possibility is that PlanSpy seems to have found a planet table,
but is mistaken by some values that match the right pattern. You can prevent
this by using the parameter /i0 and thus switch off the search for the
planet table. With /i0 the planet table is searched for only at the exact
position given by the offset. Naturally, this can only work if the offset
is given correctly. Default offset and default code are taken from the
planets.exe version dating 11-07-1994, 16:10:38 h, size 298194 bytes and
will only work with this or closely related versions. The version dating
03-28-1993, 11:55:48 h, size 298166 bytes, for instance, has its planet
table 64 bytes after that of the above version. To make the other version
run with the parameter /i0, the offset must be changed with /o251362,
correspondingly.

If needed, a new code for the planets.exe base adress can be entered
with the parameter /b[s], where [s] is a character string that takes
the encoded code. The encoding is bytewise in the following way: Each
byte of the code is entered into the string as a number. If this number
is decimal, it is preceded by `#'. If it is hexadecimal, it is preceded
by `$'. Letters may be entered as letters. The default code in the
encoded form can look like that, for instance:
blPLANETS#32#0#0#146qR#6     or
$62$6c$50$4C$41$4e$45$54$53$20$00$00$92$71$52$6 .
Important: The code may be no longer than 16 bytes. It must take an
even number of bytes! When /B is used without a string, PlanSpy sets back
to the default code. As long as a code given by /B is active, /i2
is reset to /i1 or /i0 (depending on which of those was active last).

Whoever must enter a code or offset with /b[s] of /o[n] because
the parameters /i1 and /i2 prove insufficient, please write me an
e-mail with the size and date of your version of planets.exe and also,
if you found out, with a working code and/or offset.


8. Obligatory note

As any other program, also PlanSpy might damage your hard- or software.
The author of this program cannot be made responsible for any kind of
damage caused by using this program.

PlanSpy may not be changed, but may be copied as often as you like and
may be given to other persons free of charge, but only in combination
with this documentation.

*** Attention! ***

The 1-versions of the Planets Spy were running with a less stable
background routine that could crash in combination with harddisk
activity. PlanSpy 2.0 has a completely new background routine
which should be `harddisksafe'. However, PlanSpy can still make
planets.exe crash in case it was unproperly installed and data were
written to planets from the construction menu.


9. Credits:

The background routine (from version 2.0) is based on a program by
Michael Tischer, see `Turbo Pascal Intern', Data Becker, 1989 (in German
language). With some PHost formulas, I was supported by Andrew Sterian.


10. History

Version 1.0ß:
- First public version.

Version 1.1ß:
- PlanSpy now controls every time a hotkey is pressed, if planets.exe
  still resides in the memory.
- Hotkey changed from LeftShift-Ctrl-S to LeftAlt-Space.
- Program now restores the Cursor after the initialisation message.

Version 1.2à:
- Constuction menu added.
- Planet armament tables added.

Version 0.1à (BGFuel)
- First public version.

Version 0.2à (BGFuel)
- Background ability temporarily disabled.
- Infos disabled since invalid.
- Fuel consumption formula for the accurate fuel model corrected: rounding
- Bug corrected for fuel consumption of warp 9 drives.

Version 2.0ß:
- Background routine exchanged. PlanSpy should now run crashsafely.
- PlanSpy now deinstallable.
- Hotkey now configurable, can be disabled with Scroll Lock key.
- PlanSpy now subsequently reconfigurable.
- Added in the main menu: forecast of minerals, clans and MCrs.
- Added in the construction menu: maximum number of buildings.
- Yellow Pages added.
- Fuel consumption calculator (former program BGFuel) added to PlanSpy.

Version 2.1ß:
- Initialization routine now more flexible. PlanSpy should now run with
  all versions of planets.exe without difficulties.
- Bug corrected: Hotkey problems when PlanSpy was called with command line
  parameters in the first run.

Version 2.02:
- Bug corrected: PlanSpy crashed on pressing LeftAlt-F when planets.exe
  was called from VPLRead.
- Main menu: Happyness of next turn is shown instead of happyness increase.
- Yellow Pages: Info table on PHost extended missions added.
- Program messages now in English instead of German.
- `English' ;-) documentation added.

Possible future enhancements
- Further consideration of races.
- Fuel consumption turnwise?
- Update main menu automatically on changing the tax rate.
- More comfortable construction menu.
- Extended undo function in the construction menu.
- More Yellow Pages with information on drives and weapons.
- Make use of ship table in planets.exe.


11. Problems

Known Problems:

- When PlanSpy is activated shortly after changing the ship or planet in
  planets.exe, it can happen that PlanSpy shows colored symbols instead of
  numbers and letters. This is due to the way planets.exe includes pictures
  into its screens. This bug is inevitable, but harmless, and the usual
  letters appear on pressing the hotkey again.
- The race of the natives is only taken into consideration with the
  happyness change and the taxes, not e.g. with the clan growth. I can
  add that later where it seems necessary. This also applies to things as
  the growth limit of clans.
- The race of the colonists is not taken into account. This applies esp. to
  the mining rates and tax (Fed, Lizard), but also to the clan growth
  on desert and arctic planets (Rebels, Crystallines). Possibly I
  will add a command line parameter for that.
- Parameters of planets which tend to be used differently in different
  games (e.g. the climate death rate) are not supported and probably
  never will be.
- Formulas are taken from the PHost FORMULAS.DOC. Pleas read this file
  and the PHost file DIFFS.DOC to learn about possible differences in
  respect to the original host (`TimHost'). Usually these differences
  are only due to different rounding behavior.


Unknown problems:

I don't know any unknown problems at the moment :-) . When you find one,
you may keep it ;-) . But you may as well share it with me. In that case,
however, it might happen that the problem will no longer occur in a future
release of PlanSpy. If you decide to dare it anyway or if you have other
suggestions for the improvement of the Planets Spy (on which I'm looking
forward to, by the way), please send an e-mail to

Michael_Herrmann@ac3.maus.de