Skip to main content
This article provides step-by-step instructions for common development and migration scenarios when using Game Saves. It covers essential setup in Microsoft Partner Center, best practices for writing data safely, platform-specific save management, and recommended testing procedures.

​
Partner Center configurations

​
Enabling XBOX services and Game Saves for your title

To use the Game Saves APIs, complete the following steps in Partner Center.
  • Enable XBOX services.
    1. Sign in to Partner Center.
    2. Go to your title, then enable XBOX services in the settings. For more information about this step, see Setting up an app or game at Partner Center, for Managed Partners.
  • Get your service configuration identifier (SCID). All read and write operations must be associated with a SCID. The SCID is also used for Game Saves initialization.
    • In Partner Center, find the SCID under the XBOX services > XBOX settings tab for your title. You can also find your Microsoft account (MSA) App ID (MSAAppID) on this page. Partner Center XBOX services view.
After you get your SCID and MSAAppID, add this App ID to the title’s config (.mgc) file. For more information about game config files, see Creating the Microsoft Game Config .mgc.

​
Development scenarios

​
Where do I integrate Game Saves in my code?

Game Saves logic depends on user sign-in. Add the Game Saves code next to the user sign-in flow.

​
How do I ensure that my game saves data doesn’t become corrupted?

To save data safely and avoid corruption, follow these steps. This guidance applies to all save operations.
  1. Write to a temporary file.
    • Serialize your save data into a new file (for example, save.tmp) rather than overwriting the live save. This step protects the existing save in case your process is interrupted mid-write.
  2. Close the write handle after the write is fully committed to disk.
  3. Replace the old save file atomically with the new temporary file by using the Win32 ReplaceFile.

​
How do I support offline devices?

You’re responsible for determining how the title behaves if there’s connection loss both before and after initializing Game Saves. For more information about offline behavior, see Understanding the Game Saves sync flow.

​
What user interactions do I need to be aware of?

The OS shows system prompts when an action requires user input. For information about these prompts, see Game Saves dialogs.

​
Is there a way to save locally and to the device only?

If you pass a null user handle to the Game Save initialization process, the system creates a machine-only provider. Data is stored locally and persists on the device, with a maximum limit of 256 MB. The data doesn’t sync to the cloud. For more information about Game Saves storage, see Game Saves storage systems.

​
Managing game saves through the device

​
Accessing local game saves on PC by using File Explorer

If your title runs on PC, you have direct access to the files. Depending on the Game Saves API implementation, you can access your local game saves at the following locations. When you manipulate data on PC, sync logic still applies. For example, modifying data when the title doesn’t have a lock causes conflicts.

​
Accessing local game saves on console

Manage the console save data via the XBOX UI. Access it by using the following steps.
  1. Select the Home button on the XBOX controller.
  2. Select My games & apps > See all.
  3. Hover over your game, and then select the View button.
  4. Select Saved data.
Console storage Game Saves management view. Consider the following when you manipulate data directly on console.
  • Deleting data on the console by using the system UI doesn’t remove the copy stored in the cloud. When you launch the title again, it syncs the data from the cloud.
  • Machine-provider data appears as a user with no name. This data stays on the device, doesn’t sync to the cloud, and is bound to the device.
For more information about the machine provider, see Game Saves storage systems. For more detailed control of game saves, use Game Saves tools.

​
Testing scenarios

When you create test cases, separate data validation from the game‑save logic.

​
Test if game saves sync correctly to and from the cloud

Use the following steps to test for correct syncing. The test flows verify the behavior. XGameSaveFiles:
  1. Confirm that the SCID is correct.
  2. Confirm that you’re using the correct user handle.
  3. Confirm that the title calls XGameSaveFilesGetFolderWithUIAsync during the current game session. If the title resumes from a suspend state, call the function.
    1. Use Fiddler to confirm the lock was acquired.
    2. Save this path and use it later to confirm that the data is uploading.
  4. Write some data to the file path provided by XGameSaveFilesGetFolderWithUIAsync.
  5. Terminate or suspend the title.
  6. Wait 10–30 seconds for the OS to automatically upload the data to the cloud and release the lock.
    1. Confirm that the data was uploaded and the lock was released by using Fiddler.
  7. Manually delete the data in the folder provided by XGameSaveFilesGetFolderWithUIAsync.
    1. On console, access this data through player settings.
  8. Launch the title again, and then attempt to sign the user in.
  9. A sync dialog appears, showing an active download sync from the cloud.
To help test successful syncing, see the following resources:

​
Test if game saves roam correctly

For a test plan to confirm if data roams, see XR-052-06 Test Plan.

​
Migration scenarios

​
Sharing game saves across titles

To transfer or access data from one title to another, complete two steps.
  1. Modify the access policies of the title you want to access in Partner Center.
  2. Initialize the Game Saves providers for both titles in source code.

​
Modify access policies

A title controls which titles have access to its game saves data by configuring access policies.
  1. Go to Partner Center.
  2. Select Apps and games > <your title> > Gameplay settings.
  3. In Gameplay Settings, select Access Policies, and then expand Connected Storage.
  4. Select Add app/service, and then add the titles that you want to provide access to.
  5. When you finish adding the titles, select Save, and then select Publish. The changes take effect within an hour.
