Document the new savefile format.
This commit is contained in:
Michael Martin
@@ -0,0 +1,145 @@
|
||||
SAVEFILE FORMAT
|
||||
---------------
|
||||
|
||||
This document represents a work in progress. The save format described
|
||||
here will evolve before finalization for 0.8.
|
||||
|
||||
The old save file format used a custom compressor and was very finicky
|
||||
about padding and alignment for machines that were not even in use
|
||||
anymore. It was also extremely fragile and hard for modders to extend.
|
||||
|
||||
The new save format seeks to alleviate these problems.
|
||||
|
||||
GENERAL FORMAT
|
||||
--------------
|
||||
|
||||
All multibyte values are little-endian. There are no alignment
|
||||
restrictions inherent in the format.
|
||||
|
||||
The save file begins with a 32-bit identifier and version number (a
|
||||
"magic number") that identifies it as a particular version of an UQM
|
||||
save file. If the format changes in a way that older versions of UQM
|
||||
cannot read it, either the identifier or the version number should
|
||||
change.
|
||||
|
||||
The vanilla UQM system has a save number of 0x01534d55, which, if
|
||||
interpreted as a byte stream is UMS (Ur-quan Masters Save) and a
|
||||
binary 1 (version 1). Vanilla UQM reserves the tags "UMSx" for all x
|
||||
for use to evolve the core save format. Modders are encouraged, but
|
||||
not required, to also use the fourth bit as a version number.
|
||||
|
||||
Following the 32-bit file identifier comes a series of chunks. All
|
||||
chunks have the same general format: a 32-bit tag, similar to that of
|
||||
the file as a whole, followed by a 32-bit integer specifying the size
|
||||
of the chunk, and then that many bytes of data.
|
||||
|
||||
Bytes in a chunk tag should all be in the range 0x20-0x7E -- that is,
|
||||
they should be printable ASCII characters. Chunks are traditionally
|
||||
referred to by their tag names.
|
||||
|
||||
Chunks whose tag has a least significant byte in the range 0x41-0x5a,
|
||||
inclusive---that is to say, whose names start with a capital
|
||||
letter---are mandatory. If you extend the set of mandatory chunks, you
|
||||
must increase the version of the file. Tags that do not start with a
|
||||
capital letter may be ignored by other versions of UQM that otherwise
|
||||
understand that data version.
|
||||
|
||||
(Why would you want to have ignorable bits of save file? Such chunks
|
||||
may contain helpful but ancillary information. For instance, at the
|
||||
time of this writing, there is an outstanding bug that life forms are
|
||||
un-stunned if you save and load in orbit. One could add a new chunk
|
||||
that tracks the stunned status of life forms on the planet you're in
|
||||
orbit around, and just revert to the old behavior if it's not there or
|
||||
if you're running on a version without that fix. Such an ancillary
|
||||
data chunk would have a tag like "stun" or "biot".)
|
||||
|
||||
Note also that despite being "mandatory", it is not the case that all
|
||||
chunks will be present in all save files. Different data is saved out
|
||||
depending on the situation you saved in.
|
||||
|
||||
Unless otherwise specified, chunks may be stored in any order in the
|
||||
save file.
|
||||
|
||||
CHUNK INVENTORY
|
||||
---------------
|
||||
|
||||
- "Summ": Summary. This chunk must come first. This chunk
|
||||
carries the flagship configuration information and some overview
|
||||
information that is displayed on the savegame view screen. It is of
|
||||
variable length, because the last element of this chunk is the name
|
||||
of the save as chosen by the user.
|
||||
|
||||
- "GlSt": Global State. This chunk must come second, after
|
||||
Summ. Represents most of the data in the global state structure in
|
||||
globdata.h.
|
||||
|
||||
- "GmSt": Game State. This chunk must come third, after GlSt. This is
|
||||
the gigantic bitfield that the GET_GAME_STATE macros modify. It is
|
||||
variably-sized; excess bytes in this array will be ignored, and if
|
||||
there are insufficient bytes in the save file, the remaining bits
|
||||
will be initialized to zero. Modders setting extra event flags may
|
||||
be able to import a legacy game into a sensible state by choosing
|
||||
their defaults judiciously.
|
||||
|
||||
- "Evts": Events. An array of values describing scripted future
|
||||
events.
|
||||
|
||||
- "Enct": Encounters. Details of battle groups that are pursuing you
|
||||
through HyperSpace.
|
||||
|
||||
- "RacQ": Available Race Queue. Which species are active in the game,
|
||||
where they are, etc. Corresponds to avail_race_q.
|
||||
|
||||
- "IGpQ": Interplanetary Group Queue. Battlegroup information for
|
||||
ships in your current star system, if you're in a current star
|
||||
system. It is currently unclear whether or not this ever needs to
|
||||
exist, but in keeping with legacy logic, it will appear whenever you
|
||||
are in a star system but not in the middle of an encounter.
|
||||
|
||||
- "NpcQ": NPC Queue. Battlegroup information for ships you are in the
|
||||
middle of encountering. This should only appear if your loaded
|
||||
activity is "IN_ENCOUNTER" and loading the game will trigger the red
|
||||
alert.
|
||||
|
||||
- "ShpQ": Ship Queue. Battlegroup information for your flagship's
|
||||
escort fleet.
|
||||
|
||||
- "Star": Star Description. Basic indexing information to indicate
|
||||
which star system you are in.
|
||||
|
||||
- "SISF": Star Info State File. An index into which planetside
|
||||
resources you have investigated and collected. See
|
||||
doc/devel/statefiles for more details.
|
||||
|
||||
- "DGSF": Defined Group State File. Battlegroup information for
|
||||
space-based encounters dictated by the plot. See
|
||||
doc/devel/statefiles for more details.
|
||||
|
||||
- "RGSF": Random Group State File. Battlegroup information for random
|
||||
encounters in interplanetary space. See doc/devel/statefiles for
|
||||
more details.
|
||||
|
||||
THINGS LEFT TO DO BEFORE MERGING
|
||||
--------------------------------
|
||||
|
||||
- Actually enforce little-endianness of everything that hits the disk.
|
||||
- This is a simple matter of improving the read_* and write_*
|
||||
functions in load.c and save.c.
|
||||
|
||||
- There are 448 bits in GmSt that are actually indices into DGSF. They
|
||||
shouldn't be there. In fact, they shouldn't even be in the
|
||||
GAME_STATE array either. They should be an array of DWORDs living
|
||||
independently in the global state
|
||||
- First, we should juggle the order of the state bits so that
|
||||
they're all at the end. That way we can ultimately just truncate
|
||||
GmSt and everything will be fine. We can do that without
|
||||
complicating legacy loads much.
|
||||
|
||||
- The State Files are (except maybe for Star Info) a horrible mess and
|
||||
we should not be replicating them in the save file. We should
|
||||
instead be regenerating them from more structured forms.
|
||||
- This is complicated by the fact that there are references to the
|
||||
_GSF chunks in both GlSt (BattleGroupRef) and GmSt
|
||||
(*_GRPOFFSET*). I have a good handle on what needs to be done to
|
||||
GmSt, but the significance of the GlSt pointer still requires
|
||||
research.
|
||||
Reference in New Issue
Block a user