©	Auxiliary Data Files The Portable Host Version 3.2.3.5g Jump to Table of Contents

INDEX

• Introduction
• Information for Host-Side Developers
• Information for Player-Side Developers
• Record Type Summary
• Record Descriptions

Introduction

This page contains information on the structure of the auxiliary data files (UTIL.DAT files) created by PHOST (described below). This information will only be of interest to programmers of add-on utilities.  Hosts, however, should ensure that they send the UTIL.DAT file for each player along with their RST file.

When you run PHOST, you will notice that in addition to the usual RST files there are an extra set of files generated (named UTIL1.DAT, UTIL2.DAT, etc.) These files contain data that is intended to enhance the operation of add-on utilities. Currently, information-management utilities (such as EchoView and VPA) rely upon parsing the messages returned from HOST for information about minefields, sensor sweeps, etc. This mechanism of information transfer is cumbersome and not easily adaptable to the multiple-language support of PHOST.

The data contained in the UTIL.DAT files is simply a subset of the information that is conveyed by player messages, except that it is presented in machine-readable form. This data, then, is independent of the player's choice of language and also does not require parsing the player messages.

UTIL.DAT files are also used by PHOST for transmitting data of any sort, when this data is not easily sent via the RST file. For example, when a player requests that the PCONFIG.SRC file be sent to him via the send config command processor command, the PCONFIG.SRC file is sent in the UTIL.DAT file. The UTIL.DAT file is therefore a standardized and extensible file transfer mechanism that does not require changes to the RST file format, which may lead to incompatibilities with existing utilities.

Back to the index

Information for Host-Side Developers

If you are writing a host-side utility (i.e., a program that is meant to run on the hosting system) then you can include your own information in UTIL.DAT files. The contents of your information are completely arbitrary, but it is suggested that you adhere to the formats described below to simplify the task of player-side utility writers.

