> ## 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 回復

> 使用新增使用者 API 上的 RollbackToLastKnownGood 或 RollbackToLastConflict 選項，將 PlayFab Game Saves 玩家存檔還原至先前的狀態。

回復可讓您將玩家的遊戲存檔還原至先前的狀態。當玩家的存檔損毀、遊戲更新引入損壞存檔資料的錯誤，或玩家想要撤銷衝突解決決策時，請使用此功能。

## 回復的運作方式

Game Saves 會追蹤玩家存檔資料的已完成版本。當您觸發回復時，服務會建立一個**新版本**，其內容與您要還原的先前狀態完全相同。回復會保留原始的版本歷程記錄。它不會刪除或覆寫先前的版本。回復後進行同步的其他裝置會將其視為一般更新。

回復有兩種類型。您可以將選項旗標傳遞給 `PFGameSaveFilesAddUserWithUiAsync` 來觸發每一種類型：

| 選項 | 描述 |
| - | - |
| `PFGameSaveFilesAddUserOptions::RollbackToLastKnownGood` | 還原最近一次經過驗證的先前雲端存檔。此存檔先前曾被載入，後來被較新的上傳取代。 |
| `PFGameSaveFilesAddUserOptions::RollbackToLastConflict` | 還原在最近一次衝突解決中落敗的存檔狀態。 |

如果沒有符合資格的還原點，這兩個選項都會回復到預設行為 (同步目前最新的版本)。

## 何時使用每種回復類型

### 回復至上次已知良好

當您懷疑最新的上傳有問題時，請使用 `RollbackToLastKnownGood`。常見的觸發情況包括：

* 下載存檔後載入失敗或完整性檢查失敗。
* 在存檔作業期間或之後立即當機。
* 玩家回報狀態損毀或倒退。

服務會自動追蹤哪些版本是「已知良好」的。您不需要明確標示它們。當您成功載入某個版本，且之後有較新的上傳取代它時，該版本就會成為已知良好。

### 回復至上次衝突

當玩家在衝突解決期間選擇了錯誤的一方時，請使用 `RollbackToLastConflict`。如 [Game Saves 衝突](/zh-TW/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` | 此遊戲未啟用 Game Saves。請先完成上線。 |
| `E_PF_GAME_SAVE_SERVICE_ONBOARDING_PENDING` | 遊戲上線仍在進行中。 |

## 考量

* \*\*回復會建立新版本。\*\*它不會清除歷程記錄。玩家的版本順序會繼續向前推進。
* \*\*服務會自動追蹤已知良好。\*\*它會根據成功的載入後取代週期，判斷哪些版本符合資格。您的遊戲不需要明確標示版本。
* \*\*每次新增使用者呼叫只能回復一次。\*\*由於每位使用者只能呼叫 `PFGameSaveFilesAddUserWithUiAsync` 一次，若要觸發第二次回復，需要先呼叫 `PFGameSaveFilesUninitializeAsync`。
* \*\*UI 回呼仍會引發。\*\*回復會經過與一般新增使用者呼叫相同的同步流程。請在呼叫 API 之前註冊您的 [UI 回呼](/zh-TW/services/playfab/player-progression/game-saves/ui-callbacks)。
* \*\*視需要限制回復。\*\*如果您的遊戲在伺服器端或透過支援工具處理復原，請使用遊戲設定旗標停用用戶端回復，以防止玩家意外還原進度。
* \*\*回復適用於所有平台。\*\*此 API 沒有平台特定的防護。


## Related topics

- [Game Saves PlayStream 事件](/zh-TW/services/playfab/player-progression/game-saves/playstream-events.md)
- [Game Saves 衝突](/zh-TW/services/playfab/player-progression/game-saves/conflicts.md)
- [Game Saves 概觀](/zh-TW/services/playfab/player-progression/game-saves/overview.md)
- [PFGameSaveFilesAddUserOptions](/zh-TW/services/playfab/api-references/c/pfgamesavefilestypes/enums/pfgamesavefilesadduseroptions.md)
- [使用 2025 年 10 月 GDK 實作 Game Saves](/zh-TW/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)