> ## 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.

# 游戏存档回滚

> 使用添加用户 API 上的 RollbackToLastKnownGood 或 RollbackToLastConflict 选项，将 PlayFab 游戏存档玩家存档恢复到较早的状态。

回滚可让您将玩家的游戏存档恢复到较早的状态。当玩家的存档损坏、作品更新引入了破坏存档数据的错误，或者玩家希望撤销冲突解决决定时，请使用回滚。

## 回滚的工作原理

游戏存档跟踪玩家存档数据的已最终确定版本。当您触发回滚时，服务会创建一个**新版本**，其内容与您要恢复的较早状态相同。回滚会保留原始版本历史。它不会删除或覆盖以前的版本。回滚后同步的其他设备会将其视为普通更新。

有两种类型的回滚。您可以通过向 `PFGameSaveFilesAddUserWithUiAsync` 传递选项标志来触发它们：

| 选项                                                       | 描述                                    |
| -------------------------------------------------------- | ------------------------------------- |
| `PFGameSaveFilesAddUserOptions::RollbackToLastKnownGood` | 恢复最近一次已验证的先前云存档。此存档先前已被加载，之后被较新的上传替换。 |
| `PFGameSaveFilesAddUserOptions::RollbackToLastConflict`  | 恢复在最近一次冲突解决中失败的存档状态。                  |

如果不存在符合条件的恢复点，这两个选项都会回退到默认行为（同步当前最新版本）。

## 何时使用每种回滚类型

### 回滚到最后已知良好

当您怀疑最新上传有问题时，请使用 `RollbackToLastKnownGood`。常见的触发场景包括：

* 下载存档后加载失败或完整性检查失败。
* 存档操作期间或刚结束后发生崩溃。
* 玩家报告状态损坏或倒退。

服务会自动跟踪哪些版本是"已知良好"的。您无需显式标记它们。当您成功加载某个版本且稍后被更新的上传替换时，该版本就会成为已知良好版本。

### 回滚到最后一次冲突

当玩家在冲突解决期间选错了一方时，请使用 `RollbackToLastConflict`。如[游戏存档冲突](/services/playfab/player-progression/game-saves/conflicts)所述，两种解决选择都会保留被丢弃的分支。此回滚选项会恢复该被保留的分支。

## 调用 API

通过向 `PFGameSaveFilesAddUserWithUiAsync` 传递相应的选项来触发回滚。您对每个用户只能调用此函数一次，因此若要对已添加的用户执行回滚，请先调用 `PFGameSaveFilesUninitializeAsync` 并等待其完成。

```cpp theme={null}
// Rollback to last known good version
XAsyncBlock async{};
async.queue = queue;
async.callback = [](XAsyncBlock* async)
{
    HRESULT hr = PFGameSaveFilesAddUserWithUiResult(async);
    if (SUCCEEDED(hr))
    {
        // Save data is now restored to the last known good version.
        // Read files from the game save folder as usual.
    }
};

HRESULT hr = PFGameSaveFilesAddUserWithUiAsync(
    localUserHandle,
    PFGameSaveFilesAddUserOptions::RollbackToLastKnownGood,
    &async
);
```

若要改为回滚到最后一次冲突失败者，请替换选项标志：

```cpp theme={null}
HRESULT hr = PFGameSaveFilesAddUserWithUiAsync(
    localUserHandle,
    PFGameSaveFilesAddUserOptions::RollbackToLastConflict,
    &async
);
```

### 回退行为

如果不存在符合所请求回滚类型的恢复点，该调用的行为就像您传入了 `PFGameSaveFilesAddUserOptions::None`。当前最新版本会正常同步。调用完成后请检查已同步的文件，以确认是否发生了回滚。

## 作品配置

您可以通过两个配置标志限制客户端发起的回滚。启用任一标志后，只有支持工具和 Game Manager 才能执行该类型的回滚。

| 标志                                         | 效果                    |
| ------------------------------------------ | --------------------- |
| `DisableClientRollbackToLastKnownGood`     | 阻止游戏客户端回滚到最后已知良好版本。   |
| `DisableClientRollbackToLastConflictLoser` | 阻止游戏客户端撤销最近一次的冲突解决决定。 |

在 Game Manager 的 **Progression > Game Saves** 下设置这些标志。

## 错误处理

| HRESULT                                                            | 含义                   |
| ------------------------------------------------------------------ | -------------------- |
| `E_PF_GAME_SAVE_MANIFEST_NOT_ELIGIBLE_FOR_ROLLBACK`                | 不存在符合所请求回滚类型的恢复点。    |
| `E_PF_GAME_SAVE_NOT_FINALIZED_MANIFEST_NOT_ELIGIBLE_AS_KNOWN_GOOD` | 目标版本不符合作为已知良好恢复点的条件。 |
| `E_PF_GAME_SAVE_SERVICE_NOT_ENABLED_FOR_TITLE`                     | 未为此作品启用游戏存档。请先完成接入。  |
| `E_PF_GAME_SAVE_SERVICE_ONBOARDING_PENDING`                        | 作品接入仍在进行中。           |

## 注意事项

* **回滚会创建新版本。** 它不会擦除历史记录。玩家的版本序列会继续向前推进。
* **服务会自动跟踪已知良好版本。** 它会根据成功的加载-然后-替换周期确定哪些版本符合条件。您的游戏无需显式标记版本。
* **每次添加用户调用只能回滚一次。** 由于您对每个用户只能调用 `PFGameSaveFilesAddUserWithUiAsync` 一次，触发第二次回滚需要先调用 `PFGameSaveFilesUninitializeAsync`。
* **UI 回调仍然会触发。** 回滚与正常的添加用户调用经过相同的同步流程。在调用 API 之前注册您的 [UI 回调](/services/playfab/player-progression/game-saves/ui-callbacks)。
* **必要时限制回滚。** 如果您的游戏在服务器端或通过支持工具处理恢复，请使用作品配置标志禁用客户端回滚，以防止玩家意外还原进度。
* **回滚适用于所有平台。** 此 API 没有特定于平台的保护。


## Related topics

- [游戏存档 PlayStream 事件](/zh-CN/services/playfab/player-progression/game-saves/playstream-events.md)
- [游戏存档概述](/zh-CN/services/playfab/player-progression/game-saves/overview.md)
- [游戏存档](/zh-CN/build/core-features/common/game-save/index.md)
- [游戏存档（目录）](/zh-CN/build/core-features/common/game-save/game-saves-toc.md)
- [游戏存档 UI 回调](/zh-CN/services/playfab/player-progression/game-saves/ui-callbacks.md)