Motivation / Problem

We have a bunch of different lists, which are all done slightly different.

• We have a "fixed-length" list, where the code dictates the length. No validation is done if that same value was also used when writing to disk, which means we have plenty of savegame bumps for cases where it did.
• We have lists like SL_REFLIST that have a 32bit length indicator.
• We have all kind of custom stuff with SL_STRUCTLIST, where sometimes the length is stored in the parent blob, saved/loaded to a global. But sometimes totally different solutions are used.

This makes self-described savegames really hard (the ultimate goal of this set of PRs, see #9322), but also means savegame-readers need to be really aware of what they are reading, and support a lot of different savegame-versions to do the right thing.

Description

So .. as you might expect, I set out to fix that problem. Now the rules are simple:

• Any list, no matter who/what you are, has a gamma before the list to indicate how many entries are in the list.

In most cases this means you know the length. For SL_STRUCT this is not the case, and as such you need to know what struct is stored to figure out the length. This will be addressed in a later PR.

As using SL_STRUCT is normally only useful if it is an optional field (why else bother making it in a new struct, and not just embed it in the parent?), internally it is a SL_STRUCTLIST of either 0 or 1 in length. So if it is empty (nothing saved), the length-field is 0. Otherwise, length-field is 1.

Limitations

• A lot of testing is involved, see Codechange: add and use the ability to store (lists of) structs in savegames #9339 and Feature: store table headers for each chunk in savegame #9322 for details. So no known issues or limitations.
• Other solutions have been considered, instead of a length-field, like for example a "type", where the last entry is an empty one indicating "end". But given the current state of the code, that is vastly more work.

Checklist for review

Some things are not automated, and forgotten often. This list is a reminder for the reviewers.

• The bug fix is important enough to be backported? (label: 'backport requested')
• This PR affects the save game format? (label 'savegame upgrade')
• This PR affects the GS/AI API? (label 'needs review: Script API')
  • ai_changelog.hpp, gs_changelog.hpp need updating.
  • The compatibility wrappers (compat_*.nut) need updating.
• This PR affects the NewGRF API? (label 'needs review: NewGRF')
  • newgrf_debug_data.h may need updating.
  • PR must be added to API tracker