Port Steam Cloud storage to the XBOX GDK

Steam enables cloud storage in one of two ways. You can make all your reads and writes by using the ISteamRemoteStorage API methods, which write files to the game’s storage folder on the local hard drive and sync them to the cloud. Alternatively, you can make all your reads and writes directly to the computer’s file system, and then use Steam Auto-Cloud to sync the local folder containing the game data to the cloud. The Microsoft Game Development Kit (GDK) supports both approaches:

For code-based cloud saves, the GDK offers a simplified wrapper of the more complex XGameSave API that provides similar functionality to the methods of ISteamRemoteStorage.
For an approach similar to Steam Auto-Cloud, the GDK supports porting previous titles to PC Game Saves with no-code cloud saves, which syncs a designated local folder to the cloud without requiring changes to your file I/O code.

No-code cloud saves aren’t supported on XBOX consoles or XBOX Cloud Gaming. If your title targets console or cloud in addition to Windows PC, use the XGameSave wrapper or the full XGameSave API instead.

The code-based wrapper is the recommended path for titles that ship on console or cloud. It maps closely to writing files locally or by using the Steam Remote Storage API. This topic focuses on the simplified wrapper.

The full, nonwrapped XGameSave API offers more functionality and flexibility than the simple wrapper. If you need any of that functionality, don’t use the wrapper. Games must not switch between the two or mix API calls from both. For more information about the XGameSave API, see Game saves.

The following code examples show how basic file operations work in the Steamworks SDK and the Microsoft Game Development Kit (GDK), along with some subtle differences between the two APIs.

File operation comparisons

The following code examples show how to accomplish basic file operations in the Steamworks Remote Storage API and the GDK equivalent. They assume that the provider variable holds a pointer to an initialized Microsoft::Xbox::Wrappers::GameSave::Provider object. If you aren’t using the Steam Remote Storage API but instead opted to use Steam Auto-Cloud, replace the Remote Storage API calls with their file system API equivalents.

Reading a file

Steamworks

int32 size = SteamRemoteStorage()->GetFileSize("MyFile.json");
if (size > 0) 
{
    char *buffer = new char[size];
    bool result = SteamRemoteStorage()->FileRead("MyFile.json", buffer, size);
}           

int32 size = GetFileSize("MyFile.json");
if (size > 0)
{
    m_readResult = SteamRemoteStorage()->FileReadAsync("MyFile.json", 0, size);
    // Check the value of m_readResult in callback for error handling.
    STEAM_CALLBACK(MyGameClass, OnFileReadCompleted, RemoteStorageFileReadAsyncComplete_t);
}

GDK

BlobData data = provider->Load("SaveSlot1", "MyData");
if(!data.empty())
{
    // Iterate over the data to read bytes from the file.
}
else
{
    // Couldn't find the container/blob name.
}

Reference documentation

Microsoft.Xbox.Wrappers.XGameSave.Provider.Load

Writing a file

Steamworks

std::string saveData = "{progress: 25}";
SteamRemoteStorage()->FileWrite("MyFile.json", saveData.c_str(), saveData.size());

std::string saveData = "{progress: 25}";
m_writeResult = SteamRemoteStorage()->FileWriteAsync("MyFile.json", saveData.c_str(), saveData.size());
STEAM_CALLBACK(MyGameClass, OnFileWriteCompleted, RemoteStorageFileWriteAsyncComplete_t);

GDK

std::vector<uint8_t> saveData; // Contains the player's data.
HRESULT hr = provider->Save("SaveSlot1", "MyData", saveData.size(), saveData.data());
if(FAILED(hr))
{
  if(hr == E_GS_QUOTA_EXCEEDED)
  {
     // Message that the user must clear out saves for this game.
  }
  else if(hr == E_GS_OUT_OF_LOCAL_STORAGE)
  {
     // Message to the user that they have run out of save space on the local device.
  }
  else if(hr == E_GS_UPDATE_TOO_BIG)
  {
     // Your save size was over 16 MB (GS_MAX_BLOB_SIZE).
  }
  else if(hr == E_GS_HANDLE_EXPIRED)
  {
     // Need to re-create the provider and try again.
     // This can happen if your game was suspended and, during that time, another
     // device initialized a provider for the same user.
  }
  else
  {
     // Log error.
  }
}

Reference documentation

Microsoft.Xbox.Wrappers.XGameSave.Provider.Save

Delete a file

On Steam, you can either delete a file in the cloud but keep the local copy (FileForget), or delete a file from both locations (FileDelete). The XGameSave wrapper API doesn’t have an equivalent to FileForget. Its Delete function works like FileDelete in Steamworks.

Steamworks

// Delete a file from the cloud but keep it locally.
bool result = SteamRemoteStorage()->FileForget("MyFile.json");

// Delete a file locally AND from the cloud.
bool result = SteamRemoteStorage()->FileDelete("MyFile.json");

GDK

// Delete a specific file.
HRESULT hr = provider->Delete("MyContainer", "MyData");

// Delete a set of files in a container. 
std::vector<std::string> toDelete = { "blob1", "blob2", "blob3" };
HRESULT hr = provider->Delete("MyContainer", toDelete);

