liveBook · Manning

Backward compatibility

As explained in High Performance Unity Game Development

Backward compatibility is the ability of newer software or data formats to continue working with older versions or previously created data.

A survival game update adds a field to its save data. Players with an older save still need to load their progress, but the new binary reader expects a different layout. Backward compatibility means keeping a way to read that older layout while saving new data in the current one. section 7.1.5

Handle a save-format change without overwriting the recovery path:

  • Write the new layout to a versioned filename, such as gamedata_v2.dat, leaving gamedata_v1.dat intact. section 7.1.5
  • Give each known layout its own reader. Try the current save first; if it is absent, try the version 1 reader. section 7.1.5 section 7.4
Listing 7.15 Loading the current save or falling back to an older version
if (GameDataIO.LoadLocal(m_gameData))
{
    Debug.Log("loaded version 2");
}
else if (GameDataIO.LoadLocalVersion1(m_gameData))
{
    Debug.Log("loaded version 1");
}

The load call tries version 2, then falls back to the version 1 reader. Each reader handles one file layout. section 7.1.5

A change in balance data creates a different problem: the number of enemy slots available now may differ from the number written to a save. Read the saved enemy count rather than assuming the current array length matches it. If the save contains fewer enemies, read only those records. If it contains more, read every record but copy only those that fit. Linear reading is easier to follow and debug than skipping through the file with Seek(). section 7.1.6

Listing 7.16 Handling the loading of more enemies than allocated
public static bool LoadLocal(GameData gameData, Balance balance)
{
    string fileName = Application.persistentDataPath +
                      "/DODSurvivor/gamedata_v" + 
                      VERSION + 
                      ".dat";
    if (File.Exists(fileName))
    {
        using (FileStream stream = File.Open(fileName, FileMode.Open))
        using (BinaryReader br = new BinaryReader(stream))
        {
            int numEnemies = br.ReadInt32();
            for (int i = 0; i < numEnemies; i++)
            {
                float x = br.ReadSingle(); #A
                float y = br.ReadSingle(); #A
                if(i < balance.NumEnemies) #B
                {
                    gameData.EnemyPosition[i].x = x; #C
                    gameData.EnemyPosition[i].y = y; #C
                }
            }
            return true;
        }
    }
    return false;
}

The loader reads every saved enemy position and writes it to GameData only when its index fits the current balance allocation. section 7.1.6

Array indices can also change when a new enemy type changes the order of balance files. Save an immutable unique identifier alongside each enemy’s game data, then use it to find that enemy’s current index when loading. A dictionary can perform this remapping once during loading, keeping its lookups out of the gameplay loop. section 10.6 section 10.8

Compatibility code adds branches and maintenance work, so add it when old saves actually need support. Balance files have a different policy: load the latest balance rather than making older balance formats playable, but retain old versions to reproduce reported bugs with the conditions players experienced. section 7.4 section 9.7

How High Performance Unity Game Development covers it

How deep it goes
Works through version-specific readers, fallback loading, bounded array copying, and identifier-based index remapping; cautions that each compatibility branch adds complexity.
Examples
Uses version 1 and 2 save files, changed enemy counts, and an added enemy that shifts existing indices.
What it assumes
Assumes familiarity with C# file I/O, binary readers, arrays, and game save data; demonstrates the compatibility changes rather than teaching those APIs from zero.
What you can do after
Build it from scratch using versioned binary readers, saved enemy counts, and immutable identifiers to load older saves without runtime remapping.
How it connects
Connects binary serialization and versioned files to balance data, array indices, unique identifiers, and load-time dictionaries.

Also explained in

Compare how 22 books explain backward compatibility →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of High Performance Unity Game Development. The section links point to the parts of the book it draws on.