![]() |
Hosting with PHost
|
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 glossary.
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.
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 or starchart.
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 formats.
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 configuration accordingly.
For your convenience, we have included a list with all new options added between PHost 3.4c and 4.0 in config/upgrade.src.
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.
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 as shiplist.txt.
Edit the pconfig.src file to suit your taste. All possible configuration options are described on the configuration page.
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 directory.
Files affected by this are:
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.
You can also use a hosting editor to manipulate the universe after mastering it.
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 add-on goes.
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.
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 VPHost itself.
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).
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.
The game-directory and root-directory parameters specify the game and root directory, respectively. Both default to the current directory if omitted.
-h | Print help summary and exit successfully. |
-q | 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. |
-Q | Totally quiet operation. Like -q, but displays nothing at all, not even warnings and errors. |
-c player |
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. ![]() |
-r |
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. |
-k | 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. |
-s number |
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. |
-S | Turn number random seed. This option behaves like -S, but uses the turn number as the random seed. |
-u | No UTIL.DAT files. This flag prevents PHost from writing auxiliary data files. In the name of your players, don't use it :-) |
-i | No INI files. Do not run PControl or Auxhost programs. |
-T |
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
Winplan). 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. |
-t | Print turn number. Just print the turn number, on a line by its own, on standard output. |
-d | Print turn timestamp. Just print the time stamp expected for incoming TRN files, on a line by its own, on standard output. |
-l | (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 |
-ll | (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. |
-F | Ignore timestamps in turn files. This flag can be used when restoring a backup. |
-V | 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. |
-v | Version info. Displays the version number on standard output and exits successfully. |
-C | 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. |
-o option=value | Set config option. This changes the value of a configuration option. 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 this switch. |
-L keyword | 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 system.
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.
Value | Meaning |
---|---|
1 | Turn file is missing |
2 | Turn file is stale |
4 | Turn file is truncated |
8 | Turn file is damaged (unknown command) |
16 | Turn file comes from wrong player |
32 | Turn file checksum is incorrect |
64 | Yellow alert |
128 | Red alert |
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 was damaged.
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 PlanetaryLosses stage processing planet 16. You can tell PHost to log events occuring in particular contexts. An event could look like this:
PlanetaryLosses:planet16:base removed |
In this case, the base on planet 16 was removed because the planet became unowned due to riots.
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 game.
When you did not heed the above advice, you can still recover from partial data loss. You need:
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 timestamp.
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
mis-type numbers.
Last updated 03 September 2006.