docs/savegame_format.md

   1 # OpenTTD's Savegame Format
   2
   3 Last updated: 2021-06-15
   4
   5 ## Outer container
   6
   7 Savegames for OpenTTD start with an outer container, to contain the compressed data for the rest of the savegame.
   8
   9 `[0..3]` - The first four bytes indicate what compression is used.
  10 In ASCII, these values are possible:
  11
  12 - `OTTD` - Compressed with LZO (deprecated, only really old savegames would use this).
  13 - `OTTN` - No compression.
  14 - `OTTZ` - Compressed with zlib.
  15 - `OTTX` - Compressed with LZMA.
  16
  17 `[4..5]` - The next two bytes indicate which savegame version used.
  18
  19 `[6..7]` - The next two bytes can be ignored, and were only used in really old savegames.
  20
  21 `[8..N]` - Next follows a binary blob which is compressed with the indicated compression algorithm.
  22
  23 The rest of this document talks about this decompressed blob of data.
  24
  25 ## Data types
  26
  27 The savegame is written in Big Endian, so when we talk about a 16-bit unsigned integer (`uint16`), we mean it is stored in Big Endian.
  28
  29 The following types are valid:
  30
  31 - `1` - `int8` / `SLE_FILE_I8` -8-bit signed integer
  32 - `2` - `uint8` / `SLE_FILE_U8` - 8-bit unsigned integer
  33 - `3` - `int16` / `SLE_FILE_I16` - 16-bit signed integer
  34 - `4` - `uint16` / `SLE_FILE_U16` - 16-bit unsigned integer
  35 - `5` - `int32` / `SLE_FILE_I32` - 32-bit signed integer
  36 - `6` - `uint32` / `SLE_FILE_U32` - 32-bit unsigned integer
  37 - `7` - `int64` / `SLE_FILE_I64` - 64-bit signed integer
  38 - `8` - `uint64` / `SLE_FILE_U64` - 64-bit unsigned integer
  39 - `9` - `StringID` / `SLE_FILE_STRINGID` - a StringID inside the OpenTTD's string table
  40 - `10` - `str` / `SLE_FILE_STRING` - a string (prefixed with a length-field)
  41 - `11` - `struct` / `SLE_FILE_STRUCT` - a struct
  42
  43 ### Gamma value
  44
  45 There is also a field-type called `gamma`.
  46 This is most often used for length-fields, and uses as few bytes as possible to store an integer.
  47 For values <= 127, it uses a single byte.
  48 For values > 127, it uses two bytes and sets the highest bit to high.
  49 For values > 32767, it uses three bytes and sets the two highest bits to high.
  50 And this continues till the value fits.
  51 In a more visual approach:
  52 ```
  53   0xxxxxxx
  54   10xxxxxx xxxxxxxx
  55   110xxxxx xxxxxxxx xxxxxxxx
  56   1110xxxx xxxxxxxx xxxxxxxx xxxxxxxx
  57   11110--- xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx
  58 ```
  59
  60 ## Chunks
  61
  62 Savegames for OpenTTD store their data in chunks.
  63 Each chunk contains data for a certain part of the game, for example "Companies", "Vehicles", etc.
  64
  65 `[0..3]` - Each chunk starts with four bytes to indicate the tag.
  66 If the tag is `\x00\x00\x00\x00` it means the end of the savegame is reached.
  67 An example of a valid tag is `PLYR` when looking at it via ASCII, which contains the information of all the companies.
  68
  69 `[4..4]` - Next follows a byte where the lower 4 bits contain the type.
  70 The possible valid types are:
  71
  72 - `0` - `CH_RIFF` - This chunk is a binary blob.
  73 - `1` - `CH_ARRAY` - This chunk is a list of items.
  74 - `2` - `CH_SPARSE_ARRAY` - This chunk is a list of items.
  75 - `3` - `CH_TABLE` - This chunk is self-describing list of items.
  76 - `4` - `CH_SPARSE_TABLE` - This chunk is self-describing list of items.
  77
  78 Now per type the format is (slightly) different.
  79
  80 ### CH_RIFF
  81
  82 (since savegame version 295, this chunk type is only used for MAP-chunks, containing bit-information about each tile on the map)
  83
  84 A `CH_RIFF` starts with an `uint24` which together with the upper-bits of the type defines the length of the chunk.
  85 In pseudo-code:
  86
  87 ```
  88 type = read uint8
  89 if type == 0
  90     length = read uint24
  91     length |= ((type >> 4) << 24)
  92 ```
  93
  94 The next `length` bytes are part of the chunk.
  95 What those bytes mean depends on the tag of the chunk; further details per chunk can be found in the source-code.
  96
  97 ### CH_ARRAY / CH_SPARSE_ARRAY
  98
  99 (this chunk type is deprecated since savegame version 295 and is no longer in use)
 100
 101 `[0..G1]` - A `CH_ARRAY` / `CH_SPARSE_ARRAY` starts with a `gamma`, indicating the size of the next item plus one.
 102 If this size value is zero, it indicates the end of the list.
 103 This indicates the full length of the next item minus one.
 104 In psuedo-code:
 105
 106 ```
 107 loop
 108     size = read gamma - 1
 109     if size == -1
 110         break loop
 111     read <size> bytes
 112 ```
 113
 114 `[]` - For `CH_ARRAY` there is an implicit index.
 115 The loop starts at zero, and every iteration adds one to the index.
 116 For entries in the game that were not allocated, the `size` will be zero.
 117
 118 `[G1+1..G2]` - For `CH_SPARSE_ARRAY` there is an explicit index.
 119 The `gamma` following the size indicates the index.
 120
 121 The content of the item is a binary blob, and similar to `CH_RIFF`, it depends on the tag of the chunk what it means.
 122 Please check the source-code for further details.
 123
 124 ### CH_TABLE / CH_SPARSE_TABLE
 125
 126 (this chunk type only exists since savegame version 295)
 127
 128 Both `CH_TABLE` and `CH_SPARSE_TABLE` are very similar to `CH_ARRAY` / `CH_SPARSE_ARRAY` respectively.
 129 The only change is that the chunk starts with a header.
 130 This header describes the chunk in details; with the header you know the meaning of each byte in the binary blob that follows.
 131
 132 `[0..G]` - The header starts with a `gamma` to indicate the size of all the headers in this chunk plus one.
 133 If this size value is zero, it means there is no header, which should never be the case.
 134
 135 Next follows a list of `(type, key)` pairs:
 136
 137 - `[0..0]` - Type of the field.
 138 - `[1..G]` - `gamma` to indicate length of key.
 139 - `[G+1..N]` - Key (in UTF-8) of the field.
 140
 141 If at any point `type` is zero, the list stops (and no `key` follows).
 142
 143 The `type`'s lower 4 bits indicate the data-type (see chapter above).
 144 The `type`'s 5th bit (so `0x10`) indicates if the field is a list, and if this field in every record starts with a `gamma` to indicate how many times the `type` is repeated.
 145
 146 If the `type` indicates either a `struct` or `str`, the `0x10` flag is also always set.
 147
 148 As the savegame format allows (list of) structs in structs, if any `struct` type is found, this header will be followed by a header of that struct.
 149 This nesting of structs is stored depth-first, so given this table:
 150
 151 ```
 152 type   | key
 153 -----------------
 154 uint8  | counter
 155 struct | substruct1
 156 struct | substruct2
 157 ```
 158
 159 With `substruct1` being like:
 160
 161 ```
 162 type   | key
 163 -----------------
 164 uint8  | counter
 165 struct | substruct3
 166 ```
 167
 168 The headers will be, in order: `table`, `substruct1`, `substruct3`, `substruct2`, each ending with a `type` is zero field.
 169
 170 After reading all the fields of all the headers, there is a list of records.
 171 To read this, see `CH_ARRAY` / `CH_SPARSE_ARRAY` for details.
 172
 173 As each `type` has a well defined length, you can read the records even without knowing anything about the chunk-tag yourself.
 174
 175 Do remember, that if the `type` had the `0x10` flag active, the field in the record first has a `gamma` to indicate how many times that `type` is repeated.
 176
 177 #### Guidelines for network-compatible patch-packs
 178
 179 For network-compatible patch-packs (client-side patches that can play together with unpatched clients) we advise to prefix the field-name with `__<shortname>` when introducing new fields to an existing chunk.
 180
 181 Example: you have an extra setting called `auto_destroy_rivers` you want to store in the savegame for your patched client called `mypp`.
 182 We advise you to call this setting `__mypp_auto_destroy_rivers` in the settings chunk.
 183
 184 Doing it this way ensures that a savegame created by these patch-packs can still safely be loaded by unpatched clients.
 185 They will simply ignore the field and continue loading the savegame as usual.
 186 The prefix is strongly advised to avoid conflicts with future-settings in an unpatched client or conflicts with other patch-packs.
 187
 188 ## Scripts custom data format
 189
 190 Script chunks (`AIPL` and `GSDT`) use `CH_TABLE` chunk type.
 191
 192 At the end of each record there's an `uint8` to indicate if there's custom data (1) or not (0).
 193
 194 There are 6 data types for scripts, called `script-data-type`.
 195 When saving, each `script-data-type` starts with the type marker saved as `uint8` followed by the actual data.
 196 - `0` - `SQSL_INT`:
 197   - an `int64` with the actual value (`int32` before savegame version 296).
 198 - `1` - `SQSL_STRING`:
 199   - an `uint8` with the string length.
 200   - a list of `int8` for the string itself.
 201 - `2` - `SQSL_ARRAY`:
 202   - each element saved as `script-data-type`.
 203   - an `SQSL_ARRAY_TABLE_END` (0xFF) marker (`uint8`).
 204 - `3` - `SQSL_TABLE`:
 205   - for each element:
 206     - key saved as `script-data-type`.
 207     - value saved as `script-data-type`.
 208   - an `SQSL_ARRAY_TABLE_END` (0xFF) marker (`uint8`).
 209 - `4` - `SQSL_BOOL`:
 210   - an `uint8` with 0 (false) or 1 (true).
 211 - `5` - `SQSL_NULL`:
 212   - (no data follows)
 213
 214 The first data type is always a `SQSL_TABLE`.