flutter3d
Showcase Changelog 62 packages API reference

Saves that survive an update

since 1.0.0-rc.1 Widgets and the rest

A save outlives the build that wrote it. Between releases a health bar becomes a row of hearts and a key ring appears, and the save from last month still has to open. It has to open the way the player left it, not with the renamed field quietly back at its default. A save also lives in more than one place, a phone and a tablet say, and sooner or later the two copies differ.

Three pieces cover this. SaveSchema in flutter3d_sim is a game's list of migrations. Autosave in flutter3d_game writes the run at the moments a session tends to end. SaveSync keeps a copy in the cloud and settles the two copies by step and digest.

The page keeps everything in memory: the storage is a map and the cloud is one slot. The two blocks are the run on this device and the run in the cloud, as tall as their step counts, and the hearts are what an old save's health became.

Step 1: A schema is its migrations #

A migration takes the run's fields at one version and returns them at the next. There is no version number to bump, because the version is the number of migrations. A number kept beside the list could be raised without writing one, and a save from the version in between would then be read as current, which is the failure this exists to stop. A change that needs no rewriting is a migration that returns its argument, so the history stays complete.

/// The game's save data, by version. Version 0 kept health as a number;
/// version 1 made it a row of hearts; version 2 added a key ring. The
/// version is the number of migrations, so it cannot move without one.
final SaveSchema _schema = SaveSchema(
  migrations: <SaveMigration>[
    (Map<String, Object?> run) {
      final int health = (run.remove('health') as num? ?? 3).toInt();
      return run..['hearts'] = <bool>[for (var i = 0; i < health; i++) true];
    },
    (Map<String, Object?> run) => run..['keys'] = <String>[],
  ],
);

Step 2: Old saves come up, newer ones are left alone #

SaveRecord is the save document: the level, the snapshot, the schema it was written at, the step the run has reached and a digest of the level and the run. SaveRecord.read never throws. A document with no schema in it was written before games had one, so it reads as version 0 and goes through every migration. A document from a newer build is refused as newer. That is somebody's real progress, which this build must not misread and must not write over.

// A save from the first release: no schema in it, so version 0, and
// health as a number.
const oldSave =
    '{"level": "cellar", "step": 900, '
    '"run": {"health": 2, "coins": 12}}';
out.old = SaveRecord.read(jsonDecode(oldSave), _schema);
// And one from a build newer than this one, which must be left alone.
out.newer = SaveRecord.read(<String, Object?>{
  'level': 'cellar',
  'schema': 3,
  'run': <String, Object?>{'hearts': <bool>[], 'coins': 1},
}, _schema);

Step 3: The game reads it through its session #

A game already describes itself to RunSession: how a level opens, how it is written down and put back. stepOf is the one addition. It says how far the run has got, in simulation steps across all its levels, and it is what two copies are compared by later. SaveFile takes the schema, so begin resumes from a migrated save without the game knowing it was old.

/// The game, as a `RunSession`: how a level is opened, written down and
/// put back, and how far the run has got in steps.
final class _Game extends RunSession<_Level> {
  _Game(SaveFile saves) : super(firstLevel: 'cellar', saves: saves);

  @override
  Future<_Level> loadLevel(String asset) async => _Level();

  @override
  RunOutcome outcomeOf(_Level level) => RunOutcome.playing;

  @override
  String? nextOf(_Level level) => null;

  @override
  Snapshot snapshotOf(_Level level) => Snapshot(<String, Object?>{
    'hearts': <bool>[for (var i = 0; i < level.hearts; i++) true],
    'coins': level.coins,
    'keys': <String>[],
  });

  @override
  void restoreInto(RunRestoreContext<_Level> context) {
    final level = context.level;
    final snapshot = context.snapshot;
    level
      ..hearts = (snapshot.data['hearts'] as List<Object?>? ?? const []).length
      ..coins = snapshot.data.integer('coins');
  }

  @override
  int stepOf(_Level level) => level.steps;
}
storage.documents[SaveFile.name] = oldSave;
final game = _Game(saves);
out.resumed = await game.begin();
out.heartsAfterLoad = game.level!.hearts;
out.coinsAfterLoad = game.level!.coins;

Step 4: Autosave at the moments a session ends #

Autosave writes at three moments. The first is on the way into a pause, since a pause comes before most of the ways a session ends. The second is at a checkpoint, when the game says one was reached. The third is when the application goes to the background, which on a phone is the only warning before the system ends the process; watchLifecycle hears it. Nothing is written every frame or on a timer, because a write inside the frame budget is a stutter and a save from the middle of a jump restores in the air.

SaveFile keeps the digest of the last run it wrote and skips writing the same run again. Opening and closing the menu costs nothing.

final autosave = Autosave(game);
final int before = storage.writes;
// Playing: nothing to do. Into a pause: written. Still paused: not again.
for (final bool now in const <bool>[false, true, true]) {
  out.autosaves.add(await autosave.paused(now: now));
}
out.writesAfter.add(storage.writes - before);
await autosave.checkpoint(); // the same run: SaveFile skips the write
out.writesAfter.add(storage.writes - before);
game.level!
  ..coins += 5
  ..steps = 960;
