Cloud Storage

Module PulseOnlineStorage (UPulseOnlineStorageSubsystem, one per game instance) reads and writes files of the online service. There are two kinds of files:

Kind What it is Typical use
Title Files of the developer, the same for every player, read only in the game. News, patch notes, event dates, the remote config.
User Files of one player in the cloud, read and written by the game. Settings, small profiles, cloud saves (Cloud Saves).
Backend Title files User files
OSS IOnlineTitleFile (EOS: Title Storage) IOnlineUserCloud (EOS: Player Data Storage)
OSSv2 (add-on PulseOnlineOSSv2) ITitleFile IUserFile
Mock In memory, set with SetMockTitleFile or the cheat PulseOnlineMockTitleFile In memory per mock user

Title files and remote config

After the first local user logged in online, the subsystem reads every file of Title Files To Read On Login and the Remote Config File (default remote_config.json). Read title files are kept in memory and, with Cache Title Files On Disk, in Saved/PulseOnline/TitleFiles. When a later read fails (offline, service down), the read request returns the cached copy and sets bFromCache.

UPulseOnlineStorageSubsystem* Storage = UPulseOnlineStorageSubsystem::Get(this);
Storage->OnTitleFileReadNative.AddUObject(this, &UMyNewsWidget::HandleTitleFile);
Storage->ReadFile(EPulseOnlineStorageKind::Title, TEXT("news.json"));

FString News = Storage->GetCachedTitleFileAsString(TEXT("news.json"));

The remote config is a flat JSON object. Values are read with defaults, so the game works without the file:

{ "motd": "Double rewards this weekend", "maxPartySize": 4, "eventActive": true }
const int32 MaxPartySize = Storage->GetRemoteConfigInt(TEXT("maxPartySize"), 3);
const bool bEvent = Storage->GetRemoteConfigBool(TEXT("eventActive"), false);

GetRemoteConfigString, GetRemoteConfigFloat, GetRemoteConfigInt, GetRemoteConfigBool and GetRemoteConfig (all keys). Nested objects and arrays are kept as JSON text. OnRemoteConfigChanged fires when a read changed the values. At start the subsystem loads the cached remote config from disk, so the values of the last session are there before login.

User files

Storage->WriteUserFile(TEXT("profile.json"), Pulse::Online::Storage::StringToBytes(Json));
UPulseOnlineReadFileRequest* Read = Storage->ReadFile(EPulseOnlineStorageKind::User, TEXT("profile.json"));
Read->OnRequestCompleteNative.AddLambda([](UPulseOnlineRequestBase* Request, bool bSuccess)
{
	const FString Text = CastChecked<UPulseOnlineReadFileRequest>(Request)->GetContentsAsString();
});
Storage->DeleteUserFile(TEXT("profile.json"));

Every file carries what the service knows of it (FPulseOnlineStorageFile): Name, SizeBytes, ModifiedAt (UTC), Version (changes with every write: the ETag of the service, else the hash; empty if unknown) and Hash (sha1:..., md5:...). The list, the read request (File) and the write request (GetWrittenFile()) return it.

User files need a user that is logged in online. Writes bigger than Max User File Size Bytes fail. Read and written contents stay in a memory cache (GetCachedUserFile) unless the request has bCacheUserFile off (for large files). The cloud saves of the bridge PulseOnlineSaveBridge call the user storage of the backend directly, without these requests and their cache (Cloud Saves).

Write conditions

Two machines of one player (a PC and a Steam Deck, two PIE instances) can write the same file. A write can carry a condition, so it does not overwrite a change it has not seen:

Condition The write succeeds when
Always (default) always: creates or replaces the file.
IfMissing the file does not exist yet.
IfVersion the file has ExpectedVersion (from a list, a read or the last write); an empty version means: the file must not exist.

A condition that does not hold fails the write with the reason Pulse.Result.Failure.Online.Conflict (error id Pulse.Online.Conflict, text “The file was changed on another device. Load it again and try once more.”, replaceable in Project Settings > Pulse > Foundation > Result Texts); the file stays as it was. Read it again, decide, write again.

