Ren'Py Engine and Persistent Data: Recovery Logic During Failed Upgrades

Question

Upgrade State Consistency
Ren'Py utilizes renpy.version within persistent data to trigger the renpy.game.upgrade() function when a version mismatch is detected. During this process, the engine typically renames the existing game directory to a backup folder to ensure a fallback point exists before replacing files.

Interoperability Constraints
A critical uncertainty exists regarding the state of the application if the upgrade process is interrupted after the directory rename but before the new files are fully written. Since the engine does not automatically revert to the previous version upon a mid-process crash, the game may launch in a partial state where the script files do not match the persistent data version.

This creates a conflict between the engine's version detection logic and the physical presence of the game_backup_ directory, potentially leading to runtime errors before the upgrade prompt can be re-triggered.

Does the engine prioritize the renpy.version check over the presence of a backup directory during the boot sequence?
  In what specific scenario will the engine offer a restore from the backup folder without requiring a manual developer override?

Siddharth · Answer

Upgrade State and Recovery Logic
The Ren'Py engine prioritizes the renpy.version check stored within the persistent data over the physical presence of a backup directory. If the engine boots and finds a version mismatch, it triggers the upgrade sequence. However, the engine does not possess an automated "rollback" mechanism that detects a partial file write or a mid-process crash to automatically restore from a game_backup_ folder.

Engine Behavior and Constraints
Because the version check is the primary trigger, a crash during the upgrade process often leaves the application in a corrupted state. If the script files are missing or mismatched but the persistent data already reflects the "new" version (or is corrupted by the interrupted process), the engine will attempt to boot into the current (incomplete) state rather than reverting to the backup.

Confirmed Facts:

Persistent data is serialized via Python's pickle module, making it highly sensitive to structural changes between versions.
  The game_backup_ directory is a filesystem-level safeguard, not a state-machine managed recovery point that the engine monitors during every boot sequence.
  Version mismatches typically result in AttributeError or ImportError if the persistent objects no longer align with the loaded script definitions.

Recovery Scenarios
The engine will not offer a restore from the backup folder without manual intervention or a developer-implemented recovery script. To resolve a failed upgrade state, you must manually restore the files or reset the persistent state.

Manual Recovery Steps:

Filesystem Restore: Manually move the contents of the game_backup_ directory back into the primary game/ folder, overwriting the partial installation.
  Persistent Reset: If the game boots but crashes due to corrupted persistent data, the persistent file must be cleared. This can be done via the developer console: persistent._clear()
  Physical Deletion: Locate the persistent file within the directory defined by config.save_directory and delete it manually.

Note: Resetting persistent data is irreversible and will wipe all global flags and unlocked content.

Diagnostic Requirement
To determine if the crash is caused by a version mismatch or a corrupted pickle object, please provide the specific Python traceback (e.g., AttributeError vs ImportError) occurring at boot.

Ren'Py Engine and Persistent Data: Recovery Logic During Failed Upgrades

Upgrade State Consistency

Interoperability Constraints

1 answer

Upgrade State and Recovery Logic

Engine Behavior and Constraints

Recovery Scenarios

Diagnostic Requirement

Your perspective belongs here.

0 question comments