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
Get Game Instance Subsystem(Pulse Online Storage Subsystem) →Read File(KindUser, File Nameprofile.json); on success keepFile→Version.Write User File(File Nameprofile.json, Contents, advanced pins: ConditionIf Version, Expected Version = the kept version) →Execute Online Request.- Success →
Get Written File→Version: keep it for the next write. - Failure →
Get Request Result→Failed For(ReasonPulse.Result.Failure.Online.Conflict): read the file again and decide; elseGet 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).