Game Saves 오프라인 모드

​

연결 모드

​

클라우드 연결 모드

• 모든 API가 정상적으로 작동하며 완전한 클라우드 동기화가 수행됩니다.
• 세이브 데이터 업로드가 정상적으로 작동합니다.
• 저장소 할당량 정보를 사용할 수 있습니다.
• 활성 디바이스 모니터링이 제대로 작동합니다.

​

오프라인 모드(클라우드 미연결)

​

초기 동기화 중 네트워크 실패 처리

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

• PFGameSaveFilesGetFolder() - 로컬 세이브 폴더 경로를 반환합니다.

​

제한된 기능을 가진 API

• PFGameSaveFilesUploadWithUiAsync() - 즉시 S_OK를 반환하지만, 비동기 완료는 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD를 반환합니다.
• PFGameSaveFilesGetRemainingQuota() - E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD를 반환합니다.
• PFGameSaveFilesSetActiveDeviceChangedCallback() - 설정할 수는 있지만 트리거되지 않습니다.

​

온라인 모드로 복귀

• PFGameSaveFilesAddUserWithUiAsync()를 다시 호출하여 재연결을 시도합니다.
• Game Saves 시스템을 완전히 다시 초기화할 필요는 없습니다.
• 네트워크가 여전히 사용 불가능하면 실패 UI가 다시 표시됩니다.
• 재시도 후 PFGameSaveFilesIsConnectedToCloud()를 사용하여 연결 상태를 확인합니다.

​

Game Saves가 오프라인 모드로 진입하거나 오류를 반환하는 경우

• 오프라인 모드는 오류가 아니라 성공 결과입니다. 명시적인 Use Offline 선택으로만 진입하며, 비동기 작업은 S_OK로 완료됩니다. PFGameSaveFilesIsConnectedToCloud()로 감지합니다.
• 일시적/기술적 실패는 동기화 실패 UI를 통해 표시되며, PFGameSaveFilesAddUserWithUiAsync에서 직접 반환되지 않습니다. 그런 다음 사용자(또는 자동 응답)가 Retry, UseOffline 또는 Cancel을 선택하며, 이는 위의 세 가지 결과 중 하나로 이어집니다.
• 취소는 종료 결과이며 세이브 폴더를 생성하지 않습니다. “취소됨”(또는 폴더를 남기지 않는 모든 실패)은 플레이를 허용하지 않음으로 처리하세요.
• 플레이어 취소와 게임 취소는 서로 다른 코드를 반환합니다. 플레이어가 프롬프트에서 Cancel을 선택한 경우에만 E_PF_GAMESAVE_USER_CANCELLED가 생성됩니다. 게임이 XAsyncCancel로 작업을 직접 취소하면 E_ABORT로 완료됩니다. 둘을 같은 방식으로 처리하려면 두 코드를 모두 확인하세요.

​

Game Saves 오류 코드

​

추가 연결 상태 시나리오

• 동기화 중 네트워크 사용 불가: 사용자가 명시적으로 오프라인 플레이를 선택합니다.
• 활성 디바이스 변경: 다른 디바이스가 활성 디바이스로 인계되어 이 디바이스가 자동으로 오프라인 모드로 전환됩니다.

​

오프라인 지원을 위한 모범 사례

1. 항상 동기화 실패 콜백을 구현하여 네트워크 문제를 원활하게 처리하세요
2. 클라우드 작업을 시도하기 전에 PFGameSaveFilesIsConnectedToCloud()를 사용하여 연결 상태를 정기적으로 확인하세요
3. 오프라인 모드로 작동 중일 때 플레이어에게 알려서 세이브가 동기화되지 않는다는 점을 인지시키세요
4. 네트워크 연결이 복구되면 재시도 옵션을 제공하세요
5. 로컬 세이브는 항상 작동합니다 - 플레이어는 네트워크 상태와 관계없이 계속 플레이할 수 있습니다
6. 연결 해제 모니터링 - 다른 디바이스가 활성화될 때 디바이스가 연결 해제될 수 있음을 기억하세요

​

연결 모드에서의 업로드 동작

1. PFGameSaveFilesUiSyncFailedCallback이 오류 세부 정보와 함께 실행됩니다.
2. XAsyncBlock 콜백은 아직 실행되지 않습니다. 시스템이 응답을 기다리는 동안 작업이 일시 중지됩니다.
3. 사용자가 Retry를 선택하면 업로드가 재시도됩니다. 다시 실패하면 콜백이 다시 실행되고 사용자가 다시 응답해야 합니다.
4. 사용자가 Cancel을 선택하면 XAsyncBlock 콜백이 E_PF_GAMESAVE_USER_CANCELLED로 실행됩니다.
5. 재시도가 성공하면 XAsyncBlock 콜백이 S_OK로 실행됩니다.

​

업로드로 인해 세션이 오프라인이 되는 경우

• 세션이 이미 오프라인 상태였습니다. 네트워크가 복구되었더라도 업로드는 실행되지 않고 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD로 완료됩니다.
• 클라우드에 더 최신 세이브가 있습니다. 업로드를 마무리할 때 다른 디바이스에서 더 최신 세이브가 커밋되었다고 서비스가 보고하면, Game Saves는 세션을 오프라인으로 전환하고 활성 디바이스 변경 콜백을 실행한 다음 업로드를 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD로 완료합니다.
• 플레이어가 다시 잠금 프롬프트에서 Use Offline을 선택합니다. 이전 업로드가 데이터를 커밋했지만 이후에 실패한 경우, 다음 업로드는 먼저 세이브 잠금을 다시 획득해야 합니다. 이 단계에서 표시되는 동기화 실패 프롬프트에 UseOffline으로 응답할 수 있으며, 그러면 세션이 오프라인으로 전환되고 업로드는 E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD로 완료됩니다.

​

업로드 취소