Início rápido do Game Saves

O PlayFab Game Saves permite que os jogadores continuem seu progresso de forma contínua entre dispositivos, sincronizando os dados salvos com a nuvem. Este guia de início rápido orienta você na implementação de uma solução completa de jogos salvos para as plataformas XBOX e Windows.

Pré-requisitos

Antes de começar, verifique se você:

Foi integrado ao Game Saves
Revisou os requisitos de implementação na seção de visão geral
Concluiu os requisitos listados abaixo
(Opcional) Clonou ou revisou o exemplo do Game Saves completo para Windows no GitHub: PlayFabGameSaveSample-Windows. O exemplo demonstra os fluxos de inicialização, sincronização, tratamento de conflitos e upload mencionados neste início rápido.

O que você aprenderá

Neste guia, você aprenderá a:

Inicializar o sistema do Game Saves
Baixar os dados salvos existentes da nuvem
Carregar os dados salvos locais na nuvem
Tratar conflitos e retornos de chamada de interface do usuário
Gerenciar cenários de dispositivo ativo

Requisitos de desenvolvimento

Requisitos de software

Uma conta de desenvolvedor do PlayFab
O Visual Studio 2019 ou o Visual Studio 2022 é recomendado para o desenvolvimento com o Gaming Runtime. Consulte https://learn.microsoft.com/en-us/gaming/gdk/docs/gdk-dev/get-started/overviews/sdk-and-tools#install-visual-studio para obter detalhes.
Acesso ao Microsoft Game Development Kit (GDK) mais recente

Visão geral do fluxo do Game Saves

O sistema do Game Saves segue um padrão simples que funciona perfeitamente entre dispositivos:

Configuração inicial (uma vez por sessão de jogo)

Inicializar os serviços: configure os módulos PlayFab Core e Game Saves
Autenticar o usuário: conecte o jogador usando a autenticação do XBOX
Baixar os salvamentos existentes: sincronize os dados salvos de outros dispositivos com o dispositivo local
Obter o local de salvamento: obtenha a pasta raiz de salvamento local em que seu jogo deve gravar os arquivos salvos

Durante o jogo

Gravar os arquivos salvos: seu jogo grava os dados salvos na pasta raiz de salvamento local, como de costume
Carregar as alterações: carregue periodicamente na nuvem os arquivos salvos modificados
Continuar jogando: repita as etapas 5 e 6 conforme necessário durante a sessão de jogo

Fim da sessão

Upload final: carregue as alterações finais antes que o jogador saia
Sincronização em segundo plano: no XBOX/Windows, o sistema trata automaticamente os uploads finais quando o jogo é fechado

Principais benefícios

Suporte offline: os jogadores podem começar a jogar mesmo sem conexão com a Internet
Resolução automática de conflitos: a interface do usuário integrada trata os conflitos de salvamento entre dispositivos
Uploads incrementais: somente os arquivos alterados são carregados, melhorando o desempenho
Continuidade entre dispositivos: experiência contínua ao trocar de dispositivo

Detalhes da implementação

As seções a seguir fornecem exemplos de código detalhados para cada etapa:

Etapa 1: inicializar o Game Saves

O Game Saves foi projetado para funcionar online e offline, o que o diferencia de outras APIs do PlayFab. Ele mantém uma identidade de usuário local persistente que funciona mesmo quando o dispositivo é iniciado offline.

Conceitos principais

PFLocalUserHandle: um identificador de usuário persistente que funciona offline
PFServiceConfigHandle: a configuração do seu título do PlayFab
Design com prioridade para o modo offline: o sistema funciona imediatamente, mesmo sem conectividade com a Internet

Pré-requisitos

Antes de inicializar o Game Saves, verifique se você:

Chamou XGameRuntimeInitialize() para inicializar o runtime do XBOX
Chamou XUserAddAsync() para conectar um usuário e obter um XUserHandle
Tem a ID do título do PlayFab do Game Manager

Implementação

// Step 1: Initialize PlayFab Core
HRESULT hr = PFInitialize(nullptr);
if (FAILED(hr))
{
    // Handle initialization failure - log error and exit gracefully
    return hr;
}

// Step 2: Create service config handle with your title information
PFServiceConfigHandle serviceConfigHandle{ nullptr };
hr = PFServiceConfigCreateHandle(
    "https://<titleId>.playfabapi.com",    // Replace <titleId> with your actual PlayFab Title ID
    "<titleId>",                           // Replace <titleId> with your actual PlayFab Title ID
    &serviceConfigHandle);