The following screenshot shows an example of making the GameSaveFilesCombo title fully accessible to the GameSaveSample title. Partner Center view for modifying a title's access policy.

​
Initialize Game Save providers

Now that you have permission to access the first title, you can read the XGameSave data from the other title.
  • If you’re using XGameSave, call XGameSaveInitializeProvider or XGameSaveInitializeProviderAsync for each title.
  • If you’re using XGameSaveFiles, the providers are implicitly initialized. Call XGameSaveFilesGetFolderWithUiAsync for each title.

​
Interop between XGameSave and XGameSaveFiles

A title might need to use XGameSave together with XGameSaveFiles. The typical reasons might be as follows:
  • The publisher has an existing title on console that’s already using XGameSave.
  • The publisher doesn’t want to update that existing title to use XGameSaveFiles.
  • The publisher thinks that adding XGameSaveFiles to a PC title is easier than using XGameSave, but still wants to support cross-saves between PC, console, and XBOX game streaming.
Moving between XGameSave and XGameSaveFiles is fairly straightforward. When the title calls XGameSaveFilesGetFolderWithUiAsync, it maps containers and blobs to directories and files by using the following rules:
  • Any forward slash (/) in the container name creates the directory structure in which the file resides.
  • The following characters are invalid for XGameSaveFiles. If the system encounters these characters, it maps them to an underscore (_):
    • Characters from \0 through \001f, inclusive.
  • The following characters aren’t valid for XGameSaveFiles. If the system encounters these characters, it maps them to a period (.):
    • Quotation marks (”)
    • Less than sign (<)
    • Greater than sign (>)
    • Pipe (|)
    • Asterisk (*)
    • Question mark (?)
    • Backslash (\)
  • A slash (/) in the blob name maps to a period (.) in the file name.
  • Files are limited to 16 MB. XGameSave supports a maximum upload size of 16 MB.
When the title moves from XGameSaveFiles back to XGameSave, it restores the original container and blob names if the file names remain unchanged or aren’t moved.

​
Porting previous titles to PC Game Saves with no-code cloud saves

Some titles that you port to PC Game Pass might require a no-code cloud save solution. This requirement can occur in the following scenarios:
  • The title runs as an x86 application. It uses the Microsoft Game Development Kit (GDK) only in its packaged form.
  • The title is created without custom code, using tools such as Blueprint in Unreal Engine or Bolt in Unity.
Titles that use no-code cloud saves read and write to their designated save directory through standard Win32 file I/O APIs. The system automatically syncs the data. You don’t need to write special code to handle the synchronization and upload. Synchronization occurs before the title launches. No-code cloud saves are uploaded when the title is no longer running on PC. Upload occurs when one of the following conditions is met:
  • The title is terminated.
  • The tracked user signs out.
  • The PC power state changes.
  • 30 minutes have passed since the title last wrote to the designated save area.
The no-code cloud save solution is built on top of XGameSaveFiles and shares all its limitations with respect to file sizes and per-user storage limits. Files are limited to 64 MB (or 16 MB if there’s a need to have interoperation between XGameSave or Connected Storage). By default, the per-user storage is limited to 256 MB. Titles that need larger per-user storage limits can work with their Developer Partner Manager (DPM) to request an exception.
There are specific naming conventions and character limits for directories and file names. For more information, see XGameSaveFiles path logic.
No-code cloud saves are supported only on PC. The title requires the Simplified User Model. It ensures that a user is signed in before the title launches. If a user can’t be signed in to the title, it doesn’t launch. If the user is signed out during game play, it gets terminated.
No-code cloud saves require the title to be launched as a packaged build by using wdapp install. Launching the .exe directly doesn’t activate cloud save redirection.When a packaged build runs, saves written through NoCodePCRoot are redirected into XGameSaveFiles-managed storage. A later direct .exe launch reads the physical NoCodePCRoot folder instead, which might be empty, making saves appear missing. To avoid this issue, always test no-code cloud saves with packaged builds by using wdapp install.

​
Enabling no-code cloud saves

To enable no-code cloud saves, complete the following steps:
  1. Modify your MicrosoftGame.config file.
  2. Enable the simplified user model.
  3. Specify the root folder for save files.
  4. Provide the title’s corresponding SCID.
The following code example shows this process.
The root folder that you specify for NoCodePCRoot must be relative to one of a small collection of options.
Use SavedGames as the RelativeTo value. The Saved Games folder (%USERPROFILE%\Saved Games) corresponds to the Windows known folder ID FOLDERID_SavedGames. OneDrive doesn’t sync this folder by default.Avoid using other locations such as AppData (%APPDATA%). OneDrive can sync these locations and might cause conflicts with cloud save synchronization.For more information about FOLDERID_SavedGames, see SHGetKnownFolderPath.
You can’t place files directly in the root directory. Nest them within at least one subfolder from the root folder. For example, using a file name directly, like <NoCodePCRoot RelativeTo="SavedGames">savegame1.sav</NoCodePCRoot>, isn’t valid because savegame1.sav is ignored. <NoCodePCRoot> is intended to define a directory path, not a specific file.

​
Code samples

​
Reference API documentation

​
See also

Game Saves TOC
Last modified on August 20, 2026

Related topics

Game Saves overviewXGameSaveFilesGetFolderWithUiAsyncGame saveGame Saves (contents)Wrapper sample