[PHost Logo]© 

Hosting with PHOST
The Portable Host



This document describes the various issues that a host using PHOST may need to consider. It is assumed that the host is familiar with hosting VGA Planets games, as this document does not attempt to serve as an introduction to the game or to the hosting process.

Back to the index 

Program Requirements

Note: PHOST's requirements also depend on the compiler it was compiled with.

Windows Platforms

PHOST runs on all 32-bit Windows platforms including Windows 95, Windows NT, and Windows 3.1 in enhanced mode with a 32-bit DPMI server. It is a console-mode application, however, so it must be run in a DOS box. At least a 386-class machine is required.

Under Windows 3.1, the Borland C-compiled version requires the 32-bit DPMI server and support files[Remote] from the PHOST WWW page. Follow the installation instructions in this package.

DOS Platforms

PHOST will run on a non-Windows PC machine with an appropriate DPMI server installed.

Borland C: Download the necessary support software[Remote] from the PHOST WWW page. Follow the installation instructions in this package. ==> You do not need to run Windows to run PHOST 3. You do, however, need at least a 386-class machine.

DJGPP: The DJGPP distribution archive contains a DPMI server cwsdpmi.exe which is automatically used by PHOST when needed.

Unix Platforms

Unix distributions now include a binary you can directly run. You need no longer manually link PHOST. Please make sure that your operating system is similar to the one PHOST was compiled on before reporting problems: a SunOS 4 system will surely not run Solaris 2.7 programs.

Back to the index 



In the remaining text we will always assume that there are two directories of interest: It is possible that the game directory and the root directory are the same but it is far more common to create subdirectories for each separate game and to place game-specific files in the game directory.

The PHOST programs (PHOST and PVCR) accept two command-line parameters that specify the game directory and the root directory (in this order). If these parameters are not specified, then the current directory is used. For example

PHOST /games/planets/game1 /games/planets
runs PHOST on the specific game in the game1 subdirectory of the main Planets directory /games/planets. If the root directory is not specified,
PHOST game1
then the root directory is assumed to be the current directory from which the program was invoked.

Installing the Files

All of the files (except for one) that come with the PHOST distribution are to be placed in the main directory (or for executables, on your path). The exception is the PCONFIG.SRC file. This file contains configuration information for each game (see the "Configuration Parameters" page) hence it belongs in the game directory. The PCONFIG.SRC files provided in the distribution are only example configurations that you can modify to suit the characteristics of the game you want to host.

Note that you need not run the programs from the main directory, as is common with many DOS-based VGA Planets programs. These other programs all expect to find global data files (*.DAT files and others) in the current working directory hence they all expect to be run from the main directory. PHOST programs all accept full pathname specifications for both the game and main directories and may therefore be run from any directory.

The Language Files

The main file that contains the PHOST language database is called PLANG.HST. PHOST expects to find this file in either the game directory or root directory. There are variations on this theme, however, that the host should be aware of: Back to the index 

Starting a Game

If you know how to master and set up a HOST game, then you know 99% of what you need to do to host a PHOST game. The only difference is in the configuration. PHOST expects to find a PCONFIG.SRC file in the game directory containing the configuration parameters for the game. PHOST does not make use of the HCONFIG.HST file generated by the original HCONFIG program.

Other things to note when starting a game:

Back to the index 

Running a Game

Once your game has started, you simply use the PHOST program to run a new turn, just as if you would normally use the HOST program. Some other points to note, however: Back to the index 

Upgrading From PHOST 2.x

==> You cannot upgrade from PHOST v2.4 or earlier to PHOST 3. You must first upgrade to the latest PHOST v2.x version and then upgrade to PHOST 3.

If you want to upgrade an existing PHOST 2.x game to PHOST 3, follow these general steps:

Back to the index 

Command Line Options