To include data into a UTIL.DAT file, simply write your data to a UTIL.EXT file. PHOST will concatenate the existing UTIL.DAT contents with UTIL.EXT to form the new UTIL.DAT file. This happens in Phase 3 of PHOST (during UTIL.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 the UTIL.EXT file. That is, issues of endianness, word size, and structure packing must be addressed prior to writing the UTIL.EXT file. Remember that this file will be transmitted to and interpreted on a DOS system.

To ensure that your RecordType designators (see the formats below) are unique, please contact the PHOST maintainers to obtain a unique range of designators. The range of designators that have already been reserved are listed below:

Back to the index

Information for Player-Side Developers

The format of a UTIL.DAT file is described below. All entries in these files assume a DOS-oriented data model which means that:

• data is stored LSB first (little endian)
• a char is 8 bits
• a word is 16 bits
• a longword is 32 bits
• enumerations (type enum) are 16 bits

The file is divided into contiguous records where each record consists of the following header information:

                enum   RecordType           
                word   RecordSize

The RecordType field indicates the kind of message conveyed (e.g., mine scan, ship explosion, etc.) The allowable types are described below. The RecordSize field indicates the number of bytes that follow the header (the size does not include the header size).  Utilities should dynamically read and use the RecordSize 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. NOTE: RecordSize may be 0, indicating that the next record's header follows immediately, without any data for the current record.

Back to the index

Record Type Summary

This table summarizes the various record types that PHOST generates.

Back to the index

Record Descriptions

The record types along with their associated data follows below.

This message is generated when a minefield is laid, scanned, or swept, as long as some mine units still remain. This is a summary message (except for laying and sweeping) which means that only one message per minefield is generated. The minefield information that exists at the end of the host run is reported (except for laying, which is reported immediately) so that all laying, sweeping, and scooping activity is complete. Both enemy minefields and own-race minefields are reported.

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 FCodePlanet element 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. For scans of enemy minefields, this element is 0.

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

This message is generated when a ship is destroyed in battle. This message is sent to all players (including the participants in the battle).

This message is generated when a ship hits a mine. The position reported is the position at which the mine hit occurred. The damage reported is the total ship damage after the mine hit. This message is sent to both the ship owner and the owner of the minefield.

This message is sent to the Empire and his allies to which the vision level of alliance has been granted. It is a report of a Dark Sense mission.

This message is sent to the Birdmen and his allies to whom the vision level of alliance has been granted. It is a report of a Super Spy mission.

This message is sent as a result of an Exploration mission. It is also generated by a Super Spy mission or a Pillage mission. The message is sent to the player that performed the exploration mission and to the allies to which the player has enabled the vision level of alliance.

This message is sent as a result of a Sensor Sweep mission. The Activity element is a measure of the industrial activity on the planet where 0 is very light and 5 is heavy. This message is sent to the player that performed the sensor sweep mission and to the allies to which the player has enabled the vision level of alliance.

This message is sent after a battle has been performed and is used to report on the outcome of the battle. This message is sent to both participants in the battle, and to any allies they have to which they have enabled the combat, ship, and vision levels of alliance. If IsPlanet2 is 1, then ShipID2 actually refers to a planet ID. The Damage1 and Damage2 parameters refer to the damage sustained as a result of the battle. Similarly, the torps and fighters parameters indicate how many torps and fighters each ship has remaining.

The Outcome parameters can be interpreted as follows:

Note that in PHOST, planets can capture ships. Outcome 3, No Ammo, is true when after a battle a ship has no beam weapons, no torps, and no fighters remaining. This outcome will never occur as long as the ship has beam weapons.

The "seed" value is the same as in the VCR record.

This message is sent to all races after a meteor strike.

This message is sent to the owner of a planet that got hit with a meteor shower.

This message is sent when the AllowMoreThan50Targets configuration option is disabled but more than 50 enemy ships (or allied ships) are scanned, in total. The first 50 ships are stored in the player's RST file and the excess are transmitted with this message.

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.

This message is sent to a player's allies when he enables the planetary level of alliance. Basically, the allies are given information regarding the existence of the player's bases.

This message is sent to a player's allies when he enables the planetary level of alliance. The allies are given partial information about a player's planets. The NativesType enumeration indicates the type of natives on the planet and may be one of the following values:

The NativeGovernment enumeration indicates the type of native government and may be one of the following values:

The four mineral values reflect the amount of each mineral present on the surface of the planet, not in the core.

This record is generated once for every utility file. It will be the first record in the file. This record contains administrative information about the file, the game, and the current turn.

The HostRunTime entry is an 18-character array which is the same as the timestamp found as part of the RST file. By matching this timestamp with the one found in the RST file, an external program can confirm that the utility file does indeed correspond to the RST file. The TurnNumber and Player entries should also match the corresponding entries in the RST file. The Player entry can also be compared against the name of the utility file (i.e., to catch cases where the file is named UTILx.DAT but it does not belong to player 'x').

The two version entries indicate the version number (major and minor) of the PHOST program that generated the utility file. The PHOSTVersionRelease entry is a single character identifying the interim release level of the program (in between two minor version upgrades). It is a single ASCII character, possibly a blank. These version entries are for information purposes only.

The next eight entries are 32-bit digests of the ship-list data files used by the host, as well as digests of the planet positions file, the configuration file, and the race names file. The purpose of these fields is to allow player-side utilities to perform a digest on the same files on the player's system and to compare the two numbers. This information can then be used to swap data files to and from the main game directory (so that original-shiplist and alternative-shiplist games can be automatically supported). Another use for these fields is to ensure that the player is using the exact same version of the data files, so that discrepancies do not arise between what Planets sees and what PHOST sees. Finally, the digest of the configuration information can be used to determine when this information changes from one turn to the next. Such a change indicates that the player should obtain the updated configuration file from the host. The digest of the race name file serves the same purpose.

The GameName array contains a null-terminated string that represents the setting of the GameName configuration option set by the host. Player utilities can use this field to attach meaningful names to result files.

This record is generated once for every wormhole scanned. The position of the wormhole entry point is reported along with its mass and a code indicating the stability. The code is related to the stability as follows:

The ID field indicates the wormhole ID. Wormhole ID's 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 ID's may be missing due to wormholes that have collapsed or unidirectional wormholes (which will not have an odd-valued ID number).

This message is sent to the player that scanned the wormhole and to all allies to whom he has enabled the vision level of alliance.

This record is generated for every ship that travels through a wormhole. The location at which wormhole travel began is given along with two damage numbers: NewDamage indicates the damage caused by travelling through the wormhole and TotalDamage indicates the total amount of damage to the ship after adding NewDamage to the ship's existing damage level.

The ID field indicates the wormhole ID of the entry point. See the Wormhole Scan record for a discussion of wormhole ID's.

This record indicates that the ship with the given ID number has been recycled at the specified base. This message is sent to the base owner only.

This record type is not generated by PHOST. It may be used by external utilities that simulate ion storms.

This record indicates that the ship with the given ID number has been disassembled at the specified planet for the purposes of colonization. This message is sent to the ship owner only.

This record indicates that a ship has surrendered at a base. Both the ship owner and base owner are given since this record is sent to both players (ship and base owners).

This record indicates that a new ship was built. This record is sent only to the owner of the new ship. The BaseID member indicates the starbase at which the build occurred. The ByCloning member is non-zero if the ship was built by virtue of cloning another ship (using the cln friendly code).

This record is generated when a ship changes ownership by virtue of the give ship command processor command or the gsN friendly code. This record is sent to both the old owner and new owner of the ship.

This record is generated for every player that is somehow involved in an alliance (in either the offered, requested, or accepted state). The four components of this record are all 11-byte arrays that are 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, OfferTo[5] indicates the alliance levels that this player has offered to the Privateers. OfferFrom[3] indicates the alliance levels that the Birdmen have offered to this player.

Each entry in both arrays may be decoded according to the following bit assignments:

                     MSB                         LSB
                    +---+---+---+---+---+---+---+---+
                    | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
                    +---+---+---+---+---+---+---+---+
                      |   |   |   |   |   |   |   |
                      \   /   |   |   |   |   |   |________ Ship Level
                       \ /    |   |   |   |   |____________ Planet Level
                        |     |   |   |   |________________ Minefield Level
                     Unused   |   |   |____________________ Combat Level
                              |   |________________________ Vision Level
                              |____________________________ Active Bit

The 5 LSB's encode the various levels of alliance. The 6th bit, the Active Bit, indicates whether an alliance is actually offered. The other 5 bits have no meaning unless the Active Bit is set. If the Active Bit is 0, then no alliance is offered.

For example, if player number 3's alliance status record indicates that OfferTo[5] 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, OfferTo[N] and OfferFrom[N] should always be zero.

The last two arrays in this record indicate which levels of alliance have been offered on a conditional basis. Like the OfferTo and OfferFrom 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 decoding of each array element is similar to the OfferTo and OfferFrom arrays:

             MSB                         LSB
            +---+---+---+---+---+---+---+---+
            | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
            +---+---+---+---+---+---+---+---+
              |       |   |   |   |   |   |
              \_______/   |   |   |   |   |________ Ship Level Conditional
                  |       |   |   |   |____________ Planet Level Conditional
                  |       |   |   |________________ Minefield Level Conditional
                Unused    |   |____________________ Combat Level Conditional
                          |________________________ Vision Level Conditional

Note that if an alliance level is not enabled, then the conditional bit will always be 0.

This record is generated by a bioscan performed by a ship equipped with bioscanners. This message is sent to the ship's owner as well as to all allies to which the ship's owner has enabled the vision level of alliance.

See the Planet Target record for a description of the NativesType parameter. Note that both NativesType and NativePopulation may be 0 (either both are, or both are not).

This record is generated for a ship which has been destroyed because its glory device has exploded. This message is sent only to the ship's owner. Note that this message applies only to ships with a glory device that explodes, not to ships that are affected by a glory device explosion on another ship.

This record is generated for a ship that has been damaged by a glory device explosion on another ship. The total damage after the explosion is reported. This message is sent to the ship owner as well as to the owner of the ship whose glory device exploded. If the damage is greater than 100%, then the ship has been destroyed.

This record is generated when a ship is captured by a boarding party. This message is sent to both the old owner and new owner of the ship. The ShipID field is the ID of the ship that was captured, and the BoardingShipID is the ID of the ship that performed the capture.

This record is no longer generated by PHOST. In older versions of PHOST, this record was used to send the contents of the PCONFIG.SRC file to players. PHOST now uses the general file transfer record for this purpose.

This record is generated when a planet suffers a ground attack. The record is sent to the original owner of the planet as well as to the race performing the ground attack. The Outcome field can have one of the following values:

This record is generated when two minefields explode due to overlap. All players receive this message. The XCenter and YCenter parameters indicate the co-ordinates of the minefield centers. In addition, the minefield ID numbers are included for easier updating of minefield databases. The MinefieldUnits parameter indicates the number of units removed from each minefield from the explosion.

Note that, in some cases, minefields may not lose "symmetric" amounts. PHost will generate record 53 when that happens.

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. Thus, this record is also known as the CYA Record.

This record is generated when a ship scoops mine units out of a minefield to form torpedoes. The TorpsConverted parameter indicates the number of new torps added to the ship's cargo, and the UnitsScooped parameter indicates the number of minefield units by which the mine with ID MinefieldID has been reduced. The UnitsBeforeScoop parameter indicates the number of minefield units that were present in the mine prior to scooping. This message is sent to the ship's owner.

This record is generated when a Pillage mission is carried out. The number of remaining colonist and native clans on the planet are reported. This message is sent to the planet owner as well as to the player performing the pillage.

This record format is meant to be used as a template for external add-ons to use in communicating with client-side utilities. 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 first 9 fields (up to and including InfoField2) 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 UtilCode field should be just the RecordType that has been assigned to the add-on utility (see above). The client-side utility can use this information in processing the next section.

• Following the UtilCode field the add-on program can add any desired object-specific information. The client-side utility may or may not make use 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.

The ObjectID field can be used to discriminate between different objects from the same add-on program. There is one convention that should be followed regarding this field, however. If this object is also an object that is stored in the UFO.DAT file, then the ObjectID should correspond to the same ID as for the entry in the UFO.DAT file. This will allow client-side utilities to know when two objects found in the UFO information and in the UTIL.DAT file are really the same object. Thus, objects which are not in the UFO.DAT file should have ObjectID values greater than 1000 (the maximum number of objects in the UFO.DAT file).

See also General Object Destruction (Record 42).

This record is used to send host-side files to the player. Currently, PHOST uses this record for the following tasks:

• to send the PCONFIG.SRC file to the player when requested via the send config command processor command, or when a planet's friendly code is set to con

• to send the RACE.NM file to the player when requested via the send racenames command processor command

• to send an XTRFCODE.TXT file to the player when requested via the send fcodes command processor command

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

The FileName field is used to indicate the name of the file to write. It is 12 characters long in support of the MS-DOS 8.3 file naming convention. The Flags field indicates certain attributes of the file being transferred. The bit assignments in this field are currently as follows:

• Bit 0: Binary/Text Flag (0 - binary, 1 - text)

If bit 0 (the LSB) of the Flags field is 0, then the file is a binary file and should be saved as-is on the player's system. If this bit is 1, then the file is a text file and may be interpreted as such. PHOST 3 converts all text files to native MS-DOS format prior to including them in this record (unlike older PHOST versions which included them as-is). This means that client-side programs need not worry about end-of-line conversions (e.g., LF to CR-LF).

• Bit 1-7: Reserved for future use (always 0 for now)

The length of this record is variable, as it depends upon the size of the file being transmitted. The RecordSize element of the record header must be used to dynamically determine the record size.

This record is used to indicate the failure of a cloaking device on a ship. This record is only sent to the ship's owner, and only if the AllowCloakFailMessages config option is enabled. The exception to this rule is for cloak failure due to a tachyon pulse (Reason is 5). When a cloak fails for this reason, this record is generated regardless of the AllowCloakFailMessages config option setting.

The Reason element can take on one of the following values:

This record is superseded by the general Failure Notice record, but it is still sent, for backward compatibility.

This record is used to report the position and owner of a ship that has been decloaked using a tachyon beam (by a Loki ship) and is over a planet. This record is sent to the owner of the Loki ship. Since version 3.5c, the record is also sent to the owner of the decloaked ship to tell them about the event. The last field (BeforeMovement) tells you whether the reporteded position is before or after movement (AntiCloak_1 or AntiCloak_2 stage).

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*NumShips bytes, there will be NumShips sets of words, each set describing one ship ID and either that ship's true owner (in the OwnerN field) or the value 0xFFFF (all bits are 1) to indicate that this ship is forbidden from being remotely controlled. For more information, please see the "Remote Ship Control" page. Note that the total length of this record will be 2*NumShips 16-bit words or 4*NumShips bytes.

Note that this record really serves three separate purposes:

1. When ShipID is a ship that belongs to the player and Owner is a player number, this indicates that one of the player's own ships is curently under remote control.
2. When ShipID is a ship that belongs to the player and Owner is 0xFFFF, this indicates that one of the player's own ships is not available for remote control by other players (i.e., it is a forbidden ship).
3. When ShipID is a ship that does not belong to the player, then this indicates that he has scanned an enemy ship which is under remote control. The Owner field then indicates the true ship's owner.

This record is used to indicate player activity for a turn, as it relates to the ship build queue operation. The OldLevel field indicates the player activity level (or PAL) from the previous turn. The DecayPoints field indicates the number of activity points lost due to decay (as set by the PALDecayPerTurn config option). The NewPoints field indicates the number of activity points earned on this turn (known as the Turn Activity Level, or TAL, in the build queue description). Finally, the NewLevel field indicates the updated activity level for the player as of the end of the current turn.

PBPs: in PHost 3.4i and above, OldLevel is the level at the beginning of the turn. The number of used PBPs can be computed as UsedPBPs = OldLevel - DecayPoints - NewPoints - NewLevel. In previous versions, OldLevel is the level after PBP consumption (i.e. the formula will yield 0); the used PBPs can be computed as the difference between this turn's OldLevel and the previous turn's NewLevel.

This record is used to report 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 NumShips being reported, the record length will be 10*NumShips bytes. For each ship, the BaseID field indicates the starbase, HullType is the numeric code for the hull being built (see the "Custom Hull Functions" page for a list of hull numbers for both the original ship list and PLIST), Position is this build order's position in the build queue (position 1 is the next ship to be built), and Priority is this build order's priority (high priority orders are built first). Please see the "Ship Build Queue" page for more information on build order priorities.

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.

This record is used to report that a ship stuck in a web mine has run out of fuel (or continues to be out of fuel). This message is sent to the minefield's owner, which must necessarily be a Crystal race. Web mines owned by non-Crystal races do not drain fuel hence no web drain report is generated.

This record is sent to both the ship and planet owner after a successful "Rebel Ground Attack" (RGA) mission. The second field Natives says whether the planet has natives or not. This is NOT a native race number!. The third field reports the player which performs the RGA (ship owner).

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) for more information.

