> ## 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. # Início rápido do Game Saves > O início rápido do PlayFab Game Saves orienta você pela configuração inicial, pelas chamadas do SDK e pela leitura e gravação de dados salvos na nuvem, para que você possa integrar os salvamentos rapidamente. # 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](/pt-BR/services/playfab/player-progression/game-saves/onboarding) ao Game Saves * Revisou os requisitos de implementação na seção de [visão geral](/pt-BR/services/playfab/player-progression/game-saves/overview) * Concluiu os requisitos listados abaixo * (Opcional) Clonou ou revisou o **exemplo do Game Saves** completo para Windows no GitHub: [PlayFabGameSaveSample-Windows](https://github.com/PlayFab/PlayFab-Samples/tree/master/Samples/All/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](https://developer.playfab.com) * 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](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)](https://learn.microsoft.com/gaming/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) 1. **Inicializar os serviços**: configure os módulos PlayFab Core e Game Saves 2. **Autenticar o usuário**: conecte o jogador usando a autenticação do XBOX 3. **Baixar os salvamentos existentes**: sincronize os dados salvos de outros dispositivos com o dispositivo local 4. **Obter o local de salvamento**: obtenha a pasta raiz de salvamento local em que seu jogo deve gravar os arquivos salvos ### Durante o jogo 5. **Gravar os arquivos salvos**: seu jogo grava os dados salvos na pasta raiz de salvamento local, como de costume 6. **Carregar as alterações**: carregue periodicamente na nuvem os arquivos salvos modificados 7. **Continuar jogando**: repita as etapas 5 e 6 conforme necessário durante a sessão de jogo ### Fim da sessão 8. **Upload final**: carregue as alterações finais antes que o jogador saia 9. **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 ```cpp theme={null} // 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://.playfabapi.com", // Replace with your actual PlayFab Title ID "", // Replace 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 `` 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: ```cpp theme={null} 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 1. **Baixa os salvamentos existentes** de outros dispositivos (somente arquivos novos ou alterados) 2. **Preserva os carimbos de data/hora dos arquivos**, quando possível, para o controle de versão adequado 3. **Trata os conflitos** automaticamente por meio da interface do usuário integrada 4. **Define o dispositivo como ativo** para este usuário 5. **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 ```cpp theme={null} // 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 ```cpp theme={null} // 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 1. **Trate as falhas adequadamente**: problemas de rede não devem fazer seu jogo falhar 2. **Use as opções apropriadas**: * Use `KeepDeviceActive` durante o jogo para uploads adicionais * Use `ReleaseDeviceAsActive` quando o jogador estiver saindo ou retornando ao menu 3. **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](/pt-BR/services/playfab/player-progression/game-saves/limits) 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. ```cpp theme={null} // 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](/pt-BR/services/playfab/player-progression/game-saves/ui-callbacks). ## 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](/pt-BR/services/playfab/player-progression/game-saves/conflicts). ## 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](/pt-BR/services/playfab/player-progression/game-saves/offline). ## 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](/pt-BR/services/playfab/player-progression/game-saves/activedevicechanges). ## Depuração A maneira mais fácil de ver os resultados e depurar quaisquer chamadas do SDK é habilitar o [Rastreamento de depuração](/pt-BR/services/playfab/sdks/c/tracing). 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. ## Related topics - [Retornos de chamada de interface do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/ui-callbacks.md) - [Implementação do Game Saves com o GDK de outubro de 2025](/pt-BR/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md) - [Guia de implementação do PlayFab Game Saves no Steam Deck](/pt-BR/services/playfab/player-progression/game-saves/steam-deck-implementation.md) - [Estratégias de vinculação de contas para o PlayFab Game Saves](/pt-BR/services/playfab/player-progression/game-saves/linking.md) - [Início rápido](/pt-BR/services/playfab/economy-monetization/economy-v2/quickstart.md)