Normally, you needn't specify any command line options to PHOST. In special cases, however, you may wish to modify PHOST's behavior. The command-line options that are available to do this are described below.
Option Function
-q Quiet Operation 
The -q option prevents PHOST from displaying status information on the screen as it executes. Warnings and errors are still displayed as necessary. This option does not prevent PHOST from writing all messages to the HOST.LOG file so all information is still available in this file for review. This option is useful for spotting warnings and errors, since these tend to get lost in the clutter of the progress messages. 
-Q Really Quiet Operation 
This option is like a stronger -q option. It prevents all messages from being displayed on the screen, errors and warnings included. As before, all messages will still be written to the HOST.LOG file regardless of the -q and -Q flags. 
-c player Check-Only Operation 
This option runs PHOST only as a turn file checker. The player argument to this option specifies the player whose turn file is to be checked. If this argument is 0, then all turn files in the game directory are checked. See the section on Turn File Checking below. With this option, PHOST only checks turn files before exiting. Turn files are not deleted and no game files are modified. 

A file named CHECK.LOG is generated in the game directory which summarizes the result of turn file checking. 

Note that turn file checking is also a normal part of PHOST operation. In addition, PHOST checks the game data files for integrity before checking any turn files. 

==> This flag can be used to run PHOST as a turn file checker even for games which are being hosted by HOST. 

-r Read-Only Operation 
This option causes PHOST to perform all normal turn processing but no game data will be written to disk. That is, the *.HST files are not overwritten. Any *.TRN files in the game directory are not removed. Note that *.RST files are generated even when this option is present. PHOST can be run multiple times with this option with no ill effects. This option is useful for testing purposes. 

Specifying the -r option automatically implies the -k and -i options.

-k Keep *.TRN Files 
Normally, after PHOST runs, all *.TRN files in the game directory are deleted. This option causes *.TRN files to be preserved. This option is useful for debugging. 
-s seed Random Seed 
This option takes a single non-negative integer argument which specifies the starting random seed for PHOST. When PHOST starts with the same game data files and the same *.TRN files, specifying the same random seed on multiple runs causes PHOST to run to the exact same conclusion. This option is useful for debugging and for a particular backup strategy using the -F flag. 

Note that any add-on or other programs being used that may affect game data must also be able to accept a starting random seed for the same conclusion to be reached. 

-S Turn Number Random Seed 
This option causes the current turn number to be used as the random seed for PHOST. If this option is used, then re-running turns is more convenient (if the same outcome is desired) since the random seed is deterministic. This option is useful for debugging. 
-u No UTIL.DAT Files 
This flag prevents PHOST from creating the auxiliary data player files (UTIL*.DAT, see the "Auxiliary Data Files" page). For games in which these files will not be sent to players, this option allows PHOST to run slightly faster. 
-i No INI-Files 
This flag prevents PHOST from executing any INI-files. This includes the AUXHOST.INI files, as well as any INI-files that are specified via the fine-grain hosting interface. This flag is automatically implied when read-only operation is selected (with -r).
-T Generate Old-Style RST Files 
This flag causes PHOST to generate RST files that are in the same format as RST files generated by HOST 3.15. Without this flag, the RST files are in HOST 3.2 format. Specifically, using this flag causes PHOST to exclude mine scan information, ship explosion information, UFO.HST information, and the RACE.NM file in the RST file. Note that HOST 3.2-compatible RST files are only sent to registered WinPlan players. DOS Planets players, and shareware WinPlan players always receive old-style RST files (HOST 3.15-compatible). 
-t Print Turn Number 
This option causes PHOST to simply print the current turn number (on stdout) and exit. No other processing is performed. This may help some script and/or batch files in managing backups and other activities. If the turn number was successfully displayed, PHOST returns with an exit code of 0, otherwise PHOST returns with an exit code of -1 (and there may be other text displayed on stdout). 
-d Print Time Stamp 
This option causes PHOST to simply print the current turn timestamp (on stdout) and exit. No other processing is performed. This may help some script and/or batch files in managing backups and other activities.
-l Print Ship List 
This option causes PHOST to display the list of ships it is using (on stdout) and exit. 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 (using the HULLFUNC.TXT interface) then 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 writing or modifying a HULLFUNC.TXT file.

When specified twice, i.e. phost -ll, PHOST uses a slightly modified output format with exactly one line per ship. Special hull functions are not displayed in this mode.

