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

# Reversão do Game Saves

> Restaure um jogo salvo do PlayFab Game Saves para um estado anterior usando as opções RollbackToLastKnownGood ou RollbackToLastConflict na API de adição de usuário.

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](/pt-BR/services/playfab/player-progression/game-saves/conflicts), 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.

```cpp theme={null}
// 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:

```cpp theme={null}
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](/pt-BR/services/playfab/player-progression/game-saves/ui-callbacks) 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.


## Related topics

- [Eventos do PlayStream do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/playstream-events.md)
- [Conflitos do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/conflicts.md)
- [Visão geral do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/overview.md)
- [Depuração do Game Saves](/pt-BR/build/core-features/common/game-save/game-saves-debugging.md)
- [Ferramentas do Game Saves](/pt-BR/build/core-features/common/game-save/game-saves-tools.md)