if (FAILED(hr))
{
    // Handle service config creation failure
    return hr;
}

// Step 3: Initialize the Game Saves module
PFGameSaveInitArgs args = {};
// Set args.saveFolder here if you are targetting platforms such as Steam
// where you need to provide root of where the game saves are
hr = PFGameSaveFilesInitialize(&args);
if (FAILED(hr))
{
    // Handle Game Saves initialization failure
    return hr;
}

// Step 4: Create a local user handle
// NOTE: Assumes you have already obtained 'xuserHandle' from XUserAddAsync
PFLocalUserHandle localUserHandle;
hr = PFLocalUserCreateHandleWithXboxUser(serviceConfigHandle, xuserHandle, nullptr, &localUserHandle);
if (FAILED(hr))
{
    // Handle local user creation failure
    return hr;
}

// Success! The Game Saves system is now initialized and ready to use

Substitua <titleId> pela ID real do seu título do PlayFab no Game Manager. O xuserHandle deve ser obtido de uma chamada bem-sucedida a XUserAddAsync.

Plataformas alternativas

Para plataformas sem autenticação do XBOX e sem suporte offline, use outras versões de PFLocalUserCreateHandle ou PFLocalUserCreateHandleWithPersistedLocalId. Consulte a documentação específica da plataforma para obter os detalhes de implementação. Por exemplo:

PFLocalUserHandle localUserHandle;
hr = PFLocalUserCreateHandleWithSteamUser(serviceConfigHandle, nullptr, &localUserHandle);
if (FAILED(hr))
{
    // Handle local user creation failure
    return hr;
}

Etapa 2: sincronizar os dados salvos da nuvem

Após a inicialização, adicione o usuário ao sistema do Game Saves para sincronizar os dados salvos existentes de outros dispositivos. Esta etapa também configura a pasta raiz de salvamento local em que seu jogo lerá e gravará os arquivos salvos.

Quando chamar

Uma vez por sessão de jogo, após a autenticação do usuário
Quando o usuário retorna ao menu principal do jogo
Ao retomar após a suspensão/execução em segundo plano

O que esta etapa faz

Baixa os salvamentos existentes de outros dispositivos (somente arquivos novos ou alterados)
Preserva os carimbos de data/hora dos arquivos, quando possível, para o controle de versão adequado
Trata os conflitos automaticamente por meio da interface do usuário integrada
Define o dispositivo como ativo para este usuário
Fornece o caminho da pasta de salvamento em que seu jogo deve gravar os arquivos

Limitações importantes

Só pode ser chamado uma vez com êxito por sessão do Game Saves
Exige a reinicialização do sistema do Game Saves para ser chamado novamente
Dispara prompts de interface do usuário para conflitos, problemas de armazenamento e disputa de dispositivos

Implementação

// Add user to Game Saves system and sync from cloud
HRESULT hr;
XAsyncBlock async{};
hr = PFGameSaveFilesAddUserWithUiAsync(localUserHandle, PFGameSaveFilesAddUserOptions::None, &async);
if (FAILED(hr))
{
    // Handle API call failure
    return hr;
}

// Wait for the operation to complete
// For production code, consider using a callback instead of blocking
hr = XAsyncGetStatus(&async, true); 
if (FAILED(hr))
{
    // Handle async operation failure (network issues, user cancellation, etc.)
    return hr;
}

hr = PFGameSaveFilesAddUserWithUiResult(&async);
if (FAILED(hr))
{
    // Handle specific operation failures (conflicts, storage issues, etc.)
    return hr;
}

// Get the local save root folder path for your game
char saveFolder[1024] = { 0 };
hr = PFGameSaveFilesGetFolder(localUserHandle, 1024, saveFolder, nullptr);
if (FAILED(hr))
{
    // Handle folder retrieval failure
    return hr;
}

// Check remaining cloud storage quota
int64_t remainingQuota{ 0 };
hr = PFGameSaveFilesGetRemainingQuota(localUserHandle, &remainingQuota);
if (FAILED(hr))
{
    // Handle quota retrieval failure
    return hr;
}

// Success! You can now read/write save files in the saveFolder directory
printf("Save folder: %s\n", saveFolder);
printf("Remaining quota: %lld bytes\n", remainingQuota);

Próximas etapas

Depois que esta chamada for concluída com êxito:

Seu jogo poderá ler os arquivos salvos existentes no diretório saveFolder
Gravar novos arquivos salvos e criar subdiretórios conforme necessário
O dispositivo passará a ser considerado “ativo” para este usuário
Outros dispositivos mostrarão um aviso se o usuário tentar sincronizar neles

