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

- [Game Saves 빠른 시작](/ko/services/playfab/player-progression/game-saves/quickstart.md)
- [Game Saves UI 콜백](/ko/services/playfab/player-progression/game-saves/ui-callbacks.md)
- [오프라인 플레이 처리 모범 사례](/ko/services/xbox-services/develop/best-practices/live-best-practices-offline-play.md)
- [XBOX 서비스 사용자 권한의 클라이언트 측 사용](/ko/services/xbox-services/fundamentals/identity/privileges/concepts/live-user-privileges-client.md)
- [게임 저장 동기화 흐름 이해](/ko/build/core-features/common/game-save/game-saves-syncing.md)