-F Ignore Timestamps in TRN Files 
This option is potentially very dangerous and must be used with care. Specifying this option causes PHOST to ignore the timestamp present in *.TRN files. This option is necessary for restoring games from backups when only *.TRN files are stored. There are no other instances for which this option should be specified.
This flag causes PHOST to look for PLAYER*.ORG files instead of PLAYER*.TRN files, and to only process command processor commands from these files. All other information in the TRN file is ignored. This flag supports the use of VPHOST with PHOST (see the Hosting with VPHOST section below). 
-v Version Info 
This option causes PHOST to display its version information and then to exit immediately. No host processing is performed. 
-C Write Combat Log 
When doing combat, PHOST will write out a log file combat.log containing more detailed information on the battles. This file is intended to be evaluated by battle simulators.
-o option=value Set config option 
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.

Back to the index 

Turn File Checking

PHOST contains an integral turn file checking algorithm. During host processing, turn file checking occurs automatically. It is often desirable, however, to check turn files prior to hosting in order to allow turn file anomalies to be investigated and corrected as quickly as possible. The PHOST command-line option -c allows PHOST to perform this checking function without performing any other hosting functions.

The -c option requires a parameter to follow it, indicating the player number whose turn file is to be checked. For example,

PHOST -c 3 gamedir
will check the file PLAYER3.TRN in the game directory. If the player number is specified as 0, all players are checked.

Turn files are checked for a variety of problems such as staleness, bad commands, cheating, etc. Any problems are reported and PHOST exits without modifying the game files and without removing the *.TRN files. PHOST also returns an error code corresponding to any problems it finds. This makes PHOST suitable for use in a batch file or script which uses PHOST's return value to automatically take appropriate action. The return error codes are as follows:

Return Code Turn Check Result
Turn file has no errors
Turn file is missing
Turn file is stale
Turn file is too short (premature EOF)
Turn file is damaged
16  Turn file is from the wrong player
32  Turn file checksum is incorrect
64  Turn file has caused Yellow Alert
128  Turn file has caused Red Alert

When multiple turn files are checked (player number is 0), the return code represents a summary of all anomalous conditions and may consist of one or more of the above values OR'ed together. For example, a return code of 1 when checking all players means that at least 1 player's turn file is missing. A return code of 10 means that at least 1 player submitted a stale turn file (code 2), and at least one player submitted a damaged turn file (code 8).

Note that turn file checking also includes a step in which the host data files are checked for integrity. Thus, error messages may be generated which do not relate directly to the turn files being checked. These messages will be present in the CHECK2.LOG file generated by PHOST but not in the CHECK.LOG file, which is otherwise identical to CHECK2.LOG. Checking the host data files can sometimes reveal information about other players (such as positions of their bases) and this information should not be revealed to other players. Thus, the CHECK.LOG file is suitable for sending to players as a pre-host-run turn check, while the CHECK2.LOG file is suitable for review by the host.

Turn File Checking Details

Most of the status reports for turn files described above are self-explanatory. Return codes 4 and 8 (turn file too short or turn damaged) usually imply that a file transmission error has occurred and the turn file cannot be reliably interpreted. Return codes 16 and 32 may signal that cheating has been attempted although these, too, may be the result of a file transmission error. This leaves yellow alerts and red alerts as the most common reports for players trying to cheat.

A yellow alert means that the turn file is somehow invalid and the commands which are judged to be in error are simply ignored. A red alert is more serious as it is only reported when there is good evidence that an intentional attempt to cheat has been detected.

Here is a brief description of how the above error codes may arise:

In summary, a red alert is raised only if it is clear that the player is intentionally trying to cheat. If there is any possibility that the bug was caused by DOS Planets or an external utility, then a yellow alert is raised. A yellow alert also occurs if a problem is discovered that is not to the player's advantage.

Back to the index 

Turn File Histories

