[PHost Logo]

Technical Information
The Portable Host
Version 4.0f

Index

Introduction

This file is intended for programmers. It documents 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.

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

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.

Back to top


VCR Files

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.

Because VPA misidentifies VCR.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.

For upward compatiblity, PHost 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.

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

plang.hst

For historical reasons, this file is heavily encrypted. Maybe the reason is that corrupting the file might cause PHost to crash. Details are still not public.

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:

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

Additional Files

Unused Files

Back to top


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

Last updated 20 March 2004.