Etapa 3: carregar os dados salvos na nuvem

Depois que seu jogo gravar arquivos salvos e subpastas na pasta raiz de salvamento local, use esta etapa para carregar as alterações na nuvem. O sistema detecta e carrega automaticamente apenas os arquivos e subpastas que foram alterados desde o último upload. As exclusões de arquivos e pastas também são sincronizadas automaticamente com a nuvem.

Momentos sugeridos para o upload

Após um progresso significativo: quando o jogador chega a um checkpoint ou conclui um nível
Antes de transições de menu: ao retornar ao menu principal ou trocar de modo de jogo
Ao sair do jogo: antes que o jogador saia do jogo
Salvamentos periódicos: a cada poucos minutos durante sessões de jogo longas

Opções de upload

KeepDeviceActive: o dispositivo permanece ativo, permitindo uploads adicionais mais tarde
ReleaseDeviceAsActive: libera o dispositivo como ativo, permitindo uma sincronização contínua em outros dispositivos

Comportamento da plataforma

XBOX/Windows: o upload continua em segundo plano após o jogo ser fechado
Outras plataformas (Steam Deck etc.): o upload deve ser concluído antes de sair do jogo; caso contrário, os dados salvos não chegarão à nuvem

Implementação

// Upload save files to cloud
XAsyncBlock async{};
HRESULT hr = PFGameSaveFilesUploadWithUiAsync(
    localUserHandle, 
    PFGameSaveFilesUploadOption::KeepDeviceActive,  // Use ReleaseDeviceAsActive when quitting
    &async);
if (FAILED(hr))
{
    // Handle API call failure
    return hr;
}

// Wait for upload to complete
// Consider using callbacks for better user experience
hr = XAsyncGetStatus(&async, true); 
if (FAILED(hr))
{
    // Handle async operation failure (network issues, storage full, etc.)
    return hr;
}

hr = PFGameSaveFilesUploadWithUiResult(&async);
if (FAILED(hr))
{
    // Handle upload failure
    return hr;
}

// Success! Save data is now safely stored in the cloud

Quando posso gravar na pasta de salvamento novamente?

Durante o upload, o sistema lê e compacta seus arquivos salvos locais antes de carregá-los. Quando o estado de sincronização passa para Uploading (relatado por meio de PFGameSaveFilesUiProgressCallback), o sistema terminou de ler seus arquivos, e é seguro gravar na pasta de salvamento novamente. Você não precisa aguardar a conclusão do upload completo antes de retomar os salvamentos. Se você não estiver usando o retorno de chamada de progresso, aguarde a conclusão do XAsyncBlock antes de gravar novos dados salvos.

Práticas recomendadas

Trate as falhas adequadamente: problemas de rede não devem fazer seu jogo falhar
Use as opções apropriadas:
- Use KeepDeviceActive durante o jogo para uploads adicionais
- Use ReleaseDeviceAsActive quando o jogador estiver saindo ou retornando ao menu
Avise os usuários em plataformas que não são XBOX: informe os jogadores para não sair durante o upload

Considerações sobre a frequência

Vários uploads por sessão têm suporte e são eficientes
Somente os arquivos alterados são carregados, minimizando o uso de largura de banda
Consulte a documentação de limites para conhecer as cotas e restrições específicas

Etapa 4: tratar os retornos de chamada de interface do usuário (opcional)

O Game Saves fornece uma interface do usuário integrada para as plataformas XBOX e Windows. Em outras plataformas (como o Steam Deck), seu jogo deve fornecer sua própria interface do usuário tratando os retornos de chamada. Os retornos de chamada de interface do usuário são disparados durante PFGameSaveFilesAddUserWithUiAsync e PFGameSaveFilesUploadWithUiAsync. Cada retorno de chamada pausa a operação assíncrona até que seu jogo responda; o retorno de chamada do XAsyncBlock só é disparado depois que todos os retornos de chamada de interface do usuário forem resolvidos.

// Set up custom UI callbacks (call this before AddUser or Upload operations)
// See sample for detailed examples of these callbacks.
PFGameSaveUICallbacks callbacks{};
callbacks.progressCallback = MyProgressCallback;
callbacks.syncFailedCallback = MySyncFailedCallback;
callbacks.activeDeviceContentionCallback = MyActiveDeviceContentionCallback;
callbacks.conflictCallback = MyConflictCallback;
callbacks.outOfStorageCallback = MyOutOfStorageCallback;

HRESULT hr = PFGameSaveFilesSetUiCallbacks(&callbacks);

