[PHost Logo]

Utility Data Files (util.dat)
The Portable Host
Version 4.0

Index

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:

bytea 8-bit byte (0..255)
chara 8-bit ASCII character
worda 16-bit word (-32768..32767)
longa 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).

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

Record 0 - Mine ScanSince: 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 - ExplosionSince: 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 HitSince: 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 100 (150 for Lizards), the ship explodes.

Record 3 - Dark SenseSince: 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 his Vision-level allies

Record 4 - Super SpySince: 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 - ExplorationSince: 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 SweepSince: 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:

ActivityName Mines + Factories
0 minimal < 30
1 light 30 to 59
2 moderate 60 to 89
3 substantial90 to 119
4 heavy 120 to 149
5 heavy > 149
Record 7 - Battle ResultSince: 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:

0Victor: this unit won the battle
1Captured: this unit was captured (never true for planets)
2Destroyed: this unit was destroyed (in case of a planet, the planet got captured because all its defense was destroyed)
3No 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 beam weapons.

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 StrikeSince: PHost 1.0
word      Planet Id
long      Neutronium
long      Tritanium
long      Duranium
long      Molybdenum

Sent when: large meteor hits a planet

Sent to: all races

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 ShowerSince: 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 TargetSince: 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 TargetSince: 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 TargetSince: 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 RecordSince: 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 ScanSince: PHost 1.0
word      Location X
word      Location Y
word      Mass (0..32767)
word      Stability Code (0..5)
word      Id

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.

CodeStabilityApprox. 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 TravelSince: 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 RecycledSince: PHost 1.0
word      Ship Id
word      Base Id

Sent when: ship recycled at starbase

Sent to: starbase owner

Record 17 - Ion StormSince: PHost 1.3
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)

This record type is not currently generated by PHost. It may be used by external utilities that simulate ion storms. Future PHost versions which do ion storms will use this record.

Record 18 - Ship ColonizedSince: 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 SurrenderedSince: 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 ConstructedSince: 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 TradeSince: 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 StatusSince: 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 Fromindicates the alliance levels that the Privs have offered to this player.

Each element is a bitfield which may be decoded as follows:

BitMeaning
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 ReportSince: 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 ExplodedSince: 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 DeviceSince: 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 PartySince: 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 performed the capture.

Record 27 - Configuration FileSince: 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 AttackSince: 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:

0The ground attack failed. The Owner Race still owns the planet
1The ground attack succeeded. The Attacker Race now owns the planet
2All colonists are gone, the planet is now unowned
Record 29 - Minefields ExplodingSince: 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

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.

Record 30 - End of PHost InfoSince: 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 ScoopingSince: 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 - PillageSince: PHost 2.9d
word      Planet Id
long      Colonist Clans
long      Native Clans

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 ObjectSince: 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 TransferSince: 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 FailureSince: 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 CloakSince: PHost 2.11g
word      Ship Id
word      Location X
word      Location Y
word      Owner

Sent when: Loki decloaks a ship

Sent to: owner of the Loki

This record is sent to report de-cloaked ships in orbit of a planet only. De-cloaked ships not over a planet are not reported by this record since they simply show up as normal enemy targets.

Record 37 - Remote ControlSince: PHost 3.0
word      Ship Id 1
word      Remote Control Flag 1
word      Ship Id 2
word      Remote Control Flag 2
...and so on

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 ReportSince: 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 each player, as well as the points lost through decay and points gained through turn activity. Generally, the equation

New Level = Old Level - Decay Points + New Points

holds. See Build Point Details for more information on build points.

Record 39 - Build Queue ReportSince: 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 4 entries 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 CompleteSince: 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.

Record 41 - Rebel Ground AttackSince: PHost 3.3c
word      Planet Id
word      Native Flag (0=no, 1=yes)

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.

Record 42 - General Object DestructionSince: 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 StatusSince: 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 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 NoticeSince: 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. The Cause field contains a standard failure code. The record provides space for optional additional data which is currently not used.

Failure codes: The following Cause codes are currently defined. Not all of them are already used.

Code Meaning
0 Random chance
1 Insufficient fuel
2 Excess damage
3 Ionic pulse
4 Wormhole Travel
5 Tachyon pulse
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

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

Record 45 - Planet TradeSince: 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 - Nonexistant PlanetsSince: 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.

Record 48 - PAL SummarySince: 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 ScoreSince: 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

New 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 .. 99reserved for future use
100 .. 32767available 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 ScoreSince: 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

New 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 .. 99reserved for future use
100 .. 32767available for 3rd-party developers
Record 51 - Player ScoreSince: 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[Remote].
2Build points. This record will list all the build points. This record is intended to replace record 48.
3Mines 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.
3Mines 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.
4 .. 99reserved for future use
100 .. 32767available for 3rd-party developers

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:

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

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:

NumberColor NumberColor
0Black #000000 8Dark Gray #555555
1Blue #0000AA 9Light Blue #5555FF
2Green #00AA00 10Light Green #55FF55
3Cyan #00AAAA 11Light Cyan #55FFFF
4Red #AA0000 12Light Red #FF5555
5Magenta #AA00AA 13Light Magenta #FF55FF
6Brown #AAAA00 14Yellow #FFFF55
7Light Gray #AAAAAA15White #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[Remote], PCC[Remote], VPA[Remote], 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 yet 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 it may be more or fewer.

Here are all known message tags:

TagMeaning
(-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.
(-c0xxx) Tim Continuum attacking planet #xxx, or PBPs. Not used by PHost.
(-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.
(-h0000) Message from host.
(-i0xxx) Ion storm #xxx. Not used by PHost.
(-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 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 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. Not used by PHost.
(-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.

Back to top


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

Last updated 02 March 2003.