![]() |
Technical Information
|
This document is intended for programmers. It descrives 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.
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 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 ;-)
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.
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.
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).
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 cancelled 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 cancelling it. The best solution which works with every existant host is to send a BaseBuildShip for every active order, and for every changed (or cancelled) order.
Unlike HOST, PHost does not include heuristics for recovering from Xmodem transfers.
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.
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.
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".
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".
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.
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.
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.
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 |
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 |
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.
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%).
Last updated 22 January 2005.