Para ver a lista completa de tipos de retorno de chamada, APIs de resposta, ações do usuário e detalhes sobre como a máquina de estado funciona, consulte Retornos de chamada de interface do usuário do Game Saves.

Entendendo os conflitos de salvamento

Os conflitos de salvamento ocorrem quando os mesmos dados do jogo foram modificados em vários dispositivos. O Game Saves trata cada subpasta de nível raiz como uma unidade atômica para a resolução de conflitos, e os jogadores podem optar por manter os dados locais ou da nuvem quando surgirem conflitos. Para obter cenários detalhados de tratamento de conflitos e práticas recomendadas, consulte Conflitos do Game Saves.

Entendendo o modo offline do Game Saves

O Game Saves funciona online e offline. Quando conectado à nuvem, todas as APIs funcionam normalmente. Quando offline ou desconectado, os salvamentos locais continuam funcionando, mas as operações na nuvem retornam E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD. Use PFGameSaveFilesIsConnectedToCloud() para verificar o status da conexão e implemente retornos de chamada de falha de sincronização para tratar adequadamente os problemas de rede. Para obter detalhes sobre o comportamento offline e práticas recomendadas, consulte Modo offline do Game Saves.

Entendendo as alterações de dispositivo ativo do Game Saves

Quando um jogador troca de dispositivo no meio de uma sessão, é importante evitar que ele perca progresso acidentalmente ao jogar em vários dispositivos simultaneamente. Se o seu jogo só fizer o login usando o recurso Single Point of Presence (SPOP) do XBOX, esse cenário será evitado automaticamente. O SPOP garante que um usuário só possa estar conectado em um dispositivo XBOX por vez. Caso contrário, você também deve implementar o retorno de chamada de alteração do dispositivo ativo para tratar os cenários em que um jogador troca de dispositivo no meio de uma sessão Para obter detalhes sobre o comportamento e práticas recomendadas, consulte Alterações de dispositivo ativo do Game Saves.

Depuração

A maneira mais fácil de ver os resultados e depurar quaisquer chamadas do SDK é habilitar o Rastreamento de depuração. Habilitar o rastreamento de depuração permite ver os resultados na janela de saída do depurador e conectar os resultados aos logs do seu próprio jogo.

​Início rápido do Game Saves

​Pré-requisitos

​O que você aprenderá

​Requisitos de desenvolvimento

​Requisitos de software

​Visão geral do fluxo do Game Saves

​Configuração inicial (uma vez por sessão de jogo)

​Durante o jogo

​Fim da sessão

​Principais benefícios

​Detalhes da implementação

​Etapa 1: inicializar o Game Saves

​Conceitos principais

​Pré-requisitos

​Implementação

​Plataformas alternativas

​Etapa 2: sincronizar os dados salvos da nuvem

​Quando chamar

​O que esta etapa faz

​Limitações importantes

​Implementação

​Próximas etapas

​Etapa 3: carregar os dados salvos na nuvem

​Momentos sugeridos para o upload

​Opções de upload

​Comportamento da plataforma

​Implementação

​Quando posso gravar na pasta de salvamento novamente?

​Práticas recomendadas

​Considerações sobre a frequência

​Etapa 4: tratar os retornos de chamada de interface do usuário (opcional)

​Entendendo os conflitos de salvamento

​Entendendo o modo offline do Game Saves

​Entendendo as alterações de dispositivo ativo do Game Saves

​Depuração

Início rápido do Game Saves

Pré-requisitos

O que você aprenderá

Requisitos de desenvolvimento

Requisitos de software

Visão geral do fluxo do Game Saves

Configuração inicial (uma vez por sessão de jogo)

Durante o jogo

Fim da sessão

Principais benefícios

Detalhes da implementação

Etapa 1: inicializar o Game Saves

Conceitos principais

Pré-requisitos

Implementação

Plataformas alternativas

Etapa 2: sincronizar os dados salvos da nuvem

Quando chamar

O que esta etapa faz

Limitações importantes

Implementação

Próximas etapas

Etapa 3: carregar os dados salvos na nuvem

Momentos sugeridos para o upload

Opções de upload

Comportamento da plataforma

Implementação

Quando posso gravar na pasta de salvamento novamente?

Práticas recomendadas

Considerações sobre a frequência

Etapa 4: tratar os retornos de chamada de interface do usuário (opcional)

Entendendo os conflitos de salvamento

Entendendo o modo offline do Game Saves

Entendendo as alterações de dispositivo ativo do Game Saves

Depuração