UTILx.EXT - PHost - Add-on Information [V]
The UTILx.DAT files are generated by PHost to allow client programs to get information in machine readable form, without parsing messages.
PHost-aware add-ons can write their information to a UTILx.EXT file in the host directory, PHost will append that file to the final UTILx.DAT file. Note that UTILx.EXT is purely a host-side thing, it is never sent to players. Players only receive the final UTILx.DAT.
During PHost processing, add-ons still see the old UTILx.DAT files. If you want to check something in such an add-on, you may try to use the UTIL.TMP file generated by PHost, see under the `Host files' section.
In several records, PHost attempts to do you a favor in sending you "human-readable" values, namely
- you often get a population count, not the number of clans like in the other files. Divide by 100 to get clans;
- you get an actual Fahrenheit temperature, not the encoded value from the PDATAx.DAT file. Subtract from 100 to get a PDATA-compatible value.
General File Structure
The file contains records of the following layout:
+0 WORD Type
0..40 used
41..16383 reserved for PHost
16384..16399 Torsten Czerny
16400..16431 Jens Hofbauer
16432..16447 Rafael Alvarez
16448..16479 Sven Bursch
16480..16511 Ingo Korb
16512..16639 Stefan Reuther
16640..32767 Available
32768..65535 Reserved
+2 WORD Number of data bytes following
+4 n BYTEs dataThe file begins with a control record (type 13). A program can use this record to check if the file corresponds to the current turn. PHost generated records follow in more or less chronological order. Finally, an End record (type 30) terminates the PHost information, after it follow records from add-on programs (UTILx.EXT).
This file lists all known version dependencies, but you should not rely on them: to know whether a particular piece of information is available in your UTILx.DAT, check the actual record sizes, not version numbers. Records might grow in the future, so you should handle the size anyway.
The records
--- Type 0 (Mine field) ---
+0 WORD Mine field Id
+2 WORD X
+4 WORD Y
+6 WORD Owner
+8 DWORD Mine Units
+12 WORD Type (1=Web, 0=normal)
--- PHost 2.0+ (?): ---
+14 WORD for own mine fields, Id of planet with friendly code,
zero otherwise.
--- PHost 2.6d+: ---
+16 WORD Cause of this report:
0 Mine field laid
1 Mine field swept
2 Mine field scannedThe most current information comes last. If the player this minefield belongs to uses Winplan, non-existence of a `Minefield scanned' record means the minefield does no longer exist.
--- Type 1 (Explosion) --- +0 WORD X +2 WORD Y +4 WORD Ship Id --- PHost 3.4+: --- +6 20 BYTEs Ship name --- Type 2 (Mine hit) --- +0 WORD Ship Id +2 WORD X +4 WORD Y +6 WORD Damage % --- PHost 3.4b+: --- +8 20 BYTEs Ship name --- Type 3 (Dark Sense) --- +0 WORD Planet Id +2 WORD Owner +4 4 DWORDs Minerals (N,T,D,M) +20 DWORD Money +24 WORD 1=Starbase exists --- Type 4 (Super Spy) --- +0 WORD Planet Id +2 WORD Mines +4 WORD Factories +6 WORD Defense Posts +8 3 BYTEs Friendly Code +11 4 DWORDs Minerals (N,T,D,M) +27 DWORD Money --- PHost 3.0+: --- +31 DWORD Supplies --- Type 5 (Planet) --- +0 WORD Planet Id +2 WORD Temperature (actual value, not 100-F like in PDATAx.DAT) +4 WORD Owner (0-11) +6 DWORD Colonists (not number of clans!) +10 WORD 1=Starbase exists --- Type 6 (Sensors) --- +0 WORD Planet Id +2 WORD Owner (1-11) +4 WORD Industrial activity 0 minimal 0 .. 29 structures 1 light 30 .. 59 structures 2 moderate 60 .. 89 structures 3 substantial 90 .. 119 structures 4 heavy >= 120 structures 5 heavy >= 150 structures (structures is mines + factories)
Note that the value 5 here gives more information than there is in the actual messages. This is considered a (minor) bug and may be removed in the future.
--- Type 7 (Battle result) ---
+0 WORD left ship Id
+2 WORD right ship/planet Id
+4 WORD 1=right is planet
+6 2 WORDs Owners (left, right)
+10 2 WORDs Damage after fight
+14 2 WORDs Torpedoes after fight
+18 2 WORDs Fighters after fight
+22 2 WORDs Battle results
0 Winner
1 Object captured (ships only)
2 Object destroyed
3 Object without ammunition
--- PHost 1.3+: ---
+26 WORD X
+28 WORD Y
--- PHost 3.4b+: ---
+30 WORD Random Seed
--- Type 8 (Meteor) ---
--- Type 9 (Meteorite Shower) ---
+0 WORD Planet Id
+2 4 DWORD Minerals (N,T,D,M)
--- Type 10 (Visual Contact) ---
+0 WORD Id Number
+2 WORD Owner
+4 WORD Warp
+6 WORD X position
+8 WORD Y position
+10 WORD Type of starship hull
+12 WORD Heading in degrees, 0=North, 90=East, 180=South, 270=West
+14 20 BYTEs Ship nameThis is the same format as in TARGETx.DAT.
--- Type 11 (allied starbase) --- +0 WORD Base Id +2 WORD Base owner --- Type 12 (allied planet) --- +0 WORD Planet Id +2 WORD Owner +4 WORD Temperature (0-100, actual value, not 100-F) +6 WORD Native race +8 WORD Native government +10 DWORD Natives (number of natives, not clans!) +14 4 DWORDs Mined minerals (N,T,D,M) +30 DWORD Colonists (number of colonists, not clans!) +34 DWORD Supplies +38 DWORD Money --- Type 13 (Control record - File Header) --- +0 18 BYTEs Timestamp +18 WORD Turn number +20 WORD Player number +22 BYTE PHost Major version +23 BYTE PHost Minor version +24 8 DWORDs "Digests" of the files HULLSPEC.DAT, ENGSPEC.DAT, BEAMSPEC.DAT, TORPSPEC.DAT, TRUEHULL.DAT, XYPLAN.DAT, PCONFIG.???, RACE.NM, see below +56 32 BYTEs Game Name --- PHost 2.11h+: --- +88 BYTE PHost Release Code ('e' in 3.2e) --- Type 14 (Wormhole) --- +0 WORD X +2 WORD Y +4 WORD Mass +6 WORD Stability Chance of successful passage 0 very stable 95% 1 stable 85% 2 quite stable 70% 3 unstable 50% 4 very unstable 20% 5 totally unstable <20% +8 WORD Id. Even number for entry points, odd for exits --- PHost 3.4h/4.0e+: --- +10 WORD Id of corresponding Ufo +12 WORD 1=bidirectional, 0=enter only
For how wormholes and wormhole Ufos correspond, see UFO.HST.
--- Type 15 (Wormhole Travel) --- +0 WORD Ship Id +2 WORD X +4 WORD Y +6 WORD caused damage +8 WORD Total damage = original damage of ship + caused damage +10 WORD Wormhole Id --- Type 16 (Ship recycled) --- +0 WORD Ship Id +2 WORD Base Id --- Type 17 (Ion storm) [PHost 1.3+] --- +0 WORD Storm Id +2 WORD X +4 WORD Y +6 WORD Voltage +8 WORD Heading +10 WORD Speed +12 WORD Radius +14 WORD Class (1..5) +16 WORD Growth
This record has been defined since PHost 1.3, but is not generated until 4.0j. There is at least one add-on (by Vladimir Babchuk) which also generates these records.
--- Type 18 (Colonize Mission) [PHost 1.3+] --- +0 WORD Ship Id +2 WORD Planet Id --- Type 19 (Ship surrendered) [PHost 1.3+] --- +0 WORD Ship Id +2 WORD old ship owner +4 WORD Base Id +6 WORD base owner
In PHost 1.3, this record did not contain the base owner (same format as type 20), and reported a ship that surrendered to the enemy.
--- Type 20 (Ship built) [PHost 1.4+] --- +0 WORD Ship Id +2 WORD Base Id +4 WORD 0=normal build, cloned otherwise
This record is used since PHost 1.4. In PHost 1.3, record 20 reported a ship that surrendered to us:
+0 WORD Ship Id
+2 WORD Base Id
+4 WORD original owner
--- Type 21 (Ship given away, "gsN" friendly code) [PHost 1.3c+] ---
+0 WORD Ship Id
+2 WORD old owner
+4 WORD new owner
--- Type 22 (Alliance) [PHost 1.4b+] ---
+0 11 BYTEs Offered to ...
+11 11 BYTEs Offers exist from ...
Bit 0 Ships
Bit 1 Planets
Bit 2 Minefields
Bit 3 Combat
Bit 4 Visibility
Bit 5 1=Valid offer, 0=invalid
Bits 6,7 = 0
--- PHost 2.6+: ---
+22 11 BYTEs Conditionally offered to ...
+33 11 BYTEs Conditional offers exist from ...
Bits 0..4 like above, rest 0
--- Type 23 (Bioscan) [PHost 2.6+] ---
+0 WORD Planet Id
+2 WORD Native race (see PDATAx.DAT)
+4 DWORD Natives (people, not clans!)
+8 WORD Temperature
--- Type 24 (Glory Device exploded) [PHost 2.6+] ---
+0 WORD Ship Id
+2 WORD X
+4 WORD Y
--- Type 25 (damaged by Glory Device) [PHost 2.6+] ---
+0 WORD Ship Id
+2 WORD X
+4 WORD Y
+6 WORD Total damage
+8 WORD Ship Owner
--- PHost 3.4b+: ---
+10 WORD Hull type of damaged ship
+12 20 BYTEs Name of damaged ship
--- Type 26 (Ship boarded) [PHost 2.6+] ---
+0 WORD Ship Id
+2 WORD Old owner
+4 WORD New owner
--- PHost 2.9e+: ---
+6 WORD Id of boarding ship
--- Type 27 (PCONFIG.SRC) [PHost 2.6 to 2.9] ---
+0 n BYTEs File data. Verbatim copy of PCONFIG.SRC.This record isn't in use any more since PHost 2.10.
--- Type 28 (Ground combat) [PHost 2.6+] ---
+0 WORD Planet
+2 WORD Owner
+4 WORD Attacker
+6 WORD Result
0 Owner wins
1 Attacker wins
2 All colonists killed
--- Type 29 (Minefields explode) [PHost 2.6d+] ---
+0 WORD X Mine field 1
+2 WORD Y Mine field 1
+4 WORD Id Mine field 1
+6 WORD X Mine field 2
+8 WORD Y Mine field 2
+10 WORD Id Mine field 2
+12 DWORD Number of exploded mines
--- Type 30 (End of PHost info) [PHost 2.7a+] ---
This record doesn't contain data.PHost sends this record as the last one in UTILx.DAT, before it appends UTILx.EXT.
--- Type 31 (Mines scooped "msc") [PHost 2.9d+] ---
+0 WORD Ship Id
+2 WORD Mine field Id
+4 WORD Number of torpedoes made
+6 DWORD Number of removed mines
--- PHost 2.11h+: ---
+10 DWORD Number of mines before this action
--- Type 32 (Pillage Mission) [PHost 2.9d+] ---
+0 WORD Planet Id
+2 DWORD Colonist clans(!)
+6 DWORD Native clans(!)
--- PHost 3.4g/4.0c+: ---
+10 WORD Owner of Klingon ship (important in PlayerRace games)
--- Type 33 (General Object) [PHost 2.10+] ---
+0 WORD Id (Ufo Id, or bigger than 1000 if there isn't a matching
Ufo record)
+2 WORD X
+4 WORD Y
+6 WORD Color
+8 WORD Radius
+10 WORD Speed
+12 WORD Heading
+14 20 BYTEs Name
+34 20 BYTEs Info 1
+54 20 BYTEs Info 2
Note that the PHost specification file does not say
anything about the format of these strings. By analogy with
Ufos, one would expect standard BASIC strings (space
padded), but the fact that PHost is in C speaks for zero-
terminated strings. So, for a robust program, expect both
types.
+74 WORD Type code
1024 Ion Storm by Vladimir Babchuk
32765-32766 QVS by Hans Wilmer
32767 Starbeamer by Hans Wilmer
+76 n BYTEs optional additional informationNote that it is definitely possible to receive two objects with the same Id, but different type codes, as it's quite hard to synchronize add-ons among each other. It is not quite clear if it's legal for an add-on program to generate two objects with the same Object Id and type code, which only differ in the info strings and in the additional information block. Most existing client programs (EchoView, PCC) will not handle this.
This record is never generated by PHost; it is intended for use by add-ons.
--- Type 34 (File) [PHost 2.9d+] ---
+0 12 BYTEs File name
+12 BYTE Flags
Bit 0 1=Text file, 0=binary
Bits 1..7 are reserved
+13 n BYTEs File dataThis record type is used by PHost to transfer RACE.NM, PCONFIG.SRC and XTRFCODE.TXT, the results of the "send racenames", "send config" and "send fcodes" commands. It should not problematic for your add-on to use it for similar purposes.
--- Type 35 (Cloak failure) [PHost 2.10b+] ---
+0 WORD Ship Id
+2 WORD Cause
0 Cloak Failure Rate
1 No fuel
2 Hull damaged
3 Ionic pulse (Super Spy)
4 Wormhole passed
5 Tachyon pulse (Loki)This record is superseded by type 44, but is still sent.
--- Type 36 (Cloaked ship detected) [PHost 2.11g+] ---
+0 WORD Ship Id
+2 WORD X
+4 WORD Y
+6 WORD Owner
--- PHost 3.4e/4.0c+: ---
+8 WORD 1=before movement, 0=after
--- Type 37 (Remote-controlled ships) [PHost 3.0+] ---
+0 x BYTEs Records of 4 bytes each
+0 WORD Ship Id
+2 WORD True owner. If the ship is in your
SHIPx.DAT file, you're controlling a ship
owned by this player. If it's a target,
you're scanning a remote controlled ship.
-1 for an own ship means remote control is
disabled for that ship.
--- Type 38 (Activities) [PHost 3.0+] ---
+0 DWORD old value
+4 DWORD decayed points
+8 DWORD gained points
+12 DWORD new value
--- Type 39 (Build Queue) [PHost 3.0+] ---
+0 n BYTEs Records of 10 bytes each
+0 WORD Base Id
+2 WORD Hull Type
+4 WORD Position in build queue
+6 DWORD Priority
--- Type 40 (Web Drain Complete) [PHost 3.0+] ---
+0 WORD Ship Id
--- PHost 3.4d+: ---
+2 WORD Ship Owner
+4 20 BYTEs Ship Name
--- Type 41 (RGA) [PHost 3.3c+] ---
+0 WORD Planet Id
+2 WORD 0 = No natives, 1 = Planet has natives
--- PHost 3.4g/4.0d+: ---
+4 WORD RGA player (important in PlayerRace games)
--- Type 42 (General Object Destruction) [PHost 3.3c+] ---
+0 WORD Object Id
+2 WORD Type CodeSee record type 33 for more information on General Objects.
This record is never generated by PHost; it is intended for use by add-ons.
--- Type 43 (Minefield Status) [PHost 3.3c+] ---
+0 11 WORDs Minefield limits, for all players. This is the value of
the MaximumMinefieldsPerPlayer config option.
+2 11 WORDs Number of minefields, for all players. You only see the
numbers of your race and your minefield allies; the other
positions are -1 (0xFFFF).This record is only sent if it actually contains useful information; if minefield limits are not in effect, this record is not sent.
--- Type 44 (Failure Notice) [PHost 3.4+] ---
+0 WORD Action (=UTILx.DAT record number, if possible):
20 Ship construction (cloning in particular)
21 Ship trade
35 Cloaking
45 Planet trade
10000 Ship mission failed
(new actions might be added, see PHost docs for a
definite list)
+2 WORD Ship Id
+4 WORD Planet Id
+6 WORD Cause
0 Random chance
1 Not enough fuel
2 Too badly damaged
3 Ionic pulse
4 Wormhole travel
5 Tachyon pulse
6 Ion storm
10 Not enough minerals
11 Not enough tech
12 No receiver unit at this place
13 Host has disabled feature
14 Not allowed by rules
15 Not allowed by partner
16 No slot for object (global limit exceeded)
17 Player limit exceeded
18 Unit does not have needed capability
19 Target object does not exist
20 Per-unit limit exceeded
+8 ? BYTEs additional info could follow here
--- Action 10000 ---
+8 Mission number
+10 Intercept parameter
+12 Tow parameter
--- Type 45 (Planet Trade) [PHost 3.4b+] ---
+0 WORD Planet Id
+2 WORD Old owner
+4 WORD New owner
--- Type 46 (Mine field) [PHost 3.4b+] ---
+0 WORD Mine field Id
+2 WORD X
+4 WORD Y
+6 WORD Owner
+8 DWORD Mine Units
+12 WORD Type (1=Web, 0=normal)
+14 WORD Id of planet with friendly code, or zero
+16 WORD Cause of this report (0=laid, 1=swept, 2=scanned)This record has the very same format as record 0. It is used for minefields with Id numbers >500 when AllowMoreThan500Minefields is off for that player.
--- Type 47 (Nonexistent Planets) [PHost 3.4c+] ---
+0 n WORDs Ids of non-existent planets. All planets listed here do
not exist for the host and an attempt to (for example)
drop cargo there will fail.Note that this record has been defined since version 3.4c, but is actually generated only by 4.1a/3.5a+.
--- Type 48 (PAL Summary) [PHost 3.4c+] ---
+0 11 DWORDs Player Activity Level for each player. -1 if not known.
--- Type 49 (Ship Score) [PHost 3.4d / 4.0+] ---
--- Type 50 (Planet Score) [PHost 3.4d / 4.0+] ---
+0 50 BYTEs Name; player-readable description of this score.
+50 WORD Identifier
1 Ship / Planet Experience Level
2 Ship / Planet Experience Points ($FFFF if larger
than 16 bit)
3..99 reserved
100+ available
+52 WORD Limit, -1 if no limit. The interpretation of the limit
depends on the type of the score. For experience, this is
the maximum level which can be reached.
+54 2xN WORDs Scores. Each entry is a pair of object Id and score.
Units for which the score is not known are not listed here.
--- Type 51 (Player Score) [PHost 3.4d / 4.0+] ---
+0 50 BYTEs Name; player-readable description of this score.
+50 WORD Identifier
1 Per-game Score. This is intended to be used by
the "main" scoring program in use for this game
to report "the score".
2 Build points (PAL / PBP)
3 Minefields allowed
4 Minefields laid
5..99 reserved
100+ available
1000 (c2nu) Military Score
1001 (c2nu) Inventory Score
+52 WORD Turns-over-limit required to win, -1 if not known.
+54 DWORD Win limit, -1 if none
+58 11 DWORDs Scores for each player. -1 if not known.
--- Type 52 (Ship Abilities) [PHost 4.0a+] ---
+0 WORD Ship Id
+2 n WORDs List of ability numbers.See HULLFUNC.DAT for a list of special functions. Values <1000 are reserved for PHost, higher values are available to add-ons. Records are cumulative.
PHost 4.0i and later allow definition of hull functions restricted to a particular set of experience levels. The numbers used to refer to these functions are defined using record 57. Do not assume that record 57 always precedes record 52.
--- Type 53 (Minefield Exploding) [PHost 4.0b+] --- +0 WORD X +2 WORD Y +4 WORD Minefield Id +6 DWORD Units lost
This record is used by PHost since 4.1a/3.5a. It reports asymmetric losses due to rounding problems.
--- Type 54 (Enemy Report) [PHost 4.0h+] ---
+0 WORD List of enemies
bit 0 unused
bit 1 Feds
bit 2 Lizards
etc.
--- Type 55 (Production Report) [PHost 4.0i+] ---
+0 WORD Ship Id
+2 WORD Type produced
0 Neutronium
1 Tritanium
2 Duranium
3 Molybdenum
4 Colonists
5 Supplies
6 Cash
7 Ammo (Torps / Fighters)
8 Experience [PHost 4.1+]
+4 WORD Items consumed, bitfield. Can be 0 if items were free.
bit 0 cargo room of ship (e.g., alchemy)
bit 1 planet resources (e.g., gather-build torps)
+6 WORD Amount produced
--- Type 56 (Repair Report) [PHost 4.0i+] ---
+0 WORD Ship Id
+2 WORD How ship was repaired
0 Supply repair
1 Starbase "fix" order
2 Mission "Self repair"
3 Mission "Super refit"
4 Mission "Repair ship"
+4 WORD Id of unit helping with repair (planet Id for "fix" or
"super refit", ship Id for "repair ship", zero otherwise)
+6 WORD Damage repaired
+8 WORD Crew added
--- Type 57 (Special Function Definition) [PHost 4.0i+] ---
+0 WORD Function Id
+2 WORD Basic function. See HULLFUNC.DAT for a list.
+4 WORD Experience level mask (bit 0 = level 0 etc.)This record defines a modified hull function. If record 52 contains the number listed here as "Function Id", the ship has the device reported as "Basic function" restricted to the listed experience levels.
--- Type 58 (Minefield Explosion) [PHost 3.5c/4.1c+] --- +0 WORD X +2 WORD Y
This reports the explosion of a ship in a minefield. It corresponds to the Explosions field from Winplan RST files.
Digests for specification files
The control record (type 13) contains "digests" of the specification files, to help ensuring that both host and players use the same file set. These digests are kind-of a CRC, and are computed as follows:
* first, initialize a table -- as usual for CRC calculations
VAR crctab : ARRAY[0..255] OF DWORD; { 256 unsigned 32 bit quantities }
b, i : BYTE; { 8 bit, unsigned }
x : DWORD;
FOR b:=0 TO 255 DO BEGIN
x := b;
crctab[b] := 0;
FOR i:=0 TO 7 DO BEGIN
IF x AND 1 <> 0 THEN x := x XOR $10811; { `$' means Hex }
x := x DIV 2;
crctab[b] := crctab[b] + (x+1) * $10811; {*}
END;
END;* then, initialize a DWORD variable `digest' to zero.
* now, for each byte `b' from the appropriate file, do
digest := digest + crctab[(digest AND 255) XOR b] + digest DIV 65536
* the result in `digest' is the required 32 bit digest.
The computation of the digest uses the following parts of the files:
* The "undefined" bytes at the end of the files are ignored. Only the parts which are actually needed are covered:
- 6300 bytes of HULLSPEC.DAT;
- 594 bytes of ENGSPEC.DAT;
- 360 bytes of BEAMSPEC.DAT;
- 380 bytes of TORPSPEC.DAT;
- 440 bytes of TRUEHULL.DAT;
- 682 bytes of RACE.NM.
* The XYPLAN.DAT file is treated as if all owner fields were zero.
* The configuration digest is a byte-wise checksum over the internal configuration structure of PHost. It depends on the endianness of the host machine as well as the padding. In PHost below 3.0, this was the PCONFIG.HST file; I believe there is no longer a real use for this checksum outside PHost in 3.0 and later.
In PHost 3.4c and later, the configuration checksum covers the PCONFIG key names and values in text form, with whitespace and comments stripped. For example, when your PCONFIG.SRC contains "GameName = First Strike", the byte sequence "GameNameFirstStrike" is checksummed.
Note: except for the line marked {*}, this is precisely a standard CRC
(for a CRC-16, one would say `crctab[b] := x' after the inner loop). If
you have more information on this code, please tell me.
