XGameSaveFilesGetFolderWithUIAsync. It also describes the recommended Win32 automatic cloud‑sync behavior, debugging steps, quota and diagnostic guidance, performance best practices, and answers to common questions.
XGameSaveFiles provides APIs that enable your title to read and write user data, persist it across sessions, and sync it seamlessly with the cloud so players can use their data on any device. Use XGameSaveFiles for game saves in Microsoft Game Development Kit (GDK) titles. Use XGameSave only when XGameSaveFiles isn’t available for your scenario.
For the system API reference for XGameSaveFiles, see XGameSaveFiles (API contents).
The following terms appear often in XGameSaveFiles.
- Lock: A mechanism that grants exclusive access to a title’s Game Saves for a specific user on the device they’re actively using. It ensures that no other device can modify the game saves for the user while the lock is held.
- For example, if a user plays Title T on device A, it has a lock for Title T for the user.
- Provider: The intermediary process that communicates with the Game Save system and is responsible for managing the title data. The provider also manages the lock for a user on a device.
- Containers: Analogous to folders.
- Blobs: Analogous to individual files.
XGameSaveFiles path logic
XGameSaveFiles provides a file path that you can use to interact with the Game Saves system. The file path integrates with cloud synchronization, so data saved to the path automatically syncs to the cloud. Use Win32 FileIO APIs on the provided path. For GDK titles, use XGameSaveFiles as the Game Saves approach. XGameSaveFiles maps the concepts of containers to folders and blobs to files.
While XGameSaveFiles hides most of the cloud‑save system’s complexity, it still enforces directory and file‑name limits because the feature relies on Microsoft Azure Blob Storage. Consider the following example code of what a title might use for its save.
XGameSaveFilesGetFolderWithUiAsyncreturns the [ROOT].- Everything following [ROOT], up to and including the final slash, maps to a container.
- Container names are limited to uppercase letters (A-Z), lowercase letters (a-z), numbers (0-9), underscores (_), periods (.), hyphens (-), and slashes (/).
- Container names are limited to 256 characters.
- Container names can’t end in a period, contain two consecutive periods, or start with a period or hyphen.
- Everything following the final slash in the file name maps to a blob.
- File names are limited to 65 characters but can otherwise be Unicode characters that the New Technology File System (NTFS) supports.
- The full resulting path, including the file name (but not the [ROOT]), must be less than
MAX_PATH(260 characters).
Implementation of XGameSaveFiles
The following steps show the general implementation ofXGameSaveFiles.
- On title launch or resume, call
XGameSaveFilesGetFolderWithUIAsyncto initialize the provider and get the file path. - Freely read and write to the file path during game play.
XGameSaveFilesGetFolderWithUIAsync automatically manages the lifetime of the Game Saves provider and sets up the Game Saves local storage space.
Call
XGameSaveFilesGetFolderWithUIAsync when the title starts and when it resumes. This call initializes the Game Saves provider and keeps it active while the game session runs. If you skip this step, the system can behave unpredictably.Code sample
For a code sample that shows how to use theXGameSaveFiles APIs to access folders on XBOX, see GameSaveFilesCombo.
Game Saves flow
Here’s a flowchart of the simplified Game Saves flow.Title start
Title start occurs when the user launches or resumes the title.User sign in
The title begins the user sign-in process. This operation is also where you callXGameSaveFilesGetFolderWithUIAsync. For more information about user setup, see User Models.
Connection check
The title determines if it can connect to the XBOX network. If it can’t, you need to enable offline mode for the title.Data ownership check
The device checks if the user is currently playing on other devices. Only one device at a time can access the user’s data for a specific title.Sync data with the cloud
The device syncs the Game Saves local storage data with the cloud. If there’s a conflict, the system prompts the user with a conflict resolution dialog. Dialog: Which one do you want to use? If the data on the device is newer than the cloud data, the title prompts the user to choose between using the local data or the cloud data.Gameplay loop
The title can freely read and write to the folder path provided byXGameSaveFilesGetFolderWithUIAsync.
Game session end
When the game session ends, the system automatically attempts to upload the data to the cloud. This process occurs around 10–30 seconds after the title ends. For detailed sync information, see Understanding the Game Saves sync flow.Limits and quotas
Limits
The maximum file size that you can save by usingXGameSaveFiles is 64 MB. This behavior differs from XGameSave, which limits each file to 16 MB.
Quotas
The maximum data that a user can save per title is 256 MB. Use XGameSaveFilesGetRemainingQuota to get the remaining quota. To get a storage extension so that your title has a larger per-user storage limit, contact your Developer Program Manager (DPM).FAQs
Can I use XGameSaveFiles with XGameSave?
Yes. However, use this approach only for migrations. For detailed information, see Interoperability between XGameSave and XGameSaveFiles.What file path does XGameSaveFiles save to?
Console: The title provides a temporary path while it’s active. You can’t access console files by using File Explorer. PC:%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\xgs\<HexXuid>_<SCID>\
The PC path for XGameSaveFiles is different from XGameSave. It uses wgs.
Can I specify the path where the data should be saved?
Yes, but only for PC. We recommend this approach only if you’re porting your solution from another title. This solution uses no code cloud saves.Reference API documentation
See also
Game Saves TOC Yes, but only for PC. Porting your solution from another title might require this approach. This solution uses no code cloud saves.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. Alternating between packaged and direct .exe launches can cause save data to appear missing. For more information, see Porting previous titles to PC Game Saves with no-code cloud saves.