PHost - Technical Information
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.
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 ;-)
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 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.
Unlike HOST, PHost does not include heuristics for recovering from Xmodem transfers.
PHost 4.0 includes a new TRN command, SendBack (62).
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.
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.
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.
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.
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.
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:
Each object has the following format:
[*] = 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:
In PHost 3.4b and later, this file contains 4x11 longs, not just 2x11 like before.
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.
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:
If a ship does not exist, its line contains 0 0. No existing ship can have a second value of 0.
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:
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%).
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:
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:
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.
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.
Last updated 31 May 2015.
Mail firstname.lastname@example.org for support, ideas, bug reports, questions. Contact Details