Game Saves offline mode

​

Connection modes

​

Connected to cloud mode

• All APIs function normally with full cloud synchronization
• Save data uploads work as expected
• Storage quota information is available
• Active device monitoring works properly

​

Offline mode (not connected to cloud)

​

Handling network failures during initial sync

// Handle sync failure callback
void MyPFGameSaveFilesUiSyncFailedCallback(PFLocalUserHandle localUserHandle, PFGameSaveFilesSyncState syncState, HRESULT error, void* context)
{
    // Tell the user something like this:
    std::cout << "We couldn't sync your data with the cloud just now" << std::endl;
    std::cout << "Try syncing again or use this game offline" << std::endl;
    std::cout << "[Try Again]" << std::endl;
    std::cout << "[Use Offline]" << std::endl;

    // if user chooses [Try Again], call PFGameSaveFilesSetUiSyncFailedResponse(localUserHandle, PFGameSaveFilesUiSyncFailedUserAction::Retry);
    // if user chooses [Use Offline], call PFGameSaveFilesSetUiSyncFailedResponse(localUserHandle, PFGameSaveFilesUiSyncFailedUserAction::UseOffline);

    // These API calls can happen inside or outside of this callback
}

• Try Again (Retry): Retries the network call. If the retry also fails, this callback fires again and the user must respond again. The XAsyncBlock callback remains deferred through each retry loop.
• Use Offline (UseOffline): The XAsyncBlock callback fires with S_OK, but the system enters offline mode (detectable with PFGameSaveFilesIsConnectedToCloud()).
• Cancel: The XAsyncBlock callback fires with E_PF_GAMESAVE_USER_CANCELLED.

​

API behavior in offline mode

​

APIs that work normally

• PFGameSaveFilesGetFolder() - Returns local save folder path

​

APIs with limited functionality

• PFGameSaveFilesUploadWithUiAsync() - Returns S_OK immediately, but async completion returns E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD
• PFGameSaveFilesGetRemainingQuota() - Returns E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD
• PFGameSaveFilesSetActiveDeviceChangedCallback() - Can be set but will never trigger

​

Returning to online mode

• Call PFGameSaveFilesAddUserWithUiAsync() again to attempt reconnection
• No need to fully reinitialize the Game Saves system
• Will show failure UI again if network is still unavailable
• Use PFGameSaveFilesIsConnectedToCloud() to verify connection status after retry attempts

​

When Game Saves enters offline mode or returns an error

• Offline mode is a success outcome, not an error. It is only entered by an explicit Use Offline choice, and the async operation completes with S_OK. Detect it with PFGameSaveFilesIsConnectedToCloud().
• Transient/technical failures are surfaced through the sync-failed UI, not returned directly from PFGameSaveFilesAddUserWithUiAsync. The user (or your auto-response) then chooses Retry, UseOffline, or Cancel, which resolves to one of the three outcomes above.
• Cancel is terminal and produces no save folder. Treat “cancelled” (or any failure that leaves no folder) as don’t allow play.
• Player cancel and game cancel return different codes. Only the player choosing Cancel on a prompt produces E_PF_GAMESAVE_USER_CANCELLED. If your game cancels the operation itself with XAsyncCancel, it completes with E_ABORT. Check for both if you want to treat them the same way.

​

Game Saves error codes

​

Additional connection status scenarios

• Network unavailable during sync: User explicitly chooses to play offline
• Active device changed: Another device takes over as the active device, automatically putting this device in offline mode

​

Best practices for offline support

1. Always implement sync failure callbacks to handle network issues gracefully
2. Check connection status regularly using PFGameSaveFilesIsConnectedToCloud() before attempting cloud operations
3. Inform players when operating in offline mode so they understand saves won’t sync
4. Provide retry options when network connectivity is restored
5. Local saves always work - players can continue playing regardless of network status
6. Monitor for disconnection - remember that devices can be disconnected when another device becomes active

​

Upload behavior in connected mode

1. The PFGameSaveFilesUiSyncFailedCallback fires with the error details.
2. The XAsyncBlock callback doesn’t fire yet. The operation is paused while the system waits for a response.
3. If the user selects Retry, the upload retries. If it fails again, the callback fires again and the user must respond again.
4. If the user selects Cancel, the XAsyncBlock callback fires with E_PF_GAMESAVE_USER_CANCELLED.
5. If a retry succeeds, the XAsyncBlock callback fires with S_OK.

​

When an upload takes the session offline

• The session was already offline. The upload doesn’t run and completes with E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD, even if the network has been restored.
• The cloud has a newer save. If the service reports that a newer save was committed from another device when the upload finalizes, Game Saves puts the session offline, fires the active-device-changed callback, and completes the upload with E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD.
• The player chooses Use Offline on the re-lock prompt. If an earlier upload committed its data but failed afterward, the next upload first has to re-acquire the save lock. A sync-failed prompt during that step can be answered with UseOffline, which takes the session offline and completes the upload with E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD.

​

Cancelling an upload