Perguntas frequentes sobre tratamento de erros do Game Saves
Este artigo responde a perguntas comuns sobre como o Game Saves relata falhas: quais erros são transitórios (vale a pena tentar novamente), quais significam que você passou algo errado (corrija a chamada) e quando o sistema entra no modo offline em vez de retornar um erro. O Game Saves é executado de uma de duas maneiras, dependendo da plataforma, e o tratamento de erros difere ligeiramente entre elas:- Fora do processo: o serviço interno da plataforma executa a sincronização e mostra sua própria interface do sistema. O Game Saves sempre é executado dessa forma no XBOX e no Windows.
- No processo: o próprio SDK executa a sincronização com a nuvem, em plataformas onde o serviço da plataforma não está disponível (por exemplo, Steam Deck). Seu jogo controla a interface por meio de retornos de chamada.
Quando o Game Saves fica offline em vez de retornar um erro?
O modo offline é um resultado de êxito, não um erro. A sincronização inicial (PFGameSaveFilesAddUserWithUiAsync) só entra no modo offline quando o jogador escolhe explicitamente Use Offline / Play offline em um aviso de falha de sincronização (ou quando outro dispositivo se torna o dispositivo ativo). Nesse caso, a operação assíncrona é concluída com S_OK e PFGameSaveFilesIsConnectedToCloud() retorna false. Você ainda obtém uma pasta de salvamento local utilizável.
Já um Cancel deliberado do jogador é concluído com E_PF_GAMESAVE_USER_CANCELLED e não fornece uma pasta de salvamento. Trate isso como “não permitir jogar”. Se o seu jogo cancelar a operação assíncrona por conta própria com XAsyncCancel, ela será concluída com E_ABORT, também sem pasta de salvamento; trate E_ABORT como seu próprio cancelamento.
Para ver a tabela de decisão completa e a referência de códigos de erro, consulte Modo offline do Game Saves.
PFGameSaveFilesInitialize pode falhar de forma transitória?
Não. PFGameSaveFilesInitialize apenas valida seus argumentos e configura o estado. Ele não acessa a rede. Todas as falhas que ele retorna são determinísticas:
E_INVALIDARG: um argumento obrigatório está ausente ou é inválido. No processo, isso inclui umsaveFolderausente ou inválido (uma pasta válida é obrigatória nessas plataformas; no XBOX/GDK, o local é fixo e o argumento é ignorado).E_PF_GAMESAVE_ALREADY_INITIALIZED: você o chamou duas vezes sem uma chamada intermediária aPFGameSaveFilesUninitializeAsync.
Initialize falhar, tentar novamente não ajudará. Corrija a entrada. Se ele tiver êxito uma vez para uma determinada configuração, não começará a falhar mais tarde por conta própria.
PFGameSaveFilesAddUserWithUiAsync pode falhar de forma transitória?
Sim. Esta é a chamada que executa a sincronização pela rede, portanto pode encontrar falhas transitórias (rede indisponível, erros de serviço, atualização de token, falta de espaço em disco). As chamadas HTTP são repetidas de acordo com as configurações de repetição HTTP do título (PFHttpRetrySettings), mas não há garantia de que uma falha transitória seja resolvida antes que seu jogo a perceba.
Quando uma falha transitória não é resolvida por essas repetições, ela é exibida por meio da interface de falha de sincronização, na qual o jogador escolhe Retry, Use Offline ou Cancel. No processo e sem retorno de chamada de falha de sincronização registrado, ela retorna como um HRESULT bruto. Portanto, uma falha transitória normalmente resulta em online, offline ou cancelamento, em vez de um erro bruto, com uma diferença importante entre os dois caminhos (consulte a próxima pergunta).
PFGameSaveFilesAddUserWithUiAsync também pode retornar erros determinísticos que não são transitórios e não podem ser repetidos:
E_INVALIDARG: identificador/async nulo ou opções conflitantes.E_PF_GAMESAVE_NOT_INITIALIZED: chamado antes deInitialize.E_PF_GAMESAVE_USER_ALREADY_ADDED: o usuário já foi adicionado (e ainda está conectado).
Preciso registrar retornos de chamada de interface para obter a opção offline?
Esta é a principal diferença entre os dois caminhos:- No processo: sim. O fallback offline para uma falha transitória de sincronização só acontece se você tiver registrado um retorno de chamada de falha de sincronização (por meio de
PFGameSaveFilesSetUiCallbacks) antes de chamarPFGameSaveFilesAddUserWithUiAsync. Se nenhum retorno de chamada estiver registrado, uma falha transitória conclui a operação com o HRESULT de erro bruto. Não há Retry nem Use Offline. Em plataformas sem interface interna do Game Saves, registrar os retornos de chamada é obrigatório. - Fora do processo: não para falhas de sincronização comuns. A interface interna do sistema da plataforma fornece automaticamente as opções Try again / Play offline, de modo que falhas de rede comuns durante a sincronização oferecem ao jogador uma opção offline sem nenhum retorno de chamada do jogo. Você ainda pode registrar retornos de chamada para fornecer sua própria interface.
Há falhas que acontecem antes de qualquer interface aparecer?
Somente fora do processo. Antes que a interface de sincronização possa aparecer,PFGameSaveFilesAddUserWithUiAsync coleta a configuração do serviço e (opcionalmente) conecta o usuário. Falhas de configuração inicial, por exemplo, o serviço da plataforma estar momentaneamente indisponível ou o título não estar configurado para o Game Saves, podem concluir a chamada com um HRESULT bruto antes que qualquer caixa de diálogo seja exibida. Algumas delas são transitórias (repita todo o PFGameSaveFilesAddUserWithUiAsync um momento depois); outras indicam problemas de configuração (determinísticas). Falhas de entrada/token são tratadas normalmente e não fazem a chamada falhar por si só.
No processo, AddUserWithUiAsync não tem essa categoria de configuração inicial. As falhas ocorrem durante a sincronização e passam pela interface de falha de sincronização (sujeito ao requisito de retorno de chamada acima).
Um upload pode ser cancelado?
Sim.PFGameSaveFilesUploadWithUiAsync mostra uma interface (um indicador de progresso e um aviso de falha de sincronização se encontrar um erro), e o jogador pode sair de qualquer um deles. Quando isso acontece, a operação é concluída com E_PF_GAMESAVE_USER_CANCELLED (0x800704C7) e o salvamento não é enviado.
Ao contrário da sincronização inicial, um upload não tem um resultado de êxito Use Offline. Seus resultados finais são:
- Êxito (
S_OK): salvo na nuvem. - Cancelado (
E_PF_GAMESAVE_USER_CANCELLED): o jogador desistiu. - Cancelado pelo seu jogo (
E_ABORT): seu jogo chamouXAsyncCancelno upload. - Falha: todo o resto (por exemplo,
E_PF_GAMESAVE_NETWORK_FAILUREouE_PF_GAMESAVE_DEVICE_NO_LONGER_ACTIVE).
E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD, e PFGameSaveFilesIsConnectedToCloud() retorna false depois, quando a sessão já estava offline, quando a nuvem tem um salvamento mais recente de outro dispositivo ou quando o jogador escolhe Use Offline no aviso de novo bloqueio que segue um upload anterior com falha parcial. Consulte Quando um upload deixa a sessão offline.
Trate E_PF_GAMESAVE_USER_CANCELLED separadamente de outras falhas para que você possa distinguir “o jogador cancelou” de “o upload apresentou erro”. Esse é o mesmo código de cancelamento usado pela sincronização inicial, portanto, uma única verificação abrange as duas operações.
Quais erros indicam “você passou algo errado” em vez de um problema transitório?
Consulte a referência completa de HRESULT em Modo offline do Game Saves.
Recomendações
- Trate falhas de
PFGameSaveFilesInitializecomo bugs a corrigir (argumentos/configuração inválidos), e não como condições de tempo de execução a serem repetidas. - No processo: sempre registre seus retornos de chamada de interface (no mínimo, o retorno de chamada de falha de sincronização) antes de
PFGameSaveFilesAddUserWithUiAsync, para que falhas transitórias ofereçam ao jogador Retry/Use Offline em vez de um erro definitivo. - Fora do processo: esteja preparado para uma falha bruta de
PFGameSaveFilesAddUserWithUiAsyncantes de qualquer interface (serviço/configuração). Repita as transitórias; exiba problemas de configuração como erros. - Condicione o jogo ao resultado final:
S_OK+ conectado → jogar online;S_OK+ não conectado → jogar offline (avise o jogador de que os salvamentos não serão sincronizados); cancelamento/falha sem pasta → bloquear o jogo.