PHost - Utility Data Files (util.dat)

Index

• Introduction
• File Format Summary
• Record Details
  • Record 0 - Mine Scan
  • Record 1 - Explosion
  • Record 2 - Mine Hit
  • Record 3 - Dark Sense
  • Record 4 - Super Spy
  • Record 5 - Exploration
  • Record 6 - Sensor Sweep
  • Record 7 - Battle Result
  • Record 8 - Meteor Strike
  • Record 9 - Meteorite Shower
  • Record 10 - Ship Target
  • Record 11 - Starbase Target
  • Record 12 - Planet Target
  • Record 13 - Control Record
  • Record 14 - Wormhole Scan
  • Record 15 - Wormhole Travel
  • Record 16 - Ship Recycled
  • Record 17 - Ion Storm
  • Record 18 - Ship Colonized
  • Record 19 - Ship Surrendered
  • Record 20 - Ship Constructed
  • Record 21 - Ship Trade
  • Record 22 - Alliance Status
  • Record 23 - Bioscan Report
  • Record 24 - Glory Device Exploded
  • Record 25 - Damage from Glory Device
  • Record 26 - Boarding Party
  • Record 27 - Configuration File
  • Record 28 - Ground Attack
  • Record 29 - Minefields Exploding
  • Record 30 - End of PHost Info
  • Record 31 - Minefield Scooping
  • Record 32 - Pillage
  • Record 33 - General Object
  • Record 34 - File Transfer
  • Record 35 - Cloak Failure
  • Record 36 - Anti Cloak
  • Record 37 - Remote Control
  • Record 38 - Activity Level Report
  • Record 39 - Build Queue Report
  • Record 40 - Web Drain Complete
  • Record 41 - Rebel Ground Attack
  • Record 42 - General Object Destruction
  • Record 43 - Minefield Status
  • Record 44 - Failure Notice
  • Record 45 - Planet Trade
  • Record 46 - Mine Scan (High-Id)
  • Record 47 - Nonexistent Planets
  • Record 48 - PAL Summary
  • Record 49 - Ship Score
  • Record 50 - Planet Score
  • Record 51 - Player Score
  • Record 52 - Ship Abilities
  • Record 53 - Minefields Exploding
  • Record 54 - Enemy Status
  • Record 55 - Production Report
  • Record 56 - Repair Report
  • Record 57 - Special Functions Report
  • Record 58 - Explosion
• Information for Host-Side Developers
  • External Utility Data
  • Replacing Hosting Stages
  • Ufos - UFO.HST
• Sub-Space Messages

Introduction

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.

Back to top

File Format Summary

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:

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.

Back to top

Record Details

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 was laid. PHost reports the status immediately after laying (before mines-destroy-mines).
• a minefield was swept. PHost reports the status immediately after sweeping. It may report a zero-size minefield when the field was swept out.
• a minefield was scanned. PHost combined all scans into one message, and reports the minefield size at the end of all scanning. When a mine field is swept out after you scanned it, you will not get a scan record.

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.

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

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

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

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.

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.

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:

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.

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:

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.

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.

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.

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:

• When the AllowShipNames option is set appropriately, ship names may be stubbed out.
• Fuel-less ships are reported as having warp zero and no heading.
• When the RacePlus "chameleon device" is used, Lizard ships can report fake hull types.

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.

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:

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.

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.

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.

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

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.

word      Ship Id
word      Base Id

Sent when: ship recycled at starbase

Sent to: starbase owner

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.

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)

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)

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)

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

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:

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.

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.

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.

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.

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.

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.

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:

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.

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.

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.

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.

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 9 fields from Position X to Info Field 2 are generic fields not specific to any add-on program. They contain enough information to allow a client-side utility to display the object on a starchart without knowing which add-on program is the source of the object, or even what the object is. The Color field should follow the same encoding as for Ufos.
• The Object Id and Utility Code can be used to identify the object. The Utility Code should be taken from the record type range assigned to the add-on utility. Client programs which know about the add-on program can use this information to process the next section.
• The standardized data block may be followed by object-specific information. It is up to the writer of the add-on program to define the layout of this information.

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:

• EchoView
• PCC
• xk

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

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

• Bit 0 = 0: file is a binary file and must be unpacked verbatim
• Bit 0 = 1: file is a text file, in DOS text format (lines terminated with CR+LF). Unpackers may translate it accordingly. Note that PHost 2.x sends text files verbatim as they are on the host system.

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:

• to send the pconfig.src and shiplist.txt files, in response the send config command or the con friendly code. These files are text files.
• to send the race.nm file when requested via the send racenames command. This is a binary file.
• to send the xtrfcode.txt file when requested via the send fcodes command. This is a text file.