// Delete all the files in a container.
HRESULT hr = provider->Delete("MyContainer");

Reference documentation

Get all files

Steamworks

int32 fileCount = SteamRemoteStorage()->GetFileCount();
for ( int i = 0; i < fileCount; ++i ) {
    int32 fileSize;
    const char *fileName = SteamRemoteStorage()->GetFileNameAndSize( i, &fileSize );
    // Do something with fileSize and fileName.
}

GDK

// To get all the files across all containers for the game, make this = ""
// Otherwise, make it a prefix of whichever container's files you'd like.
std::string containerQuery = "";
std::vector<std::string> containers = provider->QueryContainers(containerQuery);

for (auto&& container : containers)
{
    BlobInfoSet blobs = provider->QueryContainerBlobs(container);
    for (auto&& blob : blobs)
    {
        uint32_t blobSize = blob.size;
        std::string blobName = blob.name;
        // Do something with blobSize and blobName.
    }
}

Reference documentation

Check available space

In the following examples, totalBytes is the amount of space your game is given on the cloud storage provider. availableBytes is the amount of free space remaining (that is, availableBytes = totalBytes – bytesUsed).

Steamworks

uint64 totalBytes, availableBytes;
SteamRemoteStorage()->GetQuota(&totalBytes, &availableBytes);

GDK

// totalBytes is always 256 MB.
int64_t availableBytes = provider->GetQuota();

Reference documentation

Microsoft.Xbox.Wrappers.XGameSave.Provider.GetQuota

Terminology differences

On Steam, remote storage data is managed as files, which work like files on a local hard drive. To read or write, you specify the file and then get or set the bytes that it contains. In the Microsoft Game Development Kit (GDK), the equivalent of Steam files are blobs. Blobs are grouped together in a structure called a container. A container is a named group of blobs. For example, you can use containers to support multiple save slots per user, with the same file names in each slot. If you don’t need the extra organizational layer that containers provide, place all your blobs (files) in the same container.

Container names can’t include spaces. Attempting to access or create a container name that includes a space causes the provider method to return an HRESULT of 0x80830001: the specified volume doesn’t support storage tiers.

Storage limits

The Microsoft Game Development Kit (GDK) has a lower maximum blob or file write size and overall storage limit than Steam. On Steam, each file write operation is limited to 100 mebibytes (MiB), and each file can’t be larger than 200 MiB. In contrast, the XGameSave API and its wrapper limit each blob to 16 MB and allow a maximum of 256 MB per user per game. If you need to store more than 16 MB of data in a blob, split the data into multiple blobs. Then implement a sequential read and write function to process the data one blob at a time.

Wrapper functions are blocking

The ISteamRemoteStorage interface offers two versions of read and write functions: FileRead and FileWrite, plus FileReadAsync and FileWriteAsync. The Async versions call back when the file has been read or written. The simplified XGameSave wrapper functions don’t offer asynchronous versions of its equivalents to FileRead and FileWrite. Provider::Load and Provider::Save are both blocking, so keep this behavior in mind when you use them in your game. For this reason, Provider::Initialize throws an exception if you call it from the UI thread.

Initialization

Include the header file for the wrapper in your game’s solution before you use any wrapper methods. You can find it at %GRDKLatest%\GameKit\Include\xgamesavewrappers.hpp. Before using the XGameSave wrapper’s methods, create an instance of the Provider class and call the Provider::Initialize method. Hold a pointer to the Provider instance for the lifetime of your game. Call Provider::Initialize from a thread other than the UI thread. The method throws an exception if you call it from the UI thread. To initialize the wrapper provider, you need an XUserHandle for the current user and your game’s service configuration identifier (SCID).

using namespace Microsoft::Xbox::Wrappers::GameSave;

Provider provider = new Provider();
if(SUCCEEDED(provider->Initialize(userHandle, mySCID)) {
    // Start using the XGameSave wrapper...

Reference documentation

Microsoft.Xbox.Wrappers.XGameSave.Provider.Initialize

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

File operation comparisons

Reading a file

Steamworks

GDK

Reference documentation

Writing a file

Steamworks

GDK

Reference documentation

Delete a file

Steamworks

GDK

Reference documentation

Get all files

Steamworks

GDK

Reference documentation

Check available space

Steamworks

GDK

Reference documentation

Terminology differences

Storage limits

Wrapper functions are blocking

Initialization

Reference documentation

​File operation comparisons

​Reading a file

​Steamworks

​GDK

​Reference documentation

​Writing a file

​Steamworks

​GDK

​Reference documentation

​Delete a file

​Steamworks

​GDK

​Reference documentation

​Get all files

​Steamworks

​GDK

​Reference documentation

​Check available space

​Steamworks

​GDK

​Reference documentation

​Terminology differences

​Storage limits

​Wrapper functions are blocking

​Initialization

​Reference documentation

File operation comparisons

Reading a file

Steamworks

GDK

Reference documentation

Writing a file

Steamworks

GDK

Reference documentation

Delete a file

Steamworks

GDK

Reference documentation

Get all files

Steamworks

GDK

Reference documentation

Check available space

Steamworks

GDK

Reference documentation

Terminology differences

Storage limits

Wrapper functions are blocking

Initialization

Reference documentation