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() 验证连接状态

​

Game Saves 何时进入离线模式或返回错误

• 离线模式是成功结果，而不是错误。 只有在明确选择 Use Offline 时才会进入离线模式，并且异步操作以 S_OK 完成。使用 PFGameSaveFilesIsConnectedToCloud() 检测它。
• 暂时性/技术性故障通过同步失败 UI 呈现，而不是直接从 PFGameSaveFilesAddUserWithUiAsync 返回。随后由用户（或你的自动响应）选择 Retry、UseOffline 或 Cancel，最终得到上述三种结果之一。
• 取消是最终结果，且不会提供存档文件夹。 将“已取消”（或任何未留下文件夹的失败）视为不允许游玩。
• 玩家取消和游戏取消返回不同的代码。 只有玩家在提示中选择 Cancel 才会产生 E_PF_GAMESAVE_USER_CANCELLED。如果你的游戏自行使用 XAsyncCancel 取消操作，则操作以 E_ABORT 完成。如果希望以相同方式处理两者，请同时检查这两个代码。

​

Game Saves 错误代码

​

其他连接状态场景

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

​

离线支持最佳实践

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 触发。

​

上传何时使会话进入离线状态

• 会话已经处于离线状态。 上传不会运行，并以 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD 完成，即使网络已经恢复也是如此。
• 云端有较新的存档。 如果在上传最终完成时服务报告另一台设备已提交了较新的存档，Game Saves 会使会话进入离线状态，触发活动设备变更回调，并以 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD 完成上传。
• 玩家在重新锁定提示中选择 Use Offline。 如果之前的上传已提交其数据但随后失败，则下一次上传必须先重新获取存档锁。在此步骤中出现的同步失败提示可以用 UseOffline 响应，这会使会话进入离线状态，并以 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD 完成上传。

​

取消上传