Game Saves 오류 처리 FAQ
이 문서에서는 Game Saves가 실패를 보고하는 방식에 대한 일반적인 질문에 답합니다. 어떤 오류가 일시적(재시도할 가치가 있음)인지, 어떤 오류가 잘못된 값을 전달했음(호출을 수정해야 함)을 의미하는지, 그리고 시스템이 오류를 반환하는 대신 언제 오프라인 모드로 진입하는지 설명합니다. Game Saves는 플랫폼에 따라 두 가지 방식 중 하나로 실행되며, 오류 처리는 두 방식 간에 약간 다릅니다.- Out-of-process: 플랫폼의 기본 제공 서비스가 동기화를 수행하고 자체 시스템 UI를 표시합니다. Game Saves는 XBOX와 Windows에서 항상 이 방식으로 실행됩니다.
- In-process: 플랫폼 서비스를 사용할 수 없는 플랫폼(예: Steam Deck)에서는 SDK가 클라우드 동기화를 직접 수행합니다. 게임은 콜백을 통해 UI를 구동합니다.
Game Saves는 언제 오류를 반환하는 대신 오프라인으로 전환되나요?
오프라인 모드는 오류가 아니라 성공 결과입니다. 초기 동기화(PFGameSaveFilesAddUserWithUiAsync)는 플레이어가 동기화 실패 프롬프트에서 Use Offline / Play offline을 명시적으로 선택한 경우(또는 다른 디바이스가 활성 디바이스가 된 경우)에만 오프라인 모드로 진입합니다. 이 경우 비동기 작업은 S_OK로 완료되고 PFGameSaveFilesIsConnectedToCloud()는 false를 반환합니다. 사용 가능한 로컬 세이브 폴더는 여전히 제공됩니다.
반면 플레이어가 의도적으로 Cancel을 선택하면 E_PF_GAMESAVE_USER_CANCELLED로 완료되며 세이브 폴더가 제공되지 않습니다. 이는 “플레이를 허용하지 않음”으로 처리하세요. 게임이 XAsyncCancel로 비동기 작업을 직접 취소하면 대신 E_ABORT로 완료되며, 마찬가지로 세이브 폴더가 제공되지 않습니다. E_ABORT는 게임 자체의 취소로 처리하세요.
전체 결정 표와 오류 코드 참조는 Game Saves 오프라인 모드를 참조하세요.
PFGameSaveFilesInitialize가 일시적으로 실패할 수 있나요?
아니요. PFGameSaveFilesInitialize는 인수를 검증하고 상태를 설정할 뿐이며 네트워크에 접근하지 않습니다. 반환하는 모든 실패는 결정적입니다.
E_INVALIDARG: 필수 인수가 없거나 잘못되었습니다. In-process에서는saveFolder가 없거나 잘못된 경우도 포함됩니다(해당 플랫폼에서는 유효한 폴더가 필요하며, XBOX/GDK에서는 위치가 고정되어 있으므로 이 인수는 무시됩니다).E_PF_GAMESAVE_ALREADY_INITIALIZED: 중간에PFGameSaveFilesUninitializeAsync호출 없이 두 번 호출했습니다.
Initialize가 실패하면 재시도해도 소용없으므로 입력을 수정하세요. 특정 구성에 대해 한 번 성공하면 나중에 저절로 실패하기 시작하지 않습니다.
PFGameSaveFilesAddUserWithUiAsync가 일시적으로 실패할 수 있나요?
예. 이 호출은 네트워크 동기화를 수행하므로 일시적인 실패(네트워크 중단, 서비스 오류, 토큰 새로 고침, 디스크 공간 부족)가 발생할 수 있습니다. HTTP 호출은 타이틀의 HTTP 재시도 설정(PFHttpRetrySettings)에 따라 재시도되지만, 게임이 실패를 확인하기 전에 일시적인 실패가 해결된다는 보장은 없습니다.
이러한 재시도로 일시적인 실패가 해결되지 않으면 동기화 실패 UI를 통해 표시되며, 플레이어는 여기서 Retry, Use Offline 또는 Cancel을 선택합니다. 또는 In-process에서 동기화 실패 콜백이 등록되지 않은 경우에는 원시 HRESULT로 반환됩니다. 따라서 일시적인 실패는 일반적으로 원시 오류가 아니라 온라인, 오프라인 또는 취소로 귀결되지만, 두 경로 간에는 한 가지 중요한 차이점이 있습니다(다음 질문 참조).
PFGameSaveFilesAddUserWithUiAsync는 일시적이지 않고 재시도할 수 없는 결정적 오류도 반환할 수 있습니다.
E_INVALIDARG: 핸들/비동기 블록이 null이거나 옵션이 충돌합니다.E_PF_GAMESAVE_NOT_INITIALIZED:Initialize전에 호출되었습니다.E_PF_GAMESAVE_USER_ALREADY_ADDED: 사용자가 이미 추가되어 있습니다(그리고 여전히 연결되어 있습니다).
오프라인 옵션을 사용하려면 UI 콜백을 등록해야 하나요?
이것이 두 경로 간의 핵심 차이점입니다.- In-process: 예. 일시적인 동기화 실패에 대한 오프라인 대체는
PFGameSaveFilesAddUserWithUiAsync를 호출하기 전에 (PFGameSaveFilesSetUiCallbacks를 통해) 동기화 실패 콜백을 등록한 경우에만 발생합니다. 콜백이 등록되지 않은 경우 일시적인 실패가 발생하면 작업이 원시 오류 HRESULT로 완료되며, Retry와 Use Offline이 제공되지 않습니다. 기본 제공 Game Saves UI가 없는 플랫폼에서는 콜백 등록이 필수입니다. - Out-of-process: 일반적인 동기화 실패에는 필요하지 않습니다. 플랫폼의 기본 제공 시스템 UI가 Try again / Play offline 선택지를 자동으로 제공하므로, 동기화 중 일반적인 네트워크 실패가 발생하면 게임 콜백 없이도 플레이어에게 오프라인 옵션이 제공됩니다. 자체 UI를 제공하려는 경우 여전히 콜백을 등록할 수 있습니다.
UI가 표시되기 전에 발생하는 실패가 있나요?
Out-of-process에서만 발생합니다. 동기화 UI가 표시되기 전에PFGameSaveFilesAddUserWithUiAsync는 서비스 구성을 수집하고 (선택적으로) 사용자를 로그인시킵니다. 초기 설정 실패(예: 플랫폼 서비스를 일시적으로 사용할 수 없거나 타이틀이 Game Saves용으로 구성되지 않은 경우)가 발생하면 대화 상자가 표시되기 전에 호출이 원시 HRESULT로 완료될 수 있습니다. 이 중 일부는 일시적이며(잠시 후 PFGameSaveFilesAddUserWithUiAsync 전체를 재시도), 나머지는 구성 문제(결정적)를 나타냅니다. 로그인/토큰 실패는 정상적으로 처리되며 그 자체로 호출을 실패시키지 않습니다.
In-process에서 AddUserWithUiAsync에는 이러한 초기 설정 범주가 없습니다. 실패는 동기화 중에 발생하며 동기화 실패 UI를 거칩니다(위의 콜백 요구 사항이 적용됨).
업로드를 취소할 수 있나요?
예.PFGameSaveFilesUploadWithUiAsync는 UI(진행률 표시기 및 오류 발생 시 동기화 실패 프롬프트)를 표시하며, 플레이어는 둘 중 어느 것에서든 취소할 수 있습니다. 취소하면 작업은 E_PF_GAMESAVE_USER_CANCELLED(0x800704C7)로 완료되며 세이브는 업로드되지 않습니다.
초기 동기화와 달리 업로드에는 Use Offline 성공 결과가 없습니다. 업로드의 종료 결과는 다음과 같습니다.
- 성공(
S_OK): 클라우드에 저장되었습니다. - 취소됨(
E_PF_GAMESAVE_USER_CANCELLED): 플레이어가 취소했습니다. - 게임에서 취소함(
E_ABORT): 게임이 업로드에 대해XAsyncCancel을 호출했습니다. - 실패: 그 밖의 모든 경우(예:
E_PF_GAMESAVE_NETWORK_FAILURE또는E_PF_GAMESAVE_DEVICE_NO_LONGER_ACTIVE)입니다.
E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD로 완료되며 이후 PFGameSaveFilesIsConnectedToCloud()는 false를 반환합니다. 업로드로 인해 세션이 오프라인이 되는 경우를 참조하세요.
“플레이어가 취소함”과 “업로드 오류 발생”을 구분할 수 있도록 E_PF_GAMESAVE_USER_CANCELLED를 다른 실패와 별도로 처리하세요. 이는 초기 동기화에서 사용하는 것과 동일한 취소 코드이므로 한 번의 확인으로 두 작업을 모두 처리할 수 있습니다.
어떤 오류가 “잘못된 값을 전달함”을 나타내고, 어떤 오류가 일시적인 문제를 나타내나요?
전체 HRESULT 참조는 Game Saves 오프라인 모드를 참조하세요.
권장 사항
PFGameSaveFilesInitialize실패는 재시도할 런타임 조건이 아니라 수정해야 할 버그(잘못된 인수/구성)로 처리하세요.- In-process: 일시적인 실패 시 하드 오류 대신 플레이어에게 Retry/Use Offline이 제공되도록,
PFGameSaveFilesAddUserWithUiAsync전에 항상 UI 콜백(최소한 동기화 실패 콜백)을 등록하세요. - Out-of-process: UI가 표시되기 전에
PFGameSaveFilesAddUserWithUiAsync에서 원시 실패(서비스/구성)가 발생할 수 있음에 대비하세요. 일시적인 실패는 재시도하고, 구성 문제는 오류로 표시하세요. - 최종 결과에 따라 플레이를 제어하세요.
S_OK+ 연결됨 → 온라인으로 플레이,S_OK+ 연결되지 않음 → 오프라인으로 플레이(세이브가 동기화되지 않는다고 플레이어에게 경고), 폴더 없이 취소/실패 → 플레이 차단.