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 <http://phost.de/~stefan/filefmt.html>.