Skip to main content

Interface: SaveMigration<T>

Defined in: packages/core/src/saves/migrations/types.ts:93

Defines a migration from one game version to another.

Migrations are registered by developers when they make breaking changes to the game save structure. The migration system will automatically chain migrations together to migrate saves from any old version to the current version.

Examples​

Basic migration without specific types:

const migration: SaveMigration = {
  from: "1.0.0",
  to: "1.1.0",
  description: "Added inventory system",
  migrate: (save) => ({ ...save, inventory: [] })
};

Type-safe migration with specific field types:

const migration: SaveMigration<{ player?: { inventory: string[] } }> = {
  from: "1.0.0",
  to: "1.1.0",
  description: "Added inventory system",
  migrate: (save) => {
    const player = save.player || {};
    return {
      ...save,
      player: {
        ...player,
        inventory: [], // TypeScript validates the type
      }
    };
  }
};

Type Parameters​

T​

T extends MigrationGameSaveState = GameSaveState

The shape of the game save state for this migration. Can be a partial type if the migration only touches specific fields. Defaults to GameSaveState. Using specific types provides better type safety and IDE autocomplete.

Properties​

description​

description: string

Defined in: packages/core/src/saves/migrations/types.ts:115

Human-readable description of what this migration does. Used for logging and debugging.

Examples​

"Added player inventory system"
"Renamed 'hp' field to 'health'"

from​

from: string

Defined in: packages/core/src/saves/migrations/types.ts:100

The source version this migration starts from. Should be a valid semver string (e.g., "1.0.0", "1.2.3")

migrate​

migrate: SaveMigrationFn<T>

Defined in: packages/core/src/saves/migrations/types.ts:121

The migration function that transforms the data. Should be pure and not mutate the input.

to​

to: string

Defined in: packages/core/src/saves/migrations/types.ts:106

The target version this migration migrates to. Should be a valid semver string (e.g., "1.1.0", "2.0.0")