This record is deprecated and may be removed sometimes in the future. The same information is also sent in record 51.

When minefield limits are active (MaximumMinefieldsPerPlayer), this record is sent to players each turn. The Allowed array contains, for each player, the number of minefields he is allowed to lay (the value of the above-mentioned config option).

The Laid array 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.

This record is send to tell you about failed actions. The "action" field contains a util.dat record number and says what failed, the other fields tell you why. The "cause" field contains a standard failure code.

Code	Meaning
0	Random chance
1	Insufficient fuel
2	Excess damage
3	Ionic pulse
4	Wormhole Travel
5	Tachyon pulse
6	Ion storm
10	Lacking resources
11	Lacking tech
12	No receiver unit
13	Feature disabled by host
14	Not allowed by rule
15	Not allowed by partder
16	Global object limit exceeded
17	Per-player limit exceeded
18	Required ability missing
19	Target object does not exist
20	Per-unit limit exceeded

• 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 sent when the clone order was successfully submitted to the build queue, but you did not have enough minerals when your turn came.
  • 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.
• Action = 21 (Ship Trade)
  • Cause = 12: receiver didn't have a ship or planet at the ship position
• 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)
• Action = 45 (Planet Trade)
  • 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).
  • Cause = 0: Rob failed due to random chance
  • Cause = 10: towing ship ran out of 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 (MineIdNeedsPermission); a Gather-type mission failed because the planet was not friendly.
  • Cause = 16: all minefield slots are used
  • Cause = 17: MaximumMinefieldsPerPlayer exceeded
  • Cause = 18: tow strength too weak to tow target
  • Cause = 19: attempt to add mines to a non-existing or non-matching field.

