Game Saves 离线模式

​

连接模式

​

已连接云端模式

• 所有 API 均正常工作，支持完整的云端同步
• 存档数据可按预期上传
• 存储配额信息可用
• 活动设备监控可正常工作

​

离线模式（未连接云端）

​

处理初次同步时的网络故障

// 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
}

• 再试一次（Retry）：重新发起网络调用。如果重试仍失败，此回调会再次触发，用户须再次响应。在每次重试循环中 XAsyncBlock 回调都会保持延迟。
• 使用离线模式（UseOffline）：XAsyncBlock 回调以 S_OK 触发，但系统进入离线模式（可通过 PFGameSaveFilesIsConnectedToCloud() 检测）。
• 取消：XAsyncBlock 回调以 E_PF_GAMESAVE_USER_CANCELLED 触发。

​

离线模式下的 API 行为

​

正常工作的 API

• PFGameSaveFilesGetFolder() —— 返回本地存档文件夹路径

​

功能受限的 API

• PFGameSaveFilesUploadWithUiAsync() —— 立即返回 S_OK，但异步完成时返回 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD
• PFGameSaveFilesGetRemainingQuota() —— 返回 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD
• PFGameSaveFilesSetActiveDeviceChangedCallback() —— 可以设置，但永远不会触发

​

恢复在线模式

• 再次调用 PFGameSaveFilesAddUserWithUiAsync() 以尝试重新连接
• 无需完全重新初始化 Game Saves 系统
• 如果网络仍不可用，会再次显示失败 UI
• 重试后使用 PFGameSaveFilesIsConnectedToCloud() 验证连接状态

​

其他连接状态场景

• 同步期间网络不可用：用户明确选择离线游玩
• 活动设备变更：另一台设备接管成为活动设备，会自动将当前设备置于离线模式

​

离线支持最佳实践

1. 始终实现同步失败回调，以妥善处理网络问题
2. 在尝试云端操作前，定期使用 PFGameSaveFilesIsConnectedToCloud() 检查连接状态
3. 在离线模式下运行时告知玩家，让他们了解存档不会同步
4. 在网络恢复时提供重试选项
5. 本地存档始终可用——不论网络状态如何，玩家都可以继续游玩
6. 监控断开事件——请记住，当另一台设备成为活动设备时，本设备可能被断开

​

已连接模式下的上传行为

1. PFGameSaveFilesUiSyncFailedCallback 会带着错误详情触发。
2. XAsyncBlock 回调尚未触发——操作会在系统等待响应期间暂停。
3. 如果用户选择 Retry，将重试上传。如果再次失败，回调会再次触发，用户须再次响应。
4. 如果用户选择 Cancel，XAsyncBlock 回调会以 E_PF_GAMESAVE_USER_CANCELLED 触发。
5. 如果重试成功，XAsyncBlock 回调会以 S_OK 触发。