Skip to content

DEV: Handling updates and migrations

Blizzardsev edited this page Sep 26, 2022 · 1 revision

Data Migration Scripts

Creating migrations is a simple process, the key thing to keep in mind is that there are only 2 levels at which we run updates:

  1. init 10
  2. and in ch30_init (this is a label, meaning we run this at runtime)

This is due to potential race conditions and conflicts in old/new updates, as adding more levels can become increasingly confusing to maintain.

To create an update, simply define a function at the bottom of zz_data-migrations.rpy, and add the @migration decorator.

  • The first argument can accept multiple versions that consolidate to a single version to migrate to, allowing reduction of duplicated code which would be identical of two version moving to the same single version.
  • The second argument is the version being migrated to.
  • The final argument is optional, this indicates when this function is being run. Either at init 10 or actual runtime. This is marked by the enum MigrationRuntimes which has INIT and RUNTIME as values.

As an additional, it is theoretically possible for an update script to be run more than once, provided the stored old version does not change and/or the user has reverted to an old build, then back up to a new build. That said, updates past the current version of the game (defined by config.version) will not be run.

Sample Code:

#This runs a migration from version 0.0.0 to 0.0.1, and runs during the init phase, specifically at init 10.
#This script serves an example and hence, does nothing. All arguments are present however "runtime" is not necessary
#To run this during runtime instead, use `MigrationRuntimes.RUNTIME` instead
@migration(["0.0.0"], "0.0.1", runtime=MigrationRuntimes.INIT)
def to_0_0_1():
    pass