Cloud Saves

The bridge plugin PulseOnlineSaveBridge (PulseOnline + PulseSave) keeps the slots of PulseSave in the user storage of the online service too (Cloud Storage): EOS Player Data Storage, Steam Cloud through the OSS, the Mock backend, any backend with a user storage. Enable the plugin and log the player in online; the game needs no other code.

The bridge is a storage of PulseSave, Online Cloud (UPulseOnlineCloudStorage). At startup it registers this storage as the second storage of the purposes in its settings, the save game and the profiles of the players by default (UPulseSaveStorageSubsystem::AddMirrorStorage). The storage of each of these purposes becomes a mirror of PulseSave: the storage of the save settings (the folders of this machine unless the game sets another one) keeps answering the game at once, and the mirror keeps the cloud in step in the background. Rounds, conflicts and the slots the game uses are the work of the mirror; the bridge keeps the files.

How it works

  • The game saves and loads as without the bridge. A save lands on this machine first, and a round of the mirror copies it into the cloud a moment later.
  • When the player logs in online, the cloud tells PulseSave that the slots of that player changed, and the mirror compares both storages at most 2 seconds after its last round: slots saved on another machine come here, slots saved here go up, and a slot deleted on one side goes on the other side too.
  • More rounds follow every save and delete of the game, every Sync Interval Seconds of the mirror options of PulseSave (300 by default), and whenever the game asks (Sync Save Storage (Async)).
  • After a round brought slots, the save game lists its slots again (the menus follow) and a profile without changes is read again. The slot of the running game and a profile with changes are never replaced under the game; a later round takes them.
  • A slot that changed on both machines since they were last the same is a conflict. The conflict rule of PulseSave decides (Project Settings > Pulse > Save > Storage, Mirror Options; Newer by default), or the game with Ask.
  • Without an online login the cloud answers Unavailable, so a round fails and the slots of this machine are used as they are. After a failed round, or a round that left a slot the game uses for later, the next one waits 30 seconds; a login or logout starts one after the 2 seconds between rounds at most.
  • Profiles of play windows in the editor (Profile_PIE1) stay on the machine.

Using it

Most games need nothing more. A main menu that wants the newest slots of the cloud before it offers Continue, or that shows conflicts to the player, uses the mirror of PulseSave:

Blueprint C++ What it does
Sync Save Storage (Async) UPulseSaveStorageSubsystem::RequestSync(Purpose, Owner, Done) Waits for a round of the mirror (“Syncing…”): Succeeded, or Failed when the cloud could not be reached; the slots of this machine are there either way
Find Mirror UPulseSaveStorageSubsystem::FindMirror(Purpose) The mirror of a purpose; null when the purpose is not mirrored
On Conflict, Get Conflicts OnConflictNative, GetConflicts(Owner) The conflicts rule Ask leaves to the game, with time, size and package of both versions
Resolve Conflict ResolveConflict(Owner, SlotName, Choice), RequestResolveConflict(Owner, SlotName, Choice, Done) Primary keeps the version of this machine, Secondary the one of the cloud; the next round copies it over the other one. The request answers Success once the chosen version landed, Not Found when the versions changed, Busy while the game uses the slot, otherwise the failure of the round or of the copy (after Busy or a failed round the choice waits for a later round)
Is Syncing, On Sync Finished IsSyncing(Owner), OnSyncFinishedNative Whether a round runs or is about to start, or the game waits for one; not while the mirror only waits out the 30 seconds after a failed round or after a round that left a slot in use for later. The result of each round
#include "Game/PulseSaveGameSubsystem.h"
#include "Storage/PulseSaveStorageSubsystem.h"
#include "Storage/PulseSaveStorage_Mirror.h"

void UMyMainMenu::ShowCloudConflicts()
{
	UPulseSaveStorageSubsystem* storages = UPulseSaveStorageSubsystem::Get(this);
	UPulseSaveStorage_Mirror* mirror = storages ? storages->FindMirror(Pulse::Save::Storage::TAG_PurposeGame) : nullptr;
	const UPulseSaveGameSubsystem* saveGame = UPulseSaveGameSubsystem::Get(this);

	if (!mirror || !saveGame)
		return;

	for (const FPulseSaveMirrorConflict& conflict : mirror->GetConflicts(saveGame->GetOwner()))
		AddConflictRow(conflict.SlotName, conflict.Primary.ModifiedAt, conflict.Secondary.ModifiedAt);
}

The cheats PulseSaveMirror [Sync|Status] [Game|Profile] and PulseSaveMirrorResolve <Slot> <Primary|Secondary> [Game|Profile] of PulseSave start a round, show what the mirror knows (the account, the last round, conflicts) and decide a conflict. The bridge has no cheats of its own.

Accounts

The cloud keeps the slots of local users that are logged in online. The account of a player is the online service and 16 hex digits of a hash of the net id (EOS:..., Mock:...); the net id itself never shows in the debug snapshot of the mirror or the output of its cheats. The mirror keeps what it knows per account: a second account on the same machine compares its own cloud slots and does not take the slots of the first one for its own. When the online login of a player changes, the requests of that player that still wait fail Unavailable (in PulseSave and in the queue of the bridge), and a round of the mirror under the account of before ends at once: nothing asked under one account runs under the next one. A backend without a user storage keeps no slots, and the mirror then works with the storage of this machine alone.

Settings

Project Settings > Pulse > Online Cloud Save (UPulseOnlineCloudSaveSettings):

