PHost - Technical Information

Index

• Introduction
  • General Tips
• Turn Files
  • TacCom
  • Command ordering
  • Build Orders
  • Error Recovery
  • SendBack
  • Modified Costs
• VCR Files
  • Identification
  • PlayerRace
  • Hulls
  • Experience
  • Summary
• Other Files
  • utilx.dat
  • util.tmp
  • tons.hst
  • plang4.hst
  • shipscan.ext
  • combat.log
  • hullfunc.dat
  • Additional Files
  • Unused Files
  • A Word about File Names

Introduction

This document is intended for programmers. It describes the known technical differences between HOST and PHost. People who are writing client-side or host-side programs will get useful hints from this file for making their program PHost-aware and use PHost features optimally. Players usually do not need the information from this file.

General Tips

When you are writing a host-side add-on for PHost, you should definitely have a look at the PHost Development Kit (PDK). The PDK encapsulates all the logic of accessing host data files, so you can start concentrating on your add-on, not on boring things like file I/O. The PDK's goal is to be compatible with Tim's host, but probably does not yet deliver 100% compatibility. Another goal is to provide full access to all PHost specialties, but that goal has not been reached yet as well.

In any case, you should have a look at the File Format List. This list contains a complete description of almost all Planets-related file formats, for HOST and PHost. It was compiled by Stefan Reuther (now a PHost author) mostly by reverse-engineering, so it generally provides you with a more critical view than official PHost docs ;-)

Back to top

Turn Files

There are some differences between PHost's and HOST's turn file handling. Essentially, PHost accepts everything maketurn.exe and Winplan make, so if your program does the same, all is fine.

TacCom

PHost does not support TacCom-enhanced turns (turns with attachments). Actually, these are turn files embedded in a special container, along with TacCom's files, which HOST will unpack before using. PHost does not include such an unpacker, hence it will reject TacCom-enhanced TRN files as being stale or damaged.

Command ordering