UPulseOnlineWriteFileRequest* Write = Storage->WriteUserFile(TEXT("profile.json"), Bytes, EPulseOnlineWriteCondition::IfVersion, LastVersion);
Write->OnRequestCompleteNative.AddLambda([this](UPulseOnlineRequestBase* Request, bool bSuccess)
{
	const UPulseOnlineWriteFileRequest* Done = CastChecked<UPulseOnlineWriteFileRequest>(Request);
	if (bSuccess)
		LastVersion = Done->GetWrittenFile().Version;
	else if (Done->GetRequestResult().Reason == Pulse::Online::Failure::TAG_Conflict)
		ReloadProfile();
});

Blueprint: Write a cloud file only over the version you read

  1. Get Game Instance Subsystem (Pulse Online Storage Subsystem) → Read File (Kind User, File Name profile.json); on success keep File → Version.
  2. Write User File (File Name profile.json, Contents, advanced pins: Condition If Version, Expected Version = the kept version) → Execute Online Request.
  3. Success → Get Written File → Version: keep it for the next write.
  4. Failure → Get Request Result → Failed For (Reason Pulse.Result.Failure.Online.Conflict): read the file again and decide; else Get Display Text → Print Text.

GetCapabilities() of IPulseOnlineUserStorageService says what a service knows, without I/O:

Backend bModifiedTime bVersion bHash bAtomicConditions
Mock yes yes (a counter) yes (SHA1) yes: checked in the same step as the write
OSS no once a listing showed hashes in the cloud headers (EOS: MD5; Steam has none) the same no: list and compare right before the write
OSSv2 (add-on PulseOnlineOSSv2) no after a read or write (SHA1 of the contents) the same no: list, or read and compare, right before the write

Without atomic conditions two machines that write at the very same moment can both succeed; the next write with IfVersion then sees the conflict. A service without versions (Steam through the online subsystem) cannot check IfVersion on a file that exists: such a write fails with Pulse.Result.Failure.Online.NotSupported instead of a conflict; check bVersion first and write with IfMissing or Always there. The OSS backend takes the hash of a cloud header only when it is the hash of the bytes just read or written (the online subsystem often keeps an older list), else Version and Hash of the answer stay empty. A service provider for the user storage answers its own conditions (Service Providers).

Requests

All storage operations are requests in the queue Storage of the subsystem (see Requests). The subsystem functions above create and start them; for Blueprint use Create Pulse Online Request with one of these classes:

Request Inputs Result
UPulseOnlineEnumerateFilesRequest Kind Files (name, size, time, version, hash)
UPulseOnlineReadFileRequest Kind, FileName Contents, GetContentsAsString(), File, bFromCache
UPulseOnlineWriteFileRequest FileName, Contents or SetContentsFromString, Condition, ExpectedVersion GetWrittenFile()
UPulseOnlineDeleteFileRequest FileName –

Every request has UserId (empty: the first local user) and bCacheUserFile. Other modules can run them as sub-requests. User made content (mods, maps) has requests of its own in the same module (User Content).

Pulse::Online::Storage has the helpers StringToBytes / BytesToString (UTF-8) and ParseFlatJson.

EOS

  • Upload title files in the EOS developer portal (Title Storage) with the encryption key of the product. The key and the TitleStorageTags (tags used to list title files) go into the EOS settings of the project, not into the docs or version control of shared code. Reading a title file by name works without tags.
  • Player Data Storage needs no setup beyond the EOS login. Its limits (file count and size per player) are set by EOS.
  • Title storage of EOS is read only for games; there is no write request for title files.

Mock backend

SetMockTitleFile(Name, Text) sets a title file for every game instance of the process; user files are kept per mock user, with the time of the write, a version (mock-<n>, new with every write) and the SHA1 of the contents. FailNextOperation("Storage") makes the next storage call fail (title reads then fall back to the disk cache).

Cheats

PulseOnlineFiles [Title|User] (with time, version and hash), PulseOnlineReadFile <Title|User> <Name>, PulseOnlineWriteFile <Name> <Text> [IfMissing|IfVersion <Version>], PulseOnlineDeleteFile <Name>, PulseOnlineMockTitleFile <Name> <Text>, PulseOnlineRemoteConfig (see Debugging).


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