PHOST writes turn file status information to a file named TURNSTAT.LOG in the game directory after each host run. If this file doesn't already exist, it is created. This file summarizes the status of submitted TRN files for the duration of the game. A host can use this file to see at a glance which players are delinquent in submitting turns or which players consistently submit bad turns. The TURNSTAT.LOG file contains a legend which explains the symbols used to indicate turn file status history.

Back to the index 

Alternative Ship Lists and Maps

PHOST is very friendly when it comes to using alternative ship lists or custom planet layouts. The key behind this is the order in which PHOST looks for its data files. The order is as follows:
  1. All game-specific files are expected to be found in the game directory only.
  2. All specification files (usually common to many games) are searched for:
The specification files referred to in point 2. above are the following: Back to the index 

Maps with Fewer Than 500 Planets

It is possible to create a planet layout with fewer than 500 planets. Map-generator programs such as NEW_MAP[Remote] do this by placing the excess planets at faraway locations (for example, at locations with an X-ordinate of 0 or 4000). This is the recommended method for hosting with fewer than 500 planets.

==> Make sure to check your newly-created map's checksum using a verification program such as MAPCKSUM[Remote] as NEW_MAP can sometimes generate unusable maps.

If a wraparound map is being used, then you may well wonder how planets with an X-ordinate of 0 or 4000 are handled with respect to re-mapping. The key point to remember is that any planet outside of the wraparound region is considered to be non-existent by PHOST. Thus, planets outside the wraparound region will not be mapped into the wraparound region, they will simply be ignored throughout the game.

Back to the index 

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

PHOST uses the -V command line flag to support hosting with VPHOST. 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 the index 

Additional Special Friendly Codes

Add-on or external programs sometimes introduce new special friendly codes to implement new behavior. PHOST's handling of special friendly codes with respect to matching (i.e., special friendly codes never match) is a simple and consistent rule for players to follow, but it does not take into account any friendly codes introduced by add-on programs. PHOST implements a mechanism, however, that allows it to recognize an add-on's new friendly codes as being special for the purposes of matching.

To implement this mechanism, PHOST makes use of a file in the game or root directory named XTRFCODE.TXT, if it exists. This file should contain a list of friendly codes that PHOST is to consider special and will therefore never allow to match (not for combat, not for gathering minerals at planets, etc.) The format of this file is free-form, it may contain tokens of up to 3 characters each (representing friendly codes) interspersed with any amounts of white space. Each friendly code is case-sensitive. If the friendly code contains N characters, where N is less than 3, then a ship or planet's friendly code is considered special if it matches just the first N characters.

For example, if the XTRFCODE.TXT file contains:

then friendly codes of BJG, AJG, RJG as well as any friendly code that begins with J are considered special and will never match another friendly code. The above example may be suitable for use with the JUMPGATE add-on (although the J code is overly broad).

Here is another example XTRFCODE.TXT file that may be used with the RacePlus add-on:

Finally, another example XTRFCODE.TXT file that may be used with the FHOST add-on:
Note that players can obtain the contents of the XTRFCODE.TXT file by sending a send fcodes command processor command. The host should still be responsible for creating this file, for making its contents known to players, and for making sure the players understand its implications.

Back to the index 

Non-Standard Race Assignments

PHOST allows any player to play any race in the game. This is accomplished with the PlayerRace config option. This option has 11 entries, with each entry specifying the race that the given player is to play. For example:
PlayerRace = 1,1,1,1,1,6,6,6,6,6,6
has players 1 through 5 playing The Federation, and players 6 through 11 playing The Borg. A race value of 12 is also accepted, meaning that the given player will have no special racial abilities.

In the client program, the special mission listed for each race will not change, so the player needs to remember that his special mission may be different, depending upon his race assignment. For example, if player 4 selects the special mission on one of his ships then the client program will show the mission as Pillage. But if player 4 has been assigned race 5, then the ship will actually perform the Rob mission. Using the Special Mission extended mission can bypass this confusion. ==> It is suggested that players edit the MISSION.INI file to have the Special Mission extended mission reflect their true special mission, and use this extended mission instead of the usual one.

The ship list that a player sees (on the host side) is controlled by the MapTruehullByPlayerRace config option. With this config option enabled, changing the value of a PlayerRace setting also changes the ships that the player can build.

