VGA Planets(tm) 3 __________________________ File Formats and more INTRODUCTION - THIS FILE IS FOR PROGRAMMERS ONLY ================================================= Contents --------- This file contains descriptions of the file formats of the strategic play-by-email game VGA Planets(tm) 3 by Tim Wisseman, and of some 3rd party utility programs for that game. The file is meant as a help to programmers of new utility programs. I don't know where the programmers of existing utilities got their information from as I didn't find a file comparable to this one yet. I started from nothing with my hex editor and a debugger. If you don't want to do this too, here are my results. I just can't stand if there are files on my hard disk and I don't know how they are built up. Technically interested Planets players may also find one or another useful information. As stated above, this list was created with the famous "Trial and Error" method and doesn't claim to be complete and always correct. Entries marked with [V] were verified with Wisseman's PD programs (for example, VPCPLAY) and the host documentation or other "official" sources. I have not yet used all these files in my programs, sometimes I've only taken a few samples and compared them. Those are marked with [T]. If you can report success using such files, please do. This file also contains the official file format definitions for PCC, my client program, which are also marked with [V]. Really unknown information is marked with ?, other works correctly in my daily use. Since early 2001, I have been member of the PHost group; and since early 2002, I have a copy of the VPA source. Most information in this file is older; I did not walk through the sources and check everything. I think that's not needed anyway, looking at a program from the outside gets one a much better view, without obscure comments getting in the way ;-) However, for most new features (PHost 4.0), documentation in this file is written together with the implementation and can be considered authoritative. I do not guarantee for anything. If you mess up your game with this information, it's your fault. If you get an unfair advantage using this information, you're a .... (sorry, I don't know English curses ;-) and should be kicked out of the Echo Cluster. Anyway, do you want to play your turn with a Hex editor? This file now uses the Latin-1 character set. Most of it should be standard US-ASCII, but we need special characters to spell Akseli's name correctly :) On Cheating ------------ This file is not meant as a cheating guide. Though the Wisseman Host (THost for short) implements some cheat checks, there are still some major loopholes. Most client programs won't let you exploit them, but this file is for writers of new such programs. Please, play by the rules. What to consider "rules" is left to your common sense. If you want fun and challenge, play honest. If you want to cheat, play other games. Single-player Descent with BIGRED cheat comes to mind ;-) Older hosts often send you data you should not have. Nowadays, it is generally considered legal to make use of this information, as "official" and "white hat guy" programs (Winplan, EchoView) let you access it. The rationale is you should no longer use these ancient hosts (pre-3.2). Basics ------- This section contains some basic assumptions I make throughout the file. If you don't know them, the descriptions may be ambiguous, so do read this part. All original VGA Planets(tm) programs are written in a 16-bit MS BASIC dialect. This, and the implementation of Planets, has an effect on the used data types: + Character strings are, if not stated otherwise, stored in "BASIC format". This means, they are padded with spaces and stored without a length byte. Some programs will include the trailing spaces when interpreting the value, some will not. At least for names it probably makes most sense to trim trailing spaces. + Most fields are WORDs (2 bytes) and DWORDs (4 bytes). BASIC doesn't allow BYTE fields in files. All values are signed, little-endian, two's-complement integers unless specified otherwise. Most values are limited in range. If there's no limit specified here, assume 0..10000 for WORD data and 0..1000000000 (10^9) for DWORDs (TRN file check in host, client-side data may be more "flexible"). + BYTEs (characters) are unsigned, if not otherwise noted. This is the default interpretation in BASIC and Turbo Pascal, in C you should explicitly cast to `unsigned char'. Checksums generally are the sum of a memory block interpreted as a series of such unsigned bytes. + In BASIC, pointers into files count from 1, not 0 as in most other languages. This list uses the standard convention (starting with 0, decimal offsets). However, to use a pointer read from a Planets file (RST, MDATA, etc.), you have to code something like `Seek(Pointer-1)' in Pascal or C. + If there's an array with 500 elements and the description talks about "the ship", use a Ship-Id as index into the array. This is similar for Planets and Starbases, and for arrays with 11 elements and races. Note that with Host999 ship arrays are often split, one part containing the 500 "standard" ships, and one with the 499 "extra" ones. + Except for messages, high-ASCII characters should be avoided. In names, they are permitted but not displayed by PLANETS.EXE; and depending upon the client program used, they are interpreted using a DOS (cp437) or Windows/Unix (latin1) character set. In FCodes and passwords, high-ASCII characters are not allowed by the file format or the rules. + In string literals, control characters are shown using their decimal value. For example, `"CCsim",26' is the literal "CCsim" followed by character 26 (Ctrl-Z in this case). In addition, we use CR=13, LF=10. I assume you're familiar with common programmer's terminology. I use a Pascal-like notation: DIV integer division (17 DIV 5 = 3) MOD remainder (17 MOD 5 = 2) / float division (17 / 5 = 3.4) FOR i:=1 TO 10 for(i = 1; i <= 10; i++) in C ARRAY[0..9] OF X an array containing 10 elements with index 0 to 9 Trunc(x) truncate towards zero Round(x) round arithmetically (.5 rounds up) ERnd(x) round to nearest, .5 rounds towards nearest even I have also prepared an "appendix" to the File Format List, which contains a few notes about how to implement all this, and pointers to free implementations. You get this file at the same place you got this list from, or . File Names ----------- Traditionally, VGAP is played on operating systems that do not distinguish file name case. It originated on MS-DOS which converted all file names to upper case. Therefore, by convention, all file names in this documentation are shown in upper-case (and often still appear this way on Microsoft operating systems). VGAP is now also played on operating systems that do distinguish upper and lower case in file names. In these operating systems, it is customary to use lower-case file names. It is recommended to access files by their lower-case names. This will work under all circumstances: + DOS/Windows don't care + lower-case is used by most VGAP software for Unix, including PHost, PCC2/PlayVCR, GWP, k-util, PDK-based software, ... PHost and PDK-based software will also read files in all-uppercase names, but this is rarely used and not well-tested. In particular, PHost will always create files with lowercase names, even if a matching uppercase file already exists. Avoid this. Some programs create mixed-case names ("HullSpec.Dat"). This should be avoided by any means, because it is very inefficient for Unix software to figure out. As an additional MS-DOS relic, file names should adhere to the "8.3" file name length convention. Specialties ------------ Some programs interpret the file specs quite liberal, partly due to the fact that they have never been officially published. Here are some specialties you may or may not want to take care of: + `Owner' fields on ships/contacts may be 12, if the `Jumpgate' add-on is used. PCC/CCBSim also allows you to use player-12-owned ships in a simulation, PHost allows to set a player to `race 12', giving a totally unspecial race (although there is never a thing such as `Player 12'). Some simulators generate `vcr12.dat' which they hand to VCR.EXE. + The Dominion computer player often generates zero-terminated ship names, not space-padded ones. This results in junk being displayed after the actual ship name. The "peng" shiplist compiler will also do this when needed with specification files, to avoid checksum problems. You may want to add a bogon filter for item names and messages (which often cite ship names) to your program. Some PHost versions will also store some fields (VCR, Ufos) as zero-terminated strings. + Not all programs generate or evaluate the 10 signature bytes at the end of each data file. + Most third-party programs do not validate the player-side checksums (GENx.DAT, CONTROL.DAT). You should still update them to support programs which check them, in particular the Wisseman MAKETURN. + If possible and practical, you should check ranges of variables before using them. I have already seen UTILx.DAT `General Object' records with five-digit Warp factors. When taking the documentation word by word, these do not violate any constraints -- as there are none. But such speeds are clearly not usable for computing the way something will travel this turn... Special Thanks --------------- + to Franki, for PView, a killer app of which VPA is just a mere clone; and for decoding RESOURCE.PLN; + to Bart Dopheide, whose invaluable eagle eyes pointed out many mistakes here and elsewhere; + to Piotr Winiarczyk, for the original AUXDATA.HST information, and PHost wormholes; + to Akseli Mäki, for many close looks at small details; + to Tim Wisseman who likes the number 13. This has made decoding many files much easier to me. Sections of this file ---------------------- PLAYER DATA files a player has on his hard disk while playing his turn; TRN FILE describes the TRN file format in all its variations; RST FILE describes RSTs; HOST DATA describes the files the Wisseman Host (and PHost, though -- strictly speaking -- PHost is "3rd party") uses to keep universe data and other information; FIXED DATA files that are normally constant throughout a game, such as the xxxSPEC files or name lists. These are used by the host and the players; CHECKSUMS lists all checksums you may need to update if you write a player-side program; 3rd PARTY file formats of various 3rd party programs (not by Tim Wisseman). If you wish your file format to be added here, feel free to contact me. There's a client-side section and a host-side section; FILE LIST a list of file names and programs that own these files. Comes in handy when debugging game directories people sent you; FIELD LIST provides a cross-reference about which property is stored where. Note that the borders between sections are floating: what you consider a host file, I may list under `fixed' or even `3rd party'. Programs mentioned in this List -------------------------------- + VGA Planets 3.0, the original game by Wisseman + Winplan 3.5x, the Windows version + Host 3.x & Co., the Wisseman hosting programs, including Host999 + SRace, Wisseman's Race Switcher + PCC and PCC2, clients by Stefan Reuther (that's me ;-) + PView 2.0, a starchart utility by Frank Hempel + AFSim 1.2, a simulator by Sean Martens + Informer 2.x, a player-side utility by Sean Martens + VPA, a client by Alex Ivlev, now Open Source + PHost 2 and later, the Portable Host + VPUtil & Co., some client tools by Jan P. Dijkstra + Aliens!, a host add-on by Thore Schmechtig + PTScore, an alternate scoring system by Thomas Voigt + VGA Planets Movie Recorder/Player, a program by William Barath + The Killing Floor (TKF), the multi-ship combat engine by Dale Pope + ...and some random notes about others CHANGES ======== 13 Dec 2014 - minor updates to .CCB 12 Feb 2014 - added .CCB version 5 17 Feb 2013 - minor editing 20 Jan 2013 - some details for minefields in Winplan RSTs - some notes about file name case 30 Jun 2012 - Added PCC .FNT file format for completeness - ExploreMap endianness 23 Jun 2012 - Added FLAKx.DAT/FLAK.HST file format 29 Dec 2011 - PCC2 .QC file format 21 Dec 2011 - Updated PCC2 SCRIPTx.CC 30 Oct 2011 - Updated PCC2 SCRIPTx.CC - Some mentions of c2nu (planets.nu <=> RST/TRN interface) 16 Nov 2010 - PHost GEN.HST extra fields 10 Jul 2010 - PCC2 SCRIPTx.CC 03 Jan 2010 - PCC2 CHARTx.CC 18 Jul 2009 - PHost 4.1e modified hullfunc storage - checksum notes 21 Jan 2009 - notes regarding property storage in PCC 1.x vs. 2.x - new .CCB flags for PCC 1.1.17 22 Sep 2008 - UTILx.DAT record 58 30 Mar 2008 - SCORE.CC (PCC2) 22 Mar 2008 - PCC2 language files (.lang) 19 Aug 2007 - minor updates 17 Jul 2007 - VPA 3.63 new marker shapes 15 May 2007 - PLANETS.EXE's ship palette shuffling 01 Feb 2007 - PHost 4.1 PLANGxx.HST - mention "RST Format 36" 27 Oct 2006 - PHost 4.1, new HULLFUNC.DAT format 24 Aug 2006 - SHIPSCAN.EXT time stamps 15 Aug 2006 - VCRx.DAT, PHost 4.0k new capability 05 Aug 2006 - Winplan planet pictures, plus minor fixes and additions 19 May 2006 - PHost 4.0k, AUXDATA.HST block 107 28 Dec 2005 - added PHONEY.HST 02 Oct 2005 - fixed spelling 02 Sep 2005 - added .CCB version 4 02 Jul 2005 - added new UTILx.DAT records and PHost 4.0i hullfuncs 30 Dec 2004 - converted to latin1 07 Dec 2004 - added field cross-reference 22 Jul 2004 - new UTILx.DAT, DISTTABL.DAT 07 Apr 2004 - note about intra-race ship/ship transfers in PLANETS.EXE 14 Mar 2004 - odd fixes 30 Dec 2003 - new UTILx.DAT/AUXDATA.HST stuff, odd fixes 14 Sep 2003 - new VPAx.DB "SEXP" and "PEXP" blocks 07 Sep 2003 - historic: AUXHULL.DAT, DEVSPEC.DAT (I searched for ages what program did write them into my planets directory :) - random notes 01 Jul 2003 - notes about jettison 04 Jun 2003 - AUXDATA.HST updated, smaller corrections 01 May 2003 - Some TKF stuff 04 Jan 2003 - PHost 4 VCR stuff 16 Sep 2002 - upcoming SendBack / $send-file 04 Sep 2002 - VGA Planets Movie Recorder/Player (VPMC, VPMPLAY) 15 Aug 2002 - some fixes, TONS2.HST 02 Jul 2002 - new PHost 3.4b UTILx.DAT records 13 May 2002 - notes on older UTILx.DAT records 05 Apr 2002 - older HCONFIG.HST sizes; Ufo owner list updated 27 Mar 2002 - notes on ancient Host data leakage; PHost 3.4 10 Mar 2002 - fixed happiness formulas (hooray); some fixes 19 Feb 2002 - note about CORR; odd fixes 15 Feb 2002 - some notes on VPAx.DB, from VPA source 05 Feb 2002 - VPAx.DB info from Piotr Winiarczyk (PLAN, SHIP, NPLN, EPLN) - TARGETx.DAT clarified (Akseli Mäki) - .CCB version 3 updated, note on Host .31 SB cheat check 09 Jan 2002 - KOREx.DAT/SKOREx.DAT corrections from Akseli Mäki 01 Jan 2002 - CMDx.TXT 23 Dec 2001 - new UTIL.TMP format 06 Oct 2001 - added file list 03 Oct 2001 - newest Hosts (3.22.027 to .040), Explore Map, VPA10k 15 Sep 2001 - new PHost 3.3c UTILx.DAT records 02 Aug 2001 - Some VPA stuff 21 Jul 2001 - Cargo transfers (SHIPx.DAT) 26 Jun 2001 - Owner fields in VCRx.DAT from PHost 06 Jun 2001 - comment on Host500 + Unpack999 29 Apr 2001 - new FLEETx.CC format, odd fixes 11 Feb 2001 - VCRx.DAT and `NTP', thanks to Akseli Mäki 24 Jan 2001 - odd fixes 07 Jan 2001 - note about buggy ship records, new CHARTx.CC format 20 Nov 2000 - VPHost Binary Data Transfer 13 Nov 2000 - VMx.CC 26 Oct 2000 - note about PHost wormholes - .CCB version 2 18 Sep 2000 - some VPAx.DB records 22 Aug 2000 - fixed MESS35.DAT, some CC.RES details, minor corrections 28 Jul 2000 - UTIL.TMP, minor changes 21 May 2000 - more AUXDATA.HST stuff 15 May 2000 - AUXDATA.HST from Piotr, SHIPSCAN.EXT 26 Mar 2000 - `Password N' data transmissions 09 Mar 2000 - some VCR stuff, minor changes 02 Mar 2000 - PHost spec file digests 24 Feb 2000 - TEAMS.DAT (PTScore) 07 Jan 2000 - minor changes 18 Dec 1999 - VPAMSGx.DAT, ALIENS!.HST, CPx.CC 12 Dec 1999 - minor changes 15 Nov 1999 - NOTESx.DAT with Winplan999, HULLFUNC.TXT - XYPLAN and Explore Map, some Informer things 04 Oct 1999 - Host999, PHost version of BaseBuildShip, minor changes 28 Sep 1999 - Informer Alliance Information, TEAMx.CC, minor changes 23 Sep 1999 - TASKx.DAT, AUTOx.DAT nearly complete 24 Aug 1999 - minor changes, message limits 04 Aug 1999 - Improved layout - some corrections (SNOOKER.DAT) 06 Jun 1999 - VPA Data Transmission checksum 19 Mar 1999 - UTILx.DAT - PHost VCRs 16 Aug 1998 - AUTOx.DAT 30 May 1998 - VPA Data Transmission - TRN File Id Block 02 Apr 1998 - Some corrections - Removed the host run list. There are better and more complete lists available. 08 Mar 1998 - Some changes in latest hosts 30 Jan 1998 - SRace - even more Winplan 03 Jan 1998 - more Winplan info - WPVCR.DLL updated 09 Dec 1997 - VPAx.DB basics - first English version 19 Sep 1997 - Winplan, TRN attachments, parts of 3.5 TRN format 26 Aug 1997 - More host files 21 Apr 1996 - FIZZ.BIN, VCRx.DAT, complete 3.0 TRN format 24 Dec 1995 - most 3.0 player and host files 28 Oct 1995 - oldest existing copy: most important game data files, partial RST/TRN PLAYER DATA ============ The "x" in names matches the player number (1 to 11). For a description of the two signatures see GENx.DAT. For starships, planets and starbases there is a .DAT and a .DIS file. The .DAT file contains changes made by the player. The .DIS contains the information as extracted from the RST file (.DIS = "discarded"???). MAKETURN looks for differences between these and makes a TRN file. The .DIS files are generally not modified during a turn, clients only modify the .DAT. Winplan Shareware ------------------ The Winplan Shareware version is technically nearly identical to the DOS Planets client. It creates DOS TRNs and unpacks only DOS RSTs. The Windows resource files (WPVCR.DLL, BMP/WAV directory) are used anyway, as are version 3.5 message files (MESS35x.DAT). AUTOx.DAT - Winplan - Auto stuff [T] ------------------------------------- +0 WORD ? +2 4000 BYTEs 500 records of 8 bytes each, for all planets +0 WORD 1 = Auto Sell Supplies on 0 = off +2 WORD preferred mine count +4 WORD preferred factory count +8 WORD preferred defense count +4002 10 BYTEs ? +4012 n BYTEs Auto Waypoints (file format bug -- see below!) +0 6 WORDs 1 = this auto waypoint is enabled +12 6 WORDs Auto Waypoint X coordinates +24 6 WORDs Auto Waypoint Y coordinates +36 6 WORDs Missions (0=no change) +48 6 WORDs ? +60 6x3 BYTEs Friendly Codes +78 6 WORDs Task number (0=none, or 1..10), see TASKx.DAT. +90 6 WORDs 0 = delete this order if completed 1 = repeat ## Auto Waypoints Winplan allows to assign each ship up to 6 waypoints, missions and friendly codes for the future. The `repeat/delete' flag tells what to do if this order is completed (waypoint reached): if set to `delete', it is removed from the list. if set to `repeat', all tasks are shifted by one position, and this task is placed at the end of the list. Note that this file format is bogus. For each ship's Auto Waypoint, Winplan reserves 48 bytes (that is, ship #1's record is loaded from +4012, ship #2's record from +4060, etc.), though each record uses 102 bytes. So waypoints for adjacent ship Ids overlap, with garbage being displayed in the auto waypoint window. This makes it impossible to specify auto waypoints for ships with adjacent Ids, and even if the Ids are two apart, you're not safe. ## NAUTOx.DAT There's a patch to avoid the above problem. It changes the auto task storage to proper 102-byte records, starting at +4012. The file name is changed to NAUTOx.DAT. BDATAx.DAT - New Base Data [V] BDATAx.DIS - Old Base Data [V] ------------------------------- +0 WORD Number of Starbases +2 n BYTEs Records, 156 bytes each +m 10 BYTEs BDATAx.DAT: Signature 2 BDATAx.DIS: Signature 1 One Starbase Record: +0 WORD Base Id (=Id of planet with this base) +2 WORD Owner (1..11, BDATA.HST: 0=no base at this planet) +4 WORD Defense (0..200) One starbase defense unit costs 10 mc and 1 Duranium. +6 WORD Damage (0..100) +8 WORD Engine Tech Level (1..10) +10 WORD Hulls Tech Level (1..10) +12 WORD Weapon Tech Level (1..10) +14 WORD Torpedo Tech Level (1..10) Tech upgrades: going from Tech N to N+1 costs 100*N mc. +16 9 WORDs Engines in storage (for the 9 engines from ENGSPEC.DAT) +34 20 WORDs Hulls in Storage. Each race has up to 20 possible hulls it can build. These 20 words correspond to the 20 TRUEHULL.DAT slots. There's no possibility to store hulls a player can't build normally. +74 10 WORDs Beam Weapons in storage +94 10 WORDs Torpedo Launchers in storage +114 10 WORDs Torpedoes in storage All the "storage" fields can hold values between 0 and 10000. As of Host 3.22.031, these fields are not allowed to be increased without sufficient tech. This prevents the cheat of building parts without tech, but also prevents the (legal) act of moving high-tech torps from a ship to a low-tech base. +134 WORD Number of fighters (0..60) +136 WORD Id of ship to be recycled/repaired +138 WORD What to do with that ship: 0 Nothing 1 Fix 2 Recycle +140 WORD Mission (Primary Order) 0 none 1 Refuel 2 Max Defense 3 Load Torps onto ships 4 Unload freighters 5 Repair base 6 Force a surrender +142 WORD Type of ship to build (0=no build order, 1..20=index into above array) +144 WORD Engine Type +146 WORD Beam Type +148 WORD Beam Count +150 WORD Torpedo Type +152 WORD Torpedo Count +154 WORD 0. According to CPLAYER.BAS, this is a fighter count. When building a ship this value is effectively ignored, that's why PLANETS.EXE puts zero in here. This field should _really_ always be zero, after the build as many fighters as shown here are destroyed with no compensation... ## Build orders To build ship parts, ammo, tech levels or starbase defense, clients subtract the required resources from the planet and increase the starbase storage. To build a ship, you must buy the required items into storage; host will subtract them again. The build order must either be completely specified or completely zero. Beam Type and Beam Count are either both zero or both nonzero, likewise Torpedo Type and Count. Specifying a type but count zero is known to cause problems with various programs. Costs for a starbase fighter are 100 mc, 3 Tritanium and 2 Molybdenum; configurable in PHost 4.0k+. CONTRLx.DAT - Winplan - Checksums CONTROL.DAT - Checksums ---------------------------------- ## DOS Planets CONTROL.DAT exists once per directory, even for more than one player. Then it contains information for all players in this directory, all need to play in the same game. ## Winplan For each player a single CONTRLx.DAT file. Winplan can handle multiple games in one directory, and one game spread over multiple directories, as long as there are no race collisions (i.e., two times player 3 in the same directory won't work). +0 500 DWORDs Checksums of all ships For each ship in SHIPx.DAT, the sum of all bytes in the ship record is computed. Positions of unavailable ships are undefined and contain parts of deleted files. +2000 -"- Checksums of all planets. The same for all planets in PDATAx.DAT +4000 -"- Checksums of starbases The same for all starbases in BDATAx.DAT +6000 WORD 0 ? --- Host999 Games --- +6002 n BYTEs apparently unused +8000 499 DWORDs Checksums of ships 501..999. Not all these need to be present if the corresponding ships do not exist. The word at +6000 might be a side-effect when the file is created: To make room for 6000 bytes, do a `Seek(6000)' followed by some `Write' statement. If this information is incorrect, Planets doesn't show an error message. It corrects the problem, but only if the erroneous record is accessed from within the client program. MAKETURN aborts with the following error message if it finds any mismatch: "DATA ENCRIPT ERROR". (This typo has successfully hidden itself in all versions, from DOS Planets up to Winplan 3.52...) FIZZ.BIN - Even more checksums ------------------------------- This file exists once per directory, even for more than one player. It contains information for all players. All must use the same client version (shareware/registered). +0 33 DWORDs 11 records of 12 bytes for each race. Undefined if this race doesn't play in this directory: +0 DWORD Checksum for ships, equal to the number in GENx.DAT, increased by 667 +4 DWORD Checksum for planets, equal to the number in GENx.DAT, increased by 1667 +8 DWORD Checksum for starbases, equal to the number in GENx.DAT, increased by 1262 +132 DWORD ? (probably unused) +136 25 DWORDs String 1 (encrypted, see below) +236 25 DWORDs String 2 (encrypted, see below) +336 DWORD Checksum. Equal to the sum of all DWORDs in the above strings, increased by 668 (a number having nothing in common with 13). The strings are encrypted as follows: VAR Character : ARRAY[1..25] OF CHAR; Value : ARRAY[1..25] OF DWORD; FOR i:=1 TO 25 DO Value[i] := Ord(Character[i]) * i * 13; { Ord(x) = ASCII code of x } This is a signature for the registered/unregistered version of Planets. For the Shareware version the strings have the values "VGA Planets shareware " "Version 3.00 " resp. " V3.5 for windows " The host checks the first line to identify the shareware version, hence 3rd-party clients can put their own version number into line two (I have been told of some autohost software who rejects these; I believe the autohost is in error here.) For registered players, both lines need to be equal to be identified as the same player. The strings are written to REG.LOG in each host run. They are also stored in PLANETS.EXE. No, I won't describe this here... If the values from PLANETS.EXE and FIZZ.BIN don't match, Planets refuses to run with the message: "Switching PLANETS.EXE program in the middle of a turn is not allowed. (blah blah) This is to prevent errors and cheating.". UNPACK doesn't create FIZZ.BIN. However, PLANETS.EXE will always create and update the file. MAKETURN won't run if FIZZ.BIN is missing and displays a rather long error message. GAMESTAT.DAT - Winplan - Game Definitions [T] ---------------------------------------------- This file is located in the WINPLAN directory and contains information on up to 8 active games. These are presented in the game menu. +0 8 RECORDs of 206 bytes each +0 WORD 0 (?) +2 11 WORDs The races being played by the player. Each WORD is -1 if the race is played, 0 otherwise. +24 80 BYTEs TRN Download path +104 80 BYTEs RST Upload path +184 20 BYTEs Name of the game +204 WORD 0 (?) +1648 BYTE unused, contains garbage +1649 WORD Number of the game selected last in the menu (1..8) The unpacked game data is always in the WINPLAN\VPWORKx directory, where x is the sequential number of the record (1..8). There seems to be no indication what race you chose last. To figure out the race number, there are two clues: + try to open a game file (BDATAx.DAT for example). If you get a sharing violation, Winplan has that file open. + compare the files' modification times. The most recent ones are those Winplan used last. GENx.DAT - General Information ------------------------------- +0 18 BYTEs Timestamp (10 bytes date mm-dd-yyyy, 8 bytes time hh:mm:ss) +18 88 BYTEs 11 score records of 8 bytes each: +0 WORD Number of planets, 10 points each +2 WORD Number of capital ships, 10 points each +4 WORD Number of freighters, 1 point each +6 WORD Number of starbases, 120 points each +106 WORD Player Id +108 20 BYTEs Password The password has 10 characters (padded with NULs). Each character of the password is decoded as follows: VAR pw : ARRAY[0..19] OF BYTE; { this field } ch : ARRAY[0..9] OF CHAR; { password } FOR i := 0 TO 9 DO ch[i] := Chr(pw[i] - pw[19-i] + 32); +128 BYTE unused This field may belong to the password data. If you define an array of size 20 in BASIC, this field really gets 21 elements (0 to 20). The password only uses 0 to 19. +129 DWORD Checksum of SHIPx.DAT/DIS +133 DWORD Checksum of PDATAx.DAT/DIS +137 DWORD Checksum of BDATAx.DAT/DIS These checksums are the total sum of all bytes of the appropriate files (i.e., count word, data, and signature block of both files). +141 WORD 13 if the password has changed, 0 else +143 10 BYTEs New password, if any: each byte is increased by 50 +153 WORD Turn number +155 WORD Checksum of the time stamp = sum of bytes at 0 to 17 From this data, a file signature is constructed: +118 10 BYTEs (second part of password data) Signature 1 is these 10 bytes. Increase the first byte by 1, the second by 2 and so on. The result is Signature 2. ## Note on passwords Passwords are padded with NULs, not spaces. High-ASCII characters are not allowed in passwords and should be treated as NULs: MASTER sometimes generates those. The password "NOPASSWORD" disables the password query. INIT.TMP - Player List ----------------------- Congratulations, Tim Wisseman! You have fooled me with this file name for several weeks! This file has a name of a temporary file but isn't one. It contains 11 WORDs that are 1 if information for that player is available, and zero otherwise. PLANETS.EXE will not read the directory, it will trust this file. Of course, this file exists once per directory. KOREx.DAT - Winplan - Starcharts --------------------------------- +0 WORD Turn number +2 7 BYTEs junk. +9 10 BYTEs Signature 2 (see GENx.DAT) +19 83 BYTEs junk. This and the previous "junk" block are perturbed at every unpack and seem to serve no purpose (they are not used again). +102 500 RECORDs of 8 bytes each: Mine fields +0 WORD X +2 WORD Y +4 WORD Radius +6 WORD Owner/Type +4102 50 RECORDs of 12 bytes each: Ion storms +0 WORD X +2 WORD Y +4 WORD Radius +6 WORD Voltage in MeV +8 WORD Warp +10 WORD Heading in degrees +4702 50 RECORDs of 4 bytes each: Explosions +0 WORD X (0 = non-existent) +2 WORD Y +4902 100 RECORDs of 78 bytes each: Ufos, see UFO.HST +12702 4 BYTEs Signature "1211", if all visual contacts fit into the normal TARGETx.DAT file, "1120" otherwise. +? 16 BYTEs ? (unused) --- Additional Visual Contacts --- +? DWORD Number of contacts +? n RECORDs of 34 bytes each +0 WORD Id Number +2 WORD Owner +4 WORD Warp +6 WORD X location +8 WORD Y location +10 WORD Type of hull +12 WORD Heading in degrees, 0=North, 90=East, 180=South, 270=West, -1=unknown +14 20 BYTEs Ship name, encrypted FOR i:=1 TO 20 DO Encrypted[i] := Original[i] XOR (155-i) Note that, except for the encrypted ship name, this is exactly a TARGETx.DAT record. --- always --- +? 10 BYTEs Signature 2 (see GENx.DAT) For a more detailed description of the data formats, see the RST file description. This one contains a very similar data structure, except that the RST contains the race names, KOREx.DAT doesn't. MDATAx.DAT - Received Messages ------------------------------- +0 WORD Number of messages +2 n*6 BYTEs Records of 6 bytes each +0 DWORD Address of message in file + 1 +4 WORD Length of message in bytes +x y BYTEs undefined, or the messages The messages texts are encrypted: each ASCII code is increased by 13dec. A single carriage return (ASCII 0Dh, encrypted 1Ah) is a line break. Empty lines are stored as a line break only (no spaces). Messages do not need to be all of the same length. Messages from Winplan clients may have additional encrypted linefeeds (ASCII 0Ah, encrypted 17h) after the CRs. Characters with an ASCII code above 242 can't be encrypted in messages. The encryption does not have a "wraparound" (then, 250 + 13 would be 7). Attention: Planets doesn't check this and exits with an "Illegal Function Call" message. Host knows about this problem and replaces the characters with ASCII 13h (encrypted 20h = " "). Expect messages of at most about one kilobyte each: see under MESSx.DAT for host-side size limits. Of course, _real_ programs don't have arbitrary limits. ## Message Type Codes From Host 3.20 and PHost 2.6c onwards, received messages normally start with a header like this (PHost does this consistently since 3.3c): (-xy000)<<< Headline >>> The headers were introduced to allow sorting the messages in Winplan. The hyphen identifies this message as a message from the current turn. If there is an "o" instead, it's an older message because the player has missed some turns. "x" specifies the type of the message. "y" is a race number, and "000" a planet or ship id. The following list shows the existing message types (in the following list, capital letters are variable, the rest is fixed): (-90XXX) Race-specific mission (Hiss, Dark Sense), XXX is a planet Id. (-a0XXX) Message from 3rd-party add-on, see below. (-afile) TKF File transfer. See below. (-c0XXX) Tim Continuum attacking planet #XXX. XXX is zero for ship attacks and priority points. (-d0XXX) Ship or starbase built at planet #XXX. (-dRXXX) Ship of race R (1..9, a, b) surrendered at base #XXX. (-e0XXX) Emergency call from ship #XXX. (-f0XXX) Ship or planet #XXX has been destroyed or captured. (-g0000) HConfig. (-h0000) External message (see MESS.EXT), usually from the host (SENDMESS); may also read `(-h000)'. (-i0XXX) Ion storm #XXX. (-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. (-p0XXX) Message from planet #XXX. (-pRXXX) New native life, overtaxed, or bad climate at planet #XXX. R is a native race (0..9) or "c" for colonists. (-r000) Anonymous message. (-rX000) Message from race X (0..9, a, b). (-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 (this type is not generated by host. Currently, only PCC evaluates it, but other authors are encouraged to use this, too, as it allows a nice and consistent interface for messages associated with an Ufo. PHost uses it for wormhole messages since 4.0e/3.4h). (-w0XXX) Ship #XXX ran on a web mine. (-x0XXX) Explosion on long range sensors (#XXX = sequential number of explosion). (-y0XXX) Meteor on planet #XXX. (-z0XXX) (Bio-)scanner report from planet #XXX. Some Ids can be longer than 3 characters: (-l) and (-m) on PHost 3.3 with CPNumMinefields>=1000, (-u), possibly (-a) and (-x). Note that some message types allow both planet and ship Ids in the "000" field (codes `f' and `s' are known to do this). I suggest trying to link the message to a ship first, and if this fails, to the planet. Generally there are exactly as many (-f) messages as there are VCRs. Knowing this may make it easier assigning these messages to objects. ## Add-on Messages (-a0XXX) For messages starting with "(-a0XXX)", Winplan displays a the file WINPLAN\BMP\VPAUXxxx.BMP in the message reader. Those pictures are not transferred with the RST file; players have to install them in advance. Tim assigns Id numbers. Range | Used by... ==============|================================================= 010 | Wormhole by Kevin D. Foster and James W. Allan 101..126 | Dan & Dave Add-ons (RacePlus, Starbase+, etc.) 149 | Neutral Zone by Dan Gale 191..192 | HugeRock 1.2 by Ryo Nakamura 202 | Unity by Wolfgang Merkel 401 | Trade 1.20 by Nestor Delfino & Alejandro Biondo 403..405 | 1st Corsarian Satellite Bank by -"- 450 | Space Dragons or Non-Aligned Worlds by Joe Thomas 451 | Non-Aligned Worlds by Joe Thomas 451..454 | Lurkers/Stormfront 500 | Gryphon by Oleg Shvartsman 503..507 | Space Dragons by Joe Thomas 510 | Nemesis by Oleg Shvartsman 528 | JS-Q 601 | Margetios Bazaars 602 | mcpEdge 666..668 | Aliens! (default configuration) 700..717 | RAW! by Dan & Dave 800 | GivePlan by Ryo Nakamura 801 | PName by Ryo Nakamura 802..803 | HugeRock Advanced by Ryo Nakamura 805..816 | Interstellar Pig by Chris Stucchio 870..873 | Portal by Rene Gallati ## VPA Data Transmission VPA data transmissions are normal player-to-player messages where the message body looks like this: <<< VPA Data Transmission >>> OBJECT: Planet 555 <--- Object & Id DATA: 1234567890 <--- Checksum in ASCII aaaaaaaaaaaaaaaaaaaaaaaaa <--- Data aaaaaaaaaaaaaaaaaaaaaaaaa Two data characters form one byte. "a" stands for 0, "p" for 15: the value of the byte encoded by two characters is 16*(second char) + (first char). Line breaks are inserted after 40 columns (20 bytes). The checksum is a 32 bit number, encoded as a signed decimal figure. The lower 16 bits are the size of the data block in bytes, the upper 16 bits are some kind of checksum: { let this array contain the characters of the message, i.e. the 'a' to 'p' letters, but not the headers or the linefeeds: } VAR bytes : ARRAY[0..nchars-1] OF BYTE; sum := 0; i := 0; WHILE i < nchars DO BEGIN X := 256*bytes[i+1] + bytes[i]; sum := 2*sum + X i := i + 2; END (nchars is the number of characters in the message, i.e. two times the number of bytes to encode) This checksum effectively only depends upon the last 16 bytes of the text to be encoded, that is, the last 32 characters of the message. Note that the characters are case-insensitive for the decoder, but not for the checksummer. 'A' means the same as 'a', namely the digit 0, but has a different value for checksumming. The decoded blocks read as follows: --- Planet ("OBJECT: Planet 123") --- +0 WORD Turn number +2 WORD Turn number +4 WORD Owner of planet +6 81 BYTEs Contents of planet record at offset 4 (Friendly Code), see PDATAx.DAT for description. Unknown values are set to -1. +87 WORD ? ("when") +89 WORD Flags ("EPLN"). Bits 0..7 Owner Bits 8..10 Industry level Bit 14 1 = No starbase Bit 15 1 = Starbase present --- Mine field ("OBJECT: Mine field 29") --- +0 WORD Turn number +2 WORD X +4 WORD Y +6 WORD Owner +8 DWORD Mine units +12 WORD Type 0 Normal 1 Web --- Marker ("OBJECT: Marker") --- +0 BYTE Type 1 Flag "p" 2 Small circle "o" 3 Cross "x" 4 Square "[]" 5 Diamond "<>" 6 Dot "." 7 Circle with arbitrary radius 8 Line 9 Dotted line --- VPA 3.60+: --- 10 Grave "t" 11 Cactus "y" --- VPA 3.63+: --- 12 Black flag "P" 13 White flag "P" 14 Flag "k" 15 Up arrow 16 Up/Right arrow 17 Right arrow 18 Down/Right arrow 19 Down arrow 20 Down/Left arrow 21 Left arrow 22 Up/Left arrow 23 Neutronium marker "Ne" 24 Tritanium marker "Tr" 25 Duranium marker "Du" 26 Molybdenum marker "Mo" 27 Skull +1 BYTE Color (1..15, standard EGA colors, see UFO.HST) +2 WORD X +4 WORD Y +6 BYTE horizontal text justification (0=marker is to the left of the text, 1=center, 2=right) +7 BYTE vertical text justification (0=marker is below the text, 1=center, 2=above) +8 WORD Lines: X extent +10 WORD Lines: Y extent Circles: radius +12 BYTE Length of comment text +13 n BYTEs Comment text For lines, relative lengths are given. The line goes from (X,Y) to (X+dx,Y+dy). --- RST Password ("OBJECT: Password 3") [V] --- +0 WORD Turn for which this password is valid +2 BYTE Password length +3 10 BYTEs Password (unused places are filled with garbage) +13 BYTE Sender (number of player who sent this message; the number which is also in the OBJECT: line) +14 BYTE Receiver (who may use this password) +15 WORD Permission flags (currently unused, set to 0) This record can currently only be used with PCC. The password is not encrypted: the hex encoding can be broken with a calculator, as can the password in the GENx.DAT file, so there would be no point in protecting the password more. This record enables the specified receiver to open the sender's RST without having to know the password. Such a transmission is only valid for one turn. The transmitted password must match the sender's current password. ## Informer Alliance Information Informer (and other tools, such as EchoView) can transfer information about a player's planets and starbases to allied players. These messages contain in the body: Allied Planets <-- Signature Passcode : 17 <-- Passcode (optional) 506 69 105 770 809 350 390 <-- Id List 405 908 The Id List contains Ids of all the player's planets, each of which is increased by 500 if the planet has a starbase. The above information thus says, `the sender has a starbase on planet 6, he owns planets 69 and 105, he has a starbase on #270, etc.'. Note that such messages are easy to fake, so use them with care and do not blindly accept them from anyone. Since the message text does not contain the originator race, you shouldn't forward such a message to anyone: it is of no use for them. The `Passcode' line may be missing. If present, it specifies a passcode both allies must have agreed to (a number between 1 and 9999). ## VPHost Binary Data Transfer VPHost's data transfer messages contain in the body << VPHOST Binary Data Transfer >> 80E300000010004586560235F6C6162702645646 5627164796F6E602020202020202020202458656 0264564637020202020202020202020202645646 020202020202020202 When you read this, run either VPUNPACK v2.20 or higher, or VPUTIL v2.50 or higher to process this message. Each line is up to 40 characters long and encodes 20 bytes. A message contains up to 13 lines with binary data. Two characters encode one byte, using normal hex digits. The only non-standard thing is that the less-significant nibble comes first (!), so the above example starts with the bytes 08h, 3Eh, 00h, 00h. The decoded data block reads as follows: +0 BYTE Type of block +1 WORD "num" Number of bytes in this message, 1 to 253. +3 WORD Offset into target file. If one block was split into multiple messages, the first message contains the first 253 bytes (offset=0), the second one contains the next 253 bytes (offset=253, because we already have 253), and so on. +5 WORD Index. Zero unless otherwise stated. +7 n BYTEs actual data ("num" bytes) + Type 6 Block: HConfig (see HCONFIG.HST); + Type 7 Block: VPConfig (VPHost's configuration file); + Type 8 Block: Race name. Index is the race number, data contains the 3 race names (30 bytes long, 20 bytes short, 12 bytes adjective = 62 bytes total). ## TKF File Transfer A TKF file transfer message looks like this: (-afile)< FILE: kfvcr5.dat [1/1] > 1'Z+!p!K"!]RJ5!"ga&!fh;H&*=/%!!!!!!7T^oQ [!!!!1\)-&*=/%!!!!!!h"81&H!!!!1\)-&*=/%! !$!!!h"81&H$>>"), a "FROM:" and a "TO:" line, and (THost only) a blank line. The file format would allow messages of up to 32 kByte per message, but since (a) the host prepends some headers, and (b) received messages must be smaller then 32 kByte, you can't completely exploit this capability, even if your host would allow to. ## Messages to many Messages to many races, such as Universal Messages, are stored as several single messages, one per addressee. The Client program (PLANETS.EXE/PCC) inserts the headers ("<<< Universal Message >>>"), not the host. It should not be problematic to have multiple message headers refer to the very same message text, but so far no program is known to do that. If you want to collapse multiple identical messages together when reading in MESSx.DAT, you may want to care for the header lines: + Universal Messages start with " <<< Universal Message >>>" (two spaces!). + VPA starts its team messages with " <<< Team Message >>>" (again, two spaces). + PCC's messages to multiple players start with "CC: other_addressees", or ">>"). MAKETURN disassembles messages into single commands. +0 WORD Number of sent messages +2 17 BYTEs ? (unused, rubbish) +19 n RECORDs containing the messages. Probably, a variable record size is possible, but not supported by Winplan: +0 BYTE unused fill byte +1 BYTE Flag. If the message is valid, this byte is 31h ("1"). If the message has been deleted, the value is 30h ("0"). +2 12 BYTEs Addressees, a list of 30h ("0") and 31h ("1") for all 11 races and the host. +14 WORD Length of message text. In my files, the value is always 600. +16 n BYTEs Encrypted message. The message encryption is the same as in MDATAx.DAT, except that line breaks contain both a CR and an LF (0Dh 0Ah, encrypted 1Ah 17h). The message is padded with encrypted spaces (2Dh, "-"). The THost line-break filter is not aware of the additional 0Ah's, so a line must not be longer than 39 characters in a Winplan message. If a message is deleted, Winplan doesn't truncate the file but copies all messages back some positions and sets the flag at the first invalid message to "0". If the file is empty (no message has been sent yet) it contains a single zero word only. Possibly, a variable record size is planned though not implemented in Winplan. Since 600 bytes is too less for a message, PCC can extend the format in this way if it knows Winplan is not installed: Winplan itself would crash reading the file. Winplan uses the Windows Editor Control. This is a full editor capable of doing automatic line breaks. CR/LF is only in the text if one has really pressed ENTER. If you have written down a complete paragraph, it will contain no single CR/LF, line breaks were only done at display time. This was "downgraded" in later Winplan versions (i.e., ENTER is required) and a host-side filter adds linefeeds after 39 columns. Winplan uses an ad-hoc conversion for Latin-1 characters (Windows) to MS-DOS characters (cp437): "translate German letters". This conversion is neither perfect nor complete, so best avoid it. ## VPA Internally, VPA can only handle DOS-style message files (MESSx.DAT). When it starts up, and MESS35x.DAT is more recent than MESSx.DAT, it converts the Winplan messages into DOS format. Likewise, when it exits, it converts MESSx.DAT back into MESS35x.DAT. This will break up messages to many people in the appropriate number of unicast messages. NOTESx.DAT - Winplan - Notes [T] --------------------------------- +0 500 RECORDs of 200 bytes each: Notes for planets. +0 100 BYTEs Note #1 +100 100 BYTEs Note #2 +? 500 RECORDs of 200 bytes each: Notes for starships. +0 200 BYTEs Note +? 500 BYTEs ? +? 640 BYTEs Color names, 16 BASIC strings of 40 bytes each +? 11 BYTEs Colors for starships of the 11 races (0..15) --- Host999 games --- +? many BYTEs unused +? 499 RECORDs of 200 bytes each: Notes for starships with Ids >500. +0 200 BYTEs Note This field starts at offset 302200 with the note for starship #501. The notes are space-padded and can contain CR/LF. This file is extraordinarily large, that's why I omitted the 6-digit offset fields here. PDATAx.DAT - New Planet Data [V] PDATAx.DIS - Old Planet Data [V] --------------------------------- This file contains all your planets, and all unowned planets you are orbiting (those for which you can request a mineral survey). Up to Host 3.14, you were getting PDATA records also for planets owned by enemies. This is problematic because they contain the friendly code, which current client programs, including recent Winplans, will happily display. Stealing minerals, sailing minefields -- it never was easier :) Up to PHost 3.4c, PHost was zeroing the fields Colonists, Supplies, Money, Mines, Factories, Defense, Colonist Tax, and Native Tax when you were scanning an unowned planet. Thus, the value zero actually means "don't know", not "zero". +0 WORD Number of planets +2 n BYTEs Records of 85 bytes each +m 10 BYTEs PDATAx.DAT: Signature 2 -> GENx.DAT PDATAx.DIS: Signature 1 One Planet record: +0 WORD Player Id, 0 for unowned planets +2 WORD Planet Id +4 3 BYTEs Friendly Code. THost permits ASCII codes 32 to 122. +7 WORD Number of mines (0..~516) +9 WORD Number of factories (0..~416) +11 WORD Number of defense posts (0..~366) The ranges are based upon the maximum population of 10 million colonists (100000 clans). The maximum number of mines on a planet is (COLON = colonist clans): COLON if COLON <= 200 ROUND(200+SQRT(COLON-200)) if COLON > 200 Replace 200 with 100 for factories, and 50 for defenses. When building structures, the client program must subtract the appropriate costs from the available resources (1 supply, and 4/3/10 mc for mines/factories/defenses). +13 DWORD Mined Neutronium +17 DWORD Mined Tritanium +21 DWORD Mined Duranium +25 DWORD Mined Molybdenum +29 DWORD Colonist clans (1 clan = 100 people). The THost limit is 100000 clans, the PHost limit is 250000 clans. +33 DWORD Supplies +37 DWORD Megacredits To sell supplies, remove the requested amount from the Supplies field and add it to the Megacredits field. +41 DWORD Neutronium in ground +45 DWORD Tritanium in ground +49 DWORD Duranium in ground +53 DWORD Molybdenum in ground >4999 abundant 1200..4999 very common 600..1199 common 100..599 rare 1..99 very rare 0 none +57 WORD Neutronium density +59 WORD Tritanium density +61 WORD Duranium density +63 WORD Molybdenum density 70..100 large masses "1 mine extracts 1 kt" 40..69 concentrated "2 mines extract 1 kt" 30..39 dispersed "3 mines extract 1 kt" 10..29 scattered "5 mines extract 1 kt" 0..9 very scattered "10 mines extract 1 kt" The figures on the right are from the docs, the actual amount of minerals extracted is - THost: ERnd(ERnd(mines * density / 100) * miningrate / 100) * RF - PHost < 3.5, 4.1: Trunc(Trunc(density * miningrate / 100) * RF * mines / 100) - PHost 3.5+, 4.1+: Round(Round(density * miningrate / 100) * RF * mines / 100) where "miningrate" is the HConfig value, and RF it the "reptile factor" (2 if Reptilian natives, 1 otherwise). +65 WORD Colonist taxes (0..100) +67 WORD Native taxes (0..100) Note that THost limits taxation: when hissing, the maximum tax rate is 75%. Cyborgs can tax natives up to 20%. +69 WORD Colonist happiness (-300..100) +71 WORD Native happiness (-300..100) 90..100 happy 70..89 calm 50..69 unhappy 40..49 very angry 20..39 rioting <20 fighting Tax collection possible for happiness>=30, population grows if >=70. +73 WORD Native Government (SPI = Socio Political Index) 0 none 0% 1 Anarchy 20% 2 Pre-Tribal 40% 3 Early-Tribal 60% 4 Tribal 80% 5 Feudal 100% 6 Monarchy 120% 7 Representative 140% 8 Participatory 160% 9 Unity 180% +75 DWORD Native clans (1 clan = 100 people). Maximum population somewhere around 150000 clans. +79 WORD Native Race 0 none 1 Humanoid 2 Bovinoid 3 Reptilian 4 Avian 5 Amorphous 6 Insectoid 7 Amphibian 8 Ghipsoldal 9 Siliconoid +81 WORD Temperature (Temperature in Fahrenheit = 100 - this value) 0..15 desert (85..100°F) 16..35 tropical (65..84°F) 36..60 warm (40..64°F) 61..85 cool (15..39°F) 86..100 arctic (0..14°F) In case you wonder why we store `100-F': originally, this was just a type code with no real-world equivalent. It was changed to mean a temperature with Host 3.20 and Winplan. +83 WORD 1=Build base, 0 otherwise. The client program must subtract the starbase cost (900mc, 402T, 120D, 340M; configurable in PHost 4.0k+) from the available resources when setting this word to 1. The happiness change can be computed from the tax level and the other planet data. It corresponds to the value shown in PLANETS.EXE as follows: <= -6 Hate you -5 .. -1 Are angry at you 0 Are undecided about you +1 .. +4 Like your leadership >= +5 Love you Formulas are different for PHost and THost. + Natives, THost: Trunc(500 + 50*SPI - 85*NativeTax - (Mines+Factories) DIV 2 - Sqrt(Natives)) DIV 100 ... plus 10 for Avians + Natives, PHost: Trunc(500 + 50*SPI - 85*NativeTax - (Mines+Factories) / 2 - Sqrt(Natives)) DIV 100 ... plus 10 for Avians (Note that the difference PHost/THost here is that THost uses integer division for industry effect while PHost does floating point). + Colonists, THost, Crystals with desert advantage: Trunc(1000 - 80*ColonistTax - Sqrt(ColonistClans) - (Mines+Factories) DIV 3 - 3*TempCode) DIV 100 + Colonists, THost, other races: Trunc(1000 - 80*ColonistTax - Sqrt(ColonistClans) - (Mines+Factories) DIV 3 - 3*Abs(TempCode-50)) DIV 100 + Colonists, PHost, Crystals with desert advantage: Trunc(1000 - 80*ColonistTax - Sqrt(ColonistClans) - (Mines+Factories) / 3 - TempCode/0.66) DIV 100 + Colonists, PHost, other races: Trunc(1000 - 80*ColonistTax - Sqrt(ColonistClans) - (Mines+Factories) / 3 - Abs(TempCode-50)/0.33) DIV 100 (Difference, again, is integer vs. floating point, and different handling of temperatures). PATH.DAT - Game Directory -------------------------- The original DOS Planets clients stored the path they were last invoked with in this file. This is necessary for invoking the VCR, see VCRINIT.TMP below. This file contains only a usable name (i.e., ending with a backslash), no newline, no Ctrl-Z. This file can be safely deleted when no Planets program is running. RN.DAT - Winplan - RACE.NM Treatment ------------------------------------- This file contains a single WORD with the value 0 if the race names from the RST should not overwrite the local ones. The WORD has the value -1 (FFFFh) or the file does not exist if the RST names should overwrite RACE.NM. This file lives in the game directory (VPWORKx). SHIPx.DAT - New Ship data [V] SHIPx.DIS - Old Ship data [V] ------------------------------ +0 WORD Number of ships +2 n BYTEs Records of 107 bytes each +m 10 BYTEs SHIPx.DAT: Signature 2 -> GENx.DAT SHIPx.DIS: Signature 1 A ship record: +0 WORD Ship Id +2 WORD Player Id (1..11, or zero in SHIP.HST for free ship slots) +4 3 BYTEs Friendly Code. THost permits ASCII codes 32 to 122. +7 WORD Warp factor (0..9) Sometimes this field is set to a negative value by the host, if the ship has more than 100% damage (due to blindly applying the max-speed-for-damaged-ship formula). +9 WORD X distance to waypoint (destination-X minus X-position) +11 WORD Y distance to waypoint (destination-Y minus Y-position) The distances must be in range -3000 .. +3000 +13 WORD X position +15 WORD Y position Usually between 1 and 4000 or 1 and 10000. Ships with (X,Y) = (0,0) should not appear, as this makes problems with the SHIPXYx.DAT file and probably many clients. +17 WORD Engine type (1..9, index into ENGSPEC.DAT) +19 WORD Hull type (1..105, index into HULLSPEC.DAT) +21 WORD Beam weapon type (0 for none, or 1..10 = index into BEAMSPEC.DAT). See note below. +23 WORD Number of beams +25 WORD Number of fighter bays (if not zero, the T-Launcher type and T-Launcher number values are ignored/set to 0, since a ship can never have Torpedoes and Fighters) +27 WORD Torpedo Launcher Type (0 for none, 1..10 as index into TORPSPEC.DAT). See note below. +29 WORD Number of Torpedoes/Fighters +31 WORD Number of Torpedo launchers +33 WORD Mission. See below. +35 WORD Primary Enemy (0 or race Id 1..11) +37 WORD Id of ship to tow, or first mission argument +39 WORD Damage % (0..149) +41 WORD Crew +43 WORD Colonist Clans +45 20 BYTEs Name +65 WORD Neutronium +67 WORD Tritanium +69 WORD Duranium +71 WORD Molybdenum +73 WORD Supplies +75 7 WORDs Unload Cargo to planet +75 WORD Neutronium +77 WORD Tritanium +79 WORD Duranium +81 WORD Molybdenum +83 WORD Colonists +85 WORD Supplies +87 WORD Planet Id or 0 for Jettison (see text below!) +89 7 WORDs Transfer to enemy ship +89 WORD Neutronium +91 WORD Tritanium +93 WORD Duranium +95 WORD Molybdenum +97 WORD Colonists +99 WORD Supplies +101 WORD Ship Id or 0 (see text below!) +103 WORD Id number for intercept mission or second mission argument. In THost, this field must contain a valid ship Id or zero, even if 3rd-party missions are used. +105 WORD Money (0..10000) ## Weapons Like for build orders (BDATAx.DAT), beam type and beam count should be either both zero (meaning no weapon) or both non-zero. The same holds for torpedo launcher types and counts. Some programs (Dominate, I suppose), generate ships with a zero count, but a non-zero type (e.g., a freighter with 0 Mark 8 launchers). So you must check both fields to tell if a ship has weapons or not. The usual hosts and clients handle this correctly (if "correctly" means that they don't crash or do something unexpected). The bad thing about this problem is that it can not really be corrected from client-side. You can sweep it under the carpet by hacking the SHIPx.DAT/.DIS files during unpack, though, which is what PCC does. PHost 3.3 corrects this at host side. ## Cargo Transfers / Ship Mass / Jettison The ship mass is computed as the sum of the masses of all components of the ship (hull, weapons), ammunition, and cargo (fields at +43 to +73). Unload/Ship transporters do not contribute to the ship mass. Note that, however, PLANETS.EXE counts transporter contents toward the ship's cargo hold. That is, if a SDSF transfers 70 kt of something to an enemy ship, it is reported as fully-loaded by PLANETS.EXE although it has nothing in its cargo hold. Host 3.22.030 enforces this limit (earlier ones do not). Common 3rd-party clients (VPA, PCC) allow overloading the ship this way, as do earlier Hosts and PHost. Since 3.22.036, this restriction is host-configurable ("VPA extra features"), and Winplan also allows overloading. When transferring cargo, you remove the cargo from the ship's own cargo hold by subtracting, and load it onto the target ship/planet or onto the transporter by adding it. When transferring stuff to an own ship, PLANETS.EXE often generates a dummy transfer (Id set, but all amounts are zero). These transfer orders should not be sent to the host, and can (should!) be canceled. When in deep space, ships can jettison cargo; this is a normal ship-to- foreign-planet transfer with the target planet set to zero. Most clients implement it this way. When the ship has no fuel, the transfer fails and the cargo is put back onto the ship. Winplan implements jettison by just subtracting the cargo from the ship's cargo hold, bypassing the transporter. This way, it can even jettison ammo and money. One can still tell how much was dropped by summing up everything of that cargo type at the particular place, and seeing how much is missing from the beginning of the turn (PCC implements such an algorithm for torps/fighters). Winplan does require the ship to have fuel to allow this, though, so the effective rules remain the same. PHost until 3.4g/4.0d supports this type of jettison only for Winplan-style TRNs, others (including Winplan shareware users!) will get a yellow status and PHost will undo the action. ## Missions THost reserves the mission numbers 0..19 for its own use and allows usage of missions 20..999 for add-on programs. THost requires the unused mission arguments (Tow, Intercept) to be zero if a standard mission other than Tow/Intercept is used. It also imposes some limits on the arguments for add-on missions: the intercept argument must be a valid ship Id number or zero. If these constraints are violated, arguments are cleared or missions are not performed. PHost uses missions 20 and up for extended missions (defaults, the base number can be changed). PHost (up to 3.3b) requires the mission arguments to be in the range zero to 500, even if the mission would allow more (e.g., beam transfer money): larger values are flagged as Yellow status when processing the turn, and are set to 250. Values outside this range can be set with 'extmission' commands. Newer PHost versions allow the full range 0..10000 for mission arguments. The interface to enter extended (i.e. code >= 20) missions in Winplan is known as M.I.T. (Mission/Intercept/Tow) and can be configured with MISSION.INI. Standard Missions: 0 none 1 THost/PHost: Explore. SRace: that what is mission 9 in "normal" hosts. 2 Mine sweep 3 Lay mines 4 Kill 5 Sensor Sweep 6 Colonize, Land & Disassemble 7 Tow, Tow argument = ship Id which must be at the same place as the towing ship. 8 Intercept, Intercept argument = ship to intercept. Must be visible and within 200 ly since Host 3.22.015. 9 Race specific missions 1 = Federation Super Refit 2 = Lizard Hisssss! 3 = Bird Man Super Spy 4 = Fascist Pillage Planet 5 = Privateer Rob Ship 6 = Cyborg Self Repair 7 = Crystal Lay Web Mines 8 = Evil Empire Dark Sense 9 = Robots Build Fighters 10 = Rebel Rebel Ground Attack 11 = Colonies Build Fighters 10 Cloak. Only possible on appropriate ships since Host 3.22.010. 11 Beam up fuel 12 Beam up Duranium 13 Beam up Tritanium 14 Beam up Molybdenum 15 Beam up Supplies 16..19 reserved --- PHost only --- 20 Make Torpedoes (like "mkt") 21 Lay Minefield, Intercept = number of torpedoes to use (0=all), Tow = identity of minefield owner (0=self, other=player Id) 22 Lay Web Minefield (Crystals only, parameters as for mission 21) 23 Scoop Torpedoes from Minefield (like "msc"). Intercept = max. number of torpedoes to make (0=as many as possible) 24 Load Minerals and make Torpedoes (like "lfm" for fighters). Intercept argument like for mission 23. 25 Beam Down Money (like "bdm"). Intercept = amount (0=all) 26 Transfer Torpedoes to ship (like "btt"). Intercept = Ship Id (other player, same location), Tow = Number of torpedoes (0=max) 27 Transfer Fighters to ship (like "btf", Parameter as for mission 26) 28 Transfer Money to ship (like "btm", Parameter as for mission 26) 29 Standard Super Spy. 30 Cloak. Like mission 10, if the client program does not allow that 31 Extended Mission. Like mission 9. 32 Gather-build fighters (like "lfm", Robot/Rebel/Colonies only). Intercept = amount (0=max) 33 Beam up credits (like "bum"). Intercept = amount (0=max) 34 Beam up clans. Intercept = amount (0=max) 35 Beam up multiple. Requires command message. 36 Add Mines to Field. Intercept = amount of torpedoes (0=all), Tow = mine field Id (0=first appropriate) 37 Add Web Mines to Field. Parameters as for mission 36. 38 [PHost 4.0+] Training. Intercept = supplies to use 39 [PHost 4.0i+] Exchange Crew. Intercept = ship Id, Tow = crew 40 [PHost 4.0i+] Repair ship. Intercept = ship Id --- Add-on Missions --- 200 .. 228 FHost missions 666 .. 680 QVS missions 800 Starbeamer SHIPXYx.DAT - Ship coordinates ------------------------------- For each ship a record of 8 bytes. Ships that are invisible or have not yet been built are stored as location (0,0). The file ends with Signature 2. These ships are visible on the starcharts, though not necessarily scannable (see TARGETx.DAT). Generally, this file contains an XY entry for every ship in the SHIPx.DAT, TARGETx.DAT, and KOREx.DAT files, and possibly more. Allied targets as sent by Host 3.22.039 do not have a corresponding entry, though. For a standard host, this file contains 500 records (4000 bytes, plus 10 for the signature), Host999 uses 999 records (7992 bytes plus signature). Note that if Host999 is not used but the RST was unpacked with Winplan999 or Unpack999, this file will have 999 entries, but the last 499 of them are garbage. These will have bad coordinates (e.g. X = 12592 ($3130, "01", first two digits of timestamp)), but not necessarily bad owners. Praise Tim. A ship record: +0 WORD X position +2 WORD Y position +4 WORD Owner +6 WORD Mass in kt SKOREx.DAT - Winplan - Extended Ufo Database [T] ------------------------------------------------- This file does not exist or has a length of 0 if the RST file had the version signature "VER3.500". For "VER3.501" RSTs, this file exists: +0 96 BYTEs ? (unused) +96 5 BYTEs Signature "yAmsz" +101 WORD Total number of Ufos. Note that this file only contains Ufos with an Id number > 100, Ufos 1 to 100 are already in KOREx.DAT. If this field is 100 or less, no Ufos follow here. The host reduces the size of the Ufo database, so if the highest existing Ufo Id is 215, you'll find the value 215 here, and 115 Ufo records following. +103 WORD RST sub-version (currently 1, the "01" in "VER3.501"). --- if "Total number of Ufos" > 100 --- +105 n RECORDs of 78 bytes each: the Ufo records (see UFO.HST). --- if "Total number of Ufos" <= 100 --- +105 5 BYTEs Marker "no000" SNOOKER.DAT - Winplan - TempLock Deluxe ---------------------------------------- SNOOKER.DAT contains timestamps for all active games, and maps these to a 11-DWORD block (44 byte) each. This is used for making TRN files. The file is located in the WINPLAN directory. +0 WORD Number of the current entry (1..40), telling which of the timestamps was added last. +2 40 RECORDs of 18 bytes each, containing the time stamps of unpacked turns. +722 40 RECORDs of 44 bytes. These entries correspond with the timestamp entries and contain random values. When unpacking a result file, Winplan checks if it already knows the time stamp and if not adds a record containing the timestamp plus 44 random bytes to this file. When making TRN files, the Id block in the TRN will contain the corresponding 44-byte block. Winplan will neither load nor MAKETURN for games not "registered" here ("Game data is stale"). TARGETx.DAT - Visible enemy ships ("Contacts") [V] TARGETx.EXT - VPUnpack/VPUtil - More enemy ships --------------------------------------------------- This file contains visual scan information for ships. + Host 3.00 packs many (all?) ships into this file, even those that can't be seen because they're orbiting a planet. Visibility is determined by PLANETS.EXE, via SHIPXYx.DAT (ships not in SHIPXYx.DAT are not visible). + Host 3.20 and later pack only ships you actually see here and in SHIPXYx.DAT. + Host 3.22.039's "FF allies" are only stored here, but not in the SHIPXYx.DAT file. Modern client programs (including Winplan and all 3rd party things) will happily display Host 3.00's "invisible" ships. They must do so, otherwise they would not support "FF allies" :-/ The standard UNPACK program can't handle TARGETx.DAT files with more than 50 targets. + in DOS-style RSTs, the host will put the 50 nearest targets here and drop the rest. + in Winplan-style RSTs, THost will put 49 targets here (no matter how far they are), and the rest goes in KOREx.DAT. PHost packs up to 50 targets. + VPHost and PHost can be told to allow more than 50 targets in the RST file ("BigTargets"). VPUnpack will split the file into TARGETx.DAT (50 targets) and TARGETx.EXT (rest); PCC and CCUnpack can do that, too. +0 WORD Number of ships +2 n BYTEs Records or 34 bytes each +m 10 BYTEs Signature 2 A ship record: +0 WORD Id Number +2 WORD Owner +4 WORD Warp (zero if ship doesn't have fuel, no matter what its real speed is) +6 WORD X position +8 WORD Y position +10 WORD Type of starship hull (might differ from real ship type if the RacePlus Chameleon Device is used) +12 WORD Heading in degrees, 0=North, 90=East, 180=South, 270=West, -1=unknown (i.e., not moving) +14 20 BYTEs Ship name. Remote-controlled ships have the remote-control player in the Owner field, the original owner is marked by appending a signature such as '*2' to the name. UTILx.DAT contains this information in a more readable form. If PHost is used with AllowShipNames restrictions, and you are not allowed to see a particular ship name, the name will be 'Ship 345', where 345 is the ship Id, possibly amended with a remote-control signature. Otherwise, there is no sign saying whether the name you're seeing is the true name or not. TASKx.DAT - Winplan - Auto Tasks [T] ------------------------------------- Winplan allows to define up to 10 tasks to be used with the Auto Waypoints. +0 WORD ? (unused) +2 n BYTEs 10 records of 46 bytes each +0 30 BYTEs Name for this task +30 WORD Neutronium to beam up +32 WORD Duranium to beam up +34 WORD Tritanium to beam up +36 WORD Molybdenum to beam up +38 WORD Supplies to beam up +40 WORD Clans to beam up +42 WORD Megacredits to beam up +44 WORD Torpedoes/Fighters to beam up All values may be negative to mean `beam down'. TEMP.PLN - Temporary file TEMP.BMP - Winplan - Temporary file ------------------------------------ This file is left in the Planets directory by the Wisseman clients. It contains a piece of RESOURCE.PLN or WPVCR.DLL. This file can be safely deleted. TEMPLOCK.DAT - Checksums ------------------------- This file is created by Tim's MAKETURN, and can normally be safely deleted. It contains 11 DWORDs containing the checksum block from the turn trailer. UTILx.DAT - PHost - Information for Client Programs [V] 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 data The 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 scanned The 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 name This 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 information Note 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 data This 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 Code See 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. VCRx.DAT - Visual Combat Recordings ------------------------------------ A Visual Combat Recording is, other than its name implies, not a video recording. It's just a list of the starting parameters of the battle. The VCR program runs the battle using the same algorithm as the host. +0 WORD Number of VCRs. For PHost, see below. +2 n BYTEs Records of 100 bytes each +x 10 BYTEs Signature 2. A VCR record: +0 WORD `init' Random Number Generator initial value. Host: Must be in range 1..119. VCR's random number generator uses a table of 119 "random numbers" used in sequence and scaled to the needed range. Host actually generates 1..111 (111 is very rare). PHost: any value is possible. +2 WORD Signature (first battle only): Host: must be zero PHost: must be `48879-init' (modulo 65536). Zero on subsequent battles. c2nu: must be 21838 ("NU" in ASCII). +4 WORD Host: Temperature code of planet for a Ship/Planet battle PHost: Capability flags (first battle only): Bit 0 "Death rays" (new weapon possibilities of PHost 4.0: weapons with Expl=0 in use, or ShieldKillScaling!=0) Bit 1 "Ship experience levels" (experience system of PHost 4.0 is in use) Bit 2 "Beams" (behaviour of beams that prefer the enemy ship over fighters, as well as fighters moving too fast to place all their strikes, PHost 4.0k+) Bit 15 Valid bit. If zero, the value of this word is undefined and should be treated as zero. +6 WORD Type of battle 0 Ship/Ship 1 Ship/Planet +8 WORD Mass of left object +10 WORD Mass of right object +12 42 BYTEs Left object (Ship) +0 20 BYTEs Name. Note that many PHost versions store this field as a zero-terminated string. +20 WORD Damage at beginning +22 WORD Crew +24 WORD Id Number +26 BYTE Owner +27 BYTE Host: zero (Host addresses +26 as a WORD) PHost: race number, 0 if equal to owner, or in older PHosts. This is used to ensure that the VCR player knows the correct value of the `PlayerRace' option. +28 BYTE Picture. This field contains the picture number (RESOURCE.PLN) only, palette rotations as done by the Planets program are not reported. So the Alchemy Ships look exactly the same as a Super Transport Freighter. The Nebula Class Cruiser usually has picture #16. However, when it has Transwarps (type 9), THost assigns it #30 for no apparent reason (easter egg?) +29 BYTE Host: zero (Host addresses +28 as a WORD) PHost: hull number of ship, 0 for planets or in older PHosts. +30 WORD Type of beams +32 BYTE Number of beams +33 BYTE Host: zero (Host addresses +32 as a WORD) PHost: experience level of object [PHost 4 and later] +34 WORD Fighter Bays +36 WORD Torpedo Type +38 WORD Number of Fighters/Torps +40 WORD Number of Torpedo Launchers See below for notes about this field. +54 42 BYTEs Right object (Ship/Planet). The same format as for the left one. +96 WORD Shields of left object +98 WORD Shields of right object ## Secondary Weapons The "Fighter Bays" (+34) or "Number of torpedo launchers" (+40) field determines whether a ship has fighter bays or torpedo launchers. If the player has set the `NTP' friendly code, hosts set these fields as follows: + THost: both are zero. However, the other fields -- torpedo type and ammunition count -- are set to their correct values(!); + PHost: PHost reports `NTP'ing ships as having the correct number and type of bays/launchers, but no fighters/torps. Thanks to Akseli Mäki for pointing this out. ## Planets A planet is always the second (right) object in a battle. In this case, the picture given in the VCR record is ignored. VCR uses a generated picture, see also description of RESOURCE.PLN. For this calculation, the planet temperature is needed. For planets, the Crew field indicates whether the planet has shields or not. If it is zero, the planet starts with 0% shields, otherwise the maximum possible value (100%). In PVCR, planets may have torpedoes and fighters, if the configuration says so. In this case, the fields at +34 and later are set as follows: +34 WORD Fighter Bays +36 WORD Torpedo Type +38 WORD Number of Fighters +40 BYTE Number of Torpedo Launchers +41 BYTE Number of Torpedoes ## What VCR? A battle record is said to "bear the PHost signature" if the WORDs at +0 and +2 add up to 48879 as described above. Rumors claim that PHost 3 also uses the value 65261, but I've never seen these in the wild. If the first battle bears the PHost signature, the file was generated by PHost, otherwise it was made by THost. Once you know you're dealing with a PHost VCR, you need to tell what version it is: + If the file contains only one battle, it's PHost 3 or 4. + If the file contains two battles, and the last one has owner fields zero, the player has used CORR (see below), and the file contains one PHost 3 or 4 fight. + If the last battle record contains a PHost signature and the "battle type" field is zero or one, it is a VCR.HST file. You can't tell the version from those. + If the last battle record contains a PHost signature and the "battle type" field is two or larger, it is a PHost 2 player VCR file and the last record is in fact the configuration record. PHost 3 and 4 can be told apart using the "Capabilities" field. That field contains a bitfield of features needed to play the file. The most significant bit must be set to tell that this field is valid; if it is clear, it should be treated as all-bits-zero. If there are capability flags set which the VCR player doesn't know, it can't play the recordings. PHost versions before 3.4d usually set this field to zero. PHost 4 combat with all capabilities zero is identical to PHost 3 combat; they can't be distinguished. ## VPA & CORR VPA (up to 3.60e) has a bug: when it receives a PHost 3 VCR file with exactly one battle, it displays no battle at all. There is a program CORR.EXE which works around this problem by adding a dummy battle. This dummy battle can not be played. It can be detected because it has almost all fields -- in particular, the owner fields -- are zero. ## PHost Configuration PHost's VCR is configurable. That's why each VCR file generated by PHost 1.x or 2.x contains a configuration record. The file contains one battle less than said in the header, the last battle record is the configuration: +0 WORD Signature (random value) +2 WORD Signature. This value plus the one at offset +0 gives 48879 (modulo 65536). +4 BYTE ("Temperature/Capabilities" field) Major version of PHost. If this is anything other than 1 or 2, you should ignore this record: PHost 3 and later never use it. +5 BYTE Minor version of PHost +6 WORD ("Battle type" field) Number of valid bytes in the following structure, 64 in all known versions (3.15.1.1 to 3.2.2.13). --- Start of Configuration Structure --- +8 WORD `BayRechargeRate' +10 WORD `BayRechargeBonus' +12 WORD `BeamRechargeRate' +14 WORD `BeamRechargeBonus' +16 WORD `TubeRechargeRate' +18 WORD `BeamHitFighterCharge' +20 WORD `BeamHitShipCharge' +22 DWORD `TorpFiringRange' +26 DWORD `BeamFiringRange' +30 WORD `TorpHitOdds' +32 WORD `BeamHitOdds' +34 WORD `BeamHitBonus' +36 WORD `StrikesPerFighter' +38 WORD `FighterKillOdds' +40 WORD `FighterBeamExplosive' +42 WORD `FighterBeamKill' +44 WORD `ShipMovementSpeed' +46 WORD `FighterMovementSpeed' +48 WORD `BayLaunchInterval' +50 WORD `MaxFightersLaunched' +52 WORD `AlternativeCombat' +54 DWORD `StandoffDistance' +58 WORD `PlanetsHaveTubes' +60 WORD `FireOnAttackFighters' +62 WORD `TorpHitBonus' +64 WORD `TubeRechargeBonus' +66 WORD `ShieldDamageScaling' +68 WORD `HullDamageScaling' +70 WORD `CrewKillScaling' --- End of Configuration Structure --- +72 n BYTEs unused PHost 3 relies upon the PCONFIG.SRC file and omits the "configuration battle". Due to the "arrayized" (per-player configurable) battle parameters, the parameters wouldn't fit in one battle record. The `PlayerRace' option is transmitted within each VCR, in the high byte of the Owner field: if an owner field is 0205hex, it names a ship owned by player 5 who plays race 2. VCRINIT.TMP - Temporary file ----------------------------- This file is used for communication between PLANETS and VCR. More precisely, VCR can be run only if this file exists, otherwise it chains to PLANETS. PLANETS will ignore a password query if VCRINIT.TMP exists and load the given player's data immediately (nice, too ;-). File Format: +0 WORD Player Number +2 WORD Signature 667 (29Bh) +4 4 BYTEs 0 ## Invoking the VCR If a program needs to call VCR, it needs to perform the following steps: + Generate a VCRx.DAT. The signature may be missing, VCR doesn't perform integrity checks. GENx.DAT is not required. + Generate a VCRINIT.TMP containing the player number. It is possible to use player number 12 to avoid file name collisions. Generate a PATH.DAT that contains the path to be used (i.e., where you put VCRx.DAT and VCRINIT.TMP). The path must be usable immediately, that is, it must be possible to append a file name and use it ("D:\PATH\", not "D:\PATH"). + Create a copy of VCR.EXE. Check locations 155A3h and 15828h. If they contain the strings "planets" and "PLANETS", you're dealing with the original VCR: patch in the 7-character name (without ".exe") of a program which just terminates itself; you need to supply this program. If the signatures are missing, don't patch. You're then probably dealing with a copy of PVCR.EXE or a compressed VCR.EXE, your patch would happily blast it into pieces. Alternatively, temporarily rename your program `planets.com', so VCR will execute that one when exiting. + Change to the Planets directory, otherwise VCR can't locate its data files. + Execute the VCR copy. + Delete the VCR copy and VCRINIT.TMP, and possibly the temporary program. Note that implementing a VCR manually is not that hard, so you may want to choose that alternative. ## Replacing the VCR This is harder, because the above method invokes hacking the VCR.EXE file. Ideally, your program would have to be ready-to-patch, but that can usually not be achieved. If you only want that your program be called when you hit the [V] button in PLANETS.EXE, use the following procedure: + Write your program as usual, but make it able to handle the PATH.DAT / VCRINIT.TMP conventions. + If your program finished, chain to PLANETS.EXE, passing it the correct path as argument. You can use a C function of the "exec()" family for this. Implementing such a function is tricky under DOS, so if you don't have it, an alternative is shrinking your program to a minimum stub and spawning PLANETS.EXE as usual, as a sub-process. Note however that this will fill up memory if the user invokes the VCR many times. Even this problem can be avoided by using some kind of a resident PLANETS.EXE loader, but it's probably not worth the trouble. TRN FILE ========= +0 WORD Player Id +2 DWORD Number of commands. THost accepts no more than 5000. +6 10 BYTEs Date of last turn: mm-dd-yyyy +16 8 BYTEs Time of last turn: hh:mm:ss +24 WORD unused +26 WORD Timestamp Checksum --- only, if commands exist --- +28 BYTE unused +29 n DWORDs File positions of the commands, each increased by 1 Command: +0 WORD Command Code +2 n BYTEs Data A command is a request for the host to change a value. For example, the action "build a factory" is encoded as three commands: `PlanetChangeFactories', `PlanetChangeMoney' and `PlanetChangeSupplies'. MAKETURN looks for differences between the xxx.DAT and xxx.DIS files, and emits such commands. A TRN file does not contain a list of things you did this turn ("sell one supply"), it contains just the net effects. If you undo one action (e.g., raise taxes, then lower them to their original value), this is not reflected in the TRN file (here: no tax change command is generated at all). There are 4 groups of commands (values in decimal, not all numbers are actually used): 1..19 Ships (SHIPx.DAT/.DIS) 20..39 Planets (PDATAx.DAT/.DIS) 40..59 Starbases (BDATAx.DAT/.DIS) >= 60 general (Password, messages - GENx.DAT, MESSx.DAT) THost rejects unknown numbers as "Unknown OPP" with a cheat warning, but no consequences for the player. PHost does not accept turns with invalid commands. The command names given below are these used in my UN-TRN program, you should recognize what they do from their names and arguments: The arguments are usually "snippets" from a player-side data file. Identification of TRN files ---------------------------- The last command is followed by a data structure. There are two types of such "trailers", one for Winplan, one for DOS. The structures are addressed from the end of the file (i.e., `Seek(F, FileSize(F) - N)', that's why it's deadly to enlarge a TRN file. If the checksums don't match, Host tries to recover from a X-Modem transfer (which appends Ctrl-Z to files) by removing Ctrl-Z's. Windows TRNs with appended Ctrl-Z's are no longer recognized as such. ## Structure for VGA Planets for DOS +0 DWORD Checksum `X' +4 DWORD Contains random data with original MAKETURN. Some MAKETURNs put a signature here. +8 204 BYTEs Signature from FIZZ.BIN (offset 136, the 2 strings + sum) +212 11 DWORDs Id block (see below) The checksum `X' is the sum of all bytes in the TRN file up to (but not including) this structure, plus 3 times the timestamp checksum, plus 13. If the TRN file doesn't contain any command, this block is located at position 28 in the file. Winplan Shareware is identical to DOS planets from this point of view and generates the same file format. ## Structure for Winplan registered +0 6 BYTEs Signature "VER3.5" +6 2 BYTEs Sub-version "00", "01"... +8 DWORD VPH35 Value, part A +12 DWORD VPH35 Value, part B +16 25 BYTEs String 1, part A (Serial number) +41 25 BYTEs String 1, part B +66 25 BYTEs String 2, part A (Registration date) +91 25 BYTEs String 2, part B +116 50 BYTEs String 3 (Name of player) +166 50 BYTEs String 4 (Address of player) +216 100 BYTEs ??? (zero) --- the DOS structure follows here --- +316 DWORD Checksum `X' +320 DWORD Contains random data with original MAKETURN. Some MAKETURNs put a signature here. +324 204 BYTEs Signature from FIZZ.BIN (offset 136, the 2 strings + sum) +528 11 DWORDs Id block (see below) Checksum `X' is computed the same way as in DOS TRNs: up to (but not including) the DOS structure. The first 316 bytes are part of this checksum! The Strings 1 and 2 give the exactly the same text as in FIZZ.BIN. Here, they are encoded as Character[i] := ( PartA[i] XOR PartB[i] ) String 1 is interpreted as a serial number, 2 as registration date. The strings 3 and 4 appear "as is" in REG.LOG, they are unencoded. They are the name and address the user entered when unlocking his Winplan copy. Both DWORDs at position 8 and 12 give a value `Y': Y = ( VPHValue_A XOR VPHValue_B ) AND 7FFFFFFFh This equals the record `VPH_Record(Turn_Number)' from VPH35.DLL, see there. The values actually written to the TRN file come from SCRAM21.OLE, a file with the same information encoded in a different way. While THost also accepts unregistered TRNs with Windows trailer, and answers with Windows RSTs, PHost evaluates the Windows trailer only for registered clients: there is no unregistered Wisseman client which generates Windows TRNs. However, PCC can do this. ## Id Block The Identification block at the end of a TRN file allows a player to play several races with one registered client program. If 2 TRN files were generated by the same program, they contain the same registration signature and the same Id Block. With MAKETURN.EXE, the Id block contains 11 DWORDs. Each of these 11 entries is the checksum `X' from the respective player's TRN file, or zero if that player was not processed by this MAKETURN invocation. For some unknown reason, player 11's position when he does not play is 0F31h. Winplan puts the respective game's SNOOKER.DAT entry here. The actual values put here do not really matter. All you must make sure that TRNs made for the same game from the same computer bear the same 11-DWORD block. With current hosts, there is no requirement for the Id block to be derived from the TRN file contents in any way, like DOS MAKETURN generates it. The really only requirement is that TRN files from the same registered copy bear the same block. Older PHosts (3.15.1.x) required the DOS-Planets behaviour (entry N = player N's checksum `X'), and thus could not be used with Winplan. Valid Commands --------------- For WORDs, possible values are generally 0..10'000, for DWORDs the range is 0..1'000'000'000. Other values (Ids, speeds) are more restricted. These ranges are the reason that ships may not carry more than 10000 mc, and that the parameters for 3rd-party missions (Intercept Id, Tow Id) must be between 0 and 500 (Ids!). See also the descriptions of the appropriate DAT files. PHost ignores the command pointers and assumes that the commands are stored directly after the pointers, with no padding inbetween. Versions up to 3.4b also will not necessarily do the Right Thing(tm) if commands are not in their canonical order (i.e. first ship commands, then planet, then base, then rest; each block sorted by Id; each object sorted by command code). Most known MAKETURNs fulfill these conditions though THost does not require them. --- Code 1 (01h=ShipChangeFc) --- +0 WORD Ship Id +2 3 BYTEs New Friendly code Note that THost allows you to send multiple `ShipChangeFc' commands to trigger multiple alliance actions (eeX, ffX). This needs a specially prepared MAKETURN, however. --- Code 2 (02h=ShipChangeSpeed) --- +0 WORD Ship Id +2 WORD New Warp factor (0..9) --- Code 3 (03h=ShipChangeWaypoint) --- +0 WORD Ship Id +2 WORD X Waypoint, difference to current location +4 WORD Y Waypoint, difference to current location (range -3000 .. 3000) --- Code 4 (04h=ShipChangeMission) --- +0 WORD Ship Id +2 WORD New mission see SHIPx.DAT --- Code 5 (05h=ShipChangePrimaryEnemy) --- +0 WORD Ship Id +2 WORD New Primary enemy --- Code 6 (06h=ShipTowShip) --- +0 WORD Ship Id +2 WORD Id of ship to be towed --- Code 7 (07h=ShipChangeName) --- +0 WORD Ship Id +2 20 BYTEs New name --- Code 8 (08h=ShipBeamDownCargo) --- +0 WORD Ship Id +2 WORD Neutronium +4 WORD Tritanium +6 WORD Duranium +8 WORD Molybdenum +10 WORD Colonists +12 WORD Supplies +14 WORD Target planet Id (0 for Jettison) --- Code 9 (09h=ShipTransferCargo) --- +0 WORD Ship Id +2 WORD Neutronium +4 WORD Tritanium +6 WORD Duranium +8 WORD Molybdenum +10 WORD Colonists +12 WORD Supplies +14 WORD Target ship Id Note that, when transferring to an own ship, PLANETS.EXE generates "dull" transfers (all amounts except for the target Id are zero), those should not be written to TRN files to avoid confusing the host (PHost up to 3.4i/4.0f only sees a intra-race transfer which is not permitted using this command). --- Code 10 (0Ah=ShipIntercept) +0 WORD Ship Id +2 WORD Id of ship to intercept --- Code 11 (0Bh=ShipChangeNeutronium) --- +0 WORD Ship Id +2 WORD Neutronium / kt --- Code 12 (0Ch=ShipChangeTritanium) --- +0 WORD Ship Id +2 WORD Tritanium / kt --- Code 13 (0Dh=ShipChangeDuranium) --- +0 WORD Ship Id +2 WORD Duranium / kt --- Code 14 (0Eh=ShipChangeMolybdenum) --- +0 WORD Ship Id +2 WORD Molybdenum / kt --- Code 15 (0Fh=ShipChangeSupplies) --- +0 WORD Ship Id +2 WORD Supplies / kt --- Code 16 (10h=ShipChangeColonists) --- +0 WORD Ship Id +2 WORD Colonist Clans --- Code 17 (11h=ShipChangeTorpedoes) --- +0 WORD Ship Id +2 WORD Number of Torpedoes --- Code 18 (12h=ShipChangeMoney) --- +0 WORD Ship Id +2 WORD Money / mc The codes 19 (13h) and 20 (14h) are unused. --- Code 21 (15h=PlanetChangeFc) --- +0 WORD Planet Id +2 3 BYTEs New Friendly Code --- Code 22 (16h=PlanetChangeMineCnt) --- +0 WORD Planet Id +2 WORD Number of Mines --- Code 23 (17h=PlanetChangeFactories) --- +0 WORD Planet Id +2 WORD Number of Factories --- Code 24 (18h=PlanetChangeDefense) --- +0 WORD Planet Id +2 WORD Number of Defense Posts --- Code 25 (19h=PlanetChangeNeutronium) --- +0 WORD Planet Id +2 DWORD Neutronium / kt --- Code 26 (1Ah=PlanetChangeTritanium) --- +0 WORD Planet Id +2 DWORD Tritanium / kt --- Code 27 (1Bh=PlanetChangeDuranium) --- +0 WORD Planet Id +2 DWORD Duranium / kt --- Code 28 (1Ch=PlanetChangeMolybdenum) --- +0 WORD Planet Id +2 DWORD Molybdenum / kt --- Code 29 (1Dh=PlanetChangeColonists) --- +0 WORD Planet Id +2 DWORD Colonist Clans --- Code 30 (1Eh=PlanetChangeSupplies) --- +0 WORD Planet Id +2 DWORD Supplies / kt --- Code 31 (1Fh=PlanetChangeMoney) --- +0 WORD Planet Id +2 DWORD Megacredits --- Code 32 (20h=PlanetColonistTax) --- +0 WORD Planet Id +2 WORD Tax rate --- Code 33 (21h=PlanetNativeTax) --- +0 WORD Planet Id +2 WORD Tax rate --- Code 34 (22h=PlanetBuildBase) --- +0 WORD Planet Id Note that the `PlanetBuildBase' command has no data. It is sent if the last word in the planet record is non-zero meaning `build a base'. For THost, you can include the data word; however, PHost does not accept such turns (see above). The codes 35 (23h) to 39 (27h) are unused. --- Code 40 (28h=BaseChangeDefense) --- +0 WORD Base Id +2 WORD Base Defense Count --- Code 41 (29h=BaseUpgradeEngineTech) --- +0 WORD Base Id +2 WORD New Tech Level --- Code 42 (2Ah=BaseUpgradeHullsTech) --- +0 WORD Base Id +2 WORD New Tech Level --- Code 43 (2Bh=BaseUpgradeWeaponsTech) --- +0 WORD Base Id +2 WORD New Tech Level --- Code 44 (2Ch=BaseBuildEngines) --- +0 WORD Base Id +2 9 WORDs Number of engines of that type on the base --- Code 45 (2Dh=BaseBuildHulls) --- +0 WORD Base Id +2 20 WORDs Number of Hulls of that type at the base. These are the 20 ship types from TRUEHULL.DAT which the player can build. --- Code 46 (2Eh=BaseBuildWeapons) --- +0 WORD Base Id +2 10 WORDs Number of Beams of that type on the base --- Code 47 (2Fh=BaseBuildLaunchers) --- +0 WORD Base Id +2 10 WORDs Number of Torpedo Launchers of that type on the base --- Code 48 (30h=BaseBuildTorpedoes) --- +0 WORD Base Id +2 10 WORDs Number of Torpedoes of that type on the base --- Code 49 (31h=BaseBuildFighters) --- +0 WORD Base Id +2 WORD Number of Fighters on the base --- Code 50 (32h=BaseFixRecycleShip) --- +0 WORD Base Id +2 WORD Ship Id --- Code 51 (33h=BaseFixRecycleShip) --- +0 WORD Base Id +2 WORD Action 0 none 1 fix 2 recycle --- Code 52 (34h=BaseChangeMission) --- +0 WORD Base Id +2 WORD Primary Order (see BDATAx.DAT) --- Code 53 (35h=BaseBuildShip) --- +0 WORD Base Id +2 WORD Hull Number +4 WORD Engine +6 WORD Beam Weapon Type +8 WORD Beam Weapon Count +10 WORD Torpedo Type +12 WORD Torpedo Count +14 WORD Set to zero. See BDATAx.DAT for more info. A well-known Winplan bug (now fixed) is that its built-in MAKETURN did not generate this command if the build order _changed_; instead it generated it if it was _present_. This prevented users from canceling a build order after the ship limit. PHost has a workaround for this, which you should be aware of when generating Winplan TRNs: if it receives a Winplan TRN, the BaseBuildShip command specifies the current build order for the starbase. If there is no such command for a particular starbase, the base's build order is canceled. So you must send this command for all bases with either changed or present build orders to generate TRNs suitable for both THost and PHost. --- Code 54 (36h=BaseUpgradeTorpTech) --- +0 WORD Base Id +2 WORD New Tech Level The codes 55 (37h) to 59 (3Bh) are unused. --- Code 60 (3Ch=SendMessage) --- +0 WORD Length of message. The maximum length in THost is 700 bytes, PHost formats the message to 40 columns and then allows 18 lines to be transmitted. +2 WORD Sender (=Player Id) +4 WORD Receiver +6 n BYTEs Message (encrypted): Each byte is increased by 13dec. While DOS programs only encode a single byte for a line feed (0Dh, encrypted as 1Ah), Windows MAKETURN uses 0Dh 0Ah (encrypted 1Ah 17h). See also MDATAx.DAT / MDATA35x.DAT. You should prefer using a single 0Dh only: a line in a message must not be longer than 40 characters, and THost counts the 0Ah as text character. --- Code 61 (3Dh=ChangePassword) --- +0 WORD 0 (?) +2 10 BYTEs New password, encrypted. Each character is increased by 32h --- Code 62 (3Eh=SendBack) [PHost 4.0+] --- +0 WORD Receiver race, 0 means same as sender. Currently must be either 0 or same as sender to avoid spoofing. +2 WORD Record Type +4 WORD Data Size. Note that the complete TRN command must be below 32k, hence this value must be < 32760. You'd better set the limit a bit lower to not tempt fate :) +6 n BYTEs Data This command is ONLY supported by PHost 4.0 and later. The enclosed data will be echoed back to the player in his UTILx.DAT, as a normal UTILx.DAT record. This way, programs can send arbitrary information through the host. In particular, by sending file transfer records (type 34), one can send files. Attachments ------------ It is possible to embed files in a TRN file. These are then copied into the host directory when Host reads the TRN. This is used by TacCom to transmit alliance information. This method is only supported by the Wisseman host, not PHost or others. As a consequence, only few hosting utilities consider TRNs with attachment valid. This function is supported by Host 3.20 and later. +0 10 BYTEs Signature "NCC1701AD9" +10 DWORD Location of original TRN data in this file (as usual, + 1) +14 DWORD Size of original TRN file in bytes +18 10 RECORDs of 20 bytes each: +0 DWORD Position of embedded file ( + 1) +4 DWORD Length of embedded file +8 12 BYTEs File name, padded with spaces. Blank (=only spaces) if this "slot" doesn't contain a file. Following are the "attachments" and the TRN file. The host uses the data at +10 and +14 to extract the original TRN file. The result of extraction must be a valid TRN file (no more attachments). Host rejects BAT, DAT, EXT, HST, INI, LOG, NM, RST and TRN files; since 3.22.035 also EXE, COM and BIN. This still is a security hole because it is still possible to upload files that end up as `.exe' on the Host's disk (I have a proof-of-concept program if you insist...) On the other hand, this is a method to work around the X Modem problem, because it explicitly encodes the TRN file size within the file. How many people still use X Modem is another question. RST FILE ========= +0 8 DWORDs Addresses of the file sections, each + 1 --- Host 3.20+ --- +32 6 BYTEs Signature "VER3.5" for Winplan RSTs. +38 2 BYTEs Sub-Version, currently either "00" or "01". +40 DWORD File position of the Winplan data, when existent. +44 DWORD Position of LEECHx.DAT, if existing (0 otherwise). --- RST version "01" --- +48 DWORD Position of extended Ufo database Normally, the data follows at 96 (60h) or 33 (21h), with some uninitialized data between the header and the data. Winplan RSTs are sent if the host didn't get a TRN file, or if it got a Windows Turn file. Winplan RSTs contain a "DOS part" built up exactly as the normal DOS file. Windows RSTs contain additional information, see below. PHost remembers the RST file style over turns, and only sends Windows RSTs to registered clients. To make your program robust, you should check all file pointers before using them. Everything but the first 8 sections was hacked into the RST format later, and earlier hosts do not blank out those fields. THost-generated RSTs sometimes (rarely) bear the "VER3.5" signature without actually being Windows-style files. This is because THost does not initialize the space after the header, and if DOS happens to assign a cluster previously used by a Windows-style file, the signature will be still there. To guard against this case, double-check the validity of the Winplan part of the file: the "1120" and "1211" signatures look like good candidates. If you found the "VER3.5" signature, the Winplan header itself usually is valid, as it comes from a real RST file: checking the file pointers alone for plausible values (i.e., "non-negative", "not more than 2 MB", ...) does not buy you much in this case. Sections --------- The 8 standard file sections have the following contents: --- Section 1 (pointer at +0): Ships --- +0 WORD Number of ships +2 n BYTEs Ship records of 107 bytes each, see SHIPx.DAT --- Section 2 (pointer at +4): Visual Contacts --- +0 WORD Number of contacts. Must be <= 50 for Wisseman clients. VPHost and PHost with AllowBigTargets allow more than 50 contacts if the client-side unpacker can handle those (VPUnpack, k-unpack, CCUnpack). +2 n BYTEs Records of 34 bytes each, see TARGETx.DAT. DOS-style RSTs: the 50 nearest contacts. Windows-style RSTs: the first 50 contacts (in Id order) --- Section 3 (pointer at +8): Planets --- +0 WORD Number of planets +2 n BYTEs Planet records of 85 bytes each, see PDATAx.DAT --- Section 4 (pointer at +12): Bases --- +0 WORD Number of starbases +2 n BYTEs Starbase records of 156 bytes each, see BDATAx.DAT --- Section 5 (pointer at +16): Messages --- +0 WORD Number of messages +2 n BYTEs Records of 6 bytes each +0 DWORD Address of message in RST file + 1 +4 WORD Length of message in bytes The messages usually follow the message headers, and are encrypted like in MDATAx.DAT. Reportedly, Winplan cannot unpack results where the number of messages exceeds 5461, i.e., where the message directory is larger than 32k. --- Section 6 (pointer at +20): Ship Coordinates --- +0 n BYTEs 500 (or 999) Records of 8 bytes each, see SHIPXYx.DAT: +0 WORD X position +2 WORD Y position +4 WORD Owner +6 WORD Mass in kt --- Section 7 (pointer at +24): GENx.DAT --- +0 18 BYTEs Timestamp +18 88 BYTEs 11 score records of 8 bytes each +106 WORD Player Id +108 20 BYTEs Password +128 3 DWORDs Checksums of ship, planet, and base block These checksums are the sum of all unsigned bytes in all ship/planet/base records in the RST file. The first word of each section ("Number of...") is not counted. Note that these are not exactly the same checksums as in GENx.DAT. +140 WORD Turn number +142 WORD Timestamp checksum See GENx.DAT for more information on each field. Not all GENx.DAT fields are stored here, set the others to zero. --- Section 8 (pointer at +28): VCRs --- +0 WORD Number of VCRs +2 n BYTEs VCR records of 100 bytes each, see VCRx.DAT. Unpack programs must generate two (nearly) identical copies of the ship, planet and base sections (.DAT and .DIS). Those files only differ in their signatures. The RST file does not contain the signatures. ## Detecting Host999 There appears to be no signature telling whether you are dealing with a Host999 file or not. This only makes a difference for the SHIPXYx.DAT part which has no length specification. If section 1 or 2 contain an Id number greater than 500, you can be sure to have a Host999 RST (not for the scores or VCRs, those could have been changed by a 3rd party add on, since they have no other effect in a front-end program). You can use the fact that the Wisseman Host always places the sections in "correct" order, so if there are exactly 4000 bytes between sections 6 and 7, it's a "Host500" RST, if there are 7992, it's from Host999. Or, always assume you have 999 ships. If you then accidentally "run into" the GENx.DAT image: valid timestamps start with two numbers, which -- interpreted as a WORD -- yield an invalid or at least improbable X coordinate for a ship. Note that the standard Winplan999 and Unpack999 programs do not attempt to detect that, and blindly copy 7992 bytes, thus making bogus SHIPXYx.DAT files (see there) if Host999 is not used. ## "RST Format 36" / "RST Format 37" With the introduction of "FF allies" in Host 3.22.039, Tim announced the change to "RST Format 36" (or 37, depending on where you look). The basic RST file format did NOT change in these versions. Unpackers need not be changed. "RST Format 36" probably references the fact that allied targets are listed in TARGETx.DAT but not in SHIPXYx.DAT, making them invisible to DOS Planets. See the description of these two files for more details. Winplan data ------------- The pointer to this section is at offset +40. +0 500 RECORDs of 8 bytes each; Mine fields +0 WORD X +2 WORD Y +4 WORD Radius. Zero if the minefield has been swept. All other information remains in this minefield slot until the slot is re-used for a new minefield. +6 WORD Owner. 0 empty record 1..11 Normal minefield belonging to race 1..11 12 Crystalline Web mine field. Note that this does not allow transmission of web minefields that do not belong to the Crystals. Non-Crystalline webs are sent as normal mines (1..11). This section contains not only the minefields the player scanned this turn, but also all of his own minefields. This implicitly provides information about minefields that were swept completely. +? 600 BYTEs Ion storms, 50 records of 12 bytes each +0 WORD X +2 WORD Y. Note that THost sometimes generates storms with negative coordinates. +4 WORD Radius +6 WORD Voltage in MeV 0 non-existent even weakening storm odd growing storm +8 WORD Warp +10 WORD Heading in degrees see also GREY.HST below. +? 50 RECORDs of 4 bytes each: Explosions +0 WORD X (0 = non-existent) +2 WORD Y THost generates an explosion entry for every ship that exploded due to excess damage in battle or after a mine hit. PHost only generates these entries for ships exploding after a mine hit. +? 682 BYTEs Contents of RACE.NM. RACE.NM remains unchanged if this field is empty (only spaces). +? 7800 BYTEs Contents of UFO.HST, filtered +? 4 BYTEs Signature "1211", if all visual contacts fit into the normal TARGETx.DAT file, "1120" otherwise. These numbers appear to be literals, not some strange flags. --- Additional Visual Contacts --- +? DWORD Number of contacts. +? n RECORDs of 34 bytes each. +0 WORD Id Number +2 WORD Owner +4 WORD Warp +6 WORD X location +8 WORD Y location +10 WORD Type of hull +12 WORD Heading in degrees, 0=North, 90=East, 180=South, 270=West, -1=unknown +14 20 BYTEs Ship name, encrypted FOR i:=1 TO 20 DO Encrypted[i] := Original[i] XOR (155-i) Note that, except for the ship name, this is exactly a TARGETx.DAT record. ## LEECHx.DAT If the value at +44 is non-zero, it points to the following data: +0 DWORD Size of LEECHx.DAT +4 n BYTEs Contents of LEECHx.DAT You only need to place a file named LEECHx.DAT in the Host directory, and the Host will send it to the players. Winplan's UNPACK will unpack it to the game directory. This file is not used otherwise. ## Extended Ufo database In version "01" RSTs, the value at +48 points to the following data: +0 WORD Total number of Ufos. The minimum value is 100, as there are already 100 Ufo records in the standard Winplan section. +2 n RECORDs of 78 bytes each: the Ufos. This field contains the Ufos from Id 101 onwards. Thus, the extended Ufo database stores 100 Ufos less than specified in the WORD above. HOST DATA ========== These host data file formats are used by THost and PHost 3. PHost 2 for non-DOS platforms uses a "native" format which is basically the same, but words are stored in the native byte order, and padding is used where required by the architecture/ABI. AUXDATA.HST - PHost - Miscellaneous [V] ---------------------------------------- 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 cloaked Size 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 unused This 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 ships The 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 ships ## PHost 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 BDATA.HST - Starbase Data [V] ------------------------------ This is nearly the same format as BDATAx.DAT: +0 WORD ? (unused?) +2 n BYTEs 500 starbase records of 156 bytes each, see BDATAx.DAT. +78000 WORD Turn number. If this number does not match the number in NEXTTURN.HST, THost prints an error message and uses the number from BDATAx.HST. BUFF.TMP - Temporary File BUFFPNT.TMP - Temporary File ----------------------------- In THost games, these files contain all anonymous messages. BUFF.TMP contains the texts, BUFFPNT.TMP contains addressee and file pointers. See MESS.EXT/MESSPNT.EXT below. The addressee of each message is set to zero when the message is delivered. THost never deletes these files, so they can grow large over time. You can safely delete them after a Host run. CLOAKC.HST - Cloak & Shield State [V] -------------------------------------- [Host 3.22.017+, PHost 3] If AUXBC.INI is used, host creates this file before running AUXBC.INI and reads it back later (at least the cloak flags). For the "normal" host and PHost 3.x, this file contains 2x500 words. For Host999 and PHost 4.x, it contains 2x999. +0 N WORDs 1, if the corresponding ship is cloaked. +2N N WORDs Shield Charge States (0..100). Non-existing ships have value 100 here. Don't confuse this with the Shield Strength measured in kt, host does not store this value as you can compute it manually: (hull mass) + (ES bonus)*(engine price)/100 ETEMPx.TMP - Temporary File ---------------------------- This file is created while making the TARGETx.DAT records for the RST files. It contains the targets not fitting into the DOS part of the RST file. You can delete this file after the host run, the host does not always do this itself. +0 DWORD Number of records +4 n BYTEs Records of 34 bytes each. See RST file description or the KOREx.DAT file format for more information. EXTMINES.HST - PHost - Minefields ---------------------------------- This file contains 9500 minefield records for minefields #501 to #10000. It is used by PHost 3.3 and later when the appropriate config option is set. The file format is the same as MINES.HST. GEN.HST - Passwords and other ------------------------------ +0 24 BYTEs ? +24 11 BYTEs PHost only: for each player, 1 if last turn was submitted in Winplan format, 0 otherwise. Unused in THost. +35 11 BYTEs PHost only: for each player, 1 if last turn was submitted using a registered client, 0 otherwise. Unused in THost. +46 11 WORDs 1, if the race is playing, 0 otherwise +68 220 BYTEs Passwords. To get the password for player X: VAR pw : ARRAY[1..22, 1..10] OF BYTE; { this field } password : ARRAY[1..10] OF CHAR; FOR i:=1 TO 10 DO password[i] := Chr( pw[X,i] - pw[X+11,11-i] + 32 ) This is similar to GENx.DAT. The resulting password is zero-padded, not space-padded. High-ASCII characters should be treated as zero, because MASTER sometimes generates those. +288 n BYTEs ? +448 WORD THost: Ship build queue: Id of starbase that built the last "normal" ship (not a priority build). Unused/not present in PHost. Fields marked with "?" are unused. GREY.HST - Miscellaneous ------------------------- +0 500 WORDs Experience values of starship crews +1000 n BYTEs Ion storms: 50 records of 16 bytes each +0 WORD X +2 WORD Y Note that Host sometimes (rarely) generates storms with negative coordinates. +4 WORD Radius +6 WORD Voltage in MeV 0 Non-existent storm 1..49 Class 1 (harmless) 50..99 Class 2 (moderate) 100..149 Class 3 (strong) 150..199 Class 4 (dangerous) >=200 Class 5 (very dangerous) Only class 4/5 storms hurt ships. +8 WORD Heading in degrees: 0=North, 90=East, ... +10 WORD 0 weakening 1 growing +12 2 WORDs ? (unused?) +1800 11 WORDs Build Priority Points --- Host 3.22.007 and later --- +1822 11 WORDs Alliances. This field contains information on who a player has declared an ally: Bit 0 1=the player set the Feds as his ally Bit 1 1=the player set the Lizards as his ally ... Bit 10 1=the player set the Colonies as his ally Ships of the player won't attack ships of his allies. --- Host 3.22.027 and later --- +1844 3 BYTEs unused (?) +1847 500 WORDs Cheat check flags, for all planets/bases. Bit 0 1=starbase with this Id has built a ship. Used to prevent multiple clones at one base. Bit 1 1=ship with this Id has moved (itself or by being towed) and is denied chunneling. Used to prevent "tow-drop chunnels". Note that this flag is also set for tow pairs when the tower does not move. There is no Host999 3.22.027 (yet?); it is unknown how it would handle this array. --- Host 3.22.039 and later --- +2847 11 WORDs Level 2 Alliances ("FF allies"). For each player, whom he has declared a level 2 ally, as a bitfield like above. If a bit is set here, the corresponding bit at +1822 is set, too. ## Ion Storms An active storm is identified by a non-zero voltage. Storms that have disappeared are still stored but have voltage 0. There may only be as many ion storms as specified in the HConfig file (default: 5), so that normally not all fields could contain real storms. When a new game is started, there are always some active Ion storms. It may happen that a player gets a message about a storm with 0 MeV. Due to the encoding here, that storm won't appear on the starcharts. Storm speeds are not stored here, they are computed when they're needed. As of Host 3.22.003, the Ion storm speeds were these: * Storms with more than 250 MeV always move at warp 8 * Storms smaller than 200 ly move at warp 6. * Larger storms move at Warp 2 (20%) Warp 3 (48%) Warp 4 (32%) Use first matching rule. Older Hosts only use the last two rules. Ion storms that move outside 0 <= X <= 4000 resp. 0 <= Y <= 4000 are deleted the turn _after_ they moved there. Thus, it is possible that a storm with negative coordinates is reported. New storms are not subject to the usual rules. They can also have other speeds (Warp 5, Warp 7). ## PHost When PHost is being used, this file is only a dummy version. PHost creates it, but sets all fields to zero. Only the alliance data is written: PHost sets a particular alliance bit to one if and only if the player has offered all five PHost alliance levels to his ally. This file is never read by PHost, changing it won't influence the host. Use AUXDATA.HST to affect PHost. PHost 4.0j and later also uses the Ion Storm field, using the same meaning as THost. HCONFIG.HST - Configuration [V] -------------------------------- Fields marked with "-" contain boolean values: 1=yes, 0=no. Probabilities are given in percent in most cases. +0 WORD Recycle Rate for "Colonize" mission, % +2 WORD Odds of a meteor +4 WORD -Minefields (independent of Web Mine setting) +6 WORD -Alchemy ships +8 WORD -Delete old messages --- the Host 3.00 HConfig ends here --- +10 WORD -Disable passwords +12 12 WORDs Ground combat: Attack ratio for each player +36 12 WORDs Ground combat: Defense ratio for each player +60 12 WORDs Free fighters on starbase per turn, for each player +84 12 WORDs Mining rates for each player (50..500%) +108 12 WORDs Tax rates for each player (50..500%) These fields contain 12 words. The first word in each range is 0, the remaining 11 entries contain the data. +132 WORD -Rebels can build fighters on ships +134 WORD -Colonies can build fighters on ships +136 WORD -Robots can build fighters on ships +138 WORD Odds of cloak failure (0..50%) +140 WORD -Privateer can rob cloaked ships (Rob Ship mission) +142 WORD Sensor range (ships visible) +144 WORD Dark Sense range +146 WORD -Lizard: Hissss mission +148 WORD -Rebel: Ground attack +150 WORD -Federation: Super Refit +152 WORD -Crystal: Web Mines +154 WORD Fuel used for cloaking in kt (1..50) +156 WORD Range of Sensor Sweep mission +158 WORD -New natives appear on planets +160 WORD -Planets attack ships +162 WORD Cyborg assimilation rate +164 WORD Web Mine decay rate +166 WORD Mine decay rate +168 WORD Maximum mine field radius +170 WORD Trans Uranium Mutation rate ("isotope TUDR") +172 WORD Structure decay +174 WORD -Overpopulation eat supplies +176 WORD -Ships without fuel can move +178 WORD Odds of running on a mine +180 WORD Odds of running on a Web mine +182 WORD Range from with mine fields can be seen +184 WORD -Mines destroy enemy mines --- Host 3.11a and later: --- +186 WORD -Engine Shield Bonus +188 WORD Engine Shield Bonus Rate +190 WORD Colonies: mine sweep rate when sweeping with fighters +192 WORD -Colonies: can use fighters for web sweeping +194 WORD Mine Sweep Rate +196 WORD Web Mine Sweep Rate +198 WORD Lizard: Hissss Effect +200 WORD Privateer: odds of a Rob Ship failure +202 WORD -Rebel can be attacked by planets +204 WORD -Fascist can be attacked by planets +206 WORD Mine Sweep range +208 WORD Web Mine Sweep range +210 WORD -Terraforming missions ("science missions") +212 WORD Odds to run on a mine with a cloaked ship, in 1/10 % +214 WORD Damage level that prevents cloaking +216 WORD -Federation: Crew bonus ("Scotty Bonus") +218 34 BYTEs Information on small meteors +0 WORD Probability +2 DWORD Minimum Neutronium +6 DWORD Minimum Duranium +10 DWORD Minimum Tritanium +14 DWORD Minimum Molybdenum +18 DWORD Maximum Neutronium +22 DWORD Maximum Duranium +26 DWORD Maximum Tritanium +30 DWORD Maximum Molybdenum +252 34 BYTEs Information on large meteors, same as above +286 WORD -Send messages for meteor impacts --- Host 3.12c and later: --- +288 WORD -One-Engine ships can tow +290 WORD -Hyperdrive ships +292 WORD Climate death rate +294 WORD -Gravity wells +296 WORD -Crystal: like hot planets --- Host 3.13b and later: --- +298 WORD -Mines destroy web mines +300 WORD -Climate limits population --- The Host 3.14 HConfig ends here --- +302 DWORD Maximum income per planet +306 WORD Maximum number of Ion storms (0..100) +308 WORD -Firecloud Chunnel +310 WORD -Super Spy Deluxe +312 WORD -Ion storms hide mine fields +314 WORD -Glory Device +316 WORD -Loki anti-cloak +318 WORD -Lady Royale gambling +320 WORD -Cloaked ships attack +322 WORD -Ship cloning +324 WORD -Crystal and Privateer: boarding (tow capture) +326 WORD -Imperial Assault --- Host 3.2 beta 2a and later: --- +328 WORD Neutronium made by the Cobol ship per ly traveled +330 WORD -Aries ship can do alchemy +332 WORD -Bioscanner +334 WORD Hull tech level, from which onwards ships are not slowed down by mine hits (Hull tech mine slowdown) --- Host 3.22.022 and later: --- +336 WORD -Loki de-cloaks Bird Men --- Host 3.22.036 and later: --- +338 WORD -Allow VPA features (i.e. large cargo transfers) New Hosts normally append their new settings after the end of the file. Note that Host itself will not upgrade the HConfig file, if the file has the wrong size, the default configuration is used. The HCONFIG.EXE program must be used to enlarge the file. Some add-ons (most notably, the D&D ones) also read HCONFIG.HST, and cease to work if it does not exist. LASTTURN.HST - Timestamp ------------------------- +0 18 BYTEs Timestamp of last host run +18 WORD 0 This file is updated after writing the RSTs. Programs run as AUXHOST use the old value. In PHost 3.x and before, this file contains the same timestamp as NEXTTURN.HST (i.e. the timestamp of the current host run, not the previous one). Thus, add-ons run during PHost processing can not access the old timestamp. See SHIPSCAN.EXT for a table of PHost's timestamp-related behaviour. MESS.OLD - Old Messages (=sent last turn) MESS.EXT - External Messages (sent by Hostmaster) MESS.TMP - Current Message Traffic -------------------------------------------------- These files contain - encrypted the usual way, see MDATAx.DAT - some message texts. The corresponding MESSPNT files contain pointers into these files. The MESS.EXT file contains messages sent by the host using the SENDMESS program. The messages must be "complete", i.e., with all headers. Host itself only prepends the "(-h000)" signature, so the MESS.EXT file must supply the "<<< Subspace Message >>>", "FROM: Host" and "TO: player" headers. Host renames it to MESS.TMP when starting. The MESS.OLD file contains all messages from the last host run, to allow delivering them after a missed turn. If this feature is enabled (HCONFIG.HST, offset +8), up to 100 old messages are saved. Before exiting, Host renames MESS.TMP to MESS.OLD, so this file stores all messages generated by the host, sent by players, and external messages. The MESS.TMP file only exists during a host run, available to AUXHOST1 and AUXHOST2 programs. See also BUFF.TMP. MESSPNT.OLD - Pointers to Old messages MESSPNT.EXT - Pointers to External messages MESSPNT.TMP - Pointers to Current messages -------------------------------------------- +0 WORD Number of messages in the file +2 n BYTEs Records of 8 bytes each +0 WORD Receiver race +2 DWORD Address in MESS.OLD/.EXT/.TMP file, 1-based +6 WORD Length of message See MESS.OLD/.EXT/.TMP for more information about usage of these files. See also BUFFPNT.TMP. MINES.HST - Mine fields ------------------------ 500 records of 12 bytes each +0 WORD X +2 WORD Y +4 WORD Owner +6 DWORD Number of Mine Units. The radius of each mine field is the square root of this value. The maximum value here is 3000²=9,000,000 (3000 is the maximum possible mine field radius that can be set in HCONFIG), resp. 25,000,000 (maximum set by the Host program). +10 WORD Type 0 Normal Mines 1 Web Mines Unused minefields are identified by the radius and owner being zero. Non-Crystalline Web Mines are problematic. They can't be transmitted to Winplan (see KOREx.DAT), and Host does sometimes still assume that Web Mines always belong to the Crystals. Minefields with Id greater than 500 are stored in EXTMINES.HST (PHost). NEXTTURN.HST - Timestamp ------------------------- +0 18 BYTEs Timestamp of last host run +18 WORD Current Turn number This file is updated before reading in the TRNs. Programs run as AUXHOST use the new turn number. OLDFIG.HST - Host Configuration -------------------------------- This file is basically the same as HCONFIG.HST. It contains the configuration of the last host run. If this file differs from HCONFIG.HST, the new HConfig is sent to the players as message. PDATA.HST - Planet data ------------------------ +0 WORD ? (unused) +2 n BYTEs 500 planet records of 85 bytes each, see PDATAx.DAT. FHost is reported to mark destroyed planets by setting their ore content, temperature, etc. to unpleasant values (everything zero). Note that the "correct" way of destroying planets is to move them out of the way using XYPLAN.DAT, not by zeroing them out in this file: the change in XYPLAN.DAT can be communicated to the players, the change in PDATA.HST can not. PHost considers planets non-existent when it has an Id of zero in this file (normally, planet slot X has Id X). Recent versions report that fact using a UTILx.DAT entry; in earlier versions, this is problematic, too, because it can't be communicated to the players. PHONEY.HST - Hull Remapping Hook --------------------------------- This file contains 500 WORDs, one per ship. If a ship's entry is a valid hull number (1..105), that number is reported as ship type through visual scans (TARGETx.DAT). If a value is outside this range (e.g. zero), or if this file does not exist, the normal hull type is reported. This file is used by the RacePlus Chameleon device. REFDATA.HST - Victory Conditions [T] ------------------------------------- This file is created by MASTER, but not used by the host. The external REF program uses this file, RCONFIG can edit it. +0 WORD 1 if a scenario was chosen in RCONFIG, 0 otherwise +2 WORD Scenario chosen in MASTER (starting conditions) 1 Classic (Homeworlds in a circle) 2 Custom (Homeworlds at selected positions) 3 Wandering Tribes (all at the same spot) 4 Wandering Tribes (all at selected positions) 5 Wandering Tribes ("mass confusion") 6 Ashes of the Empire 7 Crazy Intermix (no borders) 8 Disunited Kingdoms (all with a number of planets) Master 3.00 can do scenarios 1 to 3 only. +4 WORD ? (0) +6 11 WORDs Id numbers of homeworlds, 0=none ("Wandering Tribes" scenario, or race is not playing) Set by MASTER. +28 WORD ? (0) --- "Tantalus" --- +30 11 WORDs Number of turns the race already controlled the Tantalus machine. +52 WORD Id of planet with Tantalus machine +54 WORD Number of turns a player needs to control the Tantalus machine in order to set it off --- "Ashes of the Empire" --- +56 WORD Race playing the empire --- general --- +58 WORD Scenery chosen in RCONFIG (victory condition) 1 Elections 2 Ship Tonnage 3 Election + Ship Tonnage 4 Tantalus Machine 5 Moly The Spice of Life (Molybdenum) 6 Ashes of the Empire 7 Invasion (capture homeworlds) +60 DWORD ? (0) +64 11 DWORDs Current REF scores +156 DWORD Score required to win (except "Ashes..." and "Tantalus") +160 DWORD ? (0) +164 WORD Winning race, 0 = no one yet The fields marked ? are probably remainders of BASIC arrays: a `DIM a(11)' statement defines an array with 12 members (0..11). Fields for scenarios other than the chosen one are zero. SHIP.HST - Ship Data --------------------- +0 WORD ? (unused) +2 n BYTEs 500 (resp. 999) ship records of 107 bytes each, see SHIPx.DAT. SHIPSCAN.EXT - PHost - Ship Scan Information [V] ------------------------------------------------- This file describes who currently sees which ship. It is a text file. First line: identification - "0": this is the first turn; - "99 02-22-200022:33:44": this is turn 99, and the timestamp is "02...". Use this line to verify this file is current. Since this file is written at the end of the previous turn, you should validate the number against LASTTURN.HST. Note that many PHost versions have bugs causing the information written here to be off by up to two turns, see below. 500 (resp. 999) lines: two numbers separated by a space, for each ship. - The first number specifies what "enemies" see this ship, i.e. everybody but the owner and his allies who scanned the ship; - The second number specifies what "allies" see this ship, i.e., the ship owner, and his ship level allies. Each number should be treated as a bitfield. Bit 1 is set if the Feds see the ship, bit 2 for the Lizards, etc. Bit 0 is zero. The two sets are disjoint. Use this to verify if a player triggering some action can actually see the target ship. A line contains two zeroes if the ship does not exist. This file is written for auxiliary programs; it is never read by PHost. PHost uses information stored in AUXDATA.HST. ## Turn Numbers There are two problems which make use of the first line harder than required. + PHost 3.x updates the LASTTURN.HST file too early during the host run. Auxhost / PControl programs will see the new turn number and timestamp instead of the old one. + PHost before 3.4m/4.0k write the old turn number and timestamp to this file, which will differ from the one in LASTTURN.HST / NEXTTURN.HST. Let 'N' be the turn number from LASTTURN.HST. Summarized, we have the following behaviour: Version | During Host Run | Between Host Runs | LAST | NEXT | SHIP | LAST | NEXT | SHIP ===========|======='======='=======|======='======='======= 3.0-3.4l | N N N-2 | N N N-1 3.4m+ | N N N-1 | N N N 4.0-4.0j | N N+1 N-1 | N N N-1 4.0k+ | N N+1 N | N N N SHIPXY.HST - Ship Coordinates ------------------------------ Same as SHIPXYx.DAT. All ships are stored. Host uses this file instead of fetching the relevant data from the SHIP.HST file, hence add-ons must update both files. In particular, Host does not update it before doing Ion Storm effects, therefore it uses ship masses from the previous turn. PHost does not read this file and only writes it for compatibility. 500 (resp. 999) ship records: +0 WORD X position +2 WORD Y position +4 WORD Owner +6 WORD Mass in kt TONS.HST - Ship tons "sunk" this turn [V] ------------------------------------------ This file is created by the host, but never used again. The TONS.EXE program can make a text file from this file. This can be used for scoring purposes. +0 11 DWORDs Sum of sunk ships (total masses destroyed by player) +44 11 DWORDs Sunk tonnage this turn --- PHost 3.4b+: HeikoTons[tm]: --- +88 11 DWORDs Sum of lost ships (total masses lost by player) +132 11 DWORDs Lost tonnage this turn TONS2.HST - Ship tech sunk this turn [T] ----------------------------------------- Like TONS.HST, this one counts ship tonnage sunk this turn. However, this one scores ship mass times tech level, that is, when you destroy a 150 kt Tech 6 ship, you get 6x150=900 points. +0 11 DWORDs Sum of sunk tech (total destroyed by player) +44 11 DWORDs Sunk tech this turn This file is generated by THost only. UFO.HST - Ufos, 3rd party additions [V] ---------------------------------------- This file contains Ufo data. These are not used within the host program, but sent to Winplan users in RST files. This file allows third-party programs to create completely new objects. Players can interact with these Ufos using the mission codes 20...999, special FCodes or messages, depending upon the program. The host uses the visibility ranges to decide which Ufo to send to which player. This makes it impossible to show a particular Ufo to selected players only. The file contains 100 or 1000 records of 78 bytes each: +0 WORD Color (1..15) 0 means this Ufo doesn't exist. The color is the usual encoding for colors in VGA text and graphics modes: 0 black 8 dark gray 1 blue 9 light blue 2 green 10 light green 3 cyan 11 light cyan 4 red 12 light red 5 magenta 13 light magenta 6 brown 14 yellow 7 light gray 15 white +2 20 BYTEs Name of object, shown on the star charts +22 20 BYTEs Info 1 +42 20 BYTEs Info 2 Shown when the object is selected. +62 WORD X (0..4000) +64 WORD Y (0..4000) +66 WORD Warp speed (official range is 0..15, but some programs put other things than a Warp speed here...) +68 WORD Heading in degrees: 0=North, 90=East, 180=South, 270=West, -1=unknown; +70 WORD Distance from which a planet can see the object +72 WORD Distance from which a ship can see the object Valid values are 1..5000, all other values are equal to 5000. +74 WORD Radius of object +76 WORD Type of object. A program always should use only objects if it knows their type. To avoid collisions, each programmer should get a range of Id numbers from Tim Wisseman. These are already assigned: 1 used by PHost for wormholes 101..150 Dan Gale 151..200 Jan Peter Dijkstra 201..250 Sean Martens 251..255 Bret Lusskin 256..260 DeltaDev@GMX.net 300..310 Norman Violet 311..350 Scott Zinssell 351..400 Boris Psakhis 401..425 Nestor Delfino 426..450 Bruno Smit 451..475 Dave Killingsworth 500..525 Tony Llopis 526..550 Joerg Schueler 551..575 Markus Mann 576..599 Rick Blanchette 600..620 Michael C. Patrick 621..630 Anthony Adam 631..650 Evan Shanks 651..699 Marc Bonaventura 700..799 RAW! (Dan and Dave) 850..900 Rene Gallati 901..999 Tobias Wolf 1000..1050 Sven Bursch 1051..1075 Jean-Marie Clement 1076..1099 Scott Garner 1100..1125 Kenneth Strom 1126..1150 Atomic 1151..1175 Hofbauer Heinz 1176..1199 Kevin Foster 1200..1299 George Carey 1300..1349 Thorsten Kaben 1350..1374 BioMenaced 1375..1399 Jayesh Palshikar 1400..1420 Scott Lombard 1421..1440 Ronald Landheer 1441..1460 Greg Kazarian 1461..1470 Don Friesen (Robomaster) 1471..1555 Wolfgang Merkel 1556..1560 Bernd Ruf (PHCc) 1561..1570 Dennis Weise 10401..10499 Yann Ramin 10500..10599 Star Destroyer ## PHost Wormholes Wormholes are not stored in the UFO.HST file; only in RST files and KOREx.DAT. PHost "overlays" them during RST creation. Wormholes are mapped to Ufos and then filtered. PHost allocates one Ufo slot for unidirectional wormholes, and two slots for bidirectional ones. From the sequence of Ufos alone you can not tell whether a particular wormhole is the entry or the exit of a bidirectional wormhole. Matters are complicated by the fact that wormholes are reported with a different Id in UTILx.DAT and as Ufo. However, the sequence of Wormhole reports in UTILx.DAT and the sequence of wormhole Ufos can be matched against, so the UTILx.DAT sequence can deliver the real Ids for wormhole Ufos (UTILx.DAT does not contain the information whether a wormhole is unidirectional or bidirectional!). Thanks to Piotr Winiarczyk for this. Wormhole Ufos always have color 2. In PHost before 3.3e, they always have radius 5 and visibility range 5000; later versions report the correct values. UTIL.TMP - PHost - Temporary UTILx.DAT Files [T]/[V] ----------------------------------------------------- When PHost is run in phases, or shells out to execute an add-on (AUXHOST, PControl), it saves the data that is going to be UTILx.DAT files in a file called UTIL.TMP. You can try to make use of this. The official reading is that add-ons that are just that -- add-ons -- should write to UTILx.EXT; add-ons that replace stages in PCONTROL can write to UTIL.TMP (to make their records come out at the right place). Add-ons can read this file to gather information about what PHost told the players yet. Like UTILx.DAT, UTIL.TMP consists of multiple records. ## Portable Format [PHost 3.4 and later] [V] Each record starts with a header of the following format: +0 WORD Player Id (whose UTILx.DAT file will contain this data) +2 WORD Record Type. See UTILx.DAT in the `Player Data' section +4 WORD Record Length +6 n BYTEs Data The data is in the format you'd expect, like in UTILx.DAT. ## Unportable Format [PHost 3.3e and before] [T] In these PHost versions, UTIL.TMP was just a temporary file. Hence it contains data in host byte order, with padding inserted by the compiler, which makes accessing it a quite fragile process. Your best bet is to declare a C struct, and hope it comes out the same way as it did in PHost. For PHost 3.2e for "PC/DOS" (Borland C), the format is the following: Each record: +0 DWORD Player Id (whose UTILx.DAT file will contain this data) +4 DWORD Record Type. See UTILx.DAT in the `Player Data' section +8 WORD Record Length +10 n BYTEs Data --- Type 13 (Control record - File Header) --- +0 18 BYTEs Timestamp +18 WORD Turn number +20 WORD Player number +22 WORD 0 (not in UTILx.DAT) +24 2 BYTEs PHost version +26 8 DWORDs Specification file digests +58 32 BYTEs Game Name +90 BYTE PHost Release Code +91 BYTE 0 (not in UTILx.DAT) Under PHost 3.3e for x86/Linux (GNU C), the format is different (two padding bytes after the PHost version, two more at the end). UTILx.EXT - PHost - Add-on Information [V] ------------------------------------------- See under UTILx.DAT. If an add-on program generates UTILx.EXT, PHost appends its contents to the UTILx.DAT file sent to the player. VCR.HST - VCRs --------------- This file contains all VCRs from a turn: +0 WORD Number of VCRs +2 n RECORDs of 100 bytes each (VCRs, see VCRx.DAT) XTERNCMD.EXT - PHost - External Commands ----------------------------------------- This is a text file. PHost places all commands sent through the Command Processor's `xtern' command here. Add-on programs may make use of this. The first line contains the turn number, followed by a space and the timestamp, so add-ons can check if the file is current. On the very first turn, this file contains just the single digit "0". Following lines contain the actual commands, in the form "player number: command", where "player number" is the number from 1 to 11, and "command" is what followed the `xtern' command. As of PHost 3.4b, there are no limits of line length. You can use the `xtern' command as a replacement for comments in command messages. EchoView does this to mark auto-generated messages: these start with `xtern echoview TYPE'. It is recommended that add-ons recognize a command `cmd' also when spelled as `name: cmd', where `name' is the name of the add-on. This makes it clear whom a command belongs to. XTRFCODE.TXT - PHost - Special Friendly Codes ---------------------------------------------- This file can be generated by add-on programs to tell PHost what friendly codes to consider "special". Those will then never match during combat, etc. It must contain sequences of up to three non-whitespace characters, separated by any amount of whitespace. Whitespace can be at least the space character (ASCII 32), the tab (ASCII 9) and the newline (ASCII 10). If one definition is less than three characters long, it causes all friendly codes starting with that sequences to be considered special. E.g., if XTRFCODE.TXT contains "lfm md X", it will define "lfm" special, all codes starting with "md" (mine drop), and all starting with "X" (inhibit Super Spy Deluxe). Note that PHost itself does *not* consider "md" and "X" special because they should match. PHost 3.4 and later automatically include their own friendly codes in this file at host-side; earlier versions did not. When players request this file, their copy will always include the built-in special codes. XYPLAN.DAT - Planet coordinates XYPLAN.HST - Planet coordinates -------------------------------- 500 records of 6 bytes each: +0 WORD X coordinate (1000..3000, 1000=left) +2 WORD Y coordinate (1000..3000, 1000=bottom) +4 WORD Owner. In the .DAT file which is also used by the Planets program, this field is 0. MASTER makes a copy with the name XYPLAN.HST. PLANETS.EXE checks if XYPLAN.DAT has changed by adding up all X coordinates. The result must be exactly 998681. Otherwise, it refuses to run with the message "ERROR: Data file XYPLAN.DAT has been tampered with. Program terminated to avoid a security breach." There is a patch available, since "custom universes" are quite popular. According to Roger Burton West there is also an Y checksum with the value 1002633, but I could not confirm this. My copies of PLANETS.EXE and Winplan had no problems with this. If you roll your own map, you have two alternatives for making the checksums right: - as long as your map checksum differs by more than 500 from the required value, move it to the left or right until it is in range. To correct the rest, move some single planets; - use less than 500 planets, and use some hidden ones to compensate the checksum (see below). Or, ignore all this and require your players to use 3rd-party front-ends. XYPLAN.HST is used (and updated) by the Wisseman host only. PHost only uses XYPLAN.DAT, and never modifies it. In contrast, the Wisseman host only uses XYPLAN.HST: the copy of XYPLAN.DAT created by MASTER. ## Maps with less than 500 planets In Explore Map games, planets which were not yet scanned usually have "impossible" coordinates (e.g., zero, or 9000 and greater). Considering all planets with either or both coordinates outside the range 1..8999 as non-existent seems to work well. This is also used on "static" maps with less than 500 planets. An add-on providing Explore Map features or things like moving planets can use these hidden planets to adjust the coordinate checksums: if the Y coordinate is zero, the X coordinate can be anything that fits your needs (...and the checksum). If a wraparound map (Sphere/PWrap) is used, PHost considers all planets outside the wrap rectangle non-existent. On a non-wrapped map, these planets are not strictly non-existing. Players with sufficiently much time can still reach them and colonize them. Hence it makes sense to put them *far* away (Y=9000), and distributed well (i.e. not all at in the same sector). FIXED DATA =========== These data files usually remain constant throughout a game: it's rather painful to change them in mid-game while avoiding Tim Continuum attacks. Both the host and the players must use exactly the same data set. Some of these files are some bytes longer than required. These bytes are not used and contain only parts of deleted files on Wisseman's hard disk. Tim's CONFIG.SYS was exactly 215 bytes large on 9/May/1992 at 9:03 pm. The ship specification files need to have fixed sizes checked for by PLANETS.EXE: BEAMSPEC.DAT 360 bytes ENGSPEC.DAT 598 bytes (4 bytes more than required) HULLSPEC.DAT 6300 bytes TORPSPEC.DAT 470 bytes (90 bytes more than required) PLANETS.EXE computes a checksum each time it is started to prevent using modified files. The sum of all bytes of these 4 files must be exactly 338817. Otherwise Planets refuses to run with the message "ERROR: Main data files have been tampered with." However, the 94 superfluous bytes should be enough to compensate changes. TRUEHULL.DAT is 940 bytes by default, of which only 440 are needed. BEAMSPEC.DAT - Beam weapons [V] -------------------------------- For each weapon (10) a record of 36 bytes: +0 20 BYTEs Name +20 WORD Cost (mc) +22 WORD Tritanium needed +24 WORD Duranium needed +26 WORD Molybdenum needed +28 WORD Mass +30 WORD Tech Level +32 WORD Kill value +34 WORD Damage value ENGSPEC.DAT - Engines [V] -------------------------- For each engine (9) a record of 66 bytes: +0 20 BYTEs Name +20 WORD Cost (mc) +22 WORD Tritanium needed +24 WORD Duranium needed +26 WORD Molybdenum needed +28 WORD Tech Level +30 9 DWORDs Fuel used to travel 1 month at the given speed, for each warp factor, for a 100000 kt ship Fuel used to travel d light years with a ship of m kt at speed v: d * m * X(v) d N = ------------ t = --- (approximated) v*v * 100000 v*v N is the fuel required, t the time required (E.T.A.) and X(v) is the value from the table above. When traveling longer than 1 month (t>1), the fuel usage is calculated again each month since the ship mass changes (less Neutronium aboard). See DISTTABL.DAT (under 3rd-party Clients) for how to correctly compute the d used in this formula. The engine fuel usage commonly plotted/tabulated equals X(v) / (v*v) and yields a value in the magnitude of 100 at an engine's nominal fuel usage (exactly 100 with the standard list), around 900 for the most inefficient speed (standard StarDrive 1 at Warp 9). Values of 120 or lower are generally considered efficient by automatic speed selection functions (PCC, VPA). After the engine records, 4 unused bytes follow. FRIDAY.DAT - SRace - Race Assignments -------------------------------------- This file contains 11 WORDs with the new race / player assignments. The first WORD contains the race number of the first player etc. HULLFUNC.DAT - PHost - Hull Functionalities [V] ------------------------------------------------ PHost generates this file from HULLFUNC.TXT, for use by other programs. PHost itself never reads this file. Your program, should it want to support this mechanism, can either read this file or manually parse HULLFUNC.TXT. For example, for older PCC, the `hullgen' utility converts HULLFUNC.TXT into HULLSPEC.CC (PCC started earlier than PHost 3). +0 DWORD Signature B1297F35h (that is, 4 bytes 35h, 7Fh, 29h, B1h) +4 BYTE PHost minor version +5 BYTE PHost major version +6 32 BYTEs Game name +38 DWORD Pointer to modified hull functions structure. Zero if none present. +42 DWORD Pointer to ship functions structure. Zero if none present. This field and the previous one were part of the following "reserved" field up to PHost 4.0k, and always zero. +46 8 BYTEs reserved --- Functions assigned to hulls --- +54 WORD Number of records following +56 n RECORDs Records of variable length +0 WORD Hull Number (1..105) +2 WORD Number of special functions assigned to this hull +4 n RECORDs of 4 bytes each +0 WORD Special function; see below. +2 WORD Player bitfield. Bits 1 to 11 mark players who can use this function. Bits 0 and 12..15 are undefined --- Modified hull functions (only if pointer at +38 is nonzero) --- +? WORD Number of modified hull functions +? WORD Size of each modified hull function record +? n RECORDs Records of variable length: +0 WORD Function Id. +2 WORD Basic function. See below for a list. +4 WORD Experience level mask (bit 0 = level 0 etc.) This is the same as UTILx.DAT record 57. New data may be appended to these records in the future. --- Functions assigned to ships (only if pointer at +42 is nonzero) --- +? WORD Number of records following +? n RECORDs Records of variable length +0 WORD Hull Number (1..105) +2 WORD Number of special functions +4 n RECORDs of 4 bytes each +0 WORD Special function +2 WORD Player bitfield This is the same format as the Functions assigned to Hulls section. It describes functions assigned to ships when they are built. --- Always --- +? n BYTEs Additional future data may follow here +? DWORD Signature 1F0C219Ah +? DWORD Checksum. This is the sum of all 2-byte words (interpreted as unsigned integers) in this file, excluding this DWORD. The "Special function" field in a hull record may either be a number from the following table, or a modified function (modified with a Level assignment in HULLFUNC.TXT). Note that the assignments of the modified functions can change each turn, and need not necessarily correspond to the assignment in UTILx.DAT (because the player uses a HULLFUNC.DAT from a turn other than the current). The Function Ids from a modified hull function are taken from the reserved range. The sections are always packed tightly together without gaps; the pointer is provided (instead of a simple binary flag) for programs to find it without having to parse the whole device assignments part. Possible future data may be added before the signature field. ## Special functions Value | Function | Code for HULLFUNC.TXT ======|===============================|============================== 0 | Merlin Alchemy | Alchemy 1 | Neutronic Refinery | Refinery 2 | Aries Alchemy | AdvancedRefinery 3 | Terraforming (Bohemian) | HeatsTo50 4 | Terraforming (Eros) | CoolsTo50 5 | Terraforming (Onyx) | HeatsTo100 6 | Hyperdrive | Hyperdrive 7 | Gravitonic Accelerators | Gravitonic 8 | Advanced Wormhole scanner | ScansAllWormholes 9 | Lady Royale | Gambling 10 | Loki | AntiCloak 11 | Super Star Destroyer | ImperialAssault 12 | Firecloud Chunnel | Chunneling 13 | Cobol Ramscoop | Ramscoop 14 | Bioscanner (Pawn) | FullBioscan 15 | Advanced Cloaking | AdvancedCloak 16 | Cloaking Device | Cloak 17 | Bioscanner (Brynhild/Cobol) | Bioscan 18 | Glory Device (Saber) | GloryDeviceLowDamage 19 | Glory Device (D19b) | GloryDeviceHighDamage -------'-------------------------------'------------------------------ PHost 4.0 and later: -------.-------------------------------.------------------------------ 20 | Unclonable | Unclonable 21 | Clonable only once | CloneOnce 22 | Cannot be given away | Ungiveable 23 | Can be given away once | GiveOnce 24 | Stronger Tractor Beam | Level2Tow -------'-------------------------------'------------------------------ PHost 4.0i and later: -------.-------------------------------.------------------------------ 25 | Tractor beam | Tow 26 | Can chunnel itself | ChunnelSelf 27 | Can chunnel other ships | ChunnelOthers 28 | Can act as a chunnel target | ChunnelTarget 29 | Immune to ATT / NUK | PlanetImmunity 30 | Increases ore density | OreCondenser 31 | Can board (tow-capture) | Boarding 32 | Immune to Lokis | AntiCloakImmunity 33 | Educates crew | Academy 34 | Can repair other ships | Repairs 35 | Fully armed even if damaged | FullWeaponry 36 | Full speed even if damaged | HardenedEngines -------'-------------------------------'------------------------------ PHost 4.0j and later: -------.-------------------------------.------------------------------ 37 | Combat experience bonus | Commander 38 | Not affected by ion storms | IonShield 39 | Can cloak even if damaged | HardenedCloak -------'-------------------------------'------------------------------ PHost 4.0k and later: -------.-------------------------------.------------------------------ 40 | Advanced Anti-Cloak function | AdvancedAntiCloak Values up to 999 are reserved for future use by PHost, values above 999 are available to add-ons. PHost 4.0i and later allows to define hull functions restricted to particular experience levels. Until 4.0l, however, these are not stored in HULLFUNC.DAT. HULLSPEC.DAT - Starship Hulls [V] ---------------------------------- For each hull (105) a record of 60 bytes: +0 30 BYTEs Name +30 WORD Number of picture in RESOURCE.PLN Some pictures are used more than once, but with a different palette (e.g., Super Transport Freighter + Merlin Class Alchemy Ship + Neutronic Refinery Ship). I don't know where this information comes from, it seems to be hard-coded in PLANETS.EXE. Winplan automatically uses different pictures for hull numbers 104 and 105 (see below). +32 WORD =1. In VPCPLAY.BAS this field is identified as "image of a heavily damaged ship", though it seems to be unused. +34 WORD Tritanium needed +36 WORD Duranium needed +38 WORD Molybdenum needed +40 WORD Fuel tank size +42 WORD Crew size +44 WORD Number of engines +46 WORD Hull mass (empty) +48 WORD Tech Level +50 WORD Cargo room +52 WORD Number of fighter bays +54 WORD max. Number of torpedo launchers +56 WORD max. Number of beam weapons +58 WORD Cost (mc) A "hull number" is the number of the record in this file, where the first record is hull number 1. Information whether a hull has a cloaking device is hard-coded in PLANETS.EXE / SHIPS.EXE / HOST.EXE. The following hulls always have a cloaking device: 21 22 25 26 27 28 29 31 32 33 36 38 43 44 45 46 47. Information on Gravitonic Accelerators and other "bells and whistles" is also hard-coded and can't be changed in custom ship lists for THost. For PHost, see HULLFUNC.DAT and the PHost documentation about SHIPLIST.TXT / HULLFUNC.TXT. The number of possible starship hulls needs to be 105 or less, although the game concept would allow up to 220 different hulls (20 slots for each of the 11 players). The host simply refuses to build ships with a higher hull number, and the PHost PDK also hardwires the maximum hull Id to 105. Winplan automatically "corrects" this information (though not the disk file): hull 65 gets the name "TOPAZ CLASS GUNBOAT", hull 88 becomes a "GUARDIAN CLASS DESTROYER". Hull 104 (Neutronic refinery) is assigned picture 152, hull 105 (Merlin) gets picture 153. This removes typos in the original ship list, and ensures that the alchemy ships look different from the normal Super Transport Freighter -- but it can lead to confusion if an alternate ship list is used where slot 65 has nothing to do at all with `Topaz'. In addition, it does not correct the pictures of ships on the VCR and the ship build screen. For ship list designers, it may sound tempting to set the picture numbers for Merlin / NRS to 153/152 directly so that the ships look the same everywhere in Winplan. I do not recommend that; although this will work with Winplan, PCC and VPA, it will crash PLANETS.EXE and older PVCRs. LANG.PLN - Host Language [V] ----------------------------- This file contains texts used in screen messages and messages sent to players from the Host. The file is required by THost 3.22.012 and later. The current version contains 990 records but not all of them are actually used. Probably the file size will change in the future. +0 100 BYTEs unused +100 990 RECORDs of 6 bytes each, describe the strings. This field is indexed from 1 onwards: +0 DWORD location of string in file, as usual "+1" +4 WORD Length of string +6000 n BYTEs the strings (raw data, no space padding here). The strings are not encrypted. Tim Wisseman supplies a program with source code to create/modify this file (PCKLANG1.BAS). The strings may contain carriage returns. Some use 0Dh 0Ah as line feed character (screen messages), others use a single 0Dh (subspace messages). MISSION.INI - Winplan - Missions --------------------------------- This text file contains definitions for the "extended" missions that may be accessed via the M.I.T. window in Winplan. Each line of the file has the following format: 000 Name (I:IntArg T:TowArg)*#/123456789ab 000 is the mission number in ASCII, exactly the first 3 columns of each line are evaluated. Name is the mission name shown in the selection lists. IntArg name of Intercept parameter. TowArg name of Tow parameter. * if specified, the mission requires an Intercept parameter. # if specified, the mission requires a Tow parameter. /123 if specified, the races that can use this mission. Default is that all can use it. The text in parentheses "(I:IntArg T:TowArg)" is syntactically part of the name, and therefore completely optional. Various clients, starting with VPA, use it to name the mission parameters. However, the need for parameters is solely defined by the "*" and "#" flags. PLANET.NM - Planet names ------------------------- For each of the 500 planets a space-padded 20 character string. PLANGxx.HST - PHost - Language Data ------------------------------------ This describes the format of PLANG.HST / PLANG4.HST of PHost version 4.1 and 3.5 upwards. Previous versions use an encrypted file format not documented here. PLANGxx.HST is a container file using the "ar" file format. +0 8 BYTEs Signature, "!",10 +8 n RECORDs of variable length, containing the individual languages: +0 16 BYTEs File name. Terminated with a '/' character or, if none, with a ' '. For PLANGxx.HST, this always has the form "NAME.phl", where "NAME" is the name of the language, in lower case, truncated to 8 characters. +16 12 BYTEs File time, seconds since epoch, decimal. +28 6 BYTEs User Id, decimal. +34 6 BYTEs Group Id, decimal. +40 8 BYTEs File mode (permissions), octal. +48 10 BYTEs File size, decimal. +58 2 BYTEs Signature, "`",10 +60 n BYTEs File data +? 1 BYTE Padding. Only present if file size is odd, to align next record to even position. The numeric fields are formatted into ASCII numbers using the specified base, and stored left-justified, space-padded. PHost ignores all but the file size field, thus the others are not filled in in the file distributed with PHost. ## Format of individual Languages Each language file, "NAME.phl", consists of a sequence of strings delimited by null characters (ASCII 0). The first string in each file contains control information in the form of a sequence of assignments: VERSION=4,LANGUAGE=German,STRINGS=438 - "VERSION=4" marks this as a file for PHost 4.x - "LANGUAGE=German" contains the spelled-out language name - "STRINGS=438" contains the number of strings that follow PHost addresses strings by index, i.e. the fifth string in german.phl is the translation of the fifth string in english.phl. In order to save space, if a string in a language other than English is empty, PHost uses the English string instead. PLNHELP.DAT - Help texts ------------------------- +0 600 BYTEs 100 Records of 6 bytes each +0 DWORD Address of text in this file + 1 +4 WORD Length of text in bytes +600 y BYTEs Help texts This file has a similar structure as the message file (MDATAx.DAT). Only the "Count" field is missing, there are exactly 100 records. The texts are encrypted like the messages: Each ASCII code is increased by 13. Line ends are encoded as CR+LF (0Dh 0Ah, encrypted as 1Ah 17h). Unused help texts contain the text "RESERVED ... nn". RACE.NM - Race names --------------------- +0 330 BYTEs Long form of 11 names (30 chars): "The Robotic Empire" +330 220 BYTEs Short form of 11 names (20 chars): "The Robots" +550 132 BYTEs Adjective of 11 names (12 chars): "Robotic" Umlauts and other characters with a code >= 80h can be entered into RACE.NM using the NAMERACE program, but the Host replaces these characters with spaces in its Log files and messages. PLANETS.EXE simply omits these characters in most displays (there are no glyphs for these characters). REG.KEY - Winplan - Registration Key ------------------------------------- (Read-only Information. I could give more information, but I don't want that every wannabe is able to fake his own reg-key...). Don't touch the other bytes. +0 50 BYTEs Name of user +50 50 BYTEs Address of user These values are entered when registered Winplan is run first after registering. Both are encrypted by adding 13 to the ASCII codes. +150 DWORD Signature - 13: key is valid - 666771: key is valid, but must be unlocked by filling in the form displayed when Winplan is run (above fields are invalid in this case). RESOURCE.PLN - Pictures ------------------------ RESOURCE.PLN is the picture data file for DOS Planets. It is also used by various other programs, including VPA and PVCR. This section also describes Winplan's use of pictures, which is structurally similar. File format information mostly by Frank Hempel. RESOURCE.PLN contains 151 images numbered from 1 to 151 (important if another file such as HULLSPEC.DAT references an image). Every picture consists of a 5537 byte record built up as follows: +0 WORD Width of image, always 105 +2 WORD Height of image, always 93 +4 n BYTEs For each scanline 4 byte sequences. Each of the four byte sequences is ((Width+7) DIV 8) bytes long, in this case 4x14 bytes. The first sequence contains information for color plane 0, bit 7 is the left-most pixel. Then the color planes 1 to 3 follow. This matches the organization of VGA video memory (the BASIC commands PUT and GET normally work with memory dumps, like here). +x n BYTEs unused +5300 15 WORDs Color palette. 5 records of 3 words: +0 WORD Red (0..63) +2 WORD Blue (0..63) +4 WORD Green (0..63) See also note below. +x n BYTEs unused. Non-existent for the last picture (#151). Winplan doesn't use RESOURCE.PLN, the images are stored as single Bitmap files, as WINPLAN\BMP\VPLxx.BMP, xx is a 1- to 3-digit bitmap number. That is, the first RESOURCE.PLN picture corresponds to VPL1.BMP. There are 262 images following this scheme, most are new planet pictures. See also WPVCR.DLL. Additionally, there are the WINPLAN\BMP\VPAUXxxx.bmp files. These are used when reading messages from 3rd-party programs, see MDATAx.DAT. The BMP files have no color restrictions; palette allocation and recoloring is left to Windows' built-in API functions. ## Notes on the Color Palette Planets uses the 16 color mode of the VGA card. From these 16 colors, 11 are fixed: Color | Red Green Blue | =========|=======================|============= 0 | 0 0 0 | Black 6 | 37 18 3 | Red 7 | 42 42 42 | Light gray 8 | 20 19 22 | Dark gray 1 9 | 0 0 62 | Light blue 10 | 12 55 12 | Light green 11 | 17 17 17 | Dark gray 2 12 | 58 0 0 | Light red 13 | 11 11 11 | Dark gray 3 14 | 60 59 0 | Yellow 15 | 57 57 57 | White Colors 1 to 5 are defined by each image. In some pictures, PLANETS.EXE shuffles the color components. | Hull | Color | Transform. ========================|=======|=======|============= Image 33 | | | Super Transp. Fr. | 18 | brown | none Neutronic Ref. | 104 | green | R/G Merlin | 105 | blue | R/B ------------------------|-------|-------|------------- Image 47 | | | T-Rex | 23 | brown | none Madonnzila | 49 | green | R/G R/G means Red and Green component are exchanged, R/B means Red and Blue component are exchanged. This transformation is hardwired in PLANETS.EXE and depends on the hull number only. In the standard ship list, some other pairs of hulls share a picture, too, but for those, no tricks are played to the palette. For planets, PLANETS.EXE also uses the palette to change the images. Desert planets appear in sand colors while arctic planets appear cold as ice. In pictures for factories, defense and mines the ground has the same color as the planet so that the buildings always stay on a different ground. See also the section on planets below. Some images may not use the special colors 1 to 5: - 8 (scanner), always combined with a ship image - 21, 48, 52, 71, 83, 93, 94, 115, 126, 138, 151 (Logo), always combined with a race member (main menu) or ship image (build screen) Images of ships or planets may not use colors 6 to 10. In VCR, where 2 ships appear side by side, colors 1 to 5 of one ship are translated into colors 6 to 10, since a ship always needs the special colors. PLANETS.EXE doesn't do such translations, so that it needs to hide the planet picture by putting the scanner image (pic. 8) on it each time you request a visual scan from the planet or base screen. ## Assignment of the images All pictures not listed in the tables below are starship or planet images, see also HULLSPEC.DAT. Race | Logo | Person | Fighter ===============|========|========|========= 1 (Feds) | 21 | 22 | 34 2 (Lizard) | 48 | 44 | 81 3 (Bird Men) | 52 | 53 | 82 4 (Fascist) | 71 | 70 | 82 5 (Privateer) | 83 | 75 | 80 6 (Cyborg) | 93 | 91 | 92 7 (Crystal) | 94 | 95 | 96 8 (Empire) | 115 | 116 | 111 9 (Robot) | 126 | 127 | 125 10 (Rebel) | 138 | 139 | 130 11 (Colony) | 151 | 150 | 145 Pic. | Meaning ======|========================== 8 | Scanner Screen 23 | Starbase 30 | unused ship picture (*) 35 | Defense Post 36 | Factory 37 | Mine 38 | Planet for Mining Survey 51 | Explosion (VCR) 43 | unused planet picture A note on picture 30: This image is not used in HULLSPEC.DAT. Anyway, VCR uses it sometimes, see VCRx.DAT. ## Planet pictures To display a planet picture, the temperature and Id number are needed: INDEX := ( Temperature_Value + Id_Number ) MOD 13 The Temperature_Value is the value stored in the planet record, not the Fahrenheit temperature. Each of the Index values maps to one planet picture: INDEX | Planet Picture(s) =======|=================== 0 | 1 1..4 | 39 .. 42 5..7 | 2 .. 4 8..12 | 24 .. 28 The palette (special colors 1-5) are computed separately to reflect the planet's temperature. This special palette is also used to make the planetary buildings appear to stand on different ground depending on the climate. Winplan uses a different formula: INDEX := Id_Number MOD 95 The index maps into a table of planet pictures: INDEX | Planet Picture(s) =======|=================== 0 | 1 1..4 | 39 .. 42 5..7 | 2 .. 4 8..11 | 24 .. 27 12 | 43 13..62 | 155 .. 204 63..94 | 213 .. 244 Winplan does not modify the color palette, it displays the BMP files unchanged (they actually need not even be palette-based images). SCRAM21.OLE - Winplan - Registration Protection ------------------------------------------------ (Read-only Information. I could give more information, but I don't want that every wannabe is able to fake his own reg-key. Tim might not like this...) +178 311 DWORDs VPH Array, Part A +3710 311 DWORDs VPH Array, Part B Only these both fields are important, SCRAM21.OLE doesn't contain information that couldn't be retrieved from other files. An important thing is that each SCRAM21.OLE needs to correspond with its REG.KEY, they are not interchangeable. Both values are required for MAKETURN. Index into the array is the current turn number, decremented by 311 until the result is a value in the range 1..311. `(VPH-ArrayA[X] XOR VPH-ArrayB[X])' gives the record `VPH_Record(X)'. Both values from this file are written to the TRN file, but are not necessarily identical to those of VPH35.DLL. Only the XOR result needs to be the same. STORM.NM - Names for Ion storms -------------------------------- For each possible Ion storm (50 = Ids 1 to 50) 20 characters. Ion storms of the classes 1-3 (Ion Disturbances) get an Id number only. Strong Ion Storms get a name corresponding with the Id number. TECH.MOF - Font ---------------- TECH.MOF contains 96 characters, the ASCII codes 33 (21h) to 128 (80h). These character have a constant height of 16 and are 0 to 16 pixels wide. Each character is encoded as 16 WORDs, from top to bottom. Each of those has one bit set if the corresponding pixel is set. The least significant bit corresponds to the left-most pixel. The width of each character is defined by the right-most pixel. That's why the space character can't be encoded in this format and is handled separately. The characters 64 and 125 to 128 differ from Standard ASCII: Code | ASCII | TECH.MOF =======|=======|=================== 64 | @ | not displayable 125 | } | Left arrow 126 | ~ | Up arrow 127 | DEL | Right arrow 128 | C, | Down arrow TORPSPEC.DAT - Torpedoes [V] ----------------------------- For each torpedo launcher (10) a record of 38 bytes: +0 20 BYTEs Name +20 WORD Cost (mc for a Torpedo) +22 WORD Cost (mc for a Launcher) +24 WORD Tritanium needed for Launcher +26 WORD Duranium needed for Launcher +28 WORD Molybdenum needed for Launcher +30 WORD Mass of Launcher +32 WORD Tech Level +34 WORD Kill Value +36 WORD Damage Value Torpedoes always need 1 kt of each mineral to build and have a mass of 1 kt. The torpedo records are followed by 90 unused bytes. The Plangineer appears to write more dummy bytes than that. TRUEHULL.DAT - Assignment Player <-> Starship Hulls TRUEHOST.DAT - SRace - Original TRUEHULL.DAT ---------------------------------------------------- For each player (11) an array with 20 WORDs. Each WORD contains the number of a hull that the player can build (Index into HULLSPEC.DAT). These 20 "hull slots" correspond to the appropriate field in the starbase record. When a race can build fewer than 20 ship types, the last fields should be zero; there should not be zeroes between filled ship slots. Although Planets and Winplan can cope with that, most other client programs can not (tested with VPA, PCC and VPUtil). SRace makes a new TRUEHULL.DAT reflecting the changed situation. In a game with, say, 11 Federations, TRUEHULL.DAT contains eleven equal records with 20 WORDs each. This file is used by client programs. The SRace host uses TRUEHOST.DAT which is identical to the original TRUEHULL.DAT. PHost allows to choose an interpretation. Depending upon the MapTrueHullByRace setting, it expects an "SRace type TrueHull" (player 1 uses record 1) or a "normal" one (if player 1 plays Lizards, he uses record 2). VPH35.DLL - Version 3.5 Signatures ----------------------------------- +0 343 BYTEs Useless bytes that try to fake a DLL. +343 311 DWORDs Array 1 +1587 266 BYTEs useless +1853 311 DWORDs Array 2 +3097 n BYTEs useless Record VPH_Record(N) of VPH35.DLL is ( Array1[N] XOR Array2[N] ) AND 7FFFFFFFh N runs from 1 to 311. For larger values, counting starts at the beginning, that is 312 => 1, 313 => 2 etc. The values in the file seem to be random numbers. While the Task Manager from Windows 3.1, a 4 kB file, can be compressed by 55% using PKZIP, this file which is 5 kB and should offer more redundant data, can only be compressed to save 1%. THost will not run if it receives a Winplan TRN but can't open this file. WPVCR.DLL - Winplan - Images for the Winplan VCR [T] ----------------------------------------------------- Another faked DLL. The file contains the monochrome counterparts for the ship images in the Bitmap files. There are ships flying to the left and ships flying to the right. These are used in the VCR. --- Ships flying to the right --- +0 160 DWORDs Addresses of images in the file, as usual + 1. Some images are unused and contain address 0. +640 9 BYTEs unused +649 160 WORDs Sizes of these images +969 31 BYTEs unused --- Ships flying to the left --- +1000 the same 4 fields again. --- Images --- +1999 Here are the pictures addressed by the fields above. They are all complete 50x50 monochrome bitmap files. To display a picture, Winplan copies the image to TEMP.BMP and displays that file. It is a real BMP file that can be edited with Paintbrush. XYPLAN.DAT - Planet Coordinates -------------------------------- See in the Host Data section. ALL CHECKSUMS AT A GLANCE ========================== CONTRLx.DAT CONTROL.DAT ------------ +0 500 DWORDs Checksums for ships +2000 -"- Checksums for planets +4000 -"- Checksums for bases +6000 WORD 0 --- Host999 Games --- +8000 499 DWORDs Checksums of ships 501..999 FIZZ.BIN --------- +0 33 BYTEs 11 records of 12 bytes for each race, undefined if no data for that race. +0 DWORD Ship checksum = GENx.DAT value + 667 +4 DWORD Planet checksum = GENx.DAT value + 1667 +8 DWORD Base checksum = GENx.DAT value + 1262 +132 DWORD ? +136 51 DWORDs Registration signature GENx.DAT --------- +0 18 BYTEs Timestamp (10 bytes date mm-dd-yyyy, 8 bytes time hh:mm:ss) +18 88 BYTEs 11 score records of 8 bytes each +106 WORD Player Id +108 20 BYTEs Password (defines signatures 1 and 2) +128 BYTE 0 +129 DWORD Checksum of SHIPx.DAT/DIS +133 DWORD Checksum of PDATAx.DAT/DIS +137 DWORD Checksum of BDATAx.DAT/DIS +141 WORD 13 if the password has changed, 0 otherwise +143 10 BYTEs New password (if any) +153 WORD Turn Number +155 WORD Timestamp Sum TEMPLOCK.DAT ------------- 11 DWORDs with TRN file checksums, or 0 if no TRN file. This file is only used during a MAKETURN run, you need not write it. Static files ------------- The sum of all X coordinates of all planets in XYPLAN.DAT gives 998681. Maybe there is a Y checksum which must be 1002633. The sum of all bytes of BEAMSPEC.DAT, ENGSPEC.DAT, HULLSPEC.DAT and TORPSPEC.DAT gives 338817, where the listed files need to have exact sizes. Not all bytes are used for actual data storage, but are still part of the checksum. Ship list compilers like Penguin or peng use this to make files compliant with the checksum. File | Size | Size Used ===================|=========|=============== BEAMSPEC.DAT | 360 | 360 = 36*10 ENGSPEC.DAT | 598 | 594 = 66*9 HULLSPEC.DAT | 6300 | 6300 = 60*105 TORPSPEC.DAT | 470 | 380 = 38*10 PHost generates 32-bit digests for these files, using only the "Used" part of the files. See under UTILx.DAT for a description. Other Files ------------ The files SNOOKER.DAT, SCRAM21.OLE and VPH35.DLL may need to be read or changed, since they contain more protection functions. The TRN and RST files also contain checksums. DATA OF 3rd PARTY PROGRAMS - CLIENT SIDE ========================================= A Pascal string is a byte giving the length of the string, and this many bytes following which contain the string itself. A fixed-size Pascal string is the same, but followed by some undefined bytes to pad the whole thing to a fixed size: "Hello" as Pascal string: 05 48 65 6C 6C 6F with fixed length 10: 05 48 65 6C 6C 6F xx xx xx xx xx (xx = undefined values) The description of the `.cc' files is the definition of these: this file is my personal reference for PCC. AFSIM.SAV - AFSim - Saved simulation setup [T] ----------------------------------------------- This file contains a battle simulation saved in AFSim. Informer (a utility by the same author) can pass "real" situation in this format to AFSim. +0 WORD Number of ships in the simulation +2 50 RECORDs of 54 bytes: ships in the battle +0 BYTE 3 (Length of FCode) +1 3 BYTEs FCode of ship +4 WORD ? (1000, for empty records 2000) +6 WORD Shields +8 WORD Engine (1..9) +10 WORD Hull (1..105) +12 20 BYTEs Name, a BASIC String. The name is assigned by AFSim if the ship data is changed. When exporting the battle from Informer, a "real" ship name is stored here. +32 WORD Damage % +34 WORD Crew +36 WORD Id (for empty records 1500) +38 WORD Owner (1..11, for empty records 15) +40 WORD Number of image in RESOURCE.PLN +42 WORD Beam Type (1..10) +44 WORD Beam Count +46 WORD Number of fighter bays +48 WORD Torpedo Type +50 WORD Number of Torpedoes/Fighters +52 WORD Number of Torpedo launchers +2702 BYTE 3 (Length of FCode) +2703 3 BYTEs FCode of planet, if playing +2706 WORD Planet owner or 0 +2708 WORD Defense on planet +2710 WORD Starbase beam tech or 0 +2712 WORD Number of starbase fighters +2714 WORD Defense on starbase Unused ship records are filled with FFh, except for the fields at offset 4, 36 and 38. If there is neither a planet, nor a starbase playing, the last 14 bytes are 0. .CCB - PCC, CCBSim - Battle simulations [V] -------------------------------------------- There are multiple versions of this file format. Format Version | Signature | PCC Version | Bytes per Record ================|==============|==================|================== 0 | "CCsim",26 | 0.99.10 | 51 1 | "CCbsim0",26 | 1.0 | 53 2 | "CCbsim1",26 | 1.0.7 | 53 3 | "CCbsim2",26 | 1.0.16 1.99.2 | 57 4 | "CCbsim3",26 | 1.1.11.6 1.99.2 | 65 5 | "CCbsim4",26 | 1.99.22 | 67 All PCC/CCBSim versions can read all older format versions. Program versions 1.1.11.6/1.99.2 write version 3 if needed, higher versions only when required. Earlier versions always write their own version. After the initial 6- or 8-byte magic string and the count indicator word, the file always consists of records of the same fixed size as given in the above table. If one record requires use of a special format feature, all records are written with that variant. +0 n BYTEs Signature. 6 or 8 bytes, see above +n WORD Bit 0..14 Number of ships Bit 15 Set if a planet is participating +? n BYTEs Records of 51..67 bytes each, one for each ship. +0 42 BYTEs VCR object record for this ship. The picture / hull type field is not initialized. +42 WORD Engine Type (1..9) +44 WORD Hull Type (1..105) (Format Version 3): 0 means a "custom ship" (no corresponding HULLSPEC entry) +46 WORD Shield status (0..100) +48 3 BYTEs Friendly Code --- Format version 1 and higher --- +51 WORD Aggressiveness 0 passive 1..12 Primary Enemy 13 no fuel -1 Kill --- Format version 3 and higher --- +53 WORD Mass (used when the hull type is zero) +55 WORD Flags bit 0 "Random FC" enabled bits 1..3 (1.0.17+) randomize these chars of FC only bit 4 (1.1.11.6+) rating override should be used, implies use of format version 4 or higher bit 5 (1.1.13+) ship is cloaked bit 6 (1.1.13+) ship is deactivated bits 7..8 (1.1.17+) PlanetImmunity bits 9..10 (1.1.17+) FullWeaponry bits 11..12 (1.1.17+) Commander Ship function flags (bits 7..12) can have the following values for each function: 0x Use default assignment 10 Ship does not have device 11 Ship has device --- Format version 4 and higher --- +57 DWORD FLAK Targeting rating +61 WORD FLAK Compensation rating These two fields are evaluated only if flag bit 4 is set. +63 WORD (1.99+) Intercept Target, for intercept-attack. This field is reserved and must be zero in earlier versions. --- Format version 5 and higher --- +65 WORD Additional flags bits 0..1 Triple Beam Kill Ability bits 2..3 Double Beam Charge Ability bits 4..5 Double Torp Charge Ability bits 6..7 Elusive Ability bits 8..9 Squadron Ability The interpretation of the Ability bit pairs is the same as for the ship functions in the first Flags field. --- only if planet participates --- +? n BYTEs Planet record (51..67 bytes): +0 10 WORDs (Format version 2 and higher) Torpedoes on starbase. Unused in earlier versions. +20 2 WORDs (unused) +24 WORD Id +26 WORD Owner +28 WORD (unused) +30 WORD Beam Tech Level on starbase (1..10, 0=no starbase) +32 WORD (unused) +34 WORD Number of fighters on starbase +36 WORD (unused) +38 WORD (Format versions 0 and 1) Number of torpedoes on starbase, corresponding to the torpedo type below. Unused in later versions. +40 WORD Torpedo Tech Level on starbase (1..10, 0=Tech 1). Only used in PHost mode with PlanetsHaveTorps option enabled. +42 WORD Starbase defense posts +44 WORD Planetary defense posts +46 WORD (unused) +48 3 BYTEs Friendly Code --- Format version 1 and higher --- +51 WORD (unused) --- Format version 3 and higher --- +53 WORD (unused) +55 WORD Flags (unused, must be zero) --- Format version 4 and higher --- +57 DWORD FLAK Targeting rating +61 WORD FLAK Compensation rating +63 WORD reserved, 0 --- Format version 5 and higher --- +65 WORD reserved, 0 Unused fields should be zero. Planets in a simulation currently are a horrible hack. Owner fields may be 12, for a totally "unspecial" race (Alien Marauders). Note that PCC 1.0.11 and higher permit to generate ships with Id numbers greater than 500. The maximum number of ships in a simulation is 100 in PCC 1.0.9 and earlier, and 200 in later versions. CC.RES - PCC - Resources [V] ----------------------------- With this section I want to prevent that anyone tries to completely analyze my resource file... +0 2 BYTEs Signature "RZ" +2 DWORD File offset of resource directory +6 WORD Number of entries in file ## Resource Directory The RD contains a record for each entry of the file: +0 WORD Id Number +2 DWORD Location of entry in resource file +6 DWORD Size of entry in bytes It is allowed to have multiple directory entry pointing to the same data, and there is no requirement that the entries be sorted in any way. ## The entries The entries in the file are identified by their Id number and are copies of other files that can have many different formats: - pictures - fonts (see .FNT) - help texts - and the default specification files - some other files, intentionally undocumented, change without notice There are (almost) no type tags. When PCC finds a wrong type somewhere, it will likely crash. Some entries are compressed, some not. ## Compression PCC uses a simple RLE compression. Each compressed file starts with a DWORD specifying the length of the decompressed data. Then, the compressed file follows, split into chunks of the following format: +0 WORD Uncompressed length of the following chunk +2 BYTE Value used as prefix code in this chunk +3 n BYTEs Compressed data. Either single bytes, or runs encoded as `pp nn dd', where `pp' is the prefix byte: this means, `repeat byte `dd' `nn' times'. The prefix byte may differ from chunk to chunk, however, most files only have one chunk. After the last chunk, a WORD with the value 0 must (!) follow. ## Pictures Pictures are stored in 3 formats; some are compressed using the above RLE scheme, some aren't. Here the description of the decompressed files. PCC will crash if it gets a compressed picture where it expects an uncompressed one, or vice versa, or a picture in the wrong format. RGB values range from 0 to 63. Not all pictures are allowed to use their private colors (for example, the three structures which are shown simultaneously on the Build screen must share one palette). Format 1 (16 colors, always compressed): +0 2 BYTEs Signature "CC" +2 WORD Width +4 WORD Height +6 15 BYTEs Palette. 5 RGB triplets for color slots 10 to 14. Colors 1 to 9 and 15 are fixed, see CHARTx.CC. +21 n BYTEs Bitmap data, from top to bottom, left to right. Two pixels per byte, the left pixel is in the lower nibble. If the width is odd, one half byte is wasted per line. Interesting pictures of this type are Id | Meaning ================|================================ 201 .. 211 | Race persons 1001 .. 1153 | Starships, corresponding to | RESOURCE.PLN entries 1 to 149, | plus alchemy ships 4001 .. 4011 | Fighters 4601 .. 4610 | Torpedo blueprints 4701 .. 4710 | Torpedo launcher blueprints 4801 .. 4810 | Beam weapon blueprints Format 2 (256 colors, always compressed): +0 2 BYTEs Signature "CD" +2 WORD Width +4 WORD Height +6 192 BYTEs Palette. 96 RGB triplets for color slots 192 to 255. +198 n BYTEs Bitmap data, from top to bottom, left to right. A 256-color picture Id (X) is automatically used as a replacement for 16-color picture (X - 20000). Format 3 (sometimes compressed): +0 WORD 0800h (Signature) +2 WORD Width +4 WORD Height +6 n BYTEs Bitmap data, from top to bottom, left to right. Usually, the value 255 means a transparent pixel. ## Help Texts Help texts can be found at Ids 10000 to 19999 (help page Ids). They are normal ASCII texts with special control characters: 1 (Ctrl-A) Followed by 2 ASCII characters: anchor (supported by PCC 1.0.6.1 and later) 2 (Ctrl-B) At beginning of line, underlines (use only for page headings); 3 (Ctrl-C) At beginning of line, centers the line; 5 (Ctrl-E) Hide everything till end of line in graphics mode, print it in text mode (used for ASCII replacement of graphics in MAKEGLOS.EXE); 7 (Ctrl-G) Followed by 6 ASCII digits. Graphics: the first digit specifies the segment of the image, the following five specify the image Id; 10 (Ctrl-J) Linefeed; 11 (Ctrl-K) Quote next character. Prevents special meanings of next character, in particular, prevent that a name in brackets is turned into a key-cap; 16 (Ctrl-P) End of hyperlink; 17 (Ctrl-Q) Begin of hyperlink. Followed by 5 ASCII digits (reference target). Hyperlinks can't contain linefeeds. PCC 1.0.6.1 and later supports an additional format where two ASCII characters and a colon precede the 5 ASCII digits, which automatically jumps to the named anchor (^Qab:10000Main^P = jump to anchor "ab" on page 10000); 20 (Ctrl-T) Followed by an ASCII digit. Tabulator: ^T0 moves to 40 pixels from the left, ^T1 to 80 pixels, and so on; Some printing characters give different symbols in PCC than on a standard codepage 437 text screen, see the .FNT font file format. CHARTx.CC - PCC - Starchart entries [V] ---------------------------------------- This file contains information on various things that are on the player's starcharts and are archived over a few turns. ## New Format [PCC 1.0.8+] The new starcharts file format is designed to be extensible, and to be parsable by a program which does not fully understand it. So it is divided into chunks, somewhat like UTILx.DAT. Header: +0 8 BYTEs Signature, "CCchart",26 +8 WORD Turn number +10 WORD Start of first data block (file offset, 0-based) +12 WORD Number of extra planet properties +14 WORD Number of extra starship properties +n n BYTEs Names of extra planet properties +n n BYTEs Names of extra ship properties By default, there is a planet property `COMMENT' and a ship property `COMMENT' declared. Users may declare more properties. Blocks: +0 WORD Type 1 Planet History (one per planet) 2 Ship History (one per ship) 3 Ship Track (one per ship; but see below) 4 Mine Field (may be many) 5 Painting (may be many) 6 Auto Build (one) 7 Ship Property (one per ship) 8 Planet Property (one per planet) --- PCC 1.1.6+: --- 9 Ship Score (one per score; but see below) 10 Planet Score (one per score; but see below) 11 Painting Tag Info (see below) --- PCC 1.1.7+: --- 12 Ufo History (one per Ufo) +2 DWORD Size +6 n BYTEs data After CCMERGE is used, several of the records given here might appear multiple times even if the above says the converse: + Ship Track + Ship Score + Planet Score PCC will merge them when it loads the starchart file. PCC2 supports CHARTx.CC as well, starting with version 1.99.3. + 1.99.3: types 1, 4, 5, 6, 11 + 1.99.4 and later: types 1 .. 12 --- Type 1: Planet History (mostly a standard PDATAx.DAT record) --- +0 WORD (b) Owner +2 WORD Id [*] +4 3 BYTEs FCode +7 3 WORDs (b) Mine / factory / defense count If only industry level known ("light" etc.), the factory count is 30000+n (n = PHost industry level 0..5) +13 4 DWORDs (a) Mined N/T/D/M +29 DWORD (b) Clans +33 DWORD (d) Supplies +37 DWORD (d) mc +41 4 DWORDs (a) Ground N/T/D/M +57 4 WORDs (a) Density N/T/D/M +65 2 WORDs colonist / native tax +69 2 WORDs colonist / native happiness +73 WORD (c) native government +75 DWORD (c) Natives +79 WORD (c) Native race +81 WORD Temperature (-1 unknown) +83 WORD Starbase present? (0 or 1) +85 4 WORDs Timestamps: (a) = minerals, (b) = colonists, (c) = Natives, (d) = mc/sup --- PCC2 --- +93 BYTE Known-to-have-natives flag --- Type 2: Ship History --- +0 WORD Id [*] +2 WORD Player id [*] +4 3 BYTEs (b) FCode +7 WORD Speed +9 2 WORDs (b) WaypointDX/DY +13 2 WORDs X/Y +17 WORD (b) Engine +19 WORD Hull +21 2 WORDs (a) Beam, Beam count +25 WORD (a) Bay count +27 WORD (a) Launcher type +29 WORD (a) T/F +31 WORD (a) Launcher count +33 WORD (b) Mission +35 WORD (b) PE +37 WORD (b) Tow id +39 WORD (a) Damage +41 WORD (a) Crew +43 WORD (b) Clans +45 20 BYTEs Name +65 4 WORD (b) N, T, D, M +73 WORD (b) Supplies +75 7 WORDs (b) Unload +89 7 WORDs (b) Transfer +103 WORD (b) Intercept id +105 WORD (b) Money +107 2 WORDs Timestamps: (a) weaponry/combat, (b) rest --- Type 3: Ship Track --- +0 WORD Id +2 WORD Ref. Turn (=turn number of first record) +4 n BYTEs Records of 9 bytes each, newest turn first +0 2 WORDs X, Y +4 BYTE Speed +5 WORD Heading +7 WORD Mass --- Type 4: Mine Field --- +0 n BYTEs Records of 16 bytes each. The number of such records is determined by the size of the whole block. There may be any number of Mine Field blocks, each containing several mine fields. +0 WORD Id +2 WORD X +4 WORD Y +6 WORD Owner +8 DWORD Number of mine units +12 WORD Type 0 Normal Mines 1 Web Mines +14 WORD Turn of last information about this field --- Type 5: Painting --- +0 n BYTEs Records of variable size. The number of records is determined by the size of the whole block. There may be any number of Painting blocks, each containing several elements. +0 BYTE Type of element 0 Line 1 Rectangle 2 Circle 3 Marker Bit 7 1 if comment present +1 BYTE Color +2 WORD X1 +4 WORD Y1 +6 WORD Line, Rectangle: X2 Circles: radius Markers: Type 0 "+" (plus) 1 "!" (exclamation mark) 2 "x" (cross) 3 "<>" (diamond) 4 "p" (flag) 5 (down-up `lock' arrows) 6 "><" (right-left `lock' arrows) 7 [PCC 1.1.11+] (cactus) +8 WORD Line, Rectangle: Y2 others: zero +10 WORD Tag (non-negative for user-defined markers) +12 WORD Turn of expiry (-1=never). If this field is, for example, 17, the marker will be deleted at turn 18. +14 n BYTEs Comment (Pascal string), only if bit 7 in type set. Used only for markers. --- Type 6: Auto Build --- +? & BYTEs 500 Records of 12 BYTEs each +0 WORD Number of Mines +2 WORD Number of Factories +4 WORD Number of Defense Posts +6 WORD Number of SB Defense 0..999 specify the wanted amount, 1000 means "max". +8 BYTE Speed for Mines (1..100) +9 BYTE Speed for Factories (1..100) +10 BYTE Speed for Defense Posts (1..100) +11 BYTE Speed for SB Defense (1..100) --- Type 7: Ship Properties --- --- Type 8: Planet Properties --- +0 WORD Id +2 WORD Number of values +4 n RECORDs of 6 bytes each. These store the type information for each value, as well as scalar values. +0 WORD Type 0100h EMPTY 0200h Integer 0300h Boolean 0400h String 0500h IEEE `single' 0600h Long String 0700h (PCC2 VM) Subroutine reference 0800h (PCC2 VM) Array reference 0900h (PCC2) Blob 0A00h (PCC2) File handle 0B00h (PCC2 VM) Hash reference 0C00h (PCC2 VM) Struct reference 8000h (PCC2 VM) Ship 8100h (PCC2 VM) Planet 8200h (PCC2 VM) Minefield 8300h (PCC2 VM) Ion storm 8400h (PCC2 VM) Hull 8500h (PCC2 VM) Engine 8600h (PCC2 VM) Beam 8700h (PCC2 VM) Torpedo 8800h (PCC2 VM) Torpedo launcher 8900h (PCC2 VM) Stack frame 8A00h (PCC2 VM) Global context 8B00h (PCC2 VM) Lock (mutex) 8C00h (PCC2 VM) Iterator 8D00h (PCC2 VM) Player xx00h reserved others Real +2 DWORD Value + EMPTY: unused + Integer, Bool, File handle: value + String: 0 if empty string, nonzero if non-empty string (actual value follows below) + Real: all 6 bytes form a Turbo Pascal Real + Single: IEEE 32-bit floating point number (read by PCC 1.0.9+) + Long String, Blob: length of string, if non-zero, value follows below (PCC2, read by 1.0.18+) + Ship, planet, etc.: object id + Stack frame: index relative to current function, 0 means top ("static") + Subroutine/array/hash/struct reference: object Id, relative to current file. This is not currently supported in starchart files (CHARTx.CC), only in VM (SCRIPTx.CC) and object files. + Lock: flags; bit 0 set if this lock is associated with the current process +? n BYTEs String values. Non-empty strings follow here, in correct order. A normal string (0400h) is stored as length byte plus actual string data. A long string (0600h) contains just the data; the length is in the header. A lock contains the data for the lock: +0 DWORD Length of name +4 DWORD Length of note +8 n BYTEs Name +? n BYTEs Note Note: the variable value representation is optimized for size. It uses the fact that each Turbo Pascal Real whose first byte is zero has an effective value of zero, independently of the other bytes. We therefore normalize actual zeroes by setting them to six-bytes-zero, such that the other type tags do not appear in regular real values. Turbo Pascal Reals are 48 bits, where Bits 0..7 Exponent "e" Bits 8..46 Mantissa "f" Bit 47 Sign "s", 0 means +1, 1 means -1 The actual value is e = 0 0.0 otherwise s * 2^(e-129) * 1.f PCC 1.0.9 and later will also read files with IEEE 32-bit floating point numbers, but will never write them this way. This feature was originally intended to be used by programs such as PCC 2, which use IEEE floating point internally. However, as of 21/Jan/2009, PCC 2 writes Reals only, which have significantly higher precision. IEEE FP can still be read by both. IEEE float ("single precision") has 32 bits: Bits 0..22 Mantissa "f" Bits 23..30 Exponent "e" Bit 31 Sign "s" The actual value is e = 0, f = 0 s * 0.0 (signed zero) e = 0, f <> 0 s * 2^-126 * 0.f e = 255, f = 0 s * inf (signed infinity) e = 255, f <> 0 NaN (not a number, error) otherwise s * 2^(e-127) * 1.f Likewise, 1.0.18 can read Long Strings (although it will truncate them to 255 bytes). PCC 2 writes String or Long String, depending on the size of the string. Other values with a zero exponent are reserved. PCC up to at least 1.1.17 will read those as Real 0.0. However, if one such value describes a complex value that has data in the String Values area, those would be misparsed. PCC 2 therefore refuses to read Property records containing such values. Entries marked "PCC2 VM" are only valid in the PCC2 virtual machine state file (SCRIPTx.CC), which uses the same data structure. --- Type 9: Ship Scores [PCC 1.1.6+] --- --- Type 10: Planet Scores [PCC 1.1.6+] --- +0 WORD Size of the following structure +2 54 BYTEs Header. This is the same header as in a type-49 resp. type-50 UTILx.DAT record. The size is explicitly given above in case we someday enlarge this structure. +0 50 BYTEs Name +50 WORD Score Id +52 WORD Score Limit +x 3N WORDs Score entries. The number is implicitly given by the total block size. +0 WORD Id +2 WORD Score Value +4 WORD Turn number --- Type 11: Painting Tag Info [PCC 1.1.6+] --- +0 WORD Number of entries in this record +2 n WORDs Tag values +2N n BYTEs For each tag value, a Pascal string If existent, this record precedes a Painting record (type 5). It defines how Tag values corresponded to strings (atoms) when the file was written. Upon loading, PCC will modify the tags in the paintings accordingly. When CCMerge was used, there will be multiple Painting Tag records. Each of them only applies to the Painting record which follows. --- Type 12: Ufo History [PCC 1.1.7+] --- +0 WORD Id +2 78 BYTEs Standard Ufo record. See UFO.HST for a detailed description of the fields. +0 WORD Color +2 20 BYTEs Name +22 20 BYTEs Info 1 +42 20 BYTEs Info 2 +62 2 WORDs X, Y +66 WORD Speed +68 WORD Heading +70 WORD Planet visibility range +72 WORD Ship visibility range +74 WORD Radius +76 WORD Type +80 DWORD Real Id number. If the Ufo represents some object which has its own Id number, this Id number is stored here. For PHost wormholes, this is the wormhole Id. +84 WORD Turn when this Ufo was last seen +86 WORD X position where this Ufo was last seen +88 WORD Y position where this Ufo was last seen +90 WORD X movement per turn +92 WORD Y movement per turn PCC uses the last four fields to estimate the wormhole's current position. ## Old Format [up to PCC v1.0.7] The file may end at any --- mark, depending upon which PCC version is used. Programs must detect this and not reject the file. Likewise, the file was extended quite often at the end. Gee, is this an ugly file format... Rest in peace. +0 n BYTEs 500 records +0 WORD Color of planet (see below) +2 n BYTEs Comment as Pascal string --- Planet history --- +n WORD Number of stored planets. All planets ever seen with a Sensor Sweep Mission or visited by a ship are stored here. +n+2 m BYTEs Records of 67 bytes each +0 WORD Id number of planet +2 WORD Owner, 0=unowned +4 4 DWORDs Minerals on surface (N, T, D, M) +20 4 DWORDs Minerals in ground (N, T, D, M) +36 4 WORDs Mineral density (N, T, D, M) +44 WORD Temperature. Value 0 = unknown, 101-Temp. otherwise. This value is the PDATAx.DAT value plus 1. +46 WORD Native race +48 DWORD Number of natives (Clans) +52 DWORD Number of colonists (Clans) +56 BYTE 1, if starbase exists, 0 otherwise +57 WORD Industrialization 0 unknown 1 light 2 heavy --- PHost only --- 3 minimal 4 moderate 5 substantial This strange order reflects the fact that PCC was not originally designed for PHost. +59 WORD Turn for information at +57 +61 WORD Turn for information at +4..+36 +63 WORD Turn for information at +46..+48 +65 WORD Turn for information at +52 If one of the turn numbers is 0, no information is available. The turn number corresponds to the newest value in each group. --- Mine fields --- +y WORD Number of mine fields. All minefields ever seen are stored here. The original size is saved, PCC always computes the current size itself. +y+2 @ BYTEs Records of 16 bytes each +0 WORD Id +2 WORD X +4 WORD Y +6 WORD Owner +8 DWORD Number of mine units +12 WORD Type 0 Normal Mines 1 Web Mines +14 WORD Turn of last information about this field --- Paintings --- +n WORD Number of user paintings in starcharts +n+2 x BYTEs Records of variable size +0 BYTE Type of element 0 Line 1 Rectangle 2 Circle 3 Marker Bit 6 set if "new fields" at end Bit 7 set if comment exists +1 BYTE Color +2 WORD X1 +4 WORD Y1 +6 WORD Line, Rectangle: X2 Circles: radius Markers: Type 0 "+" (plus) 1 "!" (exclamation mark) 2 "x" (cross) 3 "<>" (diamond) 4 "p" (flag) 5 (down-up `lock' arrows) 6 "><" (right-left `lock' arrows) +8 WORD Line, Rectangle: Y2 others: zero +10 n BYTEs Comment (Pascal string), only if bit 7 in type set. Used only for markers. --- only if bit 6 of type set, v1.0.5+ --- +x WORD Tag (non-negative for user-defined markers) +y WORD Turn of expiry (-1=never). If this field is, for example, 17, the marker will be deleted at turn 18. --- Starship History [v0.98.4+] --- +q WORD Number of starship history entries +q+2 WORD Number of history entries (10) +q+4 WORD Turn number +q+2 r BYTEs Records of 93 bytes each (for 10 history entries) +0 WORD Starship Id +2 BYTE Hull Id (type), 0 = unknown +3 n BYTEs 10 records of 9 BYTEs (History entries). The first record is the turn specified above. The second one is the turn before etc. All values may be -1 for "unknown". +0 WORD X +2 WORD Y +4 BYTE Warp Factor +5 WORD Heading in degrees +7 WORD Mass Mass = -1 means the ship position was "guessed" by PCC. --- Starship History #2 --- +$ 500 BYTEs Starship owners --- Starship Comments [v0.98.5+] --- +X y BYTEs 500 Pascal strings with starship comments --- Auto Build Goals [v0.99.3+] --- +? & BYTEs 500 Records of 12 BYTEs each +0 WORD Number of Mines +2 WORD Number of Factories +4 WORD Number of Defense Posts +6 WORD Number of SB Defense 0..999 specify the wanted amount. To specify "the maximum under the current conditions", PCC up to v1.0.2.1 uses the value -1, v1.0.2.3 and later use 1000. +8 BYTE Speed for Mines (1..100) +9 BYTE Speed for Factories (1..100) +10 BYTE Speed for Defense Posts (1..100) +11 BYTE Speed for SB Defense (1..100) The 7th bit of the speed values is reserved for additional flags which might be introduced in future. PCC initializes all these records with defaults when creating this file. ## Colors in PCC Colors are stored as PCC's internal color numbers, not as the numbers 1..30 exported to scripts. 1 Dark gray 2 Light gray 3 Green 4 Red 5 Dark green 6 Light blue 7 Blue 8 Dark blue 9 Yellow 15 White 128..137 Additional colors in 256 color mode. Displayed as white in 16 color modes. CMDx.TXT - Additional Commands [V] ----------------------------------- This file contains information to be transmitted to the host, which did not fit into the standard data files. Mainly, this is the PHost command processor commands, but not only those. Commands from this file are packed into the TRN by an appropriate MAKETURN program. At the time of this writing, this file format is supported by PCC and related programs, and VPA 3.61. It is more or less the result of a discussion on the phostdev mailing list; other program authors are encouraged to use this file format if possible. CMDx.TXT is a text file. Each line has the following format: - leading whitespace (ASCII 32) is ignored; - lines whose first non-blank character is a `#' are ignored (comments); - other lines contain PHost command processor commands which are sent as command messages verbatim. Unless specified otherwise below, the order of commands does not matter; - special commands starting with `$' are reserved for programs that read/write this file. Programs should preserve these commands. Programs should support both the Unix and the DOS linefeed convention (LF or CR+LF). Programs should support lines of at least 255 characters. The following special commands are defined at the time of this writing: - `$include FILE': this token is reserved to mean "include specified file here", but as of now it is not implemented; - `$send-file name.ext': generate a type-34 UTILx.DAT record (file transfer) which contains the specified file, and send it through the Host via TRN command 62 (SendBack). See there for further information; - `$time MM-DD-YYYYhh:mm:ss': specify the timestamp of the turn to which this file belongs. If present, this must be the first command in the file; - `$thost-allies ff1ee2FF3': (PCC) alliance settings for THost. The parameter is a sequence of 3-character alliance friendly codes, which are themselves not separated anyhow; CPx.CC - PCC - PHost Command Processor Commands (obsolete) [V] --------------------------------------------------------------- This file contains information to be transmitted to the host, which did not fit into the standard data files. Mainly, this is the PHost command processor commands, but not only those. This file is never empty: if there are no such commands, it does not exist at all. PCC 1.0.6.3 and later are able to save commands in the standard message outbox (MESSx.DAT, MESS35x.DAT), so they can be seen in other clients. In that case, this file will only be used for the THost alliance command. PCC's MAKETURN will still use this file, so you can add commands to have them sent with the TRN. PCC 1.0.17 and later use the CMDx.TXT file format instead. +0 6 BYTEs Signature, "CCcmd",26 +6 18 BYTEs Timestamp +24 WORD Number of commands (0..10000) +26 n BYTEs Records of variable length, the commands: +0 WORD "c" Command code +2 WORD "i" Integer argument +4 n BYTEs "s" String arg, Pascal string (<=43 chars) The limits for number of commands and the string argument length are the current limits of PCC and will be increased as the need arises. There can be at most one command with the same (command code, integer arg) pair. ## Commands Unused arguments are zero or empty. Command 12 is only generated in THost mode, all others only in PHost mode. Commands 7 and 8 are not yet generated by the PCC user interface, but supported by PCC's MAKETURN. + c=0, s=language name: "language" command; + c=1: "send config" command; + c=2: "send racenames" command; + c=3, i=1..3, s=name: change race name; i specifies component (1=full name, 2=short, 3=adjective); + c=4, s="yes" or "no": "filter" command; + c=5, i=player number, s=codes: "allies config" command. s contains alliance configuration codes, e.g. "~v +c"; + c=6, i=player number, s="add" or "drop": "allies" command; + c=7, i=ship Id, s=stringified race number (e.g., "7"): give ship to specified race; + c=8, i=planet Id, s=stringified race number: give planet to race; + c=9, i=ship Id, s=remote control command ("control", "forbid", etc): configure remote control, or request/drop RC for allied ship; + c=10, s="forbid" or "allow": "remote default" command; + c=11, i=ship Id, s=codes: "beamup" command, s contains requested minerals; + c=12, s=codes: configure THost alliances. The string argument is a collection of control characters: bit 0..3 specify the race number, bit 6..7 is 00 (offer alliance), 10 (drop), or 01 (offer FF alliance; PCC 1.0.15+); + c=13: "send fcodes" command. DISTTABL.DAT - Distance Table [V] ---------------------------------- This file contains a look-up table to emulate the distance computations of HOST.EXE. Programs should use it to deliver exact predictions. See for details. The idea is to compute 'Trunc(dx^2 + dy^2)'. HOST.EXE has some math errors here making it hard to duplicate its behaviour easily. The file consists of 168 "rows" corresponding to dy values from 1 to 168. Each row consists of 21 bytes (168 bits) corresponding to dx values from 0 to 167. The low-order bit corresponds to the lower-valued dx. To compute the value 'Trunc(dx^2 + dy^2)', take the first dx bits in row dy, count the '1' bits, and add dy-1. If either dx or dy is negative, remove the sign; if dy is zero, swap dx and dy (for dx=dy=0, the result is obviously zero). HOST.EXE never plugs values larger than 162 into the fuel formula. FLAKx.DAT - FLAK - Combat Recordings [V] FLAK.HST - FLAK - Combat Recordings [V] ---------------------------------------- These files contain combat recordings created by FLAK, a multi-ship combat engine. Whereas FLAKx.DAT contains one player's combats, FLAK.HST contains all combats created during a host run. Each of these files contains a number of battles. Each battle is a block of binary data that can stand for its own, i.e. can be moved around without looking at its inside because it only references data contained within itself, with relative addresses. Each battle contains - ships, describing the ships' (and the planet's) initial state. There can be any number of ships, they are indexed starting with zero. - fleets that group some ships together - attack list entries, describing how fleets pick enemies +0 8 BYTEs Signature, "FLAKVCR",26 +8 WORD File format version, always 0 +10 WORD Player number, 0 for FLAK.HST +12 WORD Turn number +14 WORD Number of battles +16 18 BYTEs Timestamp +34 4 BYTEs Reserved +38 n RECORDs of variable size: battles +0 DWORD Total size of battle in bytes +4 2 WORDs X, Y of this battle in universe (lightyears) +8 DWORD Random number seed +12 DWORD Total time +16 DWORD Reserved for ambient flags +20 DWORD Number of fleets +24 DWORD Size of a fleet entry, always 24 +28 DWORD Offset of first fleet entry relative to start of this record +32 DWORD Number of ships +36 DWORD Size of a ship entry, always 62 +40 DWORD Offset of first ship entry relative to start of this record +44 DWORD Number of attack list entries +48 DWORD Size of an attack list entry, always 4 +52 DWORD Offset of first attack list entry relative to start of this record +56 n BYTEs Fleet/ship/attack list data follows ## Format of a Fleet entry +0 WORD Player number +2 WORD Index of first ship in ship list, 0-based +4 WORD Number of ships in this fleet +6 WORD Movement speed +8 DWORD Index of this fleet's attack list, 0-based +12 DWORD Number of attack list entries +16 DWORD Initial X position in combat coordinates (meters) +20 DWORD Initial Y position in combat coordinates (meters) ## Format of a Ship entry +0 20 BYTEs Ship (or planet) name +20 WORD Initial damage +22 WORD Initial crew +24 WORD Id +26 WORD Player number +28 WORD Hull number (0 for planets) +30 WORD Experience level +32 WORD Number of beams +34 WORD Beam type +36 WORD Number of torpedo launchers +38 WORD Number of torpedoes +40 WORD Torpedo type +42 WORD Number of fighter bays +44 WORD Number of fighters +46 WORD Mass +48 WORD Initial shield level +50 WORD Maximum allowed simultaneously launched fighters for this unit +52 DWORD Targeting rating +56 WORD Compensation rating +58 WORD Flags Bit 0 Set if this is a planet +60 WORD Result -1 This unit was destroyed 0 This unit survived 1..12 This unit was captured by the respective player (can be same as player number if unit was captured and then captured back in one fight) ## Format of an Attack List Entry +0 WORD Ship slot number, 0-based +2 WORD Rating bonus for picking this ship FLEETx.CC - PCC - Fleet Information [V] ---------------------------------------- This file is located in the game directories and contains information on the player's fleets. Version 0 files are used by all versions of PCC, when a standard host (500 ships) is used. Version 1 files are only used with Host999 when there is a fleet with "high" members. +0 8 BYTEs Signature "CCfleet",26 +8 BYTE Version number (0 or 1) --- Version 0 --- +9 500 WORDs fleet membership info, for all ships: Bits 0..14 Id of the fleet the ship is in (0 = not in a fleet). The fleet Id is the same as the ship Id of the leader, so if the ship Id equals the fleet Id, you're dealing with a leader. Bit 15 1 = there's a name for the fleet this ship is leader of. If a ship not owned by the player is registered as a fleet member or leader, PCC will automatically correct the situation to account for the fact that the ship might have been destroyed. +1009 n BYTEs Names as Pascal strings. If a non-fleet leader has bit 15 set, a string is read from the file, but immediately discarded. --- Version 1 [PCC 1.0.11+ and Host999] --- +9 WORD Number of entries following +11 n WORDs fleet membership info, same as above +? n BYTEs names .FNT - PCC - Fonts [V] ----------------------- PCC uses bitmapped fonts. Those come in the resource file (PCC 1.x: CC.RES), or in separate files (PCC2). +0 2 BYTEs Signature, 'FN' +2 WORD Number of fonts (styles) in this file +4 8n BYTEs Font index. For each font, one record of +0 DWORD Font Address +4 BYTE Font Flags Bit 0 Bold Bit 1 Italic +5 BYTE Font Encoding 0 System encoding 1 Codepage 866 (Cyrillic) 2 Unicode +6 2 BYTEs Unused, 0 +? n BYTEs Font name, Pascal string (leading length byte) The "Font Address" fields point to the individual fonts, which have this format: +0 WORD Font type 1 Bitmap font 2 Reserved 3 Bitmap font with pseudo anti-aliasing +2 WORD Font height +4 WORD Number of characters +6 8n BYTEs Character headers +0 DWORD Character Data Address +4 WORD Character Id +6 WORD Character Width The "Character Data Address" field points to the font data. For bitmap fonts, this is "Font height" lines of "(Character width + 7) / 8" bytes in big-endian order: the left-most pixel is the MSB of the first byte. For bitmap fonts with pseudo anti-aliasing, the anti-aliasing information follow as +0 WORD Number of entries +2 2n WORDs Pairs of (x,y). These pixels receive only half intensity. These pixels' values in the main bitmap are ignored. c2reshack saves them as zero, but this is not guaranteed. The "Character Id" field contains the character code. Characters should be stored in order of ascending Character Id. - The system encoding is codepage 437 for PCC 1.x, Latin-1 for PCC2. The Character Id is the character number; fonts must have 256 characters, where each character's index equals its Id. Codes 256*b+a are reserved for ligatures of the form "ab", but this was never implemented. - Likewise, codepage 866 must have 256 characters in the correct order. This is supported by PCC 1.x only. - For Unicode fonts, the character code is the character number. There is no way to represent characters outside the BMP. The character sequence can contain gaps. ## Font Use in PCC All PCCs support only one font per file. The font flags or name are not evaluated. PCC 1.x uses additional nonstandard glyphs; not all fonts have all glyphs. Code Glyph Note ---- ------------------------------ ---------------------------- 7 bullet regular symbol in VGA font 16 right-pointing triangle "play" or "FF" symbol 17 left-pointing triangle "REW" symbol 18 tiny vertical bar with 16 and 17 for "begin"/"end" 26 right-pointing arrow regular symbol in VGA font 27 left-pointing arrow regular symbol in VGA font 29 bent arrow ("tab") 30 up-arrow regular symbol in VGA font 31 down-arrow regular symbol in VGA font 124 small slash normally a "|" 156 ornament left used in VCR 157 ornament right used in VCR 159 "times" symbol ("x") normally a currency symbol 221 left-pointing triangle used in help 222 right-pointing triangle used in help PCC2 originally re-used PCC 1.x fonts, but with Latin-1 encoding instead of codepage 437. Since 1.99.12, it uses Unicode fonts that support a superset of the WGL4 repertoire. In addition, the following characters are used with private encodings: Unicode Glyph --------- ----------------------------------------- E100-E10F Replacement characters 0..F upper-left E110-E11F Replacement characters 0..F upper-right E120-E12F Replacement characters 0..F bottom-left E130-E13F Replacement characters 0..F bottom-right These are used to render unsupported characters. E140 bent arrow (PCC 1.x #29) E142 ornament left (PCC 1.x #156) E143 ornament right (PCC 1.x #157) E144 tiny vertical bar (PCC 1.x #18) HULLSPEC.CC - PCC - Extended Hull Specification (obsolete) [V] --------------------------------------------------------------- This file is in the PCC directory and remains constant (in most cases). When using a custom universe, it may be changed and placed in the game directory. PCC will then use that file. HULLSPEC.CC contains a record of variable length for each hull (105). That records describe additional hull features. Note that this information is used only to display in the "Build Hull" section and ship mission screens ("Cloak"). They don't affect the real ship behaviour, the host uses its own information. It can lead to problems if a "normal" ship has the "Clock" bit set here, and the PCC interface is used to set the "Cloak" mission. It depends upon the host if the ship will cloak: older THosts will do it. If you use customized HULLSPEC.DAT and TRUEHULL.DAT, this file may be edited with CCSHIPS, or generated algorithmically using HULLGEN. This file is obsolete since PCC 1.1.12. Those get the short names from NAMES.CC, and read HULLFUNC.TXT / SHIPLIST.TXT for ship functions. Each ship record has the following structure of variable length: +0 n BYTEs Short name of the hull, a Pascal String of max. 12 chars. (for use in ship lists, e.g., "Nocturne") +n WORD Special capabilities of the hull: Bit 0 Cloaking Bit 1 Hyperdrive Bit 2 Gravitonic Accelerators Bit 3 Bio Scanner Bit 4 Alchemy +n+2 m BYTEs Special capabilities that didn't fit into the above WORD, a Pascal string (e.g. "Chunnel"), for Alchemy ships a description of the reaction. INF.Gx - Informer - Game Definition [T] ---------------------------------------- This file contains the definition of a game slot for Informer. This file format is not very well-explored, as I do not use Informer on a regular basis. +0 8 BYTEs Version (Pascal string, padded to length 7: 7,"V2.3800") +8 21 BYTEs Game name (Pascal string) +29 BYTE Race +30 BYTE Turn number +31 6 BYTEs ? (0, 1, 1, 1, 0, 0) +37 BYTE ? +38 BYTE Number of history turns +39 BYTE ? (0) +40 WORD Mine decay rate +42 WORD Mine scan radius +44 WORD ? (7) +46 n BYTEs ? +164 WORD Passcode INFNOTES.Gx - Informer - Notes [T] ----------------------------------- This file contains Informer notes. This file format is not very well- explored, as I do not use Informer on a regular basis. +0 500 WORDs Note Description Bits 0..8 Entity Id (counter, or a ship Id) Bits 9..11 Priority (0..7) Bits 12..15 Type (?) 0 Non-existent 1 Marker in starcharts 8 Ship marker +1000 n RECORDs of 240 bytes each, for each non-zero word in the above array: +0 BYTE 0 +1 WORD X coordinate, 0 for ship marker +3 7 WORDs ? +17 WORD Y coordinate, 0 for ship marker +19 7 WORDs ? +33 WORD ? +35 205 BYTEs Five fixed-size Pascal strings of 41 bytes each, the marker text .KFB - TKF - Saved battle setup [T] ------------------------------------ This file contains a battle saved with the TKF viewer. This file format is not very well-explored, as I do not use TKF on a regular basis. +0 WORD TKF Version number +2 WORD TKF Version number again (probably something like "minimum version needed to play) 1..n beta versions 1..n 150 version 1.5 +4 11 WORDs Allies. For every player, the players whom is is allied with. +26 11 WORDs Enemies. For every player, the players whom he is hostile to. Bit 0 unused, zero Bit 1 set if Fed is enemy Bit 2 set if Lizard is enemy ... +38 n RECORDs Units in fight. The format is probably version specific. In version 1.5, each record has the following format: +0 WORD Id +2 WORD Owner race (1..11) +4 20 BYTEs Name. Zero- or space-padded. +24 WORD Hull type minus one (0..104), or -1 for planets +26 WORD Ship: Cargo Mass +28 WORD Planet: defense posts +30 WORD Ship: Damage times 100 (i.e. 500 = 5% damage) +32 WORD Ship: Shields times 100 (i.e. 10000 = 100%) +34 WORD Ship: Crew +36 WORD Ship: Engine type minus one (0..8) +38 WORD Ship: Beam count +40 WORD Ship: Beam type minus one (0..9) +42 WORD Ship: Fighter bay count +44 WORD Ship: Torpedo launcher count +46 WORD Ship: Torpedo type minus one (0..9) +48 WORD Ship: Torpedoes / fighters +50 WORD Aggression code (0..1000) ---- The following is not in version beta-4 --- +52 WORD Flags? KFVCRx.DAT - TKF - Battles [T] ------------------------------- This file contains a battle saved with the TKF viewer. This file format is not very well-explored, as I do not use TKF on a regular basis. This is mostly just a notepad for things I already know. +0 WORD ? +2 WORD ? (100) +4 WORD Version number +6 WORD Turn number +6 4 WORDs ? --- Configuration --- +16 11 RECORDs of 10 bytes each: configuration for each race +0 BYTE Mass bonus (50 for Feds) +1 BYTE Extra fighter bays (3 for Feds) +2 BYTE Weapons don't get damage (0=off, -1=on; this is enabled for Feds) +3 WORD Maximum damage * 100 (Lizard: 15000) +5 WORD Weapon damage scale * 100 (Lizard: 15000) +7 BYTE ? +8 BYTE Beam 3x kill bonus (0=off, -1=on; Privs) +9 BYTE Gather debris (0=off, -1=on; Cyborg) +126 BYTE EngineShieldBonusRate (?) +127 WORD MinimumDamagePerAttack * 1000 +129 BYTE TorpHitOdds (?) +130 BYTE TorpsHitFighters (0=off, -1=on) +131 10 WORDs XXXChargedMin, for 10 beams +151 10 WORDs XXXCharged, for 10 torps +171 WORD ShipBayCharged (?) +173 WORD ? +175 WORD PlanetBayCharged (?) +177 4 BYTEs ? (0, 3, 0, 0) +181 WORD FighterBeamCharged +183 WORD FighterEnergy +185 WORD FighterCostBeamCharge +187 WORD FighterCostMovement +189 WORD FighterMovementSpeed +191 BYTE FighterBeamExplosive +192 BYTE FighterBeamKill +193 WORD FighterFiringRange +195 BYTE ? (-1) +196 WORD BeamRange +198 BYTE (?) +199 WORD TorpRange +201 BYTE (?) +202 BYTE AlternateCloakIntercept (?) +203 DWORD AltCloakInterceptDistance +207 n BYTEs ? I think the structure of the records that follow is described here. --- Fights --- +262 n RECORDs Objects taking part in first fight, same format as in .KFB files .LANG - PCC2 - Language File [V] ---------------------------------- PCC2's messages in foreign (non-English) languages are stored in a database file, as a mapping of the original (English) string to the translated string. +0 8 BYTEs Signature, "CClang0",26 +8 DWORD "n" Number of entries (string pairs) +12 DWORD "inptr" Address of input pointer array +16 DWORD "outptr" Address of output pointer array +20 DWORD "inpool" Address of input text pool +24 DWORD "insize" Size of input text pool +28 DWORD "outpool" Address of output text pool +32 DWORD "outsize" Size of output text pool +36 n BYTEs Text data follows here The input/output pointer array addresses point to tables containing "n" records of the following form each: +0 DWORD "pos" String position, points into respective text pool +4 DWORD String length For example, an entry with pos=17 in the input pointer array describes a string stored at address pos+inpool in the file. To translate a string, look it up in the input pointer array. The translation can be found in the output array, at the same index. Since PCC 1.99.12, this file is in UTF-8 encoding. In previous versions, the files had a header, obtained by translating the empty string, containing a "X-PCC-Charset" line. This line named the codepage used to encode this file. MESSx.CC - PCC - Message-related Stuff (obsolete) [V] ------------------------------------------------------ This file contains the template for messages from the appropriate player (the "signature"), and the "killfile" for incoming messages. This format is no longer used in PCC 1.1.5 and later in favor of MSGx.INI. +0 656 BYTEs Message template. 16 fixed-size pascal strings with up to 40 characters (16 x 41 bytes). For messages to a single player, this information is copied into the message text directly. Messages to more than 1 player have one line less (used for "CC: xxx" or "<<< Universal >>>"), so line 9 of the template is left out. +656 WORD Number of subjects in the killfile +658 n BYTEs Fixed-size pascal strings, 36 bytes each: subjects in the killfile (like in message overview) MSGx.INI - PCC/VPA - Message Configuration [V] ----------------------------------------------- This file is used for the message template and for the filter entries. IT is used by PCC 1.1.5 and later, as well as VPA 3.61d and later. This is a text file, in standard ".ini" or "pconfig.src" file format. - "Filter = text": a message filter entry. Messages with the specified subject line are not displayed. - "Sig = text": add a line to the message template/"signature". This is currently ignored by VPA. OBJx.CC - PCC - Objects in the starcharts (obsolete) [V] --------------------------------------------------------- NOTE: This file type is only documented here for historical reasons. It is no longer supported by recent versions of PCC. Since version 1.0, it exclusively uses the KOREx.DAT file format from Winplan. Do not use this file format. The file consists of several chunks of variable length. It ends with a block with all values 0. The file contains the unpacked version of the Winplan part of a RST file. Records that were empty in the Winplan file do never appear here. +0 WORD Number of records in this chunk +2 WORD Type of record 0 End of File 1 Ufo 2 Target 3 Explosions 4 Ion Storms 5 Mine fields others are reserved and ignored +4 WORD Size of one record of this kind. It is not allowed to enlarge the record size of an already assigned record type. This field is only for calculating how many bytes to skip for really unknown records. +6 n BYTEs Data --- Ufo --- +0 WORD Ufo number (1..100) +2 78 BYTEs Ufo record from UFO.HST --- Target --- +0 34 BYTEs Normal TARGETx.DAT record --- Explosions --- +0 WORD Id of explosion (ignored by PCC) +2 WORD X +4 WORD Y --- Ion Storms --- +0 WORD Id (1..50) +2 WORD X +4 WORD Y +6 WORD Radius +8 WORD Voltage +10 WORD Warp +12 WORD Heading See also GREY.HST and the RST file format. --- Mine Fields --- +0 WORD Id +2 WORD X +4 WORD Y +6 WORD Radius +8 WORD Owner (1..11), 12=Crystalline Web Mines PVIEW.NTP - PView - Notepad ---------------------------- This file contains notes for object (notepad function). Addresses into the file use 0 as file start as usual. This file exists once per directory. +0 500 DWORDs Addresses of notes for planets 500 DWORDs Addresses of notes for ships 50 DWORDs Addresses of notes for Ion storms The addresses are 0 if there is no note for that object +4200 n BYTEs Notes. Each note entry consists of 10 fixed-size Pascal strings with maximum length 40, so each note is 410 bytes total. .QC - PCC2 - Compiled Script [V] --------------------------------- This format can be used to store compiled scripts, like object files in conventional programming languages. Although this ability isn't yet available in any released PCC2 version as of December 2011, tools to manipulate this format exist within the PCC2 source archive. +0 6 BYTEs Signature 'CCobj',26 +6 BYTE Format version (100) +7 BYTE Unused +8 WORD Number of bytes following in header (currently 4) +10 DWORD "entry" Object Id of entry point --- end of header --- +14 n BYTEs Objects Objects are the same types and format as in SCRIPTx.CC, although process objects (type 2) are not allowed. When a .QC file is loaded, the interpreter generates a call to the bytecode object with Id "entry". SCORE.CC - PCC2 - Score Statistics [V] --------------------------------------- This file contains the score statistics. It replaces PCC 1.x's STAT.CC. It can store multiple score series. It starts with a header describing the file contents; the header itself is divided in a fixed portion and a number of sub-fields. The file data is stored in records of identical format, one per turn, in ascending order of turn numbers. Each record consists of a record header and a number of score entries. The header can contain additional information about that turn; currently it contains turn number and timestamp. This file format allows read and update of the scores in a file even when the structure is not fully understood by the accessing program. However, we need knowledge of the file format to change its structure (=add a new series), to be able to rewrite the header and sub-fields. +0 8 BYTEs Signature, "CCstat0",26 +8 DWORD "h" total size of file header and sub-fields, pointer to records +12 WORD "nf" number of sub-fields in file header, at least 2 +14 WORD "n" number of records +16 WORD "rh" size of record header, usually 20 +18 WORD "rd" number of scores per record This makes the record size "rh + 44*rd" +20 nf WORDs Pointers to sub-fields --- First sub-field: Record description --- +? rd WORDs Record description. Each entry describes a slot of a record: -1 Planet count -2 Capital ships -3 Freighters -4 Bases or a value matching the Identifier in a score description. The default setup is -1,-2,-3,-4,2. Negative-numbered fields may be described in the second sub-field, but don't have to; non-negative numbers correspond to score entries from UTILx.DAT record #51 and must be described in the second sub-field. Values -100 and below are reserved for internal use and should not appear in files. --- Second sub-field: Score descriptions --- +? WORD "nd" Number of descriptions +? nd RECORDs of 58 bytes (similar to UTIL.DAT #51): +0 50 BYTEs Name; player-readable description of this score. +50 WORD Identifier +52 WORD Turns-over-limit required to win, or -1 +54 DWORD Win limit, -1 if none --- Records --- +h n RECORDs of (rh + 44*rd) bytes, sorted in ascending order of turn number --- Header --- +0 WORD Turn +2 10 BYTEs Date mm-dd-yyyy +12 8 BYTEs Time hh:mm:ss --- Data --- +rh 11*rd DWORDs Entries. 11 scores corresponding to first slot, 11 scores corresponding to second, etc. Value can be -1 if unknown. SCRIPTx.CC - PCC2 - Virtual Machine State (Scripts) [V] -------------------------------------------------------- This file is for PCC2 what VMx.CC is for PCC 1.x. It contains the state of PCC's script interpreter for player x. Scripts which are suspended (`Stop') end up here, including auto tasks. The file is structured in objects, where each object has a certain type and some properties. Note that although the header structure is the same as for PCC 1.x's VMx.CC, the file cannot be called the same because PCC 1.1.18 doesn't validate the version number and would try to parse it. Format of header (same as VMx.CC): +0 4 BYTEs Signature 'CCvm' +4 18 BYTEs Timestamp +22 BYTE Signature 26 (^Z) +23 BYTE Format version (currently 100) +24 WORD Number of bytes following in header (currently 4) +26 WORD Turn number +28 WORD Player Id --- end of header --- +30 n BYTEs Objects Format of an object: +0 DWORD Object Type 1 Bytecode object (code snippet) 2 Process object (suspended script) 3 Stack frame (only valid within a process object's stack frame property) 4 Array data 5 Hash data 6 Structure data 7 Structure type definition +4 DWORD Object Id +8 DWORD Object Size, covering property headers and data +12 DWORD "n" Number of properties +16 n RECORDs of 8 bytes each: property headers +0 DWORD "count" Property element count +4 DWORD "size" Property total size +? x BYTEs Property data. For each property, "size" bytes. The interpretation depends on the property and its "count". ## Bytecode object The Id from the object header is used to refer to this bytecode object. + property 0: reserved + property 1: header +0 WORD Flags Bit 0 This is a SUB, not a FUNCTION Bit 1 Varargs routine +2 WORD Minimum number of arguments when called +4 WORD Maximum number of arguments when called +6 WORD Number of labels in code segment + property 2: data, data segment (literals used within the bytecode), see below. + property 3: names, name list (names used within the bytecode), see below. + property 4: code. Contains "count" 32-bit instructions. Each instruction has this format (little endian, thus "backwards"): +0 WORD Parameter +2 BYTE Minor opcode +3 BYTE Major opcode 0 push 1 binary operation 2 unary operation 3 ternary operation 4 jump 5 indirect call 6 stack operations 7 pop 8 store 9 member reference 10 variable creation 11 special + property 5: local names, name list (local variables). + property 6: name, string (name hint for loading). The property contains the raw string without a terminator or additional length field. + property 7: source file name, string + property 8: source line numbers. Contains "count" records +0 DWORD address (0-based index into code) +4 DWORD source line number ## Process object The Id from the object header is not used. + property 0: reserved + property 1: header +0 BYTE Priority +1 BYTE Process kind. This is used to find processes, it has no effect upon their operation. 0 normal 1 ship auto task 2 planet auto task 3 base auto task +2 WORD context_tos; number of contexts that were created before the process started (i.e. its initial environment) + Property 2: name, string + Property 3: frames. This property contains "count" Stack frame objects + Property 4: contexts, data segment + Property 5: exceptions. Contains "count" records of 16 bytes each +0 DWORD frame_sp +4 DWORD context_sp +8 DWORD value_sp +12 DWORD pc + Property 6: value stack, data segment ## Stack frame object The Id from the object header contains this frame's nesting level, i.e. frames are numbered, starting at 0. + property 0: reserved + property 1: header +0 DWORD Id of bytecode object executing here +4 DWORD pc +8 DWORD context_sp +12 DWORD exception_sp +16 DWORD flags Bit 0 Caller wants a result + property 2: local values, data segment + property 3: local names, name list ## Array data object The Id from the object header contains the array Id used to refer to the array from data segments. + property 0: reserved + property 1: dimensions. Contains "count" DWORDs with the array dimensions, in normal order. + property 2: values, data segment. Contains array values in "C"/"Pascal" order. Empty values at the end are omitted. ## Hash data object The Id from the object header contains the hash Id used to refer to the hash from data segments. A hash is a pool of key/value pairs, where the keys are unique strings; new values can be added at any time. Each key slot names the corresponding value slot. + property 0: reserved + property 1: keys, name list. + property 2: values, data segment. ## Structure data object The Id from the object header contains the structure Id used to refer to the structure from data segments. A structure is a list of values associated with a fixed list of names. The names are defined in the structure type and can be shared with other structures of the same type. + property 0: reserved + property 1: header +0 DWORD Id of structure type definition + property 2: values, data segment. ## Structure type definition The Id from the object header contains the type Id used to refer to this structure type from structure data objects. A structure type definition contains the names used for structure objects. Each name slot names the structure's corresponding value slot. + property 0: reserved + property 1: names, name list ## Data segments A data segment consists of "count" 6-byte values optionally followed by data, see CHARTx.CC, block 7/8. Data segments used in a Process's Contexts property can only contain context references, i.e. values that have the highest bit in the Tag word set. Reference data (arrays, hashes, structs, subroutines) is stored in separate objects, not in the data segment itself. That is, multiple values referring to the same object will still refer to the same object after loading. Forward references are permitted but should be avoided if possible. Object references are typed, that is, an array object and a hash object with the same Id can coexist, and are uniquely identified by Array or Hash reference entries in a data segment. ## Name Lists A name list is a sequence of Pascal strings (length byte + text). Other than the implied 255 limit, PCC2 has no limit on identifier length. Valid characters in identifiers are capital letters, digits, `$', `.' and `_'. .SEL - PCC - Saved Selection [V] --------------------------------- These files contain saved selections, in a simple text format. + Line 1 has the form "CCsel0 ", where is the 18-place turn timestamp, and is the number of saved selection layers in this file. Valid values for are currently 1 and 8. The timestamp can be a single dash "-" to turn off timestamp checking. + Following lines contain "p " or "s ", where is the planet/ship Id. is a bitmask of layers where this object is marked, for = 1 the only valid value is 1, for = 8, 1 to 255 are allowed. Objects where would be zero (not marked) are not stored. STAT.CC - PCC - Statistics [V] ------------------------------- This file exists once per directory, even for more than 1 player. PCC expects all information coming from the same game, the original Planets also expects this. The scores from that player data are stored in STAT.CC and can be called on several places in the game. +0 8 BYTEs Signature "CC-Stat",26 +8 WORD Number of entries in file +10 WORD Size of a record. If the size of a record is expanded some day, old files can still be read. +12 x RECORDs of N bytes. The current size is 130 bytes: +0 WORD Turn Number +2 10 BYTEs Date mm-dd-yyyy +12 8 BYTEs Time hh:mm:ss +20 88 BYTEs 11 records of 8 bytes each +0 WORD Planets +2 WORD Capital Ships +4 WORD Freighters +6 WORD Bases +108 11 WORDs Priority Build Points / PAL points. Note that this does NOT allow representation of PAL values >32k. ## Historic Format This format is written by PCC before 0.97; versions generating it probably did not circulate widely. This description is just for completeness. +0 WORD Number of entries +2 n RECORDs of 108 bytes each: +0 WORD Turn number +2 10 BYTEs Date +12 8 BYTEs Time +20 11 RECORDs of 8 bytes each: Planets/Capital/Freighter/Base TEAMx.CC - PCC - Team Settings [V] ----------------------------------- +0 8 BYTEs Signature "CCteam0", 26 +8 WORD Flags Bit 0 Automatic synchronisation with alliances Bit 1 Automatic synchronisation of transfer settings with teams Bits 2..15 Reserved, set to 0 +10 12 BYTEs Player teams. Each byte specifies for each player which team he is in. Team numbers range from 1 to 11. Player slot 12 has the constant team number 12, for handling the Alien Marauders. +22 12 BYTEs Reserved for team colors. +34 n BYTEs 12 Pascal strings with team names. --- Data Transfer Settings [PCC v1.0.2.1+] --- +? 11 BYTEs Automatic sending of alliance messages, indexed by receiver of information: Bit 0 Automatically send Informer Alliance Messages (planet list) Bit 3 Automatically send RST password +? 11 BYTEs Acceptance of alliance messages, indexed by sender of message: Bit 0 Accept Informer planet lists Bit 1 Accept VPA planet transmissions Bit 2 Accept VPA mine field transmissions Bit 3 Automatically load allied RST Bits 3..7 reserved, 0 +? WORD Passcode for Informer messages (0..9999) The data transfer settings may be missing (PCC 1.0.2), in this case they are considered to be all-zero (no passcode, no transfer enabled). VMx.CC - PCC - Virtual Machine State [V] ----------------------------------------- This file contains the state of PCC's script interpreter for player x. Scripts which are suspended (`Stop') end up here, including auto tasks. You should understand how PCC's interpreter works before attempting to manipulate this. The file format consists of a header, followed by a sequence of code snippets, followed by a sequence of suspended processes. Format of header: +0 4 BYTEs Signature 'CCvm' +4 18 BYTEs Timestamp +22 BYTE Signature 26 (^Z) +23 BYTE Format version (currently 0) +24 WORD Number of bytes following in header (currently 4) +26 WORD Turn number +28 WORD Player Id --- end of header --- +30 n BYTEs Code snippets +x n BYTEs Processes Format of a code snippet: +0 DWORD Size of this record, not including this DWORD (0=last entry; then this is the only word in this snippet) +4 DWORD "uid" Unique identifier. This code snippet is referenced by this number. This may be any bit pattern, there's no particular rule imposed on this (actually, PCC uses raw 16:16 bit pointers here which are meaningless once PCC exits) +8 WORD Minimum argument count +10 WORD Maximum argument count +12 WORD "nalloc" Number of allocated argument names +14 WORD "code" Total size of code in bytes +16 n BYTEs "Name hint". Pascal string with a subroutine name. Can be anything without very negative consequences. The VM loader can use this, the "nalloc" field and the argument names as a hint that this code snippet originally was the specified subroutine, and if it matches the current definition, merge them; if the subroutine is not defined, this has no effect (this optimisation isn't implemented in any PCC version until now). +x n BYTEs Argument names; "nalloc" names (see `Name List' below) +x n BYTEs Code. "code" bytes, a sequence of pascal strings. Format of a process: +0 DWORD Size of this record, not including this DWORD (0=last process) +4 WORD "sp" Stack pointer (number of inactive code blocks) +6 WORD "ctos" Context stack pointer. Specifies how many contexts this process entered, and thus must leave before terminating. The others were created by PCC before the process was started. +8 BYTE Process status. Should be 3 (suspended). +9 BYTE Process priority, 0 to 99. Low priorities run first. +10 n BYTEs Process name, pascal string (currently 45 characters max). +? n BYTEs Command sources. "sp+1" records of variable length, see below. A command source contains one or more commands that are to be executed. +? n BYTEs Contexts. Records of variable length, see below. At least "ctos" contexts, usually "ctos+2" or more. Format of a saved command source (stack frame): +0 BYTE Type of command source (0 or 1) +1 BYTE Capabilities of this command source 0 "One" 1 "Stream" 2 "Random" Usually, type 0 command sources have the value 2 here, type 1 command sources have the value 0. +2 DWORD Instruction pointer; index of next line to be executed +6 WORD "nnam" Number of local variable names +8 WORD "nval" Number of saved local variable values. The previous two words do not have any connection, there can be more names than values or vice versa. +10 n BYTEs Local variable names, "nnam" names (see `Name List' below) +? 6N BYTEs Local variable values, "nval" records of 6 bytes each. +? n BYTEs String values of local variables. See CHARTx.CC, block 7/8, for details about the previous two fields. --- Type 0 Command Source --- +? DWORD "ip" of first line in saved code snippet +? DWORD Code snipped identifier ("uid") --- Type 1 Command Source --- +n n BYTEs Pascal string, line 0 +n n BYTEs Pascal string, line 1 (must be a single command word, may be empty) Format of a saved context: +0 WORD Type. 0=last context, no information follows. All other contexts contain at least one (possibly unused) WORD. Values not defined here are reserved for the future; there is no way to load a saved context with an unknown number. --- Type 1 (Struc) --- +2 WORD - --- Type 2 (Global) --- +2 WORD - --- Type 3 (If/Select) --- +2 WORD Subtype; used for syntax checking 0 "Else" branch of an "If" 1 "If" branch of an "If" 2 (1.1.13+) "Case" of a "Select" --- Type 4 (With) --- +2 WORD 1 if one-line "With" --- Type 5 (Try) --- +2 WORD 1 if in "Else" branch, 0 otherwise +4 DWORD "ip" of "Try" statement + 1 +8 WORD "sp" of "Try" statement --- Type 6 (Do) --- +2 WORD - +4 DWORD "ip" of "Do" statement + 1 +8 WORD "sp" of "Do" statement +10 BYTE Type of loop/condition: 0 = "Do", 1 = "Do While", 2 = "Do Until", 3 = "For" +11 n BYTEs Condition (Pascal string) --- Type 7 (ForEach) --- +2 WORD - +4 DWORD "ip" of "Do" statement + 1 +8 WORD "sp" of "Do" statement --- Type 8 (Sub) --- +2 WORD "sp" of this subroutine (what the value of the process's "sp" field would be if the subroutine contained a single `Stop' only) --- Type 9 (Planet) --- +2 WORD Planet Id --- Type 10 (Engine) --- +2 WORD Engine Id --- Type 11 (Torpedo) --- +2 WORD Torpedo System Id --- Type 12 (Launcher) --- +2 WORD Torpedo System Id --- Type 13 (Beam) --- +2 WORD Beam Id --- Type 14 (Ship) --- +2 WORD Ship Id --- Type 15 (Hull) --- +2 WORD Hull Id --- Type 16 (Player; 1.0.8+) --- +2 WORD Player Id --- Type 17 (Minefield; 1.0.11+) --- +2 WORD Minefield Id --- Type 18 (Ion Storm; 1.0.11+) --- +2 WORD Ion storm Id --- Type 19 (Lock; 1.1.2+) --- +2 WORD 0 +4 n BYTEs Lock name, Pascal string +x n BYTEs Info text, Pascal string ## Name Lists As of PCC v1.0.7, a name list is a sequence of Pascal strings (length byte + text), with a maximum identifier length of 31 characters. Valid characters in identifiers are capital letters, digits, `$', `.' and `_'. VPAx.DB - VPA - Database [T] ----------------------------- This file contains history and other information of the VGA Planets Assistant. The file begins with a signature: +0 14 BYTEs "VPA Database",13,10 +14 BYTE Database format version. Has the value 6 for all VPA versions in use nowadays (3.49+), and the text below describes format version 6. Then, for each turn, a block follows. It has the following structure: +0 4 BYTEs Block name = "TURN" +4 DWORD Size of data (counted from offset 116 onwards) +8 WORD Turn Number +10 18 BYTEs Timestamp of turn +28 11x4 WORDs Scores (see GENx.DAT) +116 n BYTEs Data The Data block consists of several sub blocks containing various information: +0 4 BYTEs Block name +4 DWORD Total size of data (counted from offset 10) +8 WORD "Count" Number of elements (=ships, planets, ...) in the block, if more than 1 are possible. 0 otherwise (e.g., for PBPs). +10 n BYTEs Data The following paragraphs describe the various sub-blocks in the file: + "BASE" - Starbase data Contains information on starbases (records as in BDATAx.DAT) + "EPLN" - Planet information 500 records of the following structure, one per planet. The Count field is 500. +0 WORD Turn of last scan, or 0 +2 BYTE Owner, or 0 if unknown +3 BYTE Flags Bit 7 Starbase exists Bit 6 Starbase does not exist Both bits zero: not known Bits 0..2 Industry level 0 unknown 1 minimal 2 light 3 moderate 4 substantial 5 heavy (the same as in PHost UTILx.DAT, plus one) + "IMSG" - Incoming messages Incoming messages kept in the database using the "Keep" command in VPA.MSG. The number of messages is in the "count" field in the block header. The data block contains a sequence of message headers followed by the texts. Message headers have the same format as in MDATAx.DAT: +0 DWORD Offset +2 WORD Length The offsets are relative to the position of the "count" word minus one. That is, when you copy the "count" word and the block data into a separate file, you get a standard MDATAx.DAT file. + "IONS" - Ion Storms Records of 22 bytes each: +0 WORD Storm Id +2 WORD X +4 WORD Y +6 WORD Radius +8 WORD Voltage +10 WORD Heading +12 BYTE Warp +13 BYTE 1=growing, 0=weakening +14 4 WORDs ? (-1, probably previous coordinates) + "MARK" - Markers Records of 12 bytes each, followed by comment texts +0 BYTE Type (see data transmission, under MDATAx.DAT) +1 BYTE Color +2 WORD X +4 WORD Y +6 WORD Number of message (see "IMSG" block) of this marker. 0 for user-made markers. Negative ship id if bound to a ship. +8 WORD Lines: X extent Markers: position of comment text in text area (1-based, 0=no comment) +10 WORD Lines: Y extent Circles: radius Markers: text justification After the marker records, the text area follows. It is indexed 1-based and contains the comments as Pascal strings. The field at +8 is not used for circle markers. VPA sets it to 0 when it creates a marker, but preserves different values if you put them there (by editing the file). VPA10k uses this fact to mark its own markers and find them again later; it puts the value 4711 there. For more information on VPA markers, refer to the VPA data transmission section in the MDATAx.DAT description. + "MINE" - Mine fields Records of 16 bytes each (compare this to the minefield data transmission, which is the same except that the Id is missing): +0 WORD Minefield Id +2 WORD Turn of last scan +4 WORD X +6 WORD Y +8 WORD Owner race +10 DWORD Mine units +14 WORD 1=Web mines + "MSGO" - Message Information One DWORD for each message in "IMSG". See VPAMSGx.DAT for description. + "NPLN" - Planet Flags 500 bytes, one for each planet: which values are known this turn: bit 0 Enemy planet (owner known) bit 1 Minerals, money known bit 2 Industry known (mines, factories, DP, FC) bit 3 Colonist population known bit 4 Native population known bit 5 Temperature known bit 6 (Non-)Existence of starbase known bit 7 Number of supplies known This corresponds to various actions as follows: 01h Planet was scanned (sensor sweep) 30h Planet was bioscanned 41h Ship surrendered 43h Planet was dark-sensed 69h Ship in orbit 6Fh Planet was super-spied + "OMSG" - Sent messages Similar to the MESSx.DAT file, with the "Count" word being the first word of the MESSx.DAT file. Does not have a gap between message headers and data. + "PASS" - Password Password, using the same encryption as in GENx.DAT. The size is 20, the count is 0. VAR pw : ARRAY[0..19] OF BYTE; { this field } ch : ARRAY[0..9] OF CHAR; { password } FOR i := 0 TO 9 DO ch[i] := Chr(pw[i] - pw[19-i] + 32); + "PBPS" - Priority Build Points Contains 11 WORDs with the PBPs of the players. A value is -1 if the race doesn't play or the number is unknown. The Count word in the block header is 0. + "PEXP" - Planet Experience [v3.61f+] Contains 500 bytes, one for each planet. Each entry contains the experience level (>= 0) or 255 if not known. This record only exists when PHost 4.x experience is actually used. + "PHST" - PHost Version Number Exists if PHost is being used. Contains the PHost version number ("3.2e"). The Size field contains the length in characters of this string, the Count field is zero. + "PLAN" - Planet data This block contains the information of PDATAx.DAT and information on scanned planets. This uses modified planet records (89 bytes each), unknown values are set to -1. +0 WORD Planet id +2 WORD Turn of first scan +4 WORD Turn of last scan +6 WORD Owner +8 81 BYTEs Contents of planet record at offset 4 (Friendly Code), see PDATAx.DAT for description. Unknown values are set to -1. + "REFS" - unused This header tag is recognized but not evaluated by current versions of VPA. + "SCOR" - unused This header tag is recognized but not evaluated by current versions of VPA. + "SEXP" - Ship Experience [v3.61f+] Contains 999 bytes, one for each ship. Each entry contains the experience level (>= 0) or 255 if not known. This record only exists when PHost 4.x experience is actually used. + "SHIP" - Ship data Contains data for all starships, same as SHIPx.DAT, plus all scanned ships. This uses modified ship records (123 bytes each), unknown values are -1. +0 WORD Ship Id +2 WORD Turn of last scan +4 WORD Owner +6 103 BYTEs Contents of ship record at offset 4 (FCode), see SHIPx.DAT for description. +109 WORD Last known mass +111 WORD Minimum mass scanned ever +113 WORD Maximum mass scanned ever +115 2 WORDs Last turn's X,Y +119 2 WORDs Last scanned X,Y + "UFOS" - Ufos [v3.58+] Contains the Ufo objects; 90 bytes per object. +0 WORD Ufo Id +2 WORD Turn number +4 78 BYTEs Standard Ufo record +82 4 WORDs -1 (?, probably previous coordinates) + "VCRS" - VCR records Contains all VCRs, like in VCRx.DAT. + "VERS" - VPA Version Number The Count field in the header contains the version number, encoded as 351 (decimal) for 3.51. The data area itself is empty (size 0). + "WORM" - Wormholes Entries of 12 bytes each. +0 WORD Wormhole Id +2 WORD Turn number of scan +4 WORD X +6 WORD Y +8 WORD Mass +10 WORD Stability (like values in UTILx.DAT, plus 1) 1 very stable 2 stable 3 mostly stable 4 unstable 5 very unstable 6 totally unstable + "XYPL" - Planet Coordinates 500 records with an X and Y WORD each. VPAMSG.DAT - VPA - Message Information [T] ------------------------------------------- This file contains information about the messages in one turn. It exists once per directory, and covers all players. +0 18 BYTEs Timestamp. To detect if VPAMSG.DAT and VPAMSGx.DAT need to be regenerated. +18 11 WORDs Number of messages, for each player. +40 11 WORDs Number of VCRs, for each player VPAMSGx.DAT - VPA - Message Information [T] -------------------------------------------- This file contains associations between messages and objects, as parsed from MDATAx.DAT. This is just what I found from some small samples, and seems to be rather intrinsic to VPA. +0 n DWORDs For each message from MDATAx.DAT: Bits 0..10 Object Id (0..2047) Bits 11..14 Object Type: 0000 if not associated with anything 0001 if message is associated with a planet 0010 if associated with a ship 0011 if associated with a minefield 0100 if associated with an ion storm 0101 if associated with a marker (object Id is number of marker in VPAx.DB, "MARK" block, counting from 1 0110 if associated with a wormhole 0111 if associated with an Ufo Bits 16..? associated VCR number or 0 (?) E.g., a `(-d0167)' message has the value 08A7h here, where A7h = 167 is the planet/starbase Id, and bit 11 is set to tell this message belongs to a planet. +? n WORDs For each message in the VPA database, "IMSG" block (messages that will be kept): position of this message in MDATAx.DAT, 1-based. DATA OF 3rd PARTY PROGRAMS - HOST SIDE ======================================= ALIENS!.HST - Aliens! - Hosting Information [T] ------------------------------------------------ This file contains the current status and configuration of the Aliens! add-on. +0 500 BYTEs Infected planets. Contains the number of Alien clans on each planet, 0 for uninfected planets, 1..255 for infected ones. +500 500 BYTEs Infected ships. For each ship, 1 if the ship is infected, 0 else. +1000 BYTE Enabled special functions 0 none 1 Death Pulse 2 Death Pulse, plus Dwarfstar/Topaz immunizing +1001 11 BYTEs Players who have already met the Aliens. 1 = player already got introductory message, 0 = didn't. +1012 WORD Base number for Winplan picture Id (see MDATAx.DAT). Defaults to 666. AUXHULL.DAT - VPEdit/VPHost - Auxiliary Hull Data [T] ------------------------------------------------------ This file can be edited with VPEdit. VPHost 3.16 claims to use it to define auxiliary hull information, but this seems not be true. This file assigns special abilities to ships. So far, this mechanism was never implemented completely. Just for curiosity, here it is. The file contains one record per hull, each of which is 32 bytes. +0 3 WORDs Special devices assigned to this ship. Index into DEVSPEC.DAT or 0. +6 WORD "Minimum Crew" +8 WORD "Free Device Bays" +10 11 WORDs ? DEVSPEC.DAT - VPEdit/VPHost - Device Information [T] ----------------------------------------------------- This file can be edited with VPEdit. VPHost 3.16 claims to use it to define auxiliary hull information, but this seems not be true. This file defines special devices. So far, this mechanism was never implemented completely. Just for curiosity, here it is. The file consists of a sequence of records, each of which is 255 bytes long and has the following format: +0 30 BYTEs Name of device +30 4 BYTEs Short name of device +34 WORD Engine tech required +36 WORD Hull tech required +38 WORD Beam tech required +40 WORD Torp tech required +42 WORD Tritanium required +44 WORD Duranium required +46 WORD Molybdenum required +48 WORD Money required +50 WORD Device kind 1 Alchemy device 2 Refinery device 3 Torpedo building device 4 Fighter building device 5 Gambling device 6 Ram-scoop device 7 Terraform: heating device 8 Terraform: cooling device 9 Ship repair device 10 Refit device 11 Bioscanner device 12 Industry scanner device 13 Scanner device 14 Dark sense 15 Minefield scanner 16 Deep space scanner 17 Cloaking device 18 Anti-cloak device 21 Gravitonic accelerator 22 Hyperdrive 23 Chunnel device 31 Super-spy device 32 Rob-ship device 33 Pillage device 34 RGA device 35 Combat device 36 Imperial assault device 37 Hiss device 38 Factory feed 41 Mine scoop device 42 Mine lay device 43 Web mine lay device 44 Mine sweep device 45 Fighter mine sweep device 46 Glory device 51 Terraform: optimum device (heat or cool?) 52 Native lifeform assimulator 53 Robot clan construction device 54 Colonist cloning device 55 Ground attack air supply 56 Terraform: ore condenser 57 Position jammer device 58 Chameleon device 59 Entertainment device 64 Camouflage scanner +52 WORD ? +54 10 WORDs Fuel usage, for each warp factor +74 10 WORDs "Fuel move", times 10 (i.e. 15 means 1.5) +94 10 WORDs Fuel usage, mass related, for each warp factor +114 10 WORDs Supply usage, for each warp factor +134 10 WORDs Maximum range, for each warp factor +154 10 WORDs ? +174 WORD Number of engines (required?) +176 WORD Cargo space (occupied by device?) +178 2 WORDs ? +182 WORD Maximum damage +184 WORD Minimum engine tech +186 WORD ? +188 WORD Standard (all applicable ships have it), 0 or 1 +190 WORD Device is automatic, 0 or 1 +192 WORD Shareware, 0 or 1 +194 2 WORDs ? +198 WORD Racial orders: bitfield. Bit 1 = race 1, bit 2 = race 2, ... Value 0 means 'all'. +200 WORD Racial usage: bitfield. +202 3 BYTEs 'Trigger' FCode +205 3 BYTEs 'Enable' FCode +208 3 BYTEs 'Disable' FCode +211 WORD Minimum warp +213 WORD Maximum warp +215 3 WORDs ? +221 WORD Mass (of device?) +223 16 WORDs ? EXPLMAP.HST - Explore Map - Seen Planets [T] --------------------------------------------- +0 WORD Version Code (?) +2 22 BYTEs unused +24 500 WORDs Visibility Information. For each planet: bit 0 unused bit 1 player 1 saw it bit 2 player 2 saw it ... Until version 2.2, this file is stored in host byte order, i.e. little-endian on (for example) Intel machines and big-endian on Suns. Since version 2.3, it uses little-endian order, like all other VGAP file formats. KFROBO.HST - TKF - Result Information [V] ------------------------------------------ +0 WORD Number of battles this turn +2 n RECORDs of variable length, for each battle: +0 WORD X +2 WORD Y +4 WORD Number of surviving ships +6 n WORDs Id numbers of surviving ships +? WORD Number of killed ships +? n WORDs Id numbers of killed ships KFTONS.HST - TKF - Tons score [V] ---------------------------------- This file has the same format and contents as TONS.HST. TEAMS.DAT - PTScore - Teams [T] -------------------------------- This file defines the teams used for scoring by PTScore: +0 WORD 0 (?) +2 11 WORDs Team numbers for each player (0=not in a team) VPMOVIE.TMP - VGA Planets Movie Recorder (VPMC) - State of the World [T] ------------------------------------------------------------------------- This file is created by the Movie Recorder (VPMC) to store the current state of the world. Each turn, the Recorder computes the difference between the universe and this file and stores it to the .VPM file, and updates VPMOVIE.TMP accordingly. +0 10 BYTEs "option block" (?) +10 500 BYTEs planet data bits 0..3 owner bit 4 ? (0) bit 5 starbase present bits 6, 7 ? (0) +510 500 RECORDs of 9 bytes each +0 BYTE Hull number +1 BYTE bits 0..3 owner bits 4..7 engine type +2 BYTE bits 0..3 beam type bits 4..7 beam count +3 BYTE bits 0..3 torp type bits 4..7 torp launcher count +4 WORD X +6 WORD Y +8 BYTE damage +5010 500 RECORDs of 7 bytes each +0 WORD X +2 WORD Y +4 WORD Radius +6 BYTE Bits 0..3 owner Bit 4 1=web .VPM - VGA Planets Movie Player (VPMPLAY, VPMC) - Movie [T] ------------------------------------------------------------ +0 10 BYTEs Signature "VPM 2.1",0,0,0 (probably version dependent) +10 1000 WORDs Planet coordinates. 500 X,Y pairs +2010 682 BYTEs Race names. Same format as RACE.NM +2692 n BYTEs Movie data, variable-sized blocks. Each block has the format +0 BYTE block type +1 n BYTEs block data A turn ends with a block of type 0 containing no data, i.e. just a null byte. Each block specifies the differences from the previous turn to this one. --- Planet block --- +0 BYTE 1 (block type) +1 n WORDs planet data bits 0..8 Id bits 9..12 owner bit 13 ? (0) bit 14 starbase present bit 15 ? (0) +m WORD 0 (block terminator) --- Ship block --- +0 BYTE 2 (block type) +n RECORDs of variable size: +0 WORD bit 0 hull info present bit 1 owner/engine info present bit 2 beam info present bit 3 torp info present bit 4 damage info present bit 5 X coordinate present bit 6 Y coordinate present bit 7..15 Id --- all these fields are optional: --- +? BYTE hull +? BYTE bits 0..3 owner bits 4..7 engine +? BYTE bits 0..3 beam type bits 4..7 beam count +? BYTE bits 0..3 torp type bits 4..7 torp launcher count +? BYTE damage% +? WORD X +? WORD Y +? WORD 0 (block terminator) Note: when a ship is destroyed, this is reported with an entry that has only owner/engine information with new owner zero. --- Minefield block --- +0 BYTE 3 (block type) +1 n RECORDs of variable size: +0 WORD Bits 0..8 Id Bit 15 1 if radius change only --- if Bit 15 clear --- +2 WORD X +4 WORD Y +6 WORD Radius +8 BYTE Bits 0..3 owner Bit 4 1=web --- if Bit 15 set --- +2 WORD Radius +m WORD 0 (block terminator) Note that the VPM player assumes that the first recorded turn is turn 1, no matter what it really was. FILE LIST - WHO OWNS WHAT ========================== This section contains a list of files, not all of which are documented here, with brief information on who uses them. This is useful from time to time when digging through game directories sent with bug reports. Files marked [*] have descriptions here. Obvious names have usually been omitted (i.e. `echoview.ini'). This list is expected to grow. "Standard" means that every nontrivial program handles this file. "PCC1" means PCC 1.x only, "PCC2" means PCC2 only, "PCC" means both versions. Likewise, "PHost4" means PHost 4.x only. This list, like the rest of this documentation, shows file names in all-uppercase. See the introduction for a few words about file name case. .CCB PCC, CCBSim, PlayVCR: Battle simulations [*] .CCP PCC1: printer driver (plain text) .CCR PCC1: report definition .KFB TKF: Saved battle setup [*] .Q PCC: script (plain text) .QC PCC2: compiled script [*] .PHL PHost4: single language (see PLANGxx.HST [*]) .SEL PCC: Saved Selection (plain text) [*] .VPM VPMC: Movie [*] 1BANCO.HST 1Banco (1st Corsarian Satellite Bank): ? AFSIM.SAV AFSim: Saved simulation setup [*] AFSREPL.EXE AFSim: helper program ALIENS!.HST Aliens!: Hosting Information [*] AUTOEXEC.Q PCC: user initialisation script AUTOx.DAT Winplan: Auto tasks [*] AUXBATT.INI THost: combat replacement (batch file) AUXBC.INI Standard host: before-combat hook (batch file) AUXCMDS.TXT PHost: injecting commands into host run (plain text) AUXDATA.HST PHost: Miscellaneous [*] AUXHOST1.INI Standard host: first hook (batch file) AUXHOST2.INI Standard host: last hook (batch file) AUXHULL.DAT VPHost: additional hull info BDATA.HST Standard host: Starbase data [*] BDATAx.DAT Standard client: New Base Data [*] BDATAx.DIS Standard client: Old Base Data [*] BEAMSPEC.DAT Standard static: Beam weapons [*] BRAIN.HST CPlayer: ? BUFF.TMP THost: Temporary File [*] BUFFPNT.TMP THost: Temporary File [*] C2NU.INI c2nu: State (plain text) C2RST.TXT c2nu: Downloaded RST file (plain text) C2TRN.TXT c2nu: Prepared turn file (plain text) CC.RES PCC: Resources [*] CHARTx.CC PCC: Starchart database [*] CHECK.LOG PHost: turn check result (plain text) CHECK2.LOG PHost: detailed turn check result (plain text) CLOAKC.HST Standard host: Cloak & Shield State [*] CMDx.TXT PCC: command processor commands (plain text) [*] CMRDATA.HST FHost: ? COLORx.DAT Winplan: ? COMBAT.LOG PHost: combat parameter log (simulator hook) (plain text) CONFIG.CC PCC1: Configuration (up to 1.0.16) CONFIG.TXT THost: configuration written by hconfig.exe (plain text) CONFIG2.CC PCC1: Configuration (1.0.17+) (plain text) CONTRLx.DAT Winplan: Checksums [*] CONTROL.DAT DOS Planets: Checksums [*] CORE.Q PCC: system initialisation script (plain text) COREx PCC1: core dump CPERROR.LOG CPlayer: error log (plain text) CPx.CC PCC1: Command Processor Commands [*]; no longer used DEVSPEC.DAT VPHost: device specifications DISTTABL.DAT Static: distance computation table [*] DOMERR.LOG Dominate: error log (plain text) DOMOLD.LOG Dominate: previous error log (plain text) EBANGx.DAT EchoView: explosions EBASEx.DAT EchoView: starbases EGRAPHx.DAT EchoView: drawings EHOLEx.DAT EchoView: wormholes EMINEx.DAT EchoView: minefields ENGSPEC.DAT Standard static: Engines [*] EPLANx.DAT EchoView: planets ERROR.LOG THost: current error log (plain text) ERROROLD.LOG THost: complete error log (plain text) ESCOREx.DAT EchoView: scores ESHIPSx.DAT EchoView: ships ESTORMx.DAT EchoView: storms ETEMPx.TMP THost: Temporary File [*] EUFOx.DAT EchoView: Ufos EVxxxRx.DAT EchoView: ? EXP.LOG PHost4: Experience upgrade log (plain text) EXPLMAP.HST Explore Map: Seen Planets [*] EXTMINES.HST PHost: Minefields [*] FATx.TRN Winplan: temporary file FCODES.CC PCC: Friendly code list (plain text) FHCONFIG.HST FHost: configuration file FIXPLN.EXE SRace: race picture patch FIZZ.BIN Standard client: Checksums [*] FLAK.HST FLAK: All combat [*] FLAKx.DAT FLAK: Player's combat [*] FLEETx.CC PCC: Fleet Information [*] FRIDAY.DAT SRace: Race Assignments [*] GAMEBASE PDV: ? GAMESTAT.DAT Winplan: Game list [*] GEN.HST Standard host: Passwords and other [*] GENx.DAT Standard client: General Information [*] GREY.HST THost: Miscellaneous [*] HCONFIG.HST THost: Configuration [*] HCONFIG.INI VPA: configuration file (hconfig) (plain text) HOST.LOG Standard host: log file (plain text) HOSTMESS.TXT Standard host: messages to host (plain text) HULLFUNC.DAT PHost static: Hull functions [*] HULLFUNC.TXT PHost static: Hull functions (plain text) HULLSPEC.CC PCC1: Extended Hull Specification [*] HULLSPEC.DAT Standard static: Starship Hulls [*] INCMES PDV: saved incoming messages (plain text) INF.Gx Informer: Game Definition [*] INFNOTES.Gx Informer: Notes [*] INIT.TMP Standard client: Player List [*] KFROBO.HST TKF: Battle summary [*] KFTONS.HST TKF: Tons sunk [*] KFVCRx.DAT TKF: Combat recordings [*] KOREx.DAT Winplan: Starcharts [*] LANG.PLN THost: Host Language [*] LASTTURN.HST Standard host: Timestamp [*] LEECHx.DAT THost: file sent with RST (used by Taccom) MAP.INI VPA: configuration file (starchart) (plain text) MDATAx.DAT Standard client: Received Messages [*] MESS.EXT Standard host: External Messages (sent by Hostmaster) [*] MESS.OLD Standard host: Old Messages (=sent last turn) [*] MESS.TMP Standard host: Current Message Traffic [*] MESS35x.DAT Winplan: Sent Messages [*] MESSPNT.EXT Standard host: Pointers to External messages [*] MESSPNT.OLD Standard host: Pointers to Old messages [*] MESSPNT.TMP Standard host: Pointers to Current messages [*] MESSx.CC PCC: Message-related Stuff [*] MESSx.DAT DOS Planets: Sent Messages [*] MINES.HST Standard host: Mine fields [*] MISPLAN.EXE SRace: planets.exe mission name patch MISSION.CC PCC: Mission list (plain text) MISSION.INI Winplan: Missions (plain text) [*] MSGx.INI VPA/PCC: message-related configuration (plain text) [*] MTx.TXT Winplan: MAKETURN log (plain text) MYCONFIG.SPL Spacelord: ? MYPLANx.SPL Spacelord: ? MYSHIPx.SPL Spacelord: ? NAMES.CC PCC: short name definitions (plain text) NAMES.DAT PTScore: player names (plain text) NEXTTURN.HST Standard host: Timestamp [*] NOTESx.DAT Winplan: Notes [*] NAUTOx.DAT Hacked Winplan: auto tasks (see AUTOx.DAT) [*] OBJx.CC PCC1: Objects in the starcharts [*]; no longer used OLDFIG.HST THost: Host Configuration [*] PATCH.PLN SRace: data file for FIXPLAN.EXE PATH.DAT Wisseman programs: Game Directory [*] PCONFIG.HST PHost: configuration file (compiled); no longer used PCONFIG.SRC PHost: configuration file (plain text) PDATA.HST Standard host: Planet data [*] PDATAx.DAT Standard client: New Planet Data [*] PDATAx.DIS Standard client: Old Planet Data [*] PLANETS.NM Standard static: Planet names [*] PLANG.HST PHost: Language database PLANGENG.HST PHost: English-only language database PLAYERx.RST Standard: Host-to-player communication [*] PLAYERx.TRN Standard: Player-to-host communication [*] PLNHELP.DAT DOS Planets: Help texts [*] PHONEY.HST Standard host: hull-remapping hook (used by RacePlus) PREFx.DAT Winplan: ? PSTATE.TMP PHost: temporary file; no longer used PVIEW.NTP PView: Notepad [*] RACE.NM Standard static: Race names [*] RACES.INI VPA: configuration file (SRace/PlayerRace) (plain text) REFDATA.HST THost/Ref: Victory Conditions [*] REG.KEY Winplan: Registration Key [*] REG.LOG Standard host: registration log (plain text) RESOURCE.PLN DOS Planets: Pictures [*] RN.DAT Winplan: RACE.NM Treatment [*] SCANMESS.DAT EchoView: message templates SCORE.CC PCC2: Statistics (scores) [*] SCORE.LOG Standard host: score log (plain text) SCRAM21.OLE Winplan: Registration Protection [*] SCRIPTx.CC PCC2: Virtual Machine State (scripts) [*] SGATE.HST FHost: ? SHIP.HST Standard host: Ship Data [*] SHIPSCAN.EXT PHost: Ship Scan Information (plain text) [*] SHIPXY.HST Standard host: Ship Coordinates [*] SHIPXYx.DAT Standard client: Ship coordinates [*] SHIPx.DAT Standard client: New Ship data [*] SHIPx.DIS Standard client: Old Ship data [*] SHPNAMES.HST Dominate: ship names SKOREx.DAT Winplan: Extended Ufo Database [*] SNOOKER.DAT Winplan: TempLock Deluxe [*] SUNBST.HST FHost: ? SUNDATA.HST FHost: ? STAT.CC PCC1: Statistics (scores) [*] STORM.NM Standard host: Names for Ion storms [*] TARGETx.DAT Standard client: Visible enemy ships ("Contacts") [*] TARGETx.EXT VPUnpack/VPUtil: More enemy ships [*] TASKx.DAT Winplan: Auto tasks [*] TBRAINx.HST Dominate: ? TEAMS.DAT PTScore: Teams [*] TEAMx.CC PCC: Team Settings [*] TECH.MOF DOS Planets: Font [*] TEMP.BMP Wisseman programs: Temporary file [*] TEMP.PLN Wisseman programs: Temporary file [*] TEMPLOCK.DAT DOS Planets: Checksums [*] TONS.HST Standard host: Ship tons "sunk" this turn [*] TONS2.HST THost: weighed tonnage sunk this turn [*] TORPSPEC.DAT Standard static: Torpedoes [*] TRACE.LOG PHost: event trace requested by user (plain text) TRAFFIC.HST Dominate: ? TRUEHOST.DAT SRace: Original TRUEHULL.DAT [*] TRUEHULL.DAT Standard static: Assignment Player <-> Starship Hulls [*] TRUEHULL.NEW SRace: modified TRUEHULL.DAT TURNBASE PDV: ? TURNSTAT.LOG PHost: turn status log (green/red, ...) (plain text) UFO.HST Standard host: Ufos, 3rd party additions [*] UTIL.TMP PHost: Temporary UTILx.DAT Files [*] UTILDATA.CC PCC: UTILx.DAT parser definition (plain text) UTILx.DAT PHost: Information for Client Programs [*] UTILx.EXT PHost: Add-on Information [*] VCR.CFG PlayVCR: configuration of Winplan integrator (plain text) VCR.HST Standard host: VCRs [*] VCRINIT.TMP DOS Planets: Temporary file [*] VCRx.DAT Standard client: Visual Combat Recordings [*] VMx.CC PCC1: Virtual Machine State [*] VPA.INI VPA: configuration file (plain text) VPA.MSG VPA: message templates (plain text) VPACLRx.INI VPA: configuration file (colors) (plain text) VPADATx.INI VPA: configuration file (data transfer) (plain text) VPAMSG.DAT VPA: Message Information [*] VPAMSGx.DAT VPA: Message Information [*] VPASNMx.DAT VPA: ship name scrambling VPAVCR.INI VPA: ? VPAx.DB VPA: Database [*] VPH35.DLL THost: Version 3.5 Signatures [*] VPMIDI.INI Winplan: music configuration (plain text) VPMOVIE.TMP VPMC: State of the world [*] VPSOUND.INI Winplan: sound f/x configuration (plain text) WORMHOLE.TXT PHost: wormholes (plain text) WPVCR.DLL Winplan: Images for the Winplan VCR [*] WRAPPER.LOG PlayVCR: log file of the Winplan integrator (plain text) XTERNCMD.EXT PHost: External Commands (plain text) [*] XTRFCODE.TXT PHost: Special Friendly Codes (plain text) [*] XYPLAN.DAT Standard static: Planet coordinates [*] XYPLAN.HST Standard host: Planet coordinates [*] XYPLANx.DAT Explore Map: per-player starchart (see XYPLAN.DAT) FIELD LIST - WHAT IS STORED WHERE ================================== In many cases, properties of a single object are scattered through many places. This table attempts to aid you in finding what you need. Most important properties and files are listed, some unimportant or obsolete ones have been left out. Much information is transported in messages. In general, when you're looking for the status of an object, you'll find it in some data file (and thus in this table). When you're looking for a report about some action (like "minefield laid" or "planet conquered"), you should look for messages or UTILx.DAT entries. Starships ---------- Auto waypoints AUTOx.DAT (Winplan), NAUTOx.DAT (hacked Winplan) Auto tasks TASKx.DAT (Winplan), VMx.CC (PCC), SCRIPTx.CC (PCC2) Cargo SHIPx.DAT, SHIP.HST Cloak status CLOAKC.HST Engine type SHIPx.DAT, SHIP.HST Experience UTILx.DAT (PHost), AUXDATA.HST (PHost) Fleets FLEETx.CC (PCC) Friendly code SHIPx.DAT, SHIP.HST Heading see Visual Scans, or compute from SHIPx.DAT History data CHARTx.CC (PCC), VPAx.DB (VPA) Mass SHIPXYx.DAT, SHIPXY.HST, or compute from SHIPx.DAT Mission SHIPx.DAT, SHIP.HST; also MISSION.INI Name SHIPx.DAT, SHIP.HST; also see Visual Scans Notepad NOTESx.DAT (Winplan), CHARTx.CC (PCC), INFNOTES.Gx (Informer) Owner SHIPx.DAT, SHIP.HST, SHIPXYx.DAT, SHIPXY.HST Pictures RESOURCE.PLN (image), HULLSPEC.DAT (index) Position SHIPx.DAT, SHIP.HST, SHIPXYx.DAT, SHIPXY.HST Shields CLOAKC.HST Special functions AUXDATA.HST, HULLFUNC.DAT, HULLSPEC.CC (PCC), hardwired in Host / planets.exe / Winplan, SHIPLIST.TXT/HULLFUNC.TXT Speed SHIPx.DAT, SHIP.HST; also see Visual Scans Type SHIPx.DAT, SHIP.HST; also see Visual Scans Visual scans TARGETx.DAT/TARGETx.EXT, KOREx.DAT, SKOREx.DAT, UTILx.DAT (PHost) Waypoint SHIPx.DAT, SHIP.HST Weapons SHIPx.DAT, SHIP.HST Planets & Starbases -------------------- Auto build AUTOx.DAT (Winplan), NAUTOx.DAT (hacked Winplan), CHARTx.CC (PCC) Auto tasks AUTOx.DAT (Winplan), NAUTOx.DAT (hacked Winplan), SCRIPTx.CC (PCC2), VMx.CC (PCC) Base damage BDATAx.DAT, BDATA.HST Base defense BDATAx.DAT, BDATA.HST Base fighters BDATAx.DAT, BDATA.HST Base mission BDATAx.DAT, BDATA.HST Base storage BDATAx.DAT, BDATA.HST Buildings PDATAx.DAT, PDATA.HST Building costs usually hardwired, PCONFIG.SRC (PHost 4.0k+) Building limits usually computed Colonists PDATAx.DAT, PDATA.HST Experience UTILx.DAT (PHost), AUXDATA.HST (PHost) Friendly Code PDATAx.DAT, PDATA.HST Happiness PDATAx.DAT, PDATA.HST History data CHARTx.CC (PCC), VPAx.DB (VPA) Homeworld Ids REFDATA.HST Minerals PDATAx.DAT, PDATA.HST Money PDATAx.DAT, PDATA.HST Name PLANET.NM Notepad NOTESx.DAT (Winplan), CHARTx.CC (PCC) Natives PDATAx.DAT, PDATA.HST, AUXDATA.HST (PHost: original base natives used for cheat check) Owner PDATAx.DAT, BDATAx.DAT, PDATA.HST, BDATA.HST Pictures RESOURCE.PLN (image, formula) Position XYPLAN.DAT, XYPLAN.HST Ship build order BDATAx.DAT, BDATA.HST, AUXDATA.HST (PHost: build queue) Taxes PDATAx.DAT, PDATA.HST Tech levels BDATAx.DAT, BDATA.HST Temperature PDATAx.DAT, PDATA.HST Messages --------- Command messages CMDx.TXT, AUXCMDS.TXT, XTERNCMD.EXT From Host LANG.PLN (Host), PLANG.HST (PHost), VPAx.DB (VPA) From Player MESSx.DAT (DOS), MESS35x.DAT (Winplan) Filter settings MESSx.CC (PCC), MSGx.INI (PCC/VPA), AUXDATA.HST (PHost) To Player MDATAx.DAT, MESS.OLD/EXT/TMP, MESSPNT.OLD/EXT/TMP Other ------ Alliances AUXDATA.HST (PHost), UTILx.DAT (PHost), MDATAx.DAT (as messages), GREY.HST (Host) Beam weapons BEAMSPEC.DAT Build Queue UTILx.DAT (PHost), AUXDATA.HST (PHost), GEN.HST (Host), Build Points UTILx.DAT (PHost), AUXDATA.HST (PHost), GREY.HST (Host) Combat records VCRx.DAT, VCR.HST, KFVCRx.DAT (TKF), FLAKx.DAT (FLAK), FLAKx.HST (FLAK host) Combat results UTILx.DAT (PHost) Combat simulation AFSIM.SAV (AFSim), .CCB file (CCBSim), .KFB file (TKF) Configuration HCONFIG.HST, PCONFIG.SRC/SHIPLIST.TXT/HULLFUNC.TXT, UTILx.DAT (PHost sends configuration to client), MDATAx.DAT (Host sends configuration to client as messages, also many add-ons and host systems) Enemies AUXDATA.HST (PHost, permanent enemies) Engine types ENGSPEC.DAT Explosions KOREx.DAT, UTILx.DAT (PHost) Game names GAMESTAT.DAT (Winplan), PCONFIG.SRC, UTILx.DAT Graphics RESOURCE.PLN (planets.exe), BMP directory (Winplan), WPVCR.DLL (Winplan), CC.RES (PCC) Help texts PLNHELP.DAT (planets.exe), VPLHELP.HLP (Winplan), CC.RES (PCC), PCC2HELP.XML (PCC2) Hull types HULLSPEC.DAT Ion storms KOREx.DAT, UTILx.DAT, GREY.HST, STORM.NM Map drawings CHARTx.CC (PCC), VPAx.DB (VPA) Minefields KOREx.DAT, UTILx.DAT (PHost), MINES.HST, EXTMINES.HST (PHost), CHARTx.CC (PCC) Passwords GENx.DAT, GEN.HST Race names RACE.NM Race numbers FRIDAY.HST, PCONFIG.SRC Race ships TRUEHULL.DAT, TRUEHOST.DAT (SRace) Registration Id FIZZ.BIN, REG.KEY, SCRAM21.OLE, VPH35.DLL Scores GENx.DAT, STAT.CC (PCC), SCORE.CC (PCC2), UTILx.DAT (PHost) Remote control UTILx.DAT (PHost), AUXDATA.HST (PHost) RST Upload path GAMESTAT.DAT (Winplan) Team settings TEAMx.CC (PCC), TEAMS.DAT (PTScore) Timestamp GENx.DAT, LASTTURN.HST, NEXTTURN.HST Torpedoes TORPSPEC.DAT TRN Download path GAMESTAT.DAT (Winplan) Turn number GENx.DAT Ufos KOREx.DAT, UTILx.DAT (General Object), UFO.HST Wormholes KOREx.DAT (as Ufos), UTILx.DAT, WORMHOLE.TXT Version number UTILx.DAT (PHost), MDATAx.DAT (Host, in PBP message), AUXDATA.HST (PHost) Victory condition REFDATA.HST AUTHOR & COPYRIGHT =================== This information was collected by Stefan Reuther in the years 1995 to 2014. Hereby, I place it into the PUBLIC DOMAIN. That is, you may do anything with it: copy it around, change it, translate it... But if you distribute a (possibly changed) copy of this list, or your new product is based in large parts on this list, courtesy should allow a reference to the original thing. This file is continuously updated. If you have new information, bugfixes etc. and send them to me, I will add them to the next version. YOU GET THIS DOCUMENTATION FILE ON AN "AS IS" BASIS, WITHOUT ANY WARRANTIES, THAT IS, EVEN WITHOUT A WARRANTY FOR THE CORRECTNESS, UNDERSTANDABILITY AND USABILITY OF THE GIVEN INFORMATION. YOU USE THE INFORMATION AT YOUR OWN RISK. YOU ARE RESPONSIBLE FOR ALL DAMAGE DONE TO YOU AND OTHERS THROUGH YOUR USE OF THIS INFORMATION. IN NO CASE THE AUTHOR, Stefan Reuther, MAY BE HELD RESPONSIBLE FOR THIS. Well, the information seems to be somewhat correct - I've been using much of this for a long time now in my "Planets Command Center" and other VGAP utility programs. If you don't believe this, I refer you to C:\DOS\DEBUG.EXE and C:\NU\DISKEDIT.EXE. If you want to contact me for whatever reason, mailto:Streu@gmx.de (Stefan Reuther) Updates and some other VGA Planets stuff will be released on my web page at http://phost.de/~stefan/vgapage.html Oh, remember: VGA Planets is (c) copyright and (tm) Trademark by Tim Wisseman. -EOF-