> ## 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 롤백

> add user API의 RollbackToLastKnownGood 또는 RollbackToLastConflict 옵션을 사용하여 PlayFab Game Saves 플레이어 세이브를 이전 상태로 복원합니다.

롤백을 사용하면 플레이어의 게임 세이브를 이전 상태로 복원할 수 있습니다. 플레이어의 세이브가 손상되었을 때, 타이틀 업데이트로 인해 세이브 데이터를 손상시키는 버그가 발생했을 때, 또는 플레이어가 충돌 해결 결정을 되돌리고 싶을 때 사용하세요.

## 롤백 작동 방식

Game Saves는 플레이어의 세이브 데이터의 확정된 버전을 추적합니다. 롤백을 트리거하면 서비스는 복원하려는 이전 상태와 내용이 동일한 **새 버전**을 만듭니다. 롤백은 원본 버전 기록을 보존합니다. 이전 버전을 삭제하거나 덮어쓰지 않습니다. 롤백 후 동기화하는 다른 디바이스는 이를 정상적인 업데이트로 봅니다.

두 가지 유형의 롤백이 있습니다. 각각은 `PFGameSaveFilesAddUserWithUiAsync`에 옵션 플래그를 전달하여 트리거합니다:

| 옵션                                                       | 설명                                                                   |
| -------------------------------------------------------- | -------------------------------------------------------------------- |
| `PFGameSaveFilesAddUserOptions::RollbackToLastKnownGood` | 가장 최근에 확인된 이전 클라우드 세이브를 복원합니다. 이 세이브는 이전에 로드되었으며 나중에 새 업로드로 대체되었습니다. |
| `PFGameSaveFilesAddUserOptions::RollbackToLastConflict`  | 가장 최근의 충돌 해결에서 진 세이브 상태를 복원합니다.                                      |

적격 복원 지점이 없는 경우 두 옵션 모두 기본 동작(현재 최신 버전 동기화)으로 대체됩니다.

## 각 롤백 유형을 사용할 때

### 마지막 알려진 정상으로 롤백

`RollbackToLastKnownGood`은 최신 업로드가 잘못되었다고 의심될 때 사용합니다. 일반적인 트리거는 다음과 같습니다:

* 세이브를 다운로드한 후 로드 실패 또는 무결성 검사 실패.
* 세이브 작업 중 또는 직후의 충돌.
* 손상되거나 되돌아간 상태에 대한 플레이어 보고.

서비스는 어떤 버전이 "알려진 정상"인지 자동으로 추적합니다. 명시적으로 표시할 필요가 없습니다. 성공적으로 로드하고 나중에 새 업로드가 대체하면 버전이 알려진 정상이 됩니다.

### 마지막 충돌로 롤백

`RollbackToLastConflict`는 플레이어가 충돌 해결 중에 잘못된 쪽을 선택했을 때 사용합니다. [Game Saves 충돌](/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`                        | 타이틀 온보딩이 아직 진행 중입니다.                             |

## 고려 사항

* **롤백은 새 버전을 생성합니다.** 기록을 지우지 않습니다. 플레이어의 버전 시퀀스는 계속 앞으로 진행됩니다.
* **서비스는 알려진 정상을 자동으로 추적합니다.** 성공적인 로드-후-대체 사이클을 기반으로 어떤 버전이 자격이 있는지 결정합니다. 게임이 명시적으로 버전을 표시할 필요가 없습니다.
* **add-user 호출당 하나의 롤백.** `PFGameSaveFilesAddUserWithUiAsync`는 사용자당 한 번만 호출할 수 있으므로, 두 번째 롤백을 트리거하려면 먼저 `PFGameSaveFilesUninitializeAsync`를 호출해야 합니다.
* **UI 콜백은 여전히 실행됩니다.** 롤백은 일반적인 add-user 호출과 동일한 동기화 흐름을 거칩니다. API를 호출하기 전에 [UI 콜백](/services/playfab/player-progression/game-saves/ui-callbacks)을 등록하세요.
* **필요한 경우 롤백을 제한하세요.** 게임이 서버 측 또는 지원 도구를 통해 복구를 처리하는 경우, 플레이어가 실수로 진행 상황을 되돌리는 것을 방지하기 위해 타이틀 구성 플래그로 클라이언트 롤백을 비활성화하세요.
* **롤백은 모든 플랫폼에서 작동합니다.** 이 API에는 플랫폼별 보호가 없습니다.


## Related topics

- [Game Saves PlayStream 이벤트](/ko/services/playfab/player-progression/game-saves/playstream-events.md)
- [Game Saves 충돌](/ko/services/playfab/player-progression/game-saves/conflicts.md)
- [Game Saves 개요](/ko/services/playfab/player-progression/game-saves/overview.md)
- [Save](/ko/reference/system/Wrappers/classes/provider/methods/xgamesave_wrapper_provider_save.md)
- [XGameSave](/ko/reference/system/xgamesave/xgamesave_members.md)