PHost - Hosting with PHost

Index

• Overview
• Installing PHost
  • Upgrading from an Older Version
• Setting up new Games
  • Configuring the Game
  • Special Maps and Ship Lists
  • Generating the Universe
  • Add-ons
• Invoking PHost
  • Command Line Option Summary
  • Exit Code
  • Tracing
  • Backups
  • Host File Check

Overview

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.

Back to top

Installing PHost

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

Upgrading from an Older Version

Upgrading from 4.x

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.

Upgrading from 3.x

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.1 in config/upgrade.src.

Upgrading from 2.x

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

Setting up new Games

Configuring the Game

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.

The Classic Way

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.

Special Maps and Ship Lists

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:

• hullspec.dat: starship hulls
• engspec.dat: engines
• beamspec.dat: beam weapons
• torpspec.dat: torpedoes
• 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.

Generating the Universe

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

Add-ons

Calling Add-ons from PHost

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.

Special Friendly Codes and Missions

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 details.
• All add-on missions, as well as the PHost extended missions, should be listed in mission.ini.

VPHost

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

Back to top

Invoking PHost

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

Command Line Option Summary

-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. This option can also be used to check turn files for a HOST game, to complement HOST's weaker cheat checks.
-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 utilX.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. This option also causes a hullfunc.dat file to be written.
-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.

Exit Code

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.

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.

Tracing

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.

• -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 transfer)
  • message (message being sent)
  • player (something being done to that player, e.g. turn file being read)
• -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 particular ship.
• -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.

Backups

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:

• an older game directory backup
• all TRN files used after that. You probably still have them in your mailbox.
• 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 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.

Host File Check

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