await autosave.checkpoint(); // a run that moved: written
out.writesAfter.add(storage.writes - before);
out.writtenSchema = (await saves.read())?.record?.schema ?? -1;

Step 5: The cloud, with the player's yes #

SaveSync sends nothing until the player agrees. The answer is kept in a document of its own, cloud_saves.json, and it is off on a fresh install. Without it no store is called at all, not even to look. With it, each sync fetches the cloud's copy and hands both to resolveSaves, along with the digest the two sides last agreed on.

That base is what makes this more than "the further run wins". If one copy is still the base, only the other has moved since the two last met, and that one wins whatever its step: a player who went back to an earlier checkpoint on the tablet meant to. Only when both moved is the step compared. Two different runs at the same step come back as SyncOutcome.ask, because either automatic answer throws away somebody's evening, and settle carries out the player's choice. If another device wrote between the fetch and the write, the sync tries once more against what it wrote. A cloud save from a newer build is left where it is.

final cloud = _Cloud();
final sync = SaveSync(saves: saves, store: cloud);
// Off on a fresh install: no store is called at all.
out.outcomes.add((await sync.sync()).outcome);
out.callsBeforeConsent = cloud.calls.length;

await sync.consent();
out.outcomes.add((await sync.sync()).outcome); // the cloud was empty

// Another device played on from there, three hundred steps further.
cloud
  ..document = SaveFile.encode(
    SaveRecord(
      level: 'cellar',
      run: game.snapshotOf(_Level()..coins = 40),
      step: 1260,
      schema: _schema.version,
    ),
  )
  ..revision += 1;
out.outcomes.add((await sync.sync()).outcome); // the further run is kept
out.coinsAfterDownload = (await saves.read())!.record!.run.data.integer(
  'coins',
);

// Then both played apart, equally far: only the player can choose.
await saves.writeRecord(
  SaveRecord(
    level: 'cellar',
    run: game.snapshotOf(_Level()..coins = 41),
    step: 1500,
    schema: _schema.version,
  ),
);
cloud
  ..document = SaveFile.encode(
    SaveRecord(
      level: 'cellar',
      run: game.snapshotOf(_Level()..coins = 52),
      step: 1500,
      schema: _schema.version,
    ),
  )
  ..revision += 1;
final SyncReport asked = await sync.sync();
out.outcomes.add(asked.outcome);
out.outcomes.add((await sync.settle(asked, keepLocal: true)).outcome);

The store here is one slot in memory. A game passes HttpCloudSaves, which uses GET and PUT on saves/<game>/<slot> with ETag preconditions, or PlatformCloudSaves for Play Games and iCloud.

Step 6: What the page holds itself to #

The version-0 save comes up at version 2 with two hearts, a key ring and its 900 steps, and it loads into the game. The newer one is refused as newer. The autosave writes once on entering the pause, not again while paused, not for a checkpoint that changed nothing, and again for one that did. The sync goes through not consented, uploaded, downloaded, ask and uploaded, never calling the store before consent, and both sides end on the same run.

final SaveRead? old = report.old;
if (old is! SaveFound || old.upgradedFrom != 0) {
  return 'the version-0 save was not migrated: $old';
}
final Map<String, Object?> run = old.record.run.data;
if (old.record.schema != 2 ||
    run.containsKey('health') ||
    (run['hearts'] as List<Object?>?)?.length != 2 ||
    run['keys'] is! List ||
    old.record.step != 900) {
  return 'the migrated run is $run at schema ${old.record.schema}';
}
if (report.newer is! SaveNotRead || !(report.newer! as SaveNotRead).newer) {
  return 'a save from a newer build was not refused as newer';
}
if (!report.resumed ||
    report.heartsAfterLoad != 2 ||
    report.coinsAfterLoad != 12) {
  return 'the old save did not load into the game';
}
if (report.autosaves.join(',') != 'false,true,false' ||
    report.writesAfter.join(',') != '1,1,2' ||
    report.writtenSchema != 2) {
  return 'autosave wrote ${report.writesAfter} after ${report.autosaves}';
}
final String outcomes = <String>[
  for (final SyncOutcome o in report.outcomes) o.name,
].join(',');
if (outcomes != 'notConsented,uploaded,downloaded,ask,uploaded' ||
    report.callsBeforeConsent != 0 ||
    report.coinsAfterDownload != 40 ||
    !report.inSyncAtEnd) {
  return 'the sync went $outcomes';
}

Note. The native halves of the dev.flutter3d/cloud_saves channel are not written yet. Play Games snapshots in Kotlin and CloudKit or the iCloud key-value store in Swift still need a plugin package to carry them, so PlatformCloudSaves answers that the store is unavailable for now. The reference server in cloud/ has no saves/ routes yet either, and no accounts for them to belong to.