==>  NOTE: This option should only be enabled if all players in a game are using VPA.

For example, if player #1 is given race #9 and MapTruehullByPlayerRace is enabled, then player #1 will be able to build ships normally available to race #9 (i.e., Robotic ships). Setting MapTruehullByPlayerRace to No allows more control over the ship list available to each player. In this case, each player can not only have their own race assignment, but their own individual ship list, even if two (or more) players are playing the same race. Please see the description of the MapTruehullByPlayerRace config option for more details.

To put it simply, if you are not customizing a ship list and you simply want to change races around while keeping the ship lists consistent with race assignments, just set MapTruehullByPlayerRace to Yes. This also requires that all players in your game are using a client program (currently, only VPA) that recognizes the MapTruehullByPlayerRace option.

Finally, it must be remembered that some special functions are linked to ships themselves, and not to the race that owns them. Gravitonics, for example, is an ability of a ship's hull not of the owner race. The PlayerRace config option only deals with race-related abilities, not ship abilities. Other ship functions which are not affected include hyperwarping, cloaking, terraforming, tachyon anti-cloaking, chunneling, bioscanning, Imperial Assault, glory devices, and ramscoops. Note that all of these functions can be disabled via other configuration options. In addition, the HULLFUNC.TXT interface can be used to modify the hulls that are capable of performing special functions and the players that are allowed to use them.

The special abilities that are controlled by the PlayerRace config option are as follows:

Back to the index 

Non-Standard Special Hull Functions

The adventurous host is given a large amount of flexibility in PHOST with respect to crafting a custom ship list. The HULLFUNC.TXT interface in PHOST 3 allows a host to have complete control over which ships can perform special functions (like cloaking, hyperwarping, etc.) and which players are allowed to use those functions. This interface offers a large amount of flexibility for setting up custom scenarios or designing PHOST-specific alternative ship lists. Please follow the link to the HULLFUNC.TXT interface for more information.

Back to the index 


Wormholes are implemented by an addon-type feature that is built in to PHOST. Wormholes allow players to move great distances over a single turn. This can make "dead corners" of a universe map more accessible, or connect homeworlds together in a team game, for example. Or they may be treated as random, moving events to "shake things up". For more details, please see the "Wormholes" page.

Back to the index 

Wraparound Maps

PHOST can implement a true wraparound map, much like the external add-on programs PWRAP and Sphere, except that PHOST reaches beyond the limitations of those programs to allow everything to wrap around. This includes minefields, sensor sweeps, ship scans, etc. For more details, please see the "Wraparound Maps" page.

Back to the index 

Using AUXHOST Addons

Many addons these days take advantage of the AUXHOST1.INI and AUXHOST2.INI hooks provided by the HOST program. PHOST 3 also supports these hooks, and then takes things one step further by allowing fine-grain hosting control.

PHOST versions 2.x used a phasing system to execute AUXHOST programs, but this has been eliminated in PHOST 3. The AUXHOST programs may be installed in the same way as they would be for HOST. Unlike HOST, however, PHOST gives AUXHOST programs the full amount of memory available under DOS. That is, PHOST does not keep itself in lower memory, like HOST does. As a result, AUXHOST programs have as much as 320K more memory to work with than under HOST.

Back to the index 

Compatibility with HOST Alliances

PHOST alliances are different from HOST alliances, but there are some add-on programs that only recognize the latter. To enable these add-ons to work with PHOST, a compatibility mechanism has been implemented in PHOST 3.

HOST alliances are recorded in the GREY.HST file. PHOST 3 will write a HOST-type alliance offer in this file whenever a player has offered all five alliance levels to another player, just as if the player had used an ffX friendly code. This mechanism is one-way, however; PHOST will only write to the GREY.HST file, it will not incorporate any changes to this file into its own internal alliance states.

For more details, please see the Host Alliance Compatibility section of the "Alliances" page for more details.

Back to the index 

This document is maintained by The Portable Host Project[Remote] (support@phost.de).

Last updated 7 December, 2001