Saves that survive an update
Open the live demo · Read the source · View on GitHub
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_saveschannel 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, soPlatformCloudSavesanswers that the store is unavailable for now. The reference server incloud/has nosaves/routes yet either, and no accounts for them to belong to.