This record allows additional data to follow the standard information. For Action=10000, there are three words of additional data, containing the mission, intercept and tow numbers.

This record is generated when a planet changes ownership by virtue of the give planet command processor command. This record is sent to both the old owner and new owner of the planet.

This record has the very same contents and meaning as Record 0. It is used for minefields with Id numbers >500 to support players that use "old" and "new" programs at the same time.

When AllowMoreThan500Minefields is turned off for a player but there is a minefield with an Id number > 500, PHOST will send this record type. When AllowMoreThan500Minefields is turned on, all minefields will be reported using record type 0.

This record contains a list of planets which do not exist. Clients can use this to adjust their starchart accordingly.

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.

This is a general means of reporting ship-specific scores. The Name contains the human-readable name of the score. The ScoreType contains the identifier of the score, for use by programs. The ScoreLimit 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.

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:

This is a general means of reporting planet-specific scores. It has the same format as record 49 (ship-specific scores). The Name contains the human-readable name of the score. The ScoreType contains the identifier of the score, for use by programs. The ScoreLimit is an informational limit for this score. It can be -1 (=65535) if there is no limit.

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:

This is a general means of reporting scores. The Name is a human-readable description of the score. The ScoreType contains the identifier of the score, for use by programs. The WinLimit specifies how many points a player must reach to win the game, and the TurnLimit specifies how many turns he must be above that limit. The Scores field, finally, lists the scores for all 11 players. Scores which a player is not permitted to see are -1 (=0xFFFFFFFF).

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 is sent when BuildPointReport is set to Yes or Allies, and it 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.
3	Mines laid. This record is sent when mine field limits are active. It contains the current number of minefields laid for all your mine-level allies. This record is intended to replace record 43.
2 .. 99	reserved
100 .. 32767	available for 3rd-party developers

