Reversão do Game Saves

A reversão permite restaurar o jogo salvo de um jogador para um estado anterior. Use-a quando o salvamento de um jogador for corrompido, quando uma atualização do título introduzir um bug que danifique os dados salvos ou quando um jogador quiser reverter uma decisão de resolução de conflito.

Como a reversão funciona

O Game Saves acompanha as versões finalizadas dos dados salvos de um jogador. Quando você dispara uma reversão, o serviço cria uma nova versão cujo conteúdo é idêntico ao estado anterior que você está restaurando. A reversão preserva o histórico de versões original. Ela não exclui nem sobrescreve as versões anteriores. Outros dispositivos que sincronizam após a reversão a veem como uma atualização normal. Há dois tipos de reversão. Você dispara cada um passando um sinalizador de opção para PFGameSaveFilesAddUserWithUiAsync:

Opção	Descrição
`PFGameSaveFilesAddUserOptions::RollbackToLastKnownGood`	Restaura o salvamento anterior na nuvem verificado mais recentemente. Esse salvamento foi carregado anteriormente e depois substituído por um upload mais recente.
`PFGameSaveFilesAddUserOptions::RollbackToLastConflict`	Restaura o estado de salvamento que perdeu a resolução de conflito mais recente.

Ambas as opções recorrem ao comportamento padrão (sincronizar a versão mais recente atual) se não houver um ponto de restauração qualificado.

Quando usar cada tipo de reversão

Reversão para a última versão válida conhecida

Use RollbackToLastKnownGood quando suspeitar que o upload mais recente está incorreto. Os gatilhos comuns incluem:

Falha de carregamento ou falha na verificação de integridade após baixar um salvamento.
Uma falha durante ou imediatamente após uma operação de salvamento.
Um relato de jogador sobre estado corrompido ou regredido.

O serviço acompanha automaticamente quais versões são “válidas conhecidas”. Você não precisa marcá-las explicitamente. Uma versão se torna válida conhecida quando você a carrega com êxito e um upload mais recente a substitui posteriormente.

Reversão para o último conflito

Use RollbackToLastConflict quando um jogador escolheu o lado errado durante a resolução de conflito. Conforme descrito em Conflitos do Game Saves, ambas as escolhas de resolução preservam o branch descartado. Esta opção de reversão restaura esse branch preservado.

Chamando a API

Dispare a reversão passando a opção apropriada para PFGameSaveFilesAddUserWithUiAsync. Você só pode chamar essa função uma vez por usuário; portanto, para reverter um usuário que já foi adicionado, primeiro chame PFGameSaveFilesUninitializeAsync e aguarde a conclusão.

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

Para reverter para o perdedor do último conflito, substitua o sinalizador de opção:

HRESULT hr = PFGameSaveFilesAddUserWithUiAsync(
    localUserHandle,
    PFGameSaveFilesAddUserOptions::RollbackToLastConflict,
    &async
);

Comportamento de fallback

Se não houver um ponto de restauração qualificado para o tipo de reversão solicitado, a chamada se comportará como se você tivesse passado PFGameSaveFilesAddUserOptions::None. A versão mais recente atual é sincronizada normalmente. Verifique os arquivos sincronizados após a conclusão da chamada para confirmar se ocorreu uma reversão.

Configuração do título

Você pode restringir a reversão iniciada pelo cliente por meio de dois sinalizadores de configuração. Ao habilitar qualquer um dos sinalizadores, somente as ferramentas de suporte e o Game Manager poderão executar esse tipo de reversão.

Sinalizador	Efeito
`DisableClientRollbackToLastKnownGood`	Impede que os clientes do jogo revertam para a última versão válida conhecida.
`DisableClientRollbackToLastConflictLoser`	Impede que os clientes do jogo revertam a decisão de resolução de conflito mais recente.

Defina esses sinalizadores no Game Manager em Progression > Game Saves.

Tratamento de erros

HRESULT	Significado
`E_PF_GAME_SAVE_MANIFEST_NOT_ELIGIBLE_FOR_ROLLBACK`	Não há um ponto de restauração qualificado para o tipo de reversão solicitado.
`E_PF_GAME_SAVE_NOT_FINALIZED_MANIFEST_NOT_ELIGIBLE_AS_KNOWN_GOOD`	A versão de destino não está qualificada como ponto de restauração válido conhecido.
`E_PF_GAME_SAVE_SERVICE_NOT_ENABLED_FOR_TITLE`	O Game Saves não está habilitado para este título. Conclua a integração primeiro.
`E_PF_GAME_SAVE_SERVICE_ONBOARDING_PENDING`	A integração do título ainda está em andamento.

Considerações

A reversão cria uma nova versão. Ela não apaga o histórico. A sequência de versões do jogador continua avançando.
O serviço acompanha as versões válidas conhecidas automaticamente. Ele determina quais versões se qualificam com base em ciclos bem-sucedidos de carregamento seguido de substituição. Seu jogo não precisa marcar as versões explicitamente.
Uma reversão por chamada de adição de usuário. Como você só pode chamar PFGameSaveFilesAddUserWithUiAsync uma vez por usuário, disparar uma segunda reversão exige chamar PFGameSaveFilesUninitializeAsync primeiro.
Os retornos de chamada de interface do usuário continuam sendo disparados. A reversão passa pelo mesmo fluxo de sincronização de uma chamada normal de adição de usuário. Registre seus retornos de chamada de interface do usuário antes de chamar a API.
Restrinja a reversão, se necessário. Se o seu jogo tratar a recuperação no lado do servidor ou por meio de ferramentas de suporte, desabilite a reversão pelo cliente com os sinalizadores de configuração do título para evitar que os jogadores revertam o progresso acidentalmente.
A reversão funciona em todas as plataformas. Esta API não tem proteções específicas de plataforma.

XBOX Services

PlayFab

Como a reversão funciona

Quando usar cada tipo de reversão

Reversão para a última versão válida conhecida

Reversão para o último conflito

Chamando a API

Comportamento de fallback

Configuração do título

Tratamento de erros

Considerações

​Como a reversão funciona

​Quando usar cada tipo de reversão

​Reversão para a última versão válida conhecida

​Reversão para o último conflito

​Chamando a API

​Comportamento de fallback

​Configuração do título

​Tratamento de erros

​Considerações

Como a reversão funciona

Quando usar cada tipo de reversão

Reversão para a última versão válida conhecida

Reversão para o último conflito

Chamando a API

Comportamento de fallback

Configuração do título

Tratamento de erros

Considerações