Ren'Py persistent data compatibility during engine upgrades

Handling Persistent Data Across Python Versions

There is no built-in automated migration framework for transforming persistent data schemas during a Ren'Py upgrade. Because Ren'Py 8 moves from Python 2.7 to Python 3, custom Python objects stored in the persistent store may trigger serialization errors (such as UnpicklingError) due to breaking changes in the pickle module.

The Role of config.save_version

config.save_version is a validation tool, not a transformation hook. It allows the engine to detect when a save file was created with an older version of the game and trigger a warning to the user. It does not provide a mechanism to intercept, modify, or migrate the data before the game initializes.

Recommended Migration Mechanism

To migrate custom persistent objects, you must implement a manual version-check and transformation routine during the early initialization phase of your game. Simple data types (integers, strings, booleans) generally migrate without issue, but complex custom classes require a manual rewrite.

The most reliable approach is to store a version integer within the persistent object itself and check it at the start of the game:

label start:
    if persistent.data_version < 2:
        # Perform migration logic here
        # Example: Convert legacy object to a Python 3 compatible format
        $ persistent.data_version = 2
        $ renpy.save_persistent()

Implementation Steps

1. Define a Version Flag: Add a persistent.data_version variable to your project.
2. Detect Legacy Data: In the start label (or a dedicated initialization label), check if the version flag is missing or outdated.
3. Transform Objects: Manually map the values from the legacy custom objects into new, Python 3-compatible structures.
4. Commit Changes: Call renpy.save_persistent() to write the migrated data back to disk.

Assumptions and Uncertainties

This guidance assumes you are moving from a standard Ren'Py 7.x installation to 8.x. It is uncertain whether specific custom C-extensions or highly complex nested objects can be recovered if the pickle load fails entirely before the start label is reached. If the engine crashes during the initial load of the persistent file, you may need to implement a try...except block within an init python block to catch serialization errors and reset specific corrupted keys.

Diagnostic Detail Needed: Are you using custom Python classes stored in persistent, or only standard Ren'Py variables (strings, ints, lists)? If only standard variables are used, manual migration is likely unnecessary.