This record is used by PHost 4.0a and later to report ship-specific abilities. The data area consists of a ship Id, followed by one or more function identifiers (e.g. 9=Gambling, 13=Ramscoop). A complete list is on the Custom Hull Functions page and not replicated here due to laziness of the editor. The number of functions is defined by the record size

Note that function identifiers can take any value, not just those explicitly defined in this version of the PHost documentation. Newer host versions may introduce new functions. Function codes above 1000 are reserved to be used by add-on, contact the PHost group to have an identifier allocated to you.

There might be many records for a ship, these are cumulative.

This record is generated when two minefields explode due to overlap. Normally, two minefields overlap, both lose the same amount - done. That would be reported with record 29.

In some cases, it can happen that minefield losses cannot be assigned to minefield pairs. In this case, PHost generates a type-53 record for each affected field. Type-29 and type-53 will be mixed as PHost sees fit.

All players receive this message. The XCenter and YCenter parameters indicate the co-ordinates of the minefield center. In addition, the minefield ID number is included for easier updating of minefield databases. The MinefieldUnits parameter indicates the number of units removed from this very minefield from the explosion.

This record contains a bitfield of players whom you have declared a permanent enemy. This feature is not supported in PHost 3.x.

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 CargoType field contains the type of resource produced:

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

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.

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.

Back to the index

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