Save file format: Difference between revisions
Line 128: | Line 128: | ||
Code to decompress PKWARE implode-encoded data can be found in blast.c in the contrib directory of the zlib tarball. | Code to decompress PKWARE implode-encoded data can be found in blast.c in the contrib directory of the zlib tarball. | ||
Versions older than SAV_VERSION_DEFLATE always use the <code>ImplodeCrypt</code> algorithm. To allow changing save files without | Versions older than SAV_VERSION_DEFLATE always use the <code>ImplodeCrypt</code> algorithm. To allow changing save files without decompressing all data, the value <code>0xffffffff</code> may be used to indicate that the uncompressed size is not known if (and only if) the compression algorithm is <code>ImplodeCrypt</code>. | ||
The rest of the file entry is a list of as many chunk offsets as specified. For versions older than <code>SAV_VERSION_DEFLATE</code>, the actual number of chunks is always 1 or more, even if the file entry says 0. The concatenation of the chunks referenced by these offsets makes up the compressed file data. | The rest of the file entry is a list of as many chunk offsets as specified. For versions older than <code>SAV_VERSION_DEFLATE</code>, the actual number of chunks is always 1 or more, even if the file entry says 0. The concatenation of the chunks referenced by these offsets makes up the compressed file data. |
Revision as of 23:57, 8 February 2012
This page describes the save format used by Arx Fatalis as well as Arx Libertatis extensions. All integers are encoded in little-endian byte order. Types are the same as in platform/Platform.h
- s (signed integer) / u (unsigned integer) / f (float), followed by the number of bits.
Arx save file container (.sav)
Save files are stored in a generic container that maps names (arbitrary strings) to chunks of data. Arx Libertatis adds two extensions to the vanilla Arx Fatalis .sav format. The .sav container format can be read and written using the SaveBlock
class (io/SaveBlock.h
)
Header
The file header starts at byte position 0 - there is no magic number.
Type | Description |
---|---|
u32 | File table offset |
The file table offset is the location of the file table (in bytes) relative to the first byte after the header. Add 4 bytes to get the offset relative to the start of the file.
File table
The file table starts with a file table header:
File table header
Type | Description |
---|---|
u32 | Format version |
u32 | Number of file entries |
Currently, the following version numbers are defined.
Value | Name | Description |
---|---|---|
0x00010000
|
SAV_VERSION_LEGACY
|
Legacy version |
0x00010001
|
SAV_VERSION_RELEASE
|
Current Arx Fatalis version |
0x00020000
|
SAV_VERSION_DEFLATE
|
Added support for different compression algorithms (Arx Libertatis extension) |
0x00020001
|
SAV_VERSION_NOEXT
|
Removed ".sav" suffix from internal filenames (Arx Libertatis extension) |
The file table is followed by the specified number of file entries. For save files with version SAV_VERSION_LEGACY
the first file entry should be ignored.
File table entries
Type | Description |
---|---|
null-terminated string | File name |
Each file table entry is preceded by a null-terminated string - the file name. Versions older than SAV_VERSION_NOEXT
store file names case-insensitively and append ".sav". When loading such versions, the filename should be converted to lowercase and the ".sav" extension removed.
For versions older than SAV_VERSION_DEFLATE
:
Type | Description |
---|---|
u32 | Stored (compressed) file size - This can be ignored and calculated from chunk sizes. |
u32 | Number of chunks - 0 means 1! |
u32 | Useless data. This can be safely ignored |
For SAV_VERSION_DEFLATE
and newer:
Type | Description |
---|---|
u32 | Uncompressed file size |
u32 | Number of chunks |
u32 | Compression algorithm |
Currently, the following compression algorithms are defined.
Value | Name | Description |
---|---|---|
0
|
Stored
|
No compression. Data is stored as-is. |
1
|
ImplodeCrypt
|
Data is compressed using the PKWARE implode library. The result is bitwise negated. |
2
|
Deflate
|
Data is compressed using the ZLIB deflate format. |
Code to decompress PKWARE implode-encoded data can be found in blast.c in the contrib directory of the zlib tarball.
Versions older than SAV_VERSION_DEFLATE always use the ImplodeCrypt
algorithm. To allow changing save files without decompressing all data, the value 0xffffffff
may be used to indicate that the uncompressed size is not known if (and only if) the compression algorithm is ImplodeCrypt
.
The rest of the file entry is a list of as many chunk offsets as specified. For versions older than SAV_VERSION_DEFLATE
, the actual number of chunks is always 1 or more, even if the file entry says 0. The concatenation of the chunks referenced by these offsets makes up the compressed file data.
Chunk offsets
Type | Description |
---|---|
u32 | Chunk size |
u32 | Chunk offset |
The chunk offset is the location of the chunk data (in bytes) relative to the first byte after the header. Add 4 bytes to get the offset relative to the start of the file. The chunk size is given in bytes. There is no guarantee that all parts of the .sav file are used in chunks or the file table.
Saved structures
TODO