![]() |
Utility Data Files (util.dat)
|
In addition to the normal set of result files, PHost creates an additional set of files, called utilX.dat. Those files are intended to simplify life for player-side information presentation utilities.
Traditionally, programs have been reading sub-space messages the Host sends, to figure out information like mine field locations, sensor scans, and so on. This is a tedious and error-prone process, and doesn't go well with PHost's multi-language support. To solve that problem, PHost also sends most of the sub-space messages again, in a machine-readable format, in the utilX.dat files. Ideally, all interesting information should be presented in utilX.dat, so if you're missing something, don't hesitate to tell us.
The utilX.dat files are also used to transmit data requested by players (using the send command).
This page documents the format of these files. It is of interest for host-side and player-side programmers only. Hosts, however, should make sure to send the utilX.dat files with the RST files to their players.
This page also documents other aspects of host-to-client communication, namely messages and Ufos. For the preferred means of client-to-host communication in PHost, see the Command Messages page.
Note that this section is written from the point-of-view of a player-side author who wants to read the file. Information for host-side authors is below.
The file is stored in DOS format. That is, all multi-byte values are in little-endian, two's complement format. The following data types are used:
byte | a 8-bit byte (0..255) |
char | a 8-bit ASCII character |
word | a 16-bit word (-32768..32767) |
long | a 32-bit word (-2147483648..2147483647) |
type[NN] | an array of type, usually indexed 1-based |
Each utilX.dat consists of a number of records. Each record starts with a header of the following form:
word Record Type word Record Size |
The Record Type tells you what the record contains. The header is followed by the record contents which has the length as specified in Record Size. All types defined by PHost are described below.
The maximum size of a record including its header is 32k, to avoid trouble with programs that interpret the Record Size as signed (programming languages like Java or BASIC have no unsigned types).
Strings are generally stored in BASIC format, that is, they are
padded to their field size with spaces. Since PHost lives
in a C world, some versions erroneously write out C strings
(terminated with a null byte), and some add-on programs also do
that. You should therefore accept both formats. Read the
file format list
for general advice.
There is no general convention about the extended character set used in strings (other than 7-bit ASCII). It seems that the most common extended character sets are DOS codepages, not ISO Latin or Windows codepages. This problem mostly applies to ship and race names.
Utilities should dynamically read and use the
Record Size field to determine how many extra bytes to
read after the header, rather than using pre-computed values from
sizing the data structures below. This allows utilities to not
necessarily know about or respond to certain record types (if more
record types are added after the utility has been released), and to
correctly ignore additional fields that may be added to existing
records. Some records may also be shorter than described here when
an older PHost version is used. Version dependencies, if known, are
documented here.
Record Size may be 0, indicating that the next
record's header follows immediately, without any data for the
current record.
The order of the records generally follows the host sequence, so if an item is reported several times, the most current information comes last. Note that the record numbers have no relation to the ordering in the file.
Every utilX.dat file starts with a control record.
Record 0 - Mine Scan | Since: PHost 1.0 |
word Minefield Id word X Location word Y Location word Owner (1..11) long Mine Units word Type (0=normal, 1=web) --- PHost 2.0: --- word FCode Planet Id --- PHost 2.6d: --- word Scan Type (0=lay, 1=sweep, 2=scan) |
Sent when: Minefield laid/swept/scanned
Sent to: Owner of the ship which lays/scans the mines, and his vision-level allies
This message is generated to report three events:
A minefield may be reported more than once. It is reported once if it scanned and also once for each ship that adds to the mine (or the ship that creates the mine). The last mine scan message for a given minefield will be the one that represents the number of units in the mine after all mine laying, sweeping, and scooping activity is complete.
The FCode Planet Id field indicates the planet ID which controls the minefield's friendly code. The friendly code of the minefield is the same as the friendly code of this planet. This field is only valid for own minefields and those you have a mine-level alliance with. For scans of enemy minefields, this element is 0.
The Scan Type element indicates the nature of this record. For instances of mine laying, this element is 0. When this record indicates a sweep of an enemy mine field, this element is 1. Finally, when this record is a summary scan message (for both own-race and enemy minefields), this element is 2. In general, all type 0 records will occur prior to all type 1 records (since laying happens before sweeping), which in turn will occur prior to all type 2 records (since mine scans are summarized after all sweeping activity is complete).
When a player uses Winplan, he will see all his minefields this way without explicitly scanning. Conversely, when you use Winplan and do not see one of your minefields, you know it's gone.
When AllowMoreThan500Minefields is turned on for a player, all minefields will be reported with this record type. When AllowMoreThan500Minefields is off, minefields with Id numbers above 500 will be reported using record 46 instead.
Record 1 - Explosion | Since: PHost 1.0 |
word X Location word Y Location word Ship Id --- PHost 3.4: --- char[20] Ship Name |
Sent when: ship explodes in combat
Sent to: all players
Record 2 - Mine Hit | Since: PHost 1.0 |
word Ship Id word X Location word Y Location word Damage --- PHost 3.4b: --- char[20] Name |
Sent when: ship hits a mine (web or normal)
Sent to: mine field owner and ship owner
The position reported is the position of the mine hit. The damage reported is the total ship damage after the mine hit. In particular, when it exceeds 99 (150 for Lizards), the ship explodes.
See also: Record 58 - Explosion
Record 3 - Dark Sense | Since: PHost 1.0 |
word Planet Id word Owner (1..11) long Neutronium long Tritanium long Duranium long Molybdenum long Megacredits word Starbase Flag (0=no, 1=yes) |
Sent when: ship scans a planet by means of Dark Sense
Sent to: owner of the ship, and those whom he offers Vision-level
Record 4 - Super Spy | Since: PHost 1.0 |
word Planet Id word Mines word Factories word Defense char[3] Friendly Code long Neutronium long Tritanium long Duranium long Molybdenum long Megacredits --- PHost 3.0: --- long Supplies |
Sent when: ship scans a planet by means of Super Spy (the part of the mission which happens in the SuperSpyMission stage of host order)
Sent to: owner of the ship which spies, and his vision-level allies.
Note that, in addition to the super spy information, an exploration record is sent, too.
Record 5 - Exploration | Since: PHost 1.0 |
word Planet Id word Temperature word Owner (1..11) long Colonists word Starbase Flag (0=no, 1=yes) |
Sent when: fueled ship orbits a foreign planet
Sent to: owner of the ship, and his vision-level allies.
Note that Colonists is a number of colonists,
not clans. Temperature is the actual temperature in
Fahrenheit degrees, not the temperature code as in
pdata.dat files.
Record 6 - Sensor Sweep | Since: PHost 1.0 |
word Planet Id word Owner (1..11) word Activity (0..5) |
Sent when: ship scans a planet using Sensor Sweep
Sent to: owner of the ship, and his vision-level allies.
The Activity field encodes the industrial activity on the planet. It corresponds to the values reported in messages as follows:
Activity | Name | Mines + Factories |
---|---|---|
0 | minimal | < 30 |
1 | light | 30 to 59 |
2 | moderate | 60 to 89 |
3 | substantial | 90 to 119 |
4 | heavy | >= 120 |
PHost until version 4.1/3.5 also reports a value "5", which has no equivalent in the message. Later versions limit this to the values reported by message.
Record 7 - Battle Result | Since: PHost 1.0 |
word[2] Id Numbers word Planet Flag word[2] Owners (1..12) word[2] Damage word[2] Torps word[2] Fighters word[2] Outcome --- PHost 1.3+ --- word X Location word Y Location --- PHost 3.4b+ --- word Random Seed |
Sent when: combat happens. This record is sent as a supplement to the normal vcr.dat record.
Sent to: participants of the battle, and to any allies they have to which they have enabled the combat, ship and vision level.
Each battle involves two objects, for which the result is given in this record (the initial status is in the VCR record). If the Planet Flag is zero, both objects are ships, and the Id numbers are ship Ids. If the Planet Flag is one, the second object is a planet, and the second Id number is a planet Id.
The Outcome value describes how the battle ended for this object:
0 | Victor: this unit won the battle |
1 | Captured: this unit was captured (never true for planets) |
2 | Destroyed: this unit was destroyed (in case of a planet, the planet got captured because all its defense was destroyed) |
3 | No Ammo: this unit no longer has offensive capability |
Note that in PHost, planets can capture ships. Outcome 3, No Ammo, is true when after a battle a unit has no beam weapons, no torps, and no fighters remaining. This outcome will never occur as long as the unit has effective beam weapons. Since Death Rays are not effective against a planet, such fights might also be terminated with this outcome.
The Seed value is the same as in the VCR record. Together with the Id numbers, it can be used to match util.dat records against VCR records.
Record 8 - Meteor Strike | Since: PHost 1.0 |
word Planet Id long Neutronium long Tritanium long Duranium long Molybdenum |
Sent when: large meteor hits a planet
Sent to: all players
The message reports the ore content of the meteor, which is added to the ground (not mined) minerals of the planet.
The ore content of a large meteor is defined by LargeMeteorOreRanges.
Record 9 - Meteorite Shower | Since: PHost 1.0 |
word Planet Id long Neutronium long Tritanium long Duranium long Molybdenum |
Sent when: meteorite shower hits a planet
Sent to: owner of the planet
The message reports the ore content of the meteorite shower, which is added to the ground (not mined) minerals of the planet.
The ore content of a meteorite shower is defined by MeteorShowerOreRanges.
Note that this record has the same format as record 8.
Record 10 - Ship Target | Since: PHost 1.0 |
word Ship Id word Owner (1..12) word Speed (0..9) word Location X word Location Y word Hull Number (1..105) word Heading (-1..359) char[20] Name |
Sent when: AllowMoreThan50Targets is disabled, but more than 50 enemy or allied ships are scanned, in total, and player is receiving a DOS-style RST.
This record has the very same format as a targetX.dat entry. The first 50 ships are stored in the player's RST file. The excess are transmitted with this message, or in a separate section of the result when the player uses Winplan.
Most entries in this record are self-explanatory. The Heading word is in the range 0 to 359 indicating compass direction of travel (0 is due north and the angle increases clockwise). Heading may also be -1 (0xFFFF) to indicate an unknown direction.
Name is actually a 20-byte field containing the ship's name.
Target records may differ from the real ship in the following aspects:
Record 11 - Starbase Target | Since: PHost 1.0 |
word Base Id word Base Owner (1..11) |
Sent to: your planet-level allies
This record reports that there's a starbase of the given player at the specified planet.
Record 12 - Planet Target | Since: PHost 1.0 |
word Planet Id word Owner (1..11) word Temperature (0..100) word Native Race (0..9) word Native Government (0..9) long Native Population long Neutronium long Tritanium long Duranium long Molybdenum long Colonist Population long Supplies long Megacredits |
Sent to: your planet-level allies
This record reports (partial) information about allies' planets.
The Native Government and Native Race fields can take the following values:
Index | Native Race | Government |
---|---|---|
0 | No natives | - |
1 | Humanoid | Anarchy |
2 | Bovinoid | Pre-Tribal |
3 | Reptilian | Early Tribal |
4 | Avian | Tribal |
5 | Amorphous | Feudal |
6 | Insectoid | Monarchy |
7 | Amphibian | Representative |
8 | Ghipsoldal | Participatory |
9 | Siliconoid | Unity |
The four mineral values reflect the amount of each mineral present on the surface of the planet, not in the core.
Note that the population counts are a number of people,
not clans. Temperature is the actual temperature in
Fahrenheit degrees, not the temperature code as in
pdata.dat files.
Record 13 - Control Record | Since: PHost 1.0 |
char[18] Host Run Time (Timestamp) word Turn Number word Player Number (1..11) byte PHost Version: Major (e.g. 4) byte PHost Version: Minor (e.g. 0) long HULLSPEC.DAT Digest long ENGSPEC.DAT Digest long BEAMSPEC.DAT Digest long TORPSPEC.DAT Digest long TRUEHULL.DAT Digest long XYPLAN.DAT Digest long Configuration Digest long RACE.NM Digest char[32] Game Name --- PHost 2.11h: --- byte PHost Version: Release (e.g. 'a') |
Sent when: This record always is the first record in every util.dat file. It identifies the file, and associates it with a RST file.
The Host Run Time is the same time-stamp also found in RST files. A program can confirm that a util.dat file indeed corresponds to a RST file by comparing this file, and the Turn Number and Player Number fields.
The three PHost Version fields indicate the PHost version used to generate the file. For example, PHost version 3.4c would report Major=3, Minor=4, and Release='c'. The Release file may be blank (i.e. space).
The eight 32-bit digests are intended to allow player-side utilities to verify that the player-side ship list files are the same as the ones used on the host side. Details are available on request.
The Game Name field contains the value of the GameName config option, for informational purposes.
Record 14 - Wormhole Scan | Since: PHost 1.0 |
word Location X word Location Y word Mass (0..32767) word Stability Code (0..5) word Id --- PHost 3.4h/4.0e: --- word Ufo Id word Bidirectional (0 or 1) |
Sent when: a wormhole is scanned
Sent to: owner of the ship that scans the wormhole, and his vision-level allies.
This reports a wormhole entry point along with its mass and a code indicating the stability.
Code | Stability | Approx. chance of travel failure |
---|---|---|
0 | very stable | 5% |
1 | stable | 15% |
2 | mostly stable | 30% |
3 | unstable | 50% |
4 | very unstable | 80% |
5 | completely unstable | > 80% |
The Id field indicates the wormhole Id. Wormhole Ids are even-valued if the wormhole represents an entry point and odd-valued if the wormhole is bidirectional and the given location represents the exit point. The exit point always has a wormhole Id that is 1 greater than the entry point's Id. Note that some Ids may be missing due to wormholes that have collapsed or unidirectional wormholes (which will not have an odd-valued Id number).
Record 15 - Wormhole Travel | Since: PHost 1.0 |
word Ship Id word Location X word Location Y word New Damage word Total Damage word Wormhole Id |
Sent when: ship travels through a wormhole
Sent to: owner of the ship
The Location and Wormhole Id report the position at which the travel began. New Damage is the damage done by the travel, Total Damage is the resulting total damage. If the total damage reaches 100 or more, the ship got destroyed by the flight.
Record 16 - Ship Recycled | Since: PHost 1.0 |
word Ship Id word Base Id |
Sent when: ship recycled at starbase
Sent to: starbase owner
Record 17 - Ion Storm | Since: PHost 1.3 / 4.0j |
word Storm Id (1..50) word Location X word Location Y word Voltage word Heading (0..359) word Speed (0..15) word Radius word Class (1..5) word Growth Flag (0=weakening, 1=growing) |
Sent to: everyone
This record type is defined since PHost 1.3, but only sent by PHost 4.0j and later. It reports information about one ion storm. PHost always reports all ion storms to all players.
Record 18 - Ship Colonized | Since: PHost 1.3 |
word Ship Id word Planet Id |
Sent when: ship was recycled using the Colonize mission
Sent to: ship owner
This record is only sent when a ship was
decommissioned using the Colonize
mission. It is not sent when a planet is colonized by dropping
clans (see record 28 for ground combat)
Record 19 - Ship Surrendered | Since: PHost 1.4 |
word Ship Id word Original Ship Owner (1..11) word Base Id word Base Owner (1..11) |
Sent when: ship surrenders at a starbase (via the Force surrender order)
Sent to: former ship owner, and base owner
In PHost 1.3, record 19 reports a ship surrendered to
the enemy, and has the following format:
word Ship Id word Base Id word Enemy Race Id (1..11) |
Record 20 - Ship Constructed | Since: PHost 1.4 |
word Ship Id word Base Id word Clone flag (0=no, 1=yes) |
Sent when: new ship was built
Sent to: ship owner
The Clone flag indicates whether this was a normal build order or a clone order.
In PHost 1.3, record 20 reports a ship surrendered to
us, and has the following format:
word Ship Id word Base Id word Enemy Race Id (1..11) |
Record 21 - Ship Trade | Since: PHost 1.3c |
word Ship Id word Old Owner (1..11) word New Owner (1..11) |
Sent when: ship was given away using the gsX friendly code or the give command.
Sent to: old and new owner
Record 22 - Alliance Status | Since: PHost 1.4b |
byte[11] Offered to... byte[11] Offers from... --- PHost 2.6: --- byte[11] Conditional offers to... byte[11] Conditional offers from... |
Sent to: all players that are somewhat involved in an alliance
The four components of this record are arrays indexed by player number.
The first array indicates the alliance levels that the player offers to other players. The second array indicates the alliance levels that other players have offered to the player receiving this record. For example, the fifth element of Offered To indicates the alliance levels that this player has offered to the Privateers; the fifth element of Offers From indicates the alliance levels that the Privs have offered to this player.
Each element is a bitfield which may be decoded as follows:
Bit | Meaning |
---|---|
0 (value 1) | Ship Level |
1 (value 2) | Planet Level |
2 (value 4) | Minefield Level |
3 (value 8) | Combat Level |
4 (value 16) | Vision Level |
5 (value 32) | Active bit |
Look first at bit 5 (value 32): this bit determines whether the offer is valid (i.e. the player has used the allies add command). If that's the case, the five low-order bits contain the offered levels (see allies config).
The two high-order bits are reserved and set to zero by PHost.
For example, if player number 3's alliance status record indicates that his fifth Offered To is 00101010 (binary) then this means that player 3 has offered an alliance to player 5 and has enabled the Planet Level and Combat Level of alliance.
Note that for player N, Offered To[N] and Offers From[N] should always be zero (you can't make an alliance with yourself).
The last two arrays in this record indicate which levels of alliance have been offered on a conditional basis. Like the Offered To and Offers From arrays, they are indexed by race. If a bit is set in one of the array's entries, then it indicates that the corresponding alliance level is a conditional one, and will not take effect unless the other player also offers (perhaps conditionally) this alliance level to the first player.
The encoding is the same as for the first two arrays, but the Active bit is always zero. Note that if an alliance level is not enabled, then the conditional bit will always be 0.
Record 23 - Bioscan Report | Since: PHost 2.6 |
word Planet Id word Native Race (0..9) long Native Population word Temperature |
Sent when: planet is seen by a bioscanner
Sent to: owner of the ship which scanned the planet, and his vision-level allies
See the Planet Target record for a description of the fields. Note that the native population (and race) may be 0 if the planet has no natives.
Record 24 - Glory Device Exploded | Since: PHost 2.6 |
word Ship Id word Location X word Location Y |
Sent when: Glory Device is set off (using trg or pop)
Sent to: owner of the ship
Note that this record is only sent for the glory device ship; ships affected by the glory device generate record 25.
Record 25 - Damage from Glory Device | Since: PHost 2.6 |
word Ship Id word Location X word Location Y word New Damage word Ship Owner (1..11) --- PHost 3.4b: --- word Hull Number (1..105) char[20] Name |
Sent when: ship is hit by the shock wave of a Glory Device
Sent to: owner of the ship, and owner of the glory device
This record reports a ship which got damaged by a Glory Device. The stats describe the damaged ship, not the glory device itself. The New Damage field reports the total damage after the explosion. When it's 100 or more, the ship explodes.
Record 26 - Boarding Party | Since: PHost 2.6 |
word Ship Id word Old Owner (1..11) word New Owner (1..11) --- PHost 2.9e: --- word Boarding Ship Id |
Sent when: ship is captured by a boarding party ("tow capture", see Tow mission)
Sent to: old and new owner of the ship
The Ship Id field is the Id of the ship which changed ownership, the Boarding Ship Id is the Id of the ship that boarded it.
Record 27 - Configuration File | Since: PHost 2.6 |
This record contains a verbatim copy of pconfig.src, no additional headers.
This record is no longer used as of PHost 2.10. PHost
now uses the general file transfer record
for this purpose.
Record 28 - Ground Attack | Since: PHost 2.6 |
word Planet Id word Owner Race (1..11) word Attacker Race (1..11) word Outcome (0..2) |
Sent when: planet is attacked using normal ground attack (unloading clans) or Imperial Assault
Sent to: planet owner and attacker
The Outcome field can have the following values:
0 | The ground attack failed. The Owner Race still owns the planet |
1 | The ground attack succeeded. The Attacker Race now owns the planet |
2 | All colonists are gone, the planet is now unowned |
Record 29 - Minefields Exploding | Since: PHost 2.6d |
word Minefield 1 Center X word Minefield 1 Center Y word Minefield 1 Id word Minefield 2 Center X word Minefield 2 Center Y word Minefield 2 Id long Minefield Units Lost |
Sent when: two minefields explode due to overlap
Sent to: all players
This record reports the locations and Id numbers of the two minefields, and the number of mine units removed from each of the fields.
This record is sent when minefield losses are symmetric: two minefields overlap, both lose the same amount. In some cases, losses might not be symmetric. PHost will then send a type 53 record for each affected field.
Record 30 - End of PHost Info | Since: PHost 2.7a |
This record is the last PHost-generated record in the util.dat file. Its only purpose is to indicate that all records that follow have been generated by external utilities or add-on programs. This record contains no data.
Record 31 - Minefield Scooping | Since: PHost 2.9d |
word Ship Id word Minefield Id word Torps Converted long Units Scooped --- PHost 2.11h: --- long Units Before Scoop |
Sent when: ship is scooping mines out of a minefield to form torpedoes
Sent to: owner of the ship
The Torps Converted parameter indicates the number of new torpedoes added to the ship's cargo. The Units Scooped is the number of minefield units used up for that.
Record 32 - Pillage | Since: PHost 2.9d |
word Planet Id long Colonist Clans long Native Clans --- PHost 3.4g/4.0c: --- word Ship Owner |
Sent when: planet is pillaged
Sent to: owner of the planet, and owner of the ship performing the pillage
Unlike in other records, PHost reports a number of clans
here.
Record 33 - General Object | Since: PHost 2.10 |
word Object Id word Position X word Position Y word Color (1..15) word Radius word Speed (0..15) word Heading (-1..359) char[20] Name char[20] Info Field 1 char[20] Info Field 2 word Utility Code ...auxiliary data may follow. |
This record is meant to be used as a template for external add-ons to use in communicating with client-side utilities, similar in style to HOST's ufo.hst mechanism. This record is never actually generated by PHost. It is proposed that add-on programs that wish to communicate the presence of objects in the universe to client-side utilities use this record format.
This record can be considered to contain 3 separate sections:
The use of this record for communicating objects greatly simplifies the work of client-side utility writers. It is recommended that all add-on programs use this record for transmitting object position data. Client-side programs known to evaluate General Objects so far include:
There is one convention that should be followed regarding the Object Id field: If the object is also reported via ufo.hst, the Object Id should correspond to the same Id as for the entry in the ufo.hst file, so that client-side utilities know that the records actually describe the same object. Thus, objects which are not in the ufo.hst file should have Object Id values greater than 1000 (the maximum number of objects in the ufo.hst file).
See also: General Object Destruction (Record 42), UFO.HST file
Record 34 - File Transfer | Since: PHost 2.9d |
char[12] File Name byte Flags char[...] File Data |
Sent when: player requests a file from the host (using the send command), or probably at other times
Sent to: whomever it may concern
This record is used to transmit a file from the host to a player. It consists of a 13-byte header, followed immediately by the file data.
The File Name contains the null-padded file name. Only DOS 8.3 file names are allowed which have a maximum length of 12 characters total. The Flags contain additional flags which describe the file. Currently, only the least-significant bit is used, all others are zero (reserved for future use).
Files larger than 32k can't currently be sent through
this interface. We're considering an extension to allow that at a
later time. If you need it, bug us :-)
Currently, PHost uses this record for the following tasks:
Add-on programs may use this record for a similar purpose.
Record 35 - Cloak Failure | Since: PHost 2.10b |
word Ship Id word Reason (0..5) |
Sent when: cloaking fails on a ship
Sent to: owner of the ship
This record reports a failing cloaking device. Unless the reason is a tachyon pulse, this message is only sent when AllowCloakFailMessages is enabled.
This record type is superseded by the general Failure Notice record, see there for a description of the Reason field. This record is still sent for backward compatibility.
Record 36 - Anti Cloak | Since: PHost 2.11g |
word Decloaked Ship Id word Location X word Location Y word Decloaked Ship Owner --- PHost 3.4e/4.0a: --- word Before Movement --- PHost 3.5c/4.1c: --- word Loki Id word Loki Owner |
Sent when: Loki decloaks a ship. PHost versions below 4.0/3.4d send this record only when the detected ship orbits a planet.
Sent to: owner of the Loki, (v4.1c:) owner of decloaked ship
The Before Movement field tells you whether the reported position is before (1) or after (0) movement. In absence of this field, you can derive this information from the relative position of this record in the file.
Record 37 - Remote Control | Since: PHost 3.0 |
word Ship Id word Remote Control Flag (...repeated for each ship) |
This record is used to report the original owner of ships that are under remote control and that are visible to the player this turn. This record also informs the player of his/her ships that are forbidden from being remotely controlled. This record is of variable length, depending upon the number of ships that are reported (which can be determined from the length of the record). For a record of length 4*N bytes, there will be N sets of words, each set describing one ship Id and that ship's status.
Record 38 - Activity Level Report | Since: PHost 3.0 |
long Old Level long Decay Points long New Points long New Level |
Sent when: always
Sent to: every player
This record reports the activity level for one player, as well as the points lost through decay and points gained through turn activity.
PBPs: In PHost 4.0f/3.4i and later, the amount of PBPs used can be computed as
Used_PBPs = Old_Level - Decay_Points - New_Points - New_Level |
In previous PHost versions, the Old Level is after PBP consumption. The above equation will yield zero. In this case, the used PBPs can be computed as the difference between last turn's New Level and this turn's Old Level.
If the game does not use PBPs, both methods will yield a PBP usage of zero. See Build Point Details for more information on build points.
Record 39 - Build Queue Report | Since: PHost 3.0 |
word Base Id word Hull Type (1..105) word Position long Priority (...repeated for each build order) |
Sent when: player has pending build orders
Sent to: every player
This record reports a player's build queue contents. This variable-length record contains one entry for each ship in the build queue. Thus, the size of the record determines the number of ships being reported. If there are N being reported, the record length will be 10*N bytes.
The Base Id is the starbase building the ship. The Position is the position in the global build queue; position 1 is the next ship to be built. The Priority is the order's priority; the highest priority will be built first.
Note that build orders may change in position from turn to turn based upon changes in priority. It is not necessarily true that a build order will constantly have its position reduced until it is built.
Record 40 - Web Drain Complete | Since: PHost 3.0 |
word Ship Id --- PHost 3.4d --- word Player Id char[20] Ship Name |
Sent when: ship inside a web mine field has run out of fuel, or continues to be out of fuel
Sent to: owner of the minefield
Ships may run out of fuel when they hit a web mine, or when they are just drained for being inside the field. While the latter only happens when the web is owned by a Crystal race, the former can happen for web mines owned by anyone.
In case the ship has a Ramscoop,
it may still have fuel. The fuel produced by the Ramscoop is made
available after movement, and after web mines drain fuel.
Record 41 - Rebel Ground Attack | Since: PHost 3.3c |
word Planet Id word Native Flag (0=no, 1=yes) --- PHost 3.4g/4.0d: --- word Rebel Player |
Sent when: ship does the Rebel Ground Attack mission
Sent to: owner of the ship, and owner of the planet
This record just reports whether the planet has natives or not. It does not report the native race. The Rebel Player field reports the owner of the attacking ship, in case multiple players are playing the Rebel race.
Record 42 - General Object Destruction | Since: PHost 3.3c |
word Object Id word Utility Code ...auxiliary data may follow |
Sent when: a General Object was destroyed
This record can be used by host-side add-on programs to report destruction of a General Object to the players. PHost never generates this record.
The intention is to simplify client-side information tracking. Client programs can use this record to discard obsolete objects. utilX.dat files should be parsed sequentially with respect to this record: a General Object record followed (directly or indirectly) by this record for the same object means a new object which is immediately destroyed. First a destruction record and then a General Object with the same Id/UtilCode means destruction of the old object and creation of a new one.
After the two fields defined here, programs may place auxiliary information, for example the cause of destruction.
See also: General Object (Record 33)
Record 43 - Minefield Status | Since: PHost 3.3c |
word[11] Allowed word[11] Laid |
Sent when: Minefield restrictions are active (MaximumMinefieldsPerPlayer)
Sent to: all players
This record is deprecated and might be removed sometimes
in the future. The same information is also sent in
record 51 since PHost 3.4d.
This record is sent when minefield restrictions are active. The Allowed array contains, for each player, the number of minefields he is allowed to lay (MaximumMinefieldsPerPlayer). The Laid field contains the number of minefields for each player: you will be told your allies' minefield count when he offers you the minefield alliance level. Positions of players whose value you should not see are 0xFFFF (all bits 1).
Record 44 - Failure Notice | Since: PHost 3.4 |
word Action that Failed word Ship Id (0 if not applicable) word Planet Id (0 if not applicable) word Cause ...optional addition data |
Sent when: some action fails
Sent to: owner of the unit which tried the action
This record is intended as a general failure report mechanism, to avoid the need to guess why an order didn't work.
The Action field contains the action that failed; by convention, this is a utilX.dat record number, or a larger number if there is no equivalent record. The Cause field contains a standard failure code. The record provides space for optional additional data.
Failure codes: The following Cause codes are currently defined. Not all of them are already used. The first codes are equivalent to those used in the cloak failure record.
Code | Meaning |
---|---|
0 | Random chance |
1 | Insufficient fuel |
2 | Excess damage |
3 | Ionic pulse |
4 | Wormhole Travel |
5 | Tachyon pulse |
6 | Ion storm |
10 | Lacking resources |
11 | Lacking tech |
12 | No receiver unit |
13 | Feature disabled by host |
14 | Not allowed by rule |
15 | Not allowed by partner |
16 | Global object limit exceeded |
17 | Per-player limit exceeded |
18 | Required ability missing |
19 | Target object does not exist |
20 | Per-unit limit exceeded |
Codes currently in use: These are all the Action / Cause combinations which PHost currently generates.
Record 45 - Planet Trade | Since: PHost 3.4b |
word Planet Id word Old Owner (1..11) word New Owner (1..11) |
Sent when: planet was given away using the give command.
Sent to: old and new owner
This record has the same format as the Ship Trade record.
Record 46 - Mine Scan (High-Id) | Since: PHost 3.4b |
This record has the same format and meaning as record 0, see there for more information. It is used to report minefields with Id numbers above 500.
When AllowMoreThan500Minefields is turned off for a player but there is a minefield with an Id number above 500, PHost will send this record type. When AllowMoreThan500Minefields is turned on, all minefields will be reported using record type 0.
Record 47 - Nonexistent Planets | Since: PHost 3.4c |
word[...] Planet Id |
Sent when: some planets do not exist, i.e. you are playing on a map with fewer than 500 planets
Sent to: all players
This record contains a list of planets which do not exist. Clients can use this to adjust their starchart accordingly.
Although this record has been documented since 3.4c, it
was not actually sent out until 4.1a/3.5a.
Record 48 - PAL Summary | Since: PHost 3.4c |
long[11] PAL Scores |
Sent when: always
Sent to: every player
This record is deprecated in favor of
record 51, a more general means of
reporting scores.
This record lists the known PAL values for all players. The BuildPointReport config option defines what is listed here. Entries you should not know are -1 (0xFFFFFFFF).
Unlike the subspace message, which is only sent when there is more than one player's data available, this record is always sent.
Record 49 - Ship Score | Since: PHost 3.4d / 4.0 |
char[50] Name word Score Type word Score Limit word Ship Id 1 word Score 1 word Ship Id 2 word Score 2 ...repeated for all interesting ships |
This is a general means of reporting ship-specific scores. The Name contains the human-readable name of the score. The Score Type contains the identifier of the score, for use by programs. The Score Limit is an informational limit for this score (that is, it is not a hard limit. Scores can be higher, but when a ship reaches the limit, something "interesting" happens). The meaning of this field depends on the score. It can be -1 (=65535) if there is no limit.
Programs can meaningfully display all scores, even those they do not know about, because of the Name field. Programs which look for a particular score use the Score Type field.
The three administrative fields are followed by a number of ship Id / ship score pairs. The number of such pairs is determined by the record size.
Score Identifiers:
1 |
(v4.0:) Experience levels. The limit is NumExperienceLevels, scores range from 0 to that limit. Each player gets all experience levels of his ships and his ship-level allies. |
2 |
(v4.1:) Experience points. This entry is sent only if ExactExperienceReports is enabled. Each player gets all experience levels of his ships and his ship-level allies.![]() |
3 .. 99 | reserved for future use |
100 .. 32767 | available for 3rd-party developers |
This record has the same format as the planet score record. If possible, score identifiers are kept in sync for both.
Record 50 - Planet Score | Since: PHost 3.4d / 4.0 |
char[50] Name word Score Type word Score Limit word Planet Id 1 word Score 1 word Planet Id 2 word Score 2 ...repeated for all interesting planets |
This is a general means of reporting planet-specific scores. It has the same format and meaning as record 49 (ship-specific scores).
The three administrative fields are followed by a number of planet Id / planet score pairs. The number of such pairs is determined by the record size.
Score Identifiers:
1 |
(v4.0:) Experience levels. The limit is NumExperienceLevels, scores range from 0 to that limit. Each player gets all experience levels of his planets and his planet-level allies. |
2 |
(v4.1:) Experience points. This entry is sent only if ExactExperienceReports is enabled. Each player gets all experience levels of his planets and his planet-level allies.![]() |
3 .. 99 | reserved for future use |
100 .. 32767 | available for 3rd-party developers |
Record 51 - Player Score | Since: PHost 3.4d / 4.0 |
char[50] Name word Score Type word Turn Limit long Win Limit long[11] Scores |
This record is a general means of reporting scores. The Name is a human-readable description of the score. The Score Type contains the identifier of the score, for use by programs. The Win Limit specifies how many points a player must reach to win the game, and the Turn Limit specifies how many turns he must be above that limit. Both these values may be -1 if there are no such limits. The Scores field, finally, lists the scores for all 11 players. Scores which a player is not permitted to see are -1 (=0xFFFFFFFF).
Programs can meaningfully display all scores, even those they do not know about, because of the Name field. Programs which look for a particular score use the Score Type field.
Score identifiers:
1 | "The score". This score type is not used by PHost
itself. It is recommended that 3rd-party scoring systems use this
record to report their scores, to allow automatic plotting of scores
by tools like EchoView![]() |
2 | Build points. This record will list all the build points. This record is intended to replace record 48. |
3 | Mines allowed. This record is sent when mine field limits are active. It contains the value of the MaximumMinefieldsPerPlayer config option. This record is intended to replace record 43. |
4 | Mines laid. This record is sent when mine field limits are active. It contains the current number of minefields laid for you and all your mine-level allies. This record is intended to replace record 43. |
5 .. 99 | reserved for future use |
100 .. 32767 | available for 3rd-party developers |
Record 52 - Ship Abilities | Since: PHost 4.0a |
word Ship Id word[N] Ship Abilities |
Sent to: everyone who sees the ship
This record reports the ship-specific special functions (see AssignTo=Ship statement) for one ship. Each record can contain many abilities, and there can be multiple records per ship.
Function identifiers are integers and can take the following values:
0 to 40 | Standard hull functions |
41 to 999 | reserved for future use by PHost. Currently, PHost allocates pseudo device numbers for Level-restricted devices from this range, see record 57. |
1000 to 32767 | reserved for add-ons. Contact the PHost group to have a range allocated for you. |
This record reports only abilities specifically assigned to ships (AssignTo=Ship). Abilities assigned to a particular hull (AssignTo=Hull) are not reported this way, programs have to read hullfunc.txt to figure out these.
Record 53 - Minefields Exploding | Since: PHost 3.4f / 4.0b |
word Minefield Center X word Minefield Center Y word Minefield Id long Minefield Units Lost |
Sent when: two minefields explode due to overlap
Sent to: all players
This record generated by MinesDestroyMines when rounding errors have accumulated to an extent making it impossible to report the situation in a symmetric way (using record 29).
PHost will mix type-53 and type-29 as it sees fit.
Record 54 - Enemy Status | Since: PHost 4.0h |
word Bitfield |
Sent to: all players who have declared someone as their permanent enemy
This record is sent to every player who has used the enemies add command to declare someone their enemy. It reports the current status, as a reminder for the player. The record consists of a single word which has one bit for every player:
bit 0 (1) | unused |
bit 1 (2) | Player 1 |
bit 2 (4) | Player 2 |
... | ... |
bit 11 (2048) | Player 11 |
Each bit is one if you have set the respective player as your enemy. The least significant bit as well as bits 12 to 15 are unused and zero.
Record 55 - Production Report | Since: PHost 3.4k / 4.0i |
word Ship Id word Cargo Type (0-7) word How Produced (0-3) word Amount Produced |
Sent when: a ship produced something
Sent to: owner of ship, and remote controller
There are a number of ship functions, missions and friendly code actions that cause a ship to produce things. This record reports production success.
The Cargo Type field contains the type of resource produced:
0 | Neutronium. Neutronium is produced by ramscoop and refinery ships. |
1 | Tritanium. Tritanium is produced by alchemy ships. |
2 | Duranium. Duranium is produced by alchemy ships. |
3 | Molybdenum. Molybdenum is produced by alchemy ships. |
4 | Colonists. Currently not used. |
5 | Supplies. Currently not used. |
6 | Money. Money is produced by gambling ships. |
7 | Torpedoes/Fighters. These are produced using the lfm or mkt friendly codes, the Gather-build fighters, Build fighters, Gather-build torpedoes and Build torpedoes from cargo missions, and automatically on Rebel ships. |
8 | Experience. Generated by Training. |
The How Produced field tells you what was used to produce the new items:
0 | The new items were free (ramscoop). |
1 | The ship consumed things from its cargo room (e.g., alchemy). |
2 | The ship consumed things from the planet it is orbiting (e.g. Gather-build torps). |
3 | The ship consumed things from its cargo room and the planet it is orbiting (e.g. lfm). |
Record 56 - Repair Report | Since: PHost 3.4k / 4.0i |
word Ship Id word Reason (0-4) word Repair Unit Id word Damage Repaired word Crew Given |
Sent when: a ship got repaired somehow
Sent to: owner of ship, and remote controller
This record is sent whenever a ship is repaired somehow. It describes the amount repaired. If another unit took part in the repair, it is also identified in this record.
Reason | Repair Unit Id | Action |
0 | 0 | Supply repair |
1 | Planet Id | Starbase "Fix" order |
2 | 0 | Self Repair mission |
3 | Planet Id | Super Refit mission |
4 | Ship Id | Repair Ship mission |
Record 57 - Special Functions Report | Since: PHost 4.0i |
word Function Id word Basic Function word Experience Level Mask |
Sent when: there are level-restricted ship functions in the game
Sent to: all players
This entry reports the numbers PHost uses for modified special functions in record 52. The Function Id field is the number appearing in record 52 (e.g. 65). The Basic Function is the special function assigned to the ship, e.g. 10 for AntiCloak. The Experience Level Mask contains a bitfield of all experience levels at which this device works. Bit 0 means the basic level, bit 1 means level 1, and so on.
Each turn, the assignments will be reported identically to all players. The assignments may change between turns, though.
In case PHost adds more modifiers in the future, this record will be extended to contain the new definitions, too.
Record 58 - Explosion | Since: PHost 3.5c / 4.1c |
word X word Y |
Sent when: a ship explodes in a minefield
Sent to: all players
This record is sent to all players when a ship explodes in a minefield due to excess damage. This record is sent in addition to record 2, which is only sent to involved races.
This record does not include any identification of the exploding ship, it only alerts players about events in the universe. Winplan players also receive up to 50 of these records in a special section of their RST file, so that Winplan plots them on the starchart.
See also: Record 2 - Mine Hit
This section contains information for host-side developers who want to send information to players.
Add-on programs can write their own information into utilX.dat files. The contents of your information are completely arbitrary, you can define your own record types as you see fit. To avoid collisions, you can have a range of record types assigned to you; contact the PHost group to get one. Currently, the following ranges are allocated:
Record Type Range | Assigned To |
---|---|
0 - 16383 (0x0000-0x3FFF) | PHost |
16384 - 16399 (0x4000-0x400F) | Torsten Czerny |
16400 - 16431 (0x4010-0x402F) | Jens Hofbauer |
16432 - 16447 (0x4030-0x403F) | Rafael Alvarez |
16448 - 16479 (0x4040-0x405F) | Sven Bursch |
16480 - 16511 (0x4060-0x407F) | Ingo Korb |
16512 - 16639 (0x4080-0x40FF) | Stefan Reuther |
16512 - 32767 (0x4100-0x7FFF) | available |
32768 - 65535 (0x8000-0xFFFF) | reserved -- not available |
To include data into a utilX.dat file, simply write your data to a utilX.ext file. PHost will concatenate the existing utilX.dat contents with utilX.ext to form the new utilX.dat file. This happens in Phase 3 of PHost (during utilX.dat generation). For example, PHost will copy the contents of the util1.ext file (if it exists in the game directory) to the end of the util1.dat file after the latter has been written. PHost will then remove the util1.ext file.
Note that it is completely up to you to achieve
platform-independence (data field size, endianness)
in writing utilX.ext files.
To not confuse clients, do not write records larger than 32k, and
do not re-use PHost's record numbers for things they're not
intended for. PHost will not validate the contents of
utilX.ext files in any way.
The contents of a utilX.ext file will always come out after all the normal PHost reports. This might not be worthwhile when you are replacing a hosting stage. For example, when you have externalized the give command, the Ship Trade records should still come out before Battle Results, to not confuse information tracking utilities which want to track ship ownership.
To achieve this, you can write into the util.tmp file instead of utilX.ext. PHost gathers up all records in util.tmp before generating the final utilX.dat files.
Every record in util.tmp consists of the following format:
word Receiver (1..11) word Record Type word Data Size byte[N] Data |
The Receiver designates the receiver race, the other fields are as in utilX.dat files.
Note that although PHost versions before 4.0/3.4d
also have a util.tmp, replacing hosting stages
this way will not work with these versions, because they
use a different file format, and possibly keep the file open,
preventing you from using it.
In addition to the General Object record, there's an additional method of making objects, called Ufos, visible to client programs.
This method was introduced by HOST 3.20 and Winplan 3.5. PHost supports it, too.
To make an object visible to clients, you just write it into ufo.hst, and let PHost do the rest.
The ufo.hst consists of 100 or 1000 records of the following format:
word Color (0..15) char[20] Name char[20] Info Text 1 char[20] Info Text 2 word Location X word Location Y word Speed (0..15) word Heading (-1..359) word Planet Scan Range (1..5000) word Ship Scan Range (1..5000) word Radius word Object Type |
The Color field is non-zero if the Ufo slot is in use. It determines the color in which the Ufo is to be shown on star charts, using the standard VGA color numbers:
Number | Color | Number | Color |
---|---|---|---|
0 | Black #000000 | 8 | Dark Gray #555555 |
1 | Blue #0000AA | 9 | Light Blue #5555FF |
2 | Green #00AA00 | 10 | Light Green #55FF55 |
3 | Cyan #00AAAA | 11 | Light Cyan #55FFFF |
4 | Red #AA0000 | 12 | Light Red #FF5555 |
5 | Magenta #AA00AA | 13 | Light Magenta #FF55FF |
6 | Brown #AAAA00 | 14 | Yellow #FFFF55 |
7 | Light Gray #AAAAAA | 15 | White #FFFFFF |
The Scan Range fields determine how close a planet or ship must be to see the object. The host does visibility checks and filters the file accordingly when sending it to the players.
The Object Type determines the type of the object. Your programs should only use slots which they own, or which are still available.
PHost will also send wormholes to players in Ufo format, using Id numbers as determined by WormholeUFOsStartAt. Any Ufo object in that range will not be seen by players.
Advantages: Ufos work with both HOST and PHost.
Many client programs support Ufos. Programs known to do so
include EchoView,
PCC
, VPA
, and of
course Winplan
. Ufos are easy to
use.
Disadvantages: General Objects are more flexible because the add-on author can decide who sees which object, and because they can carry additional information.
utilX.dat will not obsolete sub-space messages, players will still want to read them. To allow client programs to link messages to starchart locations, HOST 3.20 introduced message tags. PHost started to use them with version 2.6, and uses them uniformly since 3.3b.
The message tag is at the beginning of the first line of a message, and looks like this:
(-pc086)<<< Distress Call >>> |
Here are all known message tags:
Tag | Meaning |
---|---|
(-90xxx) | Race-specific mission. Hiss, Dark Sense: xxx is a planet Id. Rob: xxx is a ship Id. |
(-a0xxx) | Message from 3rd-party add-on. xxx is the add-on identifier. Not used by PHost, but generated by a number of add-ons. Winplan can associate a bitmap file provided by the add-on author (vpauxXXX.bmp) with these messages. |
(-c0xxx) | Tim Continuum attacking planet #xxx, or PBPs. Not used by PHost, which sorts these as (-h). |
(-dRxxx) | Message from starbase #xxx (starbase built, ship built or recycled). When a ship surrenders, its race code (1..9, a, b) is reported as R, otherwise, R is zero. |
(-e0xxx) | Distress call from ship #xxx. |
(-f0xxx) | Ship or planet #xxx has been destroyed or captured. In PHost, xxx always is a ship Id. |
(-g0000) | HConfig. Not used by PHost. HOST reports its configuration in these messages. |
(-h0000) | Message from host. |
(-i0xxx) | Ion storm #xxx. |
(-l0xxx) | Minefield #xxx laid. |
(-m0xxx) | Minefield #xxx scanned/swept. |
(-n0xxx) | Intercepted enemy messages: ship #xxx ran on a mine, or planet #xxx being pillaged/RGAed. |
(-pRxxx) | Message from planet #xxx. R may be a native race code (1..9) if the message concerns natives, c if the message concerns colonists, or zero otherwise. |
(-rX000) | Message from race X (1..9, a, b). X may be 0 or missing if it is an anonymous message. |
(-s0xxx) | Message from ship #xxx. #xxx is zero if the ship no longer exists (glory device). |
(-t0xxx) | Terraform status from planet #xxx. |
(-uxxxx) | Message about UFO #xxxx. Used by PHost 4.0e and later for wormhole reports. Not supported by all clients. |
(-w0xxx) | Web drain complete on ship #xxx. |
(-x0xxx) | Explosion on long range sensors (#xxx = sequential number of explosion). |
(-y0xxx) | Meteor on planet #xxx. |
(-z0xxx) | Scanner report for planet #xxx. |
Last updated 22 December 2014.