Add-on programs may use this record for a similar purpose.

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.

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.

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.

• If the Remote Control Flag is a player number (1..11), that is the ship's true owner. When you remote-control a Rebel ship, the RST file reports it as yours, and this record reports the true owner as 10. When the Lizards control one of your ships, the RST will report it as a Lizard ship, and this utilX.dat record will report your player number as the true owner.
• If the Remote Control Flag is 0xFFFF (all bits are 1), the ship is forbidden from being remotely controlled. Currently, only your own un-remoteable ships are reported.

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.

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.

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.

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.

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)

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

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.

Codes currently in use: These are all the Action / Cause combinations which PHost currently generates.

• Action = 16 (Ship Recycled)
  • Cause = 14: attempt to recycle a ship you don't own (some clients wrongly allow you to set these orders).
• Action = 18 (Ship Colonized)
  • Cause = 15: planet was inhabited by unfriendly race
• Action = 20 (Ship Construction)
  • Cause = 10: cloning of a ship failed due to lacking minerals. This message is sent when you do not have enough minerals by the turn the ship is actually scheduled for building.
  • Cause = 11: clone order not accepted because starbase doesn't have sufficient tech.
  • Cause = 14: clone order not accepted because you can build this ship normally.
  • Cause = 18: clone order not accepted because ship is unclonable.
• Action = 21 (Ship Trade, give command)
  • Cause = 12: receiver didn't have a ship or planet at the ship position
  • Cause = 18: ship is ungiveable
• Action = 35 (Cloak Failure)
  • Cause = 0: cloak failed due to random chance
  • Cause = 1: cloak failed due to insufficient fuel
  • Cause = 2: cloak failed due to excessive hull damage
  • Cause = 3: cloak failed due to an ionic pulse
  • Cause = 4: cloak failed due to wormhole travel
  • Cause = 5: cloak failed due to a tachyon pulse (from a Loki)
  • Cause = 6: cloak failed due to ion storm
• Action = 45 (Planet Trade, give command)
  • Cause = 12: receiver didn't have a ship at the planet
• Action = 56 (Repair)
  • Cause = 15: attempt to repair a ship you don't own and you are not allied with.
• Action = 10000 (ship mission failed)
  This record describes a failed ship mission, which may not have their own util.dat record number. It contains three words of additional data, reporting the mission, intercept and tow numbers.
  • Cause = 0: Rob failed due to random chance
  • Cause = 10: towing ship ran out of fuel, training ship had no fuel, Academy ship trying to exchange crew had no fuel.
  • Cause = 13: attempt to lay mines but AllowMinefields resp. AllowWebMines is off
  • Cause = 14: attempt to RGA or pillage a planet which has already been plundered this turn
  • Cause = 15: attempt to lay mines in someone else's Id without permission (AllowMinefieldIdentity, MineIdNeedsPermission); a Gather-type mission or training failed because the planet was not friendly, crew exchange failed because target ship didn't have ship-level alliance or matching friendly code.
  • Cause = 16: all minefield slots are used
  • Cause = 17: MaximumMinefieldsPerPlayer limit exceeded
  • Cause = 18: tow strength too weak to tow target
  • Cause = 19: attempt to add mines to a non-existing, non-matching, or maximum-size field, attempt to transfer torpedoes, fighters or cash to a ship that is at a different place or cannot carry the torpedoes/fighters, attempt to train while not at a planet, target ship for crew exchange not existant or at different location.
  • Cause = 20: attempt to train but ExperienceLimit already reached

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.

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.

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.

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.

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. Experience points above 65535 are reported as 65535. With usual configurations, these high scores do not occur.
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.

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. Experience points above 65535 are reported as 65535. With usual configurations, these high scores do not occur.
3 .. 99	reserved for future use
100 .. 32767	available for 3rd-party developers

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

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:

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.

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.

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:

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.

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:

The How Produced field tells you what was used to produce the new items:

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.

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.

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

Back to top

Information for Host-Side Developers

This section contains information for host-side developers who want to send information to players.

External Utility Data

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:

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.

Replacing Hosting Stages

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.

Ufos - UFO.HST

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:

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.

Back to top

Sub-Space Messages

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 >>>

• The hyphen identifies the message as a current one, it could also be o for an old message (see DeleteOldMessages, not supported by PHost).
• The first letter (p) contains the class of the message. Here, it is a planet message.
• The second place may be a number or letter and gives further information.
• The last digits finally are the Id number of the referred-to object. Usually, there are three digits, but there may be more or (rarely) fewer.

Here are all known message tags:

Back to top

Last updated 31 May 2015.