> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Game Saves 离线模式

> 使用 PlayFab Game Saves 离线模式，让玩家在无网络连接时继续保留进度，并在网络恢复后同步云存档。

Game Saves 的设计支持在线与离线两种情况，即便网络连接不可用，玩家也能继续游玩。系统会根据网络可用性和用户选择在两种不同的模式下工作。

### 连接模式

#### 已连接云端模式

当网络可用且 `PFGameSaveFilesAddUserWithUiAsync()` 成功完成时，系统运行于已连接云端模式。在此模式下：

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

#### 离线模式（未连接云端）

当网络不可用或用户选择离线游玩时，系统进入离线模式，功能受限。你可以使用 `PFGameSaveFilesIsConnectedToCloud()` 检查当前连接状态，以判断系统所处的模式。

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

当在无网络连接时调用 `PFGameSaveFilesAddUserWithUiAsync()`，会触发 `PFGameSaveFilesUiSyncFailedCallback`。系统在等待用户响应期间不会触发 `XAsyncBlock` 回调——异步操作会一直暂停，直到用户选择了一个最终动作。

```cpp theme={null}
// 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 的行为有所不同：

#### 正常工作的 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()` 验证连接状态

### 其他连接状态场景

`PFGameSaveFilesIsConnectedToCloud()` API 特别有用，因为断开连接可能以多种方式发生：

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

在尝试云端操作前使用此 API，以便向用户提供合适的反馈。

### 离线支持最佳实践

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

### 已连接模式下的上传行为

即使在已连接模式下，上传也可能因网络问题或速率限制而失败。发生此情况时，`XAsyncBlock` 回调不会立即触发——系统会在通过 [UI 回调状态机](/services/playfab/player-progression/game-saves/ui-callbacks#how-the-state-machine-works) 等待用户响应期间暂停异步操作：

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

网络恢复后，游戏可以稍后再次调用 `PFGameSaveFilesUploadWithUiAsync()`。


## Related topics

- [游戏存档快速入门](/zh-CN/services/playfab/player-progression/game-saves/quickstart.md)
- [处理离线游戏的最佳实践](/zh-CN/services/xbox-services/develop/best-practices/live-best-practices-offline-play.md)
- [XBOX 服务用户特权的客户端使用](/zh-CN/services/xbox-services/fundamentals/identity/privileges/concepts/live-user-privileges-client.md)
- [XGameSave API 概述](/zh-CN/build/core-features/common/game-save/xgamesave.md)
- [XGameSaveFiles API 概述](/zh-CN/build/core-features/common/game-save/xgamesavefiles.md)