Most of this description by Piotr Winiarczyk, with information from Heiko Schlenker, and then updated from PHost source. The 3.0/4.0 definition is "official", whatever that means, hence the [V].
Many arrays contain an unused zeroth element. PHost uses this to simplify index computations and checks. Bits not described here are zero.
The file format is version dependent.
All Versions
The AUXDATA.HST file always starts with the version number of PHost.
+0 BYTE PHost major version +1 BYTE PHost minor version
PHost 4.x
+0 BYTE PHost major version (4)
+1 BYTE PHost minor version
+2 18 BYTEs Timestamp
+20 WORD Turn number
+22 WORD First-Battle Info. For each race, one bit which is set if
the race has not yet seen a VCR and should be sent the
introductory message.
+24 14 BYTEs unused
+38 n BYTEs data. A sequence of blocks of variable size:
+0 WORD Block type
+2 WORD Block size
+4 n BYTEs Data
Programs must preserve blocks they don't know, and should
preserve the order of blocks. Blocks with numbers below
100 have permanent information, numbers above 100 are
transient and only exist during a host run.
--- Block 1 (Native races for starbases) ---
A BYTE array, indexed by planet Id, 0 to 500 (i.e. first element is
unused). Whenever a starbase is built, PHost saves the native race here.
Thus, when unregistered Cyborgs build a base on a Ghipsoldal planet,
they'll legally keep the T10 engines even when the natives are
assimilated up and a new race appears.Usually, this record is 501 bytes, but may be larger or shorter for cross-version compatibility.
--- Block 2 (Alliances) ---
An array of 169 WORDs, 13 rows of 13 WORDs each. Addressed as
`ARRAY[0..12, 0..12] OF WORD', where the first index (rows) is the race
offering an alliance, and the second index (columns) is the race the
alliance is offered to. The borders (0, 12) are there to avoid index
checks for unowned or Alien objects and are constant zero.
Bit 0 Ship level offered
Bit 1 Planet level offered
Bit 2 Mine level offered
Bit 3 Combat level offered
Bit 4 Vision level offered
Bit 5 Alliance offered
Bits 8..12 Corresponding offers are conditional
(compare to record type 22 in UTILx.DAT)This must be exactly 338 bytes.
--- Block 3 (Ship Scan Info) ---
A WORD array, indexed by ship Id, starting with 0 (i.e. first element is
unused). For each ship, this contains a bitfield of the races (other than
the owner of the ship) who saw the ship. This is used for consistency
checking of Intercept missions.
Bit 1 Fed saw it
Bit 2 Lizard saw it
:
Bit 11 Colony saw it
Bit 15 Ship is cloakedSize may vary depending on the ship limit.
--- Block 4 (Build Queue) ---
This block consists of a number of records of the following format:
+0 WORD Starbase Id
+2 WORD Hull type
+4 WORD Engine type
+6 WORD Beam type
+8 WORD Beam count
+10 WORD Torpedo type
+12 WORD Torpedo launcher count
+14 WORD 1 if cloning, 0 for regular build
+16 WORD Race
+18 DWORD Points in queue (priority)
+22 DWORD unusedThis block's size may vary depending on the build queue length.
--- Block 5 (PAL) ---
This block contains an array of DWORDs containing the current PAL for
each player. It is indexed by 0 (first element unused), and usually
contains a 13th element (index 12) which isn't used either.
--- Block 6 (Remote Control) ---
This block contains two arrays of equal size.
+0 WORD unused
+2 n RECORDs of 2 bytes each, for each ship:
+0 BYTE controller of RC'd ship, 0 if none
+1 BYTE 80h if remote control forbidden
+? WORD default remote control status
Bit 1 Player 1 said "remote forbid default"
Bit 2 Player 2 said "remote forbid default"
...
+? n WORDs real owners of remote-controlled shipsThe size of this block may vary, which affects the size of both arrays.
--- Block 7 (Ship Specials) ---
This record contains hull functions assigned to individual ships. For
each ship, it contains 8 bytes (64 bits):
+0 BYTE Special abilities 0 .. 7
+1 BYTE Special abilities 8 .. 15
+2 BYTE Special abilities 16 .. 23
etc. There is no unused dummy element.The size of this block may vary.
--- Block 8 (reserved) --- --- Block 9 (Ship Experience) --- --- Block 10 (Planet Experience) --- These records contain, for each ship/planet, one DWORD with the number of experience points it has. They do not contain an unused dummy element.
The size of this block may vary depending on the number of ships.
--- Block 11 (Permanent Enemies) [PHost 4.0h+] --- This record contains 11 WORDs, one per player. Bits in each word mark the players who are declared permanent enemies using 'enemies add', i.e. if player 3 does 'enemies add 6', bit 6 (valued 64) will be set in the third word.
There is no unused dummy element.
--- Block 12 (Modified Ship Specials) [PHost 4.0i+] --- This block contains modified ship functions. It has the same format as block 7. The actual meaning of the bits is defined in block 13.
This record can represent at most 64 modified ship specials. PHost 4.1e and later support more; those use block 14 instead of block 12 if necessary.
--- Block 13 (Modified Ship Special Definitions) [PHost 4.0i+] ---
This block contains 64 entries of the following format:
+0 WORD Basic device number (see HULLFUNC.DAT)
+2 WORD Experience level mask (bit 0 = L0 etc.)
Unused entries are zero.
--- Block 14 (Modified Ship Specials) [PHost 4.1e+] ---
This block contains modified ship functions.
+0 WORD "nbytes" Number of bytes per ship
+2 n RECORDs of "nbytes" each:
+0 BYTE Abilities 0..7
+1 BYTE Abilities 8..15
etc.The actual meaning of the ship abilities is defined by block 13. This record can represent more than 64 modified ship specials. It is used by PHost 4.1e when required. When fewer than 64 modified specials are in use, PHost 4.1e still uses block 12.
--- Block 101 (Ship Flags) [PHost 4.0d+] --- This block contains, for each ship, one DWORD with some useful flags. There is no dummy element. The size of this block may vary depending on the number of ships. Bit 0 Ship was re-crewed (captured) this turn Bits 1 .. 31 unused --- Block 102 (Planet Flags) [PHost 4.0d+] --- This block contains, for each ship, one DWORD with some useful flags. There is no dummy element. The size of this block may vary depending on the number of ships. Bit 0 Planet was re-crewed this turn (can this happen?) Bits 1 .. 31 unused --- Block 103 (New Ship Experience) [PHost 4.0d+] --- --- Block 104 (New Planet Experience) [PHost 4.0d+] --- These blocks contain, for each ship/planet, the number of new experience points gathered this turn, one DWORD per unit. Points will be collected and added to the real experience at the end of the host run.
There is no dummy element.
--- Block 105 (Turn Activity Level) [PHost 4.0f+] ---
This block contains 11 DWORDs with the turn activity level for each
player. The TAL is added to the player activity level at the end of
each turn.
--- Block 106 (Inhibited ship functions) [PHost 4.0i+] ---
This record contains the ship functions inhibited by the host or by
add-ons this turn. It has the same format as record 7 (64 bits per
ship). Only normal devices can be inhibited. If a device X is
inhibited, all modified X devices are automatically inhibited as
well, hence there is no record to parallel #12.
--- Block 107 (Explosions) [PHost 4.0k+] ---
This block contains 50 records of 4 bytes:
+0 WORD X
+2 WORD Y
(this is the same format as the Explosions field in KOREx.DAT)Blank slots have both X and Y equal to zero. The block starts with all used slots, followed by an appropriate amount of blank slots (if a blank slot sits between used slots, PHost will "compact" the data, and thus modify explosion numbers).
PHost 3.x or 2.x
The contents of a 2.x/3.x file is similar to the contents of a 4.x file, but does not contain the descriptive block headers.
+0 BYTE PHost major version
+1 BYTE PHost minor version
+2 18 BYTEs Timestamp
+20 WORD Turn number
+22 WORD PHost 3.x: First-Battle Info.
PHost 2.x: unused
+24 14 BYTEs unused
+38 501 BYTEs Native races for starbases. Indexed by planet Id, 0 to 500.
+? 169 WORDs Alliance Information.
+? 501 WORDs Ship Scan information. Indexed by ship Id, 0 to 500.
+? 500 RECORDs of 26 bytes each: ship build queue (same format as 4.x):
+0 WORD Starbase Id
+2 WORD Hull type
+4 WORD Engine type
+6 WORD Beam type
+8 WORD Beam count
+10 WORD Torpedo type
+12 WORD Torpedo launcher count
+14 WORD 1 if cloning, 0 for regular build
+16 WORD Race
+18 DWORD PHost 3.x: Points in queue (priority)
PHost 2.x: unused
+22 DWORD unused
+? 13 DWORDs Player activity levels. Slot 0 and 12 are unused.
--- PHost 3.x only: ---
+? WORD Unused
+? 500 RECORDs of 2 bytes each: remote control.
+? WORD Default remote control setting for each player.
+? 500 WORDs real owner of remote controlled shipsPHost 1.x [T]
+0 BYTE PHost major version
+1 BYTE PHost minor version
+2 501 BYTEs Native races for starbases
+? 144 BYTEs Alliance info. An `ARRAY[0..11, 0..11] OF BYTE', where
where the first index (rows) is the race offering an
alliance, and the second index (columns) is the race the
alliance is offered to. Index 0 is not used.
Bit 0 Ship level offered
Bit 1 Planet level offered
Bit 2 Mine level offered
Bit 3 Combat level offered
Bit 4 Vision level offered
Bit 5 Alliance offered
+? 501 WORDs Ship scan info, indexed 0 to 500.
+? 500 RECORDs of 14 bytes each: build queue
+0 WORD Starbase Id
+2 WORD Hull type
+4 WORD Engine type
+6 WORD Beam type
+8 WORD Beam count
+10 WORD Torpedo type
+12 WORD Torpedo launcher count