PHost needs turn files to be tightly packed, without gaps between commands. Essentially, it ignores the command pointers in the TRN header. If you send commands with gaps, PHost will get confused. (Note that this is considered to be a misfeature and will probably be changed someday. Still, it doesn't have high priority - why? the system works :-) There's only one small problem: the PlanetBuildBase command (34) has an irregular format, some people simplify their Maketurns by making it regular and including an additional data word. This works with HOST, but does not work with PHost!

PHost versions below 3.3b could get confused when you don't send commands in the canonical order (ships in Id order, planets in Id order, bases in Id order, messages, password; commands for each object in command Id order). PHost versions above that can recover from this problem, but up to 3.4a, they might shuffle messages around in return. Version 3.4b and later use The Right Way(tm).

Build Orders

Normally, a Maketurn program sends a BaseBuildShip command (53) whenever the build order on a starbase changes. Some Winplan versions, however, send the command if (and only if) a build order is present, no matter whether it changed; they do not send any command when the player cancels the build order.

PHost includes a workaround for this bug: whenever it detects a registered Winplan client, and there is no BaseBuildShip command for a starbase, PHost assumes that the ship build order on that starbase was canceled and cancels it in the host files, too (with HOST, these Winplan versions can not cancel build orders at all).

Your maketurn must therefore, if it generates Winplan-style turn files, send a BaseBuildShip command for every active build order to keep it active and prevent PHost from canceling it. The best solution which works with every existent host is to send a BaseBuildShip for every active order, and for every changed (or canceled) order.

Error Recovery

Unlike HOST, PHost does not include heuristics for recovering from Xmodem transfers.

SendBack

PHost 4.0 includes a new TRN command, SendBack (62).

 +0     WORD    Receiver race
 +2     WORD    Record Type
 +4     WORD    Data Size
 +6   n BYTEs   Data

This will copy the specified data (including record type and data size) verbatim into your util.dat. The receiver race must currently be 0 or identical to the TRN file sender, both meaning that the data is being sent back to the sender. This feature may be expanded to allow you to send data to other players someday. The main use of this command is to allow clients to "store" their auxiliary files in the TRN, using file transfer records (type 34). PHost does not interpret the data in any way. The upper limit for the size is 32000.

Modified Costs

PHost 4.0k and later allows hosts to configure certain costs that were previously hardwired (for example, StarbaseCost). These costs are also hardwired in current Planets clients. To submit a correct turn, the client must use the changed costs when it performs an action affected by this change.

PHost implements no error recovery for these cases. If the configured starbase costs are higher than the standard 402T/120D/340M/900$, players receive a red status when handing in their turn. PHost does not try to detect and correct this mistake.

Essentially, this is the same behaviour as if you were using a modified ship list. It brings a new quality of the problem, though, because players cannot fix these problems by merely installing the correct data files - they have to get an updated client.

For protection, we have added the AllowIncompatibleConfiguration option. Hosts must explicitly enable this option before being allowed to configure a game incompatible this way.

Back to top

VCR Files

This chapter describes how VCR files created by PHost differ from those of HOST. Basic knowledge with the VCR file format is assumed.

Note that the files differ not only in contents, but also the algorithm required to play them is different.

Identification

To distinguish PHost and HOST VCR files, PHost files contain a magic number. In HOST, the first word of a battle record is the initial random seed (ranging from 1..111) and the second one is zero. In PHost, the first word is the seed (full 64k allowed), and the sum of the first and second word is 48879 (mod 65536). This is called the PHost signature and is present on at least the first battle in a file.

In PHost 1.x and 2.x, all VCR files that contain combat recordings will also contain a configuration record. The exact format is documented in the PHost 1.x/2.x documentation and in the File Format List. Programs should not try to interpret this record as an actual battle. This configuration record is not sent by PHost 3.x and 4.x.

Because VPA misidentifies vcrX.dat files with only one battle, there is a program Corr that corrects the situation by adding a dummy battle. You probably want to detect that, too.

• If the first battle does not bear the PHost signature, it is HOST combat.
• If the file contains only one battle, it is PHost 3.x/4.x.
• If the file contains two battles, and the owner fields of battle 2 are zero, user has used Corr. The file contains one PHost 3.x/4.x battle, and one dummy record.
• If the file contains two or more battles, and the last battle contains the PHost signature:
  If the BattleType field is one or zero, it is a vcr.hst file. You can't tell the version from those.
  If the BattleType field is larger than one, it is a player-side vcrX.dat file from PHost 1.x/2.x.
• Everything else is PHost 3.x/4.x.

For upward compatibility, PHost 4 reports a set of capabilities which a player program needs to replay the VCR. The capability flags are stored in the first record, in the field commonly called "planet temperature" which is not used otherwise by PHost.

• bit 15 is set to indicate the field is valid.
• bits 14..3 are clear. If they are not clear, the recording needs a feature not yet known and can't be played.
• bit 2 is set if the game is configured in a way that it is played differently between PHost 4.0k and later, and previous versions.
• bit 1 is set if the recording needs Experience support.
• bit 0 is set if the recording needs support for Death Ray weapons or ShieldKillScaling.

If bit 15 is clear, treat this word as all-zero. When none of bits 0 to 14 are set, the recording is 100% compatible to PHost 3.x.

PlayerRace

In games with nonstandard PlayerRace setting, the Owner fields contain the race number in the high byte of the owner field, if it differs from the owner. That is, player 2 playing Lizards will be reported normally as "owner 2"; if he plays Privateers, he will be reported as "owner 0x502".

Hulls

A shortcoming of the VCR file format is that the hull number is not included, so you don't know immediately whether you're fighting a Merlin or a Super Freighter. PHost transmits the hull number in the high byte of the picture number. For example, the Merlin (hull 105 = 0x69, picture 33 = 0x21) will be reported as "picture 0x6921".

Experience

Experienced ships and planets have their experience level reported in the high byte of the beam count field. Possible values range from 0 to the value of NumExperienceLevels. Note that the experience reported in the VCR might differ from the one reported in util.dat; the ship might have got promoted after the fight.

Summary

Putting it all together, a VCR record looks like this:

WORD      Random number seed
WORD      PHost: signature; HOST: 0
WORD      PHost: capabilities; HOST: planet temperature
WORD      Battle type (0=s/s, 1=s/p)
WORD[2]   Left and right mass
OBJ[2]    Left and right object, see below
WORD[2]   Left and right shields

Each object has the following format:

BYTE[20]  Name
WORD      Initial damage
WORD      Crew
WORD      Id
BYTE      Player number
BYTE      PHost: Race, 0 if same as player [*]
BYTE      Picture number
BYTE      PHost: Hull number [*]
WORD      Beam type
BYTE      Beam count
BYTE      PHost: experience level [*]
WORD      Fighter bays
WORD      Torpedo type
WORD      Torpedo/Fighter count [**]
BYTE      Torpedo launcher count
BYTE      PHost: Torpedo count [**]

[*] = These fields are 0 if HOST or an older version of PHost are used

[**] = When the object is a planet, and PlanetsHaveTubes is enabled, the first field contains the number of fighters and the second one the number of torps. In all other cases, the unit has only one secondary weapons, so the first field contains the number of torps/fighters and the second one is zero.

Back to top

Other Files

utilx.dat

This file is described in great detail in its own documentation file.

New programs should definitely support util.dat instead of just doing message scanning; util.dat is much more reliable and flexible.

util.tmp

This file exists only during a host run. It contains the future util.dat files' contents, just like mess.tmp contains messages that will be in the RSTs.

Like util.dat, this file is structured in records. In PHost 3.4 and above, the format is as follows:

 +0     WORD    Player Id (whose UTILx.DAT file will contain this data)
 +2     WORD    Record Type (like in UTILx.DAT)
 +4     WORD    Record Length
 +6   n BYTEs   Data

tons.hst

In PHost 3.4b and later, this file contains 4x11 longs, not just 2x11 like before.

 +0  11 DWORDs  Sum of sunk ships (total masses destroyed by player)
+44  11 DWORDs  Sunk tonnage this turn
+88  11 DWORDs  Sum of lost ships (total masses lost by player)
+132 11 DWORDs  Lost tonnage this turn

plang4.hst

Since PHost version 4.1/3.5, The file plang4.hst is a file in standard ar(1) file format. ar(1) is the Unix librarian, generally used to generate software libraries, but also used to generate Debian packages. ar(1) was chosen for its low space and complexity overhead.

plang4.hst contains files with the names language.phl. The language part is limited to 8 characters, that is, the "NewEnglish" language is stored in a file newengli.phl. When looking for a language, PHost first looks in the game and root directories, then in plang4.hst.

This allows easy extension to new languages: if someone requests his language be changed to Kisuaheli, PHost looks for a file kisuahel.phl.

For backward-compatibility, PHost accepts a few abbreviations for language names. This list of abbreviations is fixed, new languages do not have abbreviations. See the description of the language command for details.

If you are short on disk space, you can extract the languages you want to use, and delete plang4.hst. Alternatively, remove the unused languages from plang4.hst using a command such as ar d. The English language, english.phl, must always be available, either within plang4.hst, or as a separate file.

Earlier PHost versions look for their language database also under the names plang.hst and plangeng.hst; PHost 4.1 only looks for one file name. The old language database also had a very different, heavily encrypted format.

shipscan.ext

PHost 3 and later write a file named shipscan.ext during hosting phase 3. This file is generated by PHost but is not otherwise used by PHost. It is meant to benefit add-on programs by indicating which ships were scanned by whom during the current turn. It is a plain-text file with the following format:

• The first line contains the turn number as a decimal integer, a space, and an 18-character time stamp for the current turn. The purpose of this information is to allow add-on programs to check that the shipscan.ext file does indeed correspond to the current turn (the time stamp and turn number should match the information in the lastturn.hst file).
  Note that PHost versions before 4.0k/3.4m write the previous turn number and timestamp to the file, especially the timestamp is useless because it is at that time not stored anywhere else. Since 4.0k/3.4m, PHost uses the same turn number and timestamp as stored in lastturn.hst. In addition, PHost before 4.0 updates lastturn.hst too early, causing the number to be off by two during the host run.
• Following the first line is one line per ship slot (i.e. 999 in PHost 4, 500 in PHost 3, independently of the NumShips configuration option). Each of these lines contains two decimal numbers separated by a space.
  • The first number is a bitfield of players who see the ship regularly via ScanRange, or via the show command.
  • The second number is a bitfield of players who see the ship by means of a ship level alliance granted by the ship owner (or, because he actually is the ship owner).
  In each of the values, bit 1 means player 1, bit 2 means player 2, and so on. Bit 0 is unused. The two bitfields are mutually exclusive. If someone sees the ship regularly and because of an alliance, only the alliance bit is set.

If a ship does not exist, its line contains 0 0. No existing ship can have a second value of 0.

combat.log

When the -C command line option was specified, PHost will generate a file combat.log. This file is intended for use by combat simulation programs. Programs can set up a game universe, run PHost on it, and read combat.log to obtain useful information.

The file contains three lines for each battle in vcr.hst. For example:

15 s 22
d 40 0 9 100 0 51 0 0.0 0.0 0.0 33.5 102.9 44.2 36.4 0.0 55.4 0 0
v 1300 84 6 0 0 255 0 0.0 0.0 0.0 0.0 4.9 0.0 0.0 11.1 0.0 0 0

The first line identifies the battle, by stating the Id number of the left object, the type of the right object (s=ship, p=planet), and the Id number of the right object. The left object always is a ship.

The following two lines state useful information on the left and right objects. In order:

• Status: v=victory, c=captured, d=destroyed, n=out of ammo
• Crew (at end of battle)
• Shields (at end of battle)
• Owner (original)
• Damage (at end of battle)
• Number of surviving fighters
• Number of remaining torpedoes
• Minimum fighters aboard the unit during the fight
• Three fractional numbers: crew killed, shield damage, and hull damage caused by enemy fighters
• Three fractional numbers: crew killed, shield damage, and hull damage caused by enemy torpedo hits
• Three fractional numbers: crew killed, shield damage, and hull damage caused by enemy beam weapons
• Number of fighters lost through enemy's fighters
• Number of fighters lost through enemy's beam weapons

Note that, due to rounding effects, the "damage caused by..." values may not sum up to the respective integer values. In our example, the left ship got 102.9% shield damage through torpedo hits (which translates into 100% shield damage plus some hull damage), and 44.2%+55.4% = 99.6% hull damage from torpedoes and beams (which is rounded to 100%).

hullfunc.dat

The file hullfunc.dat is generated by PHost when you use the option -l (print ship list) to invoke PHost. It contains the special ship functions in an easily machine-readable binary format. Utility programs such as EchoView use this file instead of having to parse shiplist.txt resp. hullfunc.txt.

The file consists of the following parts:

1. Header
2. Functions assigned to hulls
3. Level-restricted ship functions (optional)
4. Functions assigned to ships (optional)
5. Trailer

The parts are packed tightly together, without gaps. The header contains pointers to the optional parts to make it easier to find them. Up to PHost 4.0k, only the three mandatory parts are written. Future PHost versions may add more data before the trailer, so you should locate the trailer's position from the end of the file.

Format of Header:

 +0     DWORD   Magic Number 0xB1297F35
 +4     BYTE    PHost Minor Version (e.g. 0)
 +5     BYTE    PHost Major Version (e.g. 4)
 +6  32 BYTEs   Game Name (space-padded)
+38     DWORD   Pointer to Level-restricted ship functions
+42     DWORD   Pointer to Functions assigned to Ships
+46   8 BYTEs   Reserved, always zero

The "Pointer" fields are zero if the respective sections do not exist. This is the default in all versions of PHost up to 4.0k.

Format of Functions assigned to Hulls: This section describes the functions which are assigned to hulls (AssignTo=Hull). For example, if a ship is reported as being cloakable if it belongs to Lizards, it will only be cloakable when it actually belongs to the Lizards.

 +0     WORD    Number of Records following
 +2   n RECORDs of variable length:
                 +0     WORD    Hull Number
                 +2     WORD    Number of special functions assigned
                                to this hull
                 +4   n RECORDs of 4 bytes each:
                                 +0     WORD    Special Function.
                                 +2     WORD    Player bitfield. Bits 1 to
                                                11 mark players who can use
                                                this function. Bits 0 and
                                                12..15 are undefined

The Special Function field contains one of the following:

• a function number (field Numeric Value in the Hull Function Descriptions)
• the identifier of a level-restricted ship function, as described in the next section
• a not-yet-defined value from a future PHost version or add-on program

Format of Level-restricted ship functions: This section describes functions modified with a Level statement.

 +0     WORD    Number of functions
 +2     WORD    Size of each record
 +4   n RECORDs of the size specified above:
                 +0     WORD    Function Id
                 +2     WORD    Basic Function
                 +4     WORD    Experience Level Mask

The format of the definition records is the same as util.dat record 57, see there for more information. Its size may increase in the future with new data appended at the end. Note that the Function Ids reported in hullfunc.dat may differ from those in utilX.dat, because hullfunc.dat is generally generated only once at the beginning of the game, whereas utilX.dat represents the current state. The Function Ids reported here are valid only to interpret the Special Function fields in the Functions assigned to Hulls and Functions assigned to Ships sections in this file.

Format of Functions assigned to Ships: The format of this section is the same as the Functions assigned to Hulls field. It describes functions assigned to ships when they are built (AssignTo=Ship). For example, if a ship type is reported as being cloakable if it is built by the Lizards, all these ships built by the Lizards are cloakable, no matter who currently owns them.

This field is only useful to predict what abilities a newly-built ship will have. The current assignments for existing ships are reported in util.dat record 52.

Format of Trailer:

 +0     DWORD   Signature 0x1F0C219A
 +4     DWORD   Checksum

The Checksum is the word-wise sum (16-bit little-endian words) of all words in the file, excluding the checksum field itself. For example, the Magic Number field has the value 0xB1297F35, and thus consists of the words 0xB129 and 0x7F35, giving a checksum of 0x1305E.

Additional Files

• pconfig.src: main configuration file.
• shiplist.txt, hullfunc.txt: ship list configuration file, see Setting up Hull Functions. If shiplist.txt exists, hullfunc.txt is not read.
• wormhole.txt: Wormhole data.
• auxdata.hst: stores additional data, like alliances, remote control, cheat check information.
• check.log: log file of last turn check (-c). This file is intended to be given to players.
• check2.log: like check.log, but this one includes the result of the host data file check, too.
• extmines.hst: stores minefields #501 .. #10000, in the same format as mines.hst.
• shipscan.ext: ship scan information.
• turnstat.log: turn status log. A human-readable text file listing the turn submission status over the whole game.
• xterncmd.ext: add-on command messages.
• xtrfcode.txt: special friendly codes definition file.

Unused Files

• tons2.hst: a tons-like score which PHost does not use.
• hconfig.hst: PHost uses pconfig.src for its configuration. Some add-ons may need a valid hconfig.hst, though. See this FAQ entry.
• pconfig.hst: PHost 3.0 and later do no longer need the compiled version of the configuration file.
• leechX.dat: this is the companion to the "TacCom-enhanced" TRN file format. HOST would include this file in result files; PHost does not support that.
• auxbatt.ini: PHost does not use this file. If you wish to replace the combat sequence, you can use PControl to do that.
• auxhostX.exe, auxhostX.bat: PHost only recognizes auxhostX.ini. If you wish to run an .exe or .bat file, call it explicitly from the respective auxhostX.ini file.

A Word about File Names

VGA Planets originally ran under MS-DOS, which does not distinguish between upper-case and lower-case letters in file names. When PHost is run on Unix or another platform that distinguishes case, one has to decide for one form of file names.

PHost strongly prefers file names in all-lowercase. It contains some provisions to handle all-uppercase names, but this is much underdeveloped and less tested. In particular, PHost does not prevent creating a file with a lower-case name when the upper-case name already exists. Mixed-case names such as HullSpec.Dat are not supported at all.

Hint: Even under Unix-like operating systems such as Linux, partitions formatted with the FAT file-system often behave case-insensitive like under DOS or Windows. You can thus easily avoid all file-name case problems by storing your game directories on a FAT partition.

For compatibility across platforms, PHost uses only 8.3 file names for files it reads or creates by itself. At places where you specify the a directory or file name (for example, when passing PHost a game directory name, or in an Addon statement), you can use longer file names if your environment supports them. However, PHost does not contain any provision for quoting file names for the shell when invoking add-ons (e.g. when you're using a %d placeholder in a PControl command), so you should avoid shell meta-characters and spaces in file names.

Back to top

Last updated 31 May 2015.