This document provides a guide on how to install, set up, and
host with PHost. It is intended for hosts; players can usually
easily do without it.
This document assumes knowledge with common Planets terminology. If
in doubt, look up our definitions of root
directory, game directory,
ship list and
star chart in the
Back to top
To install PHost, just unpack the distribution archive into a
directory of your choice. That directory will be the root
directory for that version of PHost. PHost 4 distributions
contain subdirectories; these subdirectories contain the sample
configuration files. If you are using pkunzip to extract
the distribution, be sure to use the -d option to restore
the directory structure.
On all platforms, PHost comes as a readily-linked program
executable (phost.exe, phost). The
individual distributions contain additional information in a
README file, if necessary.
PHost does not include a ship list
Check the upgrade instructions in the
Changes document. Usually, you only have
to check new configuration settings. Skim
the change list to see if a change affects you.
Ensure that all add-on programs used in the game can handle
PHost 4.x. Programs compiled with PDK 4.4 or later can handle both
Several configuration options were introduced, some were
dropped. Update the configuration file. To see what you have to
change, run PHost in check-only mode with
-oConfigLevel=1, like this:
$ ./phost -oConfigLevel=1 -c0 test_game
WARNING: pconfig.src: Parameter 'AllowNewNatives' is not recognized
WARNING: pconfig.src: Parameter 'CPEnableMessage' is not recognized
WARNING: pconfig.src: default value used: 'StructureDecayOnUnowned = 1'
WARNING: pconfig.src: default value used: 'PALIncludesESB = Yes'
WARNING: pconfig.src: default value used: 'PBPCostPer100KT = 200'
WARNING: pconfig.src: default value used: 'PBPMinimumCost = 400'
WARNING: pconfig.src: default value used: 'PBPCloneCostRate = 200'
WARNING: pconfig.src: default value used: 'NumShips = 500'
WARNING: pconfig.src: default value used: 'ShieldKillScaling = 0'
Using custom hull functions defined in 'hullfunc.txt'
Game name is 'PHOST Game'
This is Turn #39.
Checking host data...
Looking for player6.trn
Turn not found!
Look up the parameters PHost complains about in the
Configuration document, and change your
For your convenience, we have included a list with all new
options added between PHost 3.4c and 4.1 in
The instructions for upgrading from version 3 hold here, too.
However, many more parameters have changed between version 2 and
3. PHost 3 contains more detailed upgrade instructions for going
from version 2 to 3, but I'm too lazy to copy them here :-)
If the game was hosted on a non-DOS system, you have to convert
it into DOS format. PHost 4.x uses the same file format on
all systems, which is the same file format as used on DOS.
Back to top
First, create the game directory. PHost comes with some
example configuration files in the config/ subdirectory;
pick one, copy it into the game directory and rename it to
pconfig.src. Likewise, pick the relevant file from the
shiplist/ directory and place it in the game directory
Edit the pconfig.src file to suit your taste. All
possible configuration options are described on the
The shiplist.txt file contains ship-list specific
configuration options and the special ship
abilities and generally remains unchanged.
Alternatively, you can ignore shiplist.txt and put
all PHost configuration options into pconfig.src,
and the special ship abilities into hullfunc.txt --
like it used to be in PHost 3.x. We recommend you to use the
above, "new" way, though, because it reduces the complexity of the
per-game configuration compared to the huge monolithic chunk of
configuration used in PHost 3.x. Ideally,
shiplist.txt is a never-changing part of the ship
list, much like hullspec.dat.
If you wish to use one map and one ship list over and over
again, copy them into the root directory. If you wish to use a
ship list or map in one particular game, copy the files into the
game directory. When looking for these files, PHost first looks
into the game directory and, if they are not there, in the root
Files affected by this are:
hullspec.dat: starship hulls
beamspec.dat: beam weapons
truehull.dat: hull/player assignments
race.nm: race names
planet.nm: planet names
xyplan.dat: planet locations
These files need not all be in the same directory. PHost will find
them even when some of them are in the game directory and some are
in the root directory.
To initialize a universe, you need a "Master" program. PHost can
not create a universe itself.
- Using master.exe: when you have access to a DOS
computer, master.exe is a quick and simple way to
generate a new universe. Invoke master.exe with the
game directory as parameter, and answer the questions it asks
you. This may require that master.exe is
installed in your root directory.
- Using AMaster: the preferred way to set up a game for
PHost is using AMaster. AMaster is
controlled by a configuration file amaster.src in a
similar format as pconfig.src. AMaster provides a
variety of options to find fair, balanced starting situations as
well as a number of special scenarios. AMaster can also create
- Using PMaster: PMaster from the
PUtils / PDK is the old PHost master program.
It works similar to AMaster, but has fewer options.
You can also use a hosting editor to manipulate the universe
after mastering it. The program used to Master the game needs not
support PHost explicitly, any universe creation / editing program
for HOST works with PHost as well.
When everything is set up right, run PHost for the first time to
generate the first set of result files.
PHost supports the Auxhost1 and Auxhost2 hooks of HOST, as well
as even finer control using "PControl". If you wish to use a
host-side add-on program, read
Manipulating the Host Sequence. The
add-on documentation will tell you where in the sequence the
When you use an add-on which provides additional friendly codes
or missions, you should make these known to PHost and the players
using the files intended for it.
- All special friendly codes should be listed in
xtrfcode.txt. PHost will then treat these codes as
special, and exempt them from matching. See
The XTRFCODE.TXT File Format for
- All add-on missions, as well as the PHost
extended missions, should be listed in
VPHost is a "near-substitute" of the HOST/PHost program,
relying upon only a small fraction of HOST's or PHost's
functionality. Almost all other functions are performed within
When you use VPHost, you should invoke PHost with the
-V command line (see below). This flag is necessary
because VPHost removes all TRN files (after making copies in
*.ORG files) and then processes the commands within those files
by itself. Unfortunately, this means that all of the
command processor commands sent by
players are never seen by PHost. The -V flag tells PHost
to look for player*.org files instead of
player*.trn files and to only process command
processor commands from those files (ignoring all other commands,
which will be performed by VPHost).
Back to top
PHost is invoked as follows:
phost [-options] game-directory [root-directory]
The options can contain any number of option letters as
described below. You can merge multiple options if you wish,
-riT is the same as -r -i -T. Options must
precede directory names.
The game-directory and root-directory
parameters specify the game and root directory, respectively. Both
default to the current directory if omitted.
See A Word about File Names for tips for choosing your game
||Print help summary and exit successfully.
Quiet operation. Does not display normal status messages on
screen. They will still be written into host.log.
Errors and warnings will still be displayed. This is useful for
running PHost from a cron job, for example.
Totally quiet operation. Like -q, but
displays nothing at all, not even warnings and errors.
Check-only Mode. PHost will just check the turn file
of the specified player, and display the results. Results will
also be written into check.log.
The player number can be zero to check all players.
Note that turn file checking is also part of normal host
processing. PHost will also check the host data files for
integrity before doing any turn checking.
This option can also be used to check turn files for a
HOST game, to complement HOST's weaker cheat checks.
Read-only Mode. PHost will do all normal host
processing, but not write any hosting files. Turn files will not
be deleted. PHost can be run multiple times with this option
with no ill effects. This option is mainly for testing purposes.
Note that PHost will generate new result files (and
thus overwrite the previous set) anyway.
This option implies -k and -i.
Keep turn files. Normally, PHost deletes all the TRN
files after host processing, because the old TRNs are no longer
meaningful with the new universe data.
Set random seed. The number must be a non-negative
integer which is used to initialize PHost's random number
generator. When PHost is started multiple times with the same
data files, the same TRN files and the same seed, it comes to
the same conclusion. This option is useful for debugging and
for restoring backups.
Note that add-on programs which involve random numbers must also
accept a random number seed to come to the same conclusion.
Turn number random seed. This option behaves like
-S, but uses the turn number as the random
No utilX.dat files. This flag prevents
PHost from writing auxiliary data
files. In the name of your players, don't use it
No INI files. Do not run
Old-style RST files. This flag causes PHost to
generate result files in the "old-style" HOST 3.15 file format.
Those do not include mine scan information, explosions, Ufos,
and race names (all this information is also available in
util.dat, but there it is not visible to
Normally, PHost sends HOST 3.20-style files to Winplan
players, and HOST 3.15-style files to DOS players.
You should never need this switch.
Print turn number. Just print the turn number, on a
line by its own, on standard output.
Print turn timestamp. Just print the time stamp
expected for incoming TRN files, on a line by its own, on
||(lower-case letter "L") Print ship list. Print the ship list on standard
output. No other processing is performed. The ships are listed
in groups of 20, with each group corresponding to a slot in the
truehull.dat file. Each ship has its name, mass,
cargo, mineral cost, etc. displayed, along with any special hull
functions that it can perform. If the special
hull functions are limited to certain players, this
information is also displayed.
This option is useful for generating a ship list report to send
to players when the ship list has been modified by the host. It
is also useful for checking your work when configuring
special ship abilities. This option also
causes a hullfunc.dat file to be
||(two lower-case "L") Print ship list. Like -l, but display ships
with exactly one line per ship on long lines. This makes
postprocessing easier. Special ship abilities are not displayed
in this mode.
Ignore timestamps in turn files. This flag can
be used when restoring a backup.
VPHost in use. When you use VPHost, you should also
use this flag. It causes PHost to look for *.org files
instead of *.trn, and just process
command messages. VPHost does its own
message processing; without this switch, PHost command messages
would not work.
Version info. Displays the version number on
standard output and exits successfully.
Write combat log. Writes a file
combat.log containing information
about all battles this turn. This file is intended to be
evaluated by a battle simulator.
Set config option. This changes the value of a
This switch is mainly intended for use while debugging or
setting up a game. For example, -oConfigLevel=2 will
temporarily set ConfigLevel to 2 so PHost will warn
you even if you forgot an optional setting. When you use this
switch to change an option which also is defined in
pconfig.src, you'll get a warning. This is by
intention; if you wish to make permanent configuration changes,
please do this in pconfig.src instead of using
Log events. This will log events related to
keyword in a file trace.log. See
below for details.
The exit status (errorlevel) is 0 if PHost successfully
performed the function you requested. When you specified
-c, exit status 0 means everything is okay.
PHost returns exit status 1 when there is a permission
problem with the game or root directory, or when you used
-d or -t on a newly-mastered game.
PHost returns exit status -1 when it encountered a different
error (like running out of memory, lacking a file), or when an
internal consistency check failed (that is, you encountered a
bug). Note that -1 is usually mapped to 255 by your operating
When PHost terminates because it received signal X, it exits
with status -X. For example, the interrupt signal (Ctrl-C) has
number 2 and causes PHost to exit with code -2 (mapped to 254 by
the operating system).
When you are checking turn files (-c), a nonzero status
means that something was wrong with the turn file.
||Turn file is missing
||Turn file is stale
||Turn file is truncated
||Turn file is damaged (unknown command)
||Turn file comes from wrong player
||Turn file checksum is incorrect
When you're checking several files at once (-c0), exit
status is the bitwise OR of all matching values. For example, an exit
code of 10 = 8+2 means that at least one turn was stale and one
In order to help hosts debug problems, PHost offers a
tracing capability. This feature is still incomplete;
many parts of PHost have not yet been instrumented. It will,
however, already generate useful information. To use this feature,
specify one or more -L options.
At every time, PHost is in some context. For example,
PlanetaryLosses:planet16 means PHost is currently in the
processing planet 16. You can tell PHost to log events occuring in
particular contexts. An event could look like this:
In this case, the base on planet 16 was removed because the
planet became unowned due to riots.
-Ltype, e.g. -Lplanet requests that all
events on objects of that particular type to be logged. Types
currently in use include
- planet (planet doing something)
- ship (ship doing something)
- target (ship being the target of another ship, e.g. in cargo
- message (message being sent)
- player (something being done to that player, e.g. turn file
-LtypeId, e.g. -Lplanet16 requests that
all events on the specified object be logged. Note that you have
to specify -Lship99 and -Ltarget99 to catch all events on a
-LStageName, e.g. -LPlanetaryLosses
requests all events occuring in the named PControl stage be
logged. Stage names include all names from
PControl as well as a few more.
-Lall requests all events to be logged.
-Ltransitions requests all state transitions to be
logged. This will generate much output, use with care.
Normally, you should keep backups of your game directory.
Ideally, you back up the game directory after each hosting, and
all TRN files just before the next hosting. If something goes
wrong, you can restore the game directory as a whole.
Usually, it suffices to have backups for the last three turns.
Nowadays, disk space is cheap, so you can also back up the whole
When you did not heed the above advice, you can still recover
from partial data loss. You need:
- an older game directory backup
- all TRN files used after that. You probably still have them in
- all host.log files, or, at least, the random number
seeds logged in them
- a pot of coffee
Let's assume your backup is from turn 17. Copy all TRN files for
turn 17 into the game directory, and re-run PHost with the same
random seed which your original turn-18 host.log
says. For example, you could use phost -s 13285 gamedir.
You now have a game directory which is in turn 18 which is
identical to the original turn-18 game directory except for the
Copy all turn-18 TRN files into that directory, and re-run PHost
with the original turn-19 random seed. You need the -F
flag this time, otherwise PHost will complain about files being
stale. Repeat these steps while drinking the coffee, until you are
at the turn you wished to restore. Good luck.
This only works when you use the very same PHost
version to re-run each turn which you used to run it in the first
place. This also only works when you do not use add-ons that
themselves include random actions.
You can also replace the coffee by another beverage of
your choice. Do not use whiskey, though, that will cause you to
When PHost is invoked, it performs a host file check.
Inconsistencies are reported and fixed.
- Problems with the game data files are corrected. For example,
if a ship has an intercept order for another ship that was
deleted (for example, using Killrace), that order will be canceled.
PHost will use the new value for its host run.
- Since version 4.1a, PHost starts implementing ship list
file checks. If one of these files has an invalid value, PHost
corrects the value internally and uses that for the host run.
However, PHost never updates the disk files. For
example, if a ship is stored in the hullspec.dat as
having a maximum crew of 0, PHost uses a value of 1 internally,
because a ship without crew cannot exist.
You should correct the specification files in this case.
Currently, the game data files are only checked once, when
PHost starts. PHost "trusts" all add-ons run through the
PControl mechanisms. If one of these
programs messes up game data files too bad, PHost may crash.
Back to top
Last updated 31 May 2015.