Ur-Quan Masters State Files --------------------------- Statefiles are a legacy component of the UQM runtime and savegame format. They represent largish (10-64KB) chunks of semi-structured data that the engine used to keep on disk during gameplay, checking and updating it as needed. These files were then dumped into and restored from save files in a compressed form. In UQM as it exists now (0.7), these files exist as expandable memory arrays that are consulted as if they were files. UQM 0.8 will change the savegame format to remove the compression (64K just isn't much anymore) and put more structure to the data within. The statefile abstraction itself is not guaranteed to be retained, and indeed core team considers it kind of horrible and would like to destroy it. There are three state files. STARINFO_FILE aka "starinfo.dat" -------------------------------- This is probably the most reasonable of the three. It keeps track of which star systems you have visited, and which mineral deposits and interesting life forms and gadgets you have harvested from the worlds therein. The file begins with one DWORD for every star system in the game. (There are 502 star systems, defined in a gigantic array in starmap_array in plandata.c). The DWORD is 0 if the star system is unvisited. It is otherwise an absolute offset within the state file. Generally speaking, UQM star systems are procedurally generated with a PRNG and various properties of the star including its type and location. Thus, the information in starmap.c is sufficient to provide an accounting of the number and quality of worlds in any given system. Each world can have up to 32 each of mineral deposits, energy signatures, or life forms. Thus, each world, in order, in the system will be listed at its offset with three DWORDS, representing mineral, energy, and biological entities respectively. Captured entities have a 1 bit set. With a little over 3,800 visitable celestial bodies, this state file is capped at a little under 50 KB. RANDGRPINFO_FILE aka "randgrp.dat" ---------------------------------- This is a "battle group file" - it tracks the information regarding groups of ships that you can encounter in interplanetary space. This file gives the location information for all ships in the last solar system you visited, and it tracks the fleet composition, health, &c for ships randomly generated due to visiting a solar system in some species's sphere of influence. Random battle groups are reset after a week in HyperSpace or upon arrival in some other star system. The data structures, and the reader/writer functions for them, are primarily defined in grpinfo.c. The RANDGRPINFO file starts with a GROUP_HEADER struct, specifying which star this information is for, when the data expires, and then 65 offsets into the file. This is a *one-indexed array* for randomly-generated groups. This is because the offset for group zero points to an entirely different data structure: the "Group List". This gives the starmap depiction and location on the Interplanetary map of every battle group in the system, whether it is randomly generated or pre-defined. This comprises two bytes (the ID of the most recently encountered group, and then the number of groups), followed by a series of 17-byte chunks representing battle groups. These are a byte indicating the race identifier of the fleet (battle groups can be mixed-composition, but only one ship appears on the map at a time; this specifies that) followed by 16 bytes that represent an IP_GROUP structure. See the Read/WriteIpGroup functions in gengrp.c for the exact layout in the virtual file. There's a lot of wasted space there, a legacy of the time when these files were actually structure dumps on 32-bit machines with very specific memory layouts. The offsets that are not Group Zero have a similar layout, interpreted differently. Each of these represents a single battle group. It retains the two-byte prologue, the second of which specifies the number of 17-byte chunks to follow. The first byte here is the displayed race identifier, again, and then each 17-byte chunk is that ship's particular race ID followed by a 16-byte representation of a SHIP_FRAGMENT. There are no requirements about order of layout or total size of this file; the only requirement is that there is a GROUP_HEADER at offset zero and that the extents described in the valid offsets do not overlap. DEFGRPINFO_FILE aka "defgrp.dat" -------------------------------- This is a random-access scratch space for battle groups that are deliberately placed by the plot. There's one GROUP_HEADER in this file, somewhere, for each star system that has ever had predefined ships and that the player has visited. There is *no guarantee of any kind* as to where they are, a priori. This information instead lives within the game state array, a 155-byte-long bitfield that is mostly used for storing plot events and event flags. 32-bit values within this array store the relevant offsets for their fleets, or a 0 if they have not yet been encountered. In vanilla UQM, there are 14 of these values, corresponding to the Ur-Quan Probe, the Zoq-Fot-Pik scout, the Shofixti Survivor, the Unzervalt Guardian, the Sa-Matra, and the nine Melnorme traders in TrueSpace. Each of these has a corresponding entry in the game state array that ends in _OFFS0. (Due to the implementation of GET_GAME_STATE, these values actually are stored as four eight-bit values each, but this can be ignored pretty much everywhere but the definition of the states themselves). If one of these offsets is non-zero, then that offset in the DEFGRPINFO_FILE will have a SHIP_FRAGMENT-based group definition in the same format as the ones in RANDGRPINFO_FILE. The Game State array uses 0 as a special value to mean "this predefined battle group has not yet been spawned." Because of that, 0 is not a legal offset to place a GROUP_HEADER. To ensure that no GROUP_HEADER is placed there, a zero is written to the first byte of the file. That way, the first defined group (which, for vanilla UQM, will always be the Ur-Quan Probe) thus begins at offset 1.