Setting Default Meaning
bEnableCloudSave True Keeps the slots of the purposes below in the cloud too (takes effect after a restart).
Purposes Game, Profile The purposes whose storage becomes a mirror of the storage of the save settings and the cloud (Pulse.Save.Storage.*; takes effect after a restart).
CloudFilePrefix PulseSave_ Start of the names of the cloud files: 1 to 16 letters, digits, _, - or .; other characters are left out.
bKeepPreviousVersion True Keeps the version before the current one of every slot in the cloud too (twice the room).

The conflict rule and the sync interval are the mirror options of PulseSave (Project Settings > Pulse > Save > Storage).

Files in the cloud

EOS takes 64 bytes per file name and slot names may have 64 characters, so the name of a slot is kept inside its files.

  • One file per version of a slot: <Prefix><Purpose><SlotHash>_<Package>_<Generation>.psc, for example PulseSave_G1a2b3c4d_9f8e7d6c_00000002.psc. Purpose: G the save game, P profiles, S the server, else 8 hex digits of the tag. Slot hash: 8 hex digits of the slot name in lower case. Package: the first 8 hex digits of the package that wrote the version. Generation: 8 hex digits of the generation of the version. The file holds the purpose, the slot name, the generation and every entry of the slot with its package, time, size and bytes, with a check sum. The bytes are those the storage gets from PulseSave, after its byte layers (compression, encryption); the bridge packs nothing itself.
  • One index per purpose: <Prefix>Index_<Purpose>.psc with the heads of the files, so a list does not read every file. It is only a cache: what counts are the files the service lists.
  • The current version of a slot is the file with the highest generation (its writer takes one more than the highest it sees), also when it carries an older time (a conflict decided for the older version, a machine whose clock is behind); between equal generations the newer time wins. The one before it is the previous version, kept while Keep Previous Version is on: the whole slot as it was before the last New Version write, a save (per write, not per entry). A Replace Current or Repair write (a meta written alone, Delete Entry) replaces only the current version and keeps that previous one. An entry the current version lacks (a deleted entry) has no previous version either.
  • A save writes its file first: when that fails, nothing changed. Then it writes the index, only from a complete picture like a reader, and deletes the versions that are too old. A reader writes the index at most; only a full list (List Slots) that finds no file of a purpose deletes its index.

Conditional writes

The bridge uses the write conditions of the user storage (Cloud Storage):

  • Files of a slot are written with IfMissing. A file name another machine took since the list (the same package written by two machines) is never written over: the service answers Conflict and the new version takes the next free name (up to four names, then Write Failed).
  • The index is written with IfVersion on the version the scan listed or read (no index yet: it must not exist). When another machine wrote it meanwhile (Conflict), the writer lists the files, reads the index again, merges its heads with its own and writes once more. When that meets a conflict too, the index stays as it is: it is only a cache, the save still succeeds and the next round of the mirror writes it.
  • The index is not read again while the service lists it with the version this storage read or wrote last; a login or logout forgets it.
  • A service without versions (GetCapabilities().bVersion false) gets the index with Always and every scan reads the index, as before. How atomic the conditions are is up to the service: the Mock backend checks them in the same step as the write, the OSS and OSSv2 (add-on PulseOnlineOSSv2) backends list and compare right before the write.

Failures

What the online service answers becomes a reason of the storage of PulseSave:

Service Storage
No online login, NotLoggedIn Unavailable
NotSupported Unsupported
NotFound for a file that went between the list and its read in Read Entry or Delete Entry Not Found
Full, or a version larger than Max User File Size Bytes Full
Timeout, Cancelled Timeout, Cancelled
Conflict of a file of a slot four times in a row Write Failed
Any other error of a list Unavailable (offline looks like that with OSS EOS)
Any other error of a read, of a write or delete Read Failed, Write Failed
A file that does not read (damaged, another version of the format) Damaged

Lists leave a file that went between the list and its read out; a save whose current version went meanwhile answers Write Failed. A version the cloud refuses (Full; the cloud never refuses a name, slot names are hashed into the file names) fails one round of the mirror; later rounds leave it alone until it changes (GetRefusedSlots of the mirror). A request that timed out still finishes its calls: a save that timed out may land after all, and the next round of the mirror finds it. The diagnosis in the log holds the error of the backend, never net ids or the contents of files.

Limits

  • The user storage of the platform limits the size and the number of files (EOS Player Data Storage, Steam Cloud quotas). A slot whose version is larger than Max User File Size Bytes of Cloud Storage stays on the machine.
  • Slots are copied whole; two versions of a slot are never merged.
  • Two machines that write the same slot at the same moment leave two versions (the conditional writes keep both files); the one with the higher generation wins when the slot is read next, between equal generations the newer time. With a service whose conditions are not atomic (OSS, OSSv2) two writes in the same moment can still meet.
  • A file that does not read and that the index does not know blocks List Slots of its purpose and every request on its slot, reads included (Damaged), until it is removed from the cloud with the tools of the online service. The bridge does not guess which slot it was: it might be the newest version. A damaged file the index knows fails only the requests that read its bytes (Damaged; the mirror reports the slot as refused), and a delete of its slot removes it.
  • The cloud keeps the slots of local users that are logged in online, one account per user.
  • Cloud files of earlier versions of the bridge (<Prefix><Slot>.pcs, <Prefix>Index.json) stay where they are and are not read.

This site uses Just the Docs, a documentation theme for Jekyll.