Skip to main content
Este artigo fornece instruções passo a passo para cenários comuns de desenvolvimento e migração ao usar o Game Saves. Ele aborda a configuração essencial no Microsoft Partner Center, as práticas recomendadas para gravar dados com segurança, o gerenciamento de salvamentos específico de cada plataforma e os procedimentos de teste recomendados.

​
Configurações do Partner Center

​
Habilitando os serviços XBOX e o Game Saves para o seu título

Para usar as APIs do Game Saves, conclua as etapas a seguir no Partner Center.
  • Habilite os serviços XBOX.
    1. Entre no Partner Center.
    2. Acesse o seu título e habilite os serviços XBOX nas configurações. Para obter mais informações sobre esta etapa, consulte Configurando um aplicativo ou jogo no Partner Center, para Parceiros Gerenciados.
  • Obtenha o identificador de configuração de serviço (SCID). Todas as operações de leitura e gravação devem estar associadas a um SCID. O SCID também é usado na inicialização do Game Saves.
    • No Partner Center, encontre o SCID na guia XBOX services > XBOX settings do seu título. Você também pode encontrar a ID do Aplicativo (MSAAppID) da sua conta Microsoft (MSA) nesta página. Exibição dos serviços XBOX no Partner Center.
Depois de obter o SCID e o MSAAppID, adicione essa ID do Aplicativo ao arquivo de configuração (.mgc) do título. Para obter mais informações sobre arquivos de configuração do jogo, consulte Criando o Microsoft Game Config .mgc.

​
Cenários de desenvolvimento

​
Onde integro o Game Saves no meu código?

A lógica do Game Saves depende da entrada do usuário. Adicione o código do Game Saves junto ao fluxo de entrada do usuário.

​
Como garanto que os dados dos meus jogos salvos não sejam corrompidos?

Para salvar dados com segurança e evitar corrupção, siga estas etapas. Esta orientação se aplica a todas as operações de salvamento.
  1. Grave em um arquivo temporário.
    • Serialize os dados salvos em um novo arquivo (por exemplo, save.tmp) em vez de substituir o salvamento ativo. Esta etapa protege o salvamento existente caso o processo seja interrompido no meio da gravação.
  2. Feche o identificador de gravação depois que a gravação estiver totalmente confirmada no disco.
  3. Substitua o arquivo de salvamento antigo de forma atômica pelo novo arquivo temporário usando a função ReplaceFile do Win32.

​
Como dou suporte a dispositivos offline?

Você é responsável por determinar como o título se comporta se houver perda de conexão antes e depois da inicialização do Game Saves. Para obter mais informações sobre o comportamento offline, consulte Noções básicas sobre o fluxo de sincronização do Game Saves.

​
Quais interações do usuário preciso conhecer?

O sistema operacional mostra prompts do sistema quando uma ação requer a entrada do usuário. Para obter informações sobre esses prompts, consulte Caixas de diálogo do Game Saves.

​
Há uma maneira de salvar localmente e somente no dispositivo?

Se você passar um identificador de usuário null para o processo de inicialização do Game Save, o sistema criará um provedor somente de máquina. Os dados são armazenados localmente e persistem no dispositivo, com um limite máximo de 256 MB. Os dados não são sincronizados com a nuvem. Para obter mais informações sobre o armazenamento do Game Saves, consulte Sistemas de armazenamento do Game Saves.

​
Gerenciando jogos salvos pelo dispositivo

​
Acessando jogos salvos locais no PC usando o Explorador de Arquivos

Se o seu título for executado no PC, você terá acesso direto aos arquivos. Dependendo da implementação da API do Game Saves, você pode acessar os jogos salvos locais nos seguintes locais. Ao manipular dados no PC, a lógica de sincronização continua se aplicando. Por exemplo, modificar dados quando o título não tem um bloqueio causa conflitos.

​
Acessando jogos salvos locais no console

Gerencie os dados salvos do console pela interface do usuário do XBOX. Acesse-os seguindo estas etapas.
  1. Selecione o botão Home no controle XBOX.
  2. Selecione Meus jogos e aplicativos > Ver tudo.
  3. Passe o cursor sobre o seu jogo e selecione o botão Exibir.
  4. Selecione Dados salvos.
Exibição de gerenciamento do Game Saves no armazenamento do console. Considere o seguinte ao manipular dados diretamente no console.
  • Excluir dados no console usando a interface do usuário do sistema não remove a cópia armazenada na nuvem. Quando você inicia o título novamente, ele sincroniza os dados a partir da nuvem.
  • Os dados do provedor de máquina aparecem como um usuário sem nome. Esses dados permanecem no dispositivo, não são sincronizados com a nuvem e ficam vinculados ao dispositivo.
Para obter mais informações sobre o provedor de máquina, consulte Sistemas de armazenamento do Game Saves. Para um controle mais detalhado dos jogos salvos, use as Ferramentas do Game Saves.

​
Cenários de teste

Ao criar casos de teste, separe a validação de dados da lógica de jogos salvos.

​
Testar se os jogos salvos são sincronizados corretamente de e para a nuvem

Use as etapas a seguir para testar a sincronização correta. Os fluxos de teste verificam o comportamento. XGameSaveFiles:
  1. Confirme se o SCID está correto.
  2. Confirme se você está usando o identificador de usuário correto.
  3. Confirme se o título chama XGameSaveFilesGetFolderWithUIAsync durante a sessão de jogo atual. Se o título for retomado de um estado de suspensão, chame a função.
    1. Use o Fiddler para confirmar que o bloqueio foi adquirido.
    2. Salve esse caminho e use-o mais tarde para confirmar que os dados estão sendo carregados.
  4. Grave alguns dados no caminho de arquivo fornecido por XGameSaveFilesGetFolderWithUIAsync.
  5. Encerre ou suspenda o título.
  6. Aguarde de 10 a 30 segundos para que o sistema operacional carregue automaticamente os dados para a nuvem e libere o bloqueio.
    1. Confirme que os dados foram carregados e que o bloqueio foi liberado usando o Fiddler.
  7. Exclua manualmente os dados na pasta fornecida por XGameSaveFilesGetFolderWithUIAsync.
    1. No console, acesse esses dados pelas configurações do jogador.
  8. Inicie o título novamente e tente fazer o usuário entrar.
  9. Uma caixa de diálogo de sincronização é exibida, mostrando uma sincronização de download ativa a partir da nuvem.
Para ajudar a testar a sincronização bem-sucedida, consulte os seguintes recursos:

​
Testar se os jogos salvos fazem roaming corretamente

Para obter um plano de teste que confirme se os dados fazem roaming, consulte Plano de Teste XR-052-06.

​
Cenários de migração

​
Compartilhando jogos salvos entre títulos

Para transferir ou acessar dados de um título em outro, conclua duas etapas.
  1. Modifique as políticas de acesso do título que você deseja acessar no Partner Center.
  2. Inicialize os provedores do Game Saves para ambos os títulos no código-fonte.

​
Modificar políticas de acesso

Um título controla quais títulos têm acesso aos seus dados de jogos salvos configurando políticas de acesso.
  1. Acesse o Partner Center.
  2. Selecione Apps and games > <your title> > Gameplay settings.
  3. Em Gameplay Settings, selecione Access Policies e expanda Connected Storage.
  4. Selecione Add app/service e adicione os títulos aos quais você deseja fornecer acesso.
  5. Quando terminar de adicionar os títulos, selecione Save e, em seguida, Publish. As alterações entram em vigor em até uma hora.
A captura de tela a seguir mostra um exemplo de como tornar o título GameSaveFilesCombo totalmente acessível ao título GameSaveSample. Exibição do Partner Center para modificar a política de acesso de um título.

​
Inicializar provedores do Game Save

Agora que você tem permissão para acessar o primeiro título, pode ler os dados de XGameSave do outro título.
  • Se você estiver usando XGameSave, chame XGameSaveInitializeProvider ou XGameSaveInitializeProviderAsync para cada título.
  • Se você estiver usando XGameSaveFiles, os provedores são inicializados implicitamente. Chame XGameSaveFilesGetFolderWithUiAsync para cada título.

​
Interoperabilidade entre XGameSave e XGameSaveFiles

Um título pode precisar usar XGameSave junto com XGameSaveFiles. Os motivos típicos podem ser os seguintes:
  • O editor tem um título existente no console que já usa XGameSave.
  • O editor não quer atualizar esse título existente para usar XGameSaveFiles.
  • O editor acha que adicionar XGameSaveFiles a um título de PC é mais fácil do que usar XGameSave, mas ainda deseja dar suporte a salvamentos cruzados entre PC, console e streaming de jogos XBOX.
Alternar entre XGameSave e XGameSaveFiles é bastante simples. Quando o título chama XGameSaveFilesGetFolderWithUiAsync, ele mapeia contêineres e blobs para diretórios e arquivos usando as seguintes regras:
  • Qualquer barra (/) no nome do contêiner cria a estrutura de diretórios em que o arquivo reside.
  • Os caracteres a seguir são inválidos para XGameSaveFiles. Se o sistema encontrar esses caracteres, ele os mapeará para um sublinhado (_):
    • Caracteres de \0 a \001f, inclusive.
  • Os caracteres a seguir não são válidos para XGameSaveFiles. Se o sistema encontrar esses caracteres, ele os mapeará para um ponto (.):
    • Aspas (”)
    • Sinal de menor que (<)
    • Sinal de maior que (>)
    • Barra vertical (|)
    • Asterisco (*)
    • Ponto de interrogação (?)
    • Barra invertida (\)
  • Uma barra (/) no nome do blob é mapeada para um ponto (.) no nome do arquivo.
  • Os arquivos são limitados a 16 MB. XGameSave dá suporte a um tamanho máximo de carregamento de 16 MB.
Quando o título volta de XGameSaveFiles para XGameSave, ele restaura os nomes originais de contêineres e blobs se os nomes de arquivo permanecerem inalterados ou não forem movidos.

​
Portando títulos anteriores para o Game Saves do PC com salvamentos na nuvem sem código

Alguns títulos que você porta para o PC Game Pass podem exigir uma solução de salvamento na nuvem sem código. Esse requisito pode ocorrer nos seguintes cenários:
  • O título é executado como um aplicativo x86. Ele usa o Microsoft Game Development Kit (GDK) apenas em sua forma empacotada.
  • O título é criado sem código personalizado, usando ferramentas como o Blueprint no Unreal Engine ou o Bolt no Unity.
Os títulos que usam salvamentos na nuvem sem código leem e gravam em seu diretório de salvamento designado por meio das APIs padrão de E/S de arquivos do Win32. O sistema sincroniza os dados automaticamente. Você não precisa escrever código especial para lidar com a sincronização e o carregamento. A sincronização ocorre antes de o título ser iniciado. Os salvamentos na nuvem sem código são carregados quando o título não está mais em execução no PC. O carregamento ocorre quando uma das seguintes condições é atendida:
  • O título é encerrado.
  • O usuário rastreado sai.
  • O estado de energia do PC muda.
  • Passaram-se 30 minutos desde a última vez que o título gravou na área de salvamento designada.
A solução de salvamento na nuvem sem código é construída sobre XGameSaveFiles e compartilha todas as suas limitações com relação a tamanhos de arquivo e limites de armazenamento por usuário. Os arquivos são limitados a 64 MB (ou 16 MB se houver necessidade de interoperabilidade com XGameSave ou Connected Storage). Por padrão, o armazenamento por usuário é limitado a 256 MB. Os títulos que precisam de limites maiores de armazenamento por usuário podem trabalhar com o Gerente de Parceiros de Desenvolvedor (DPM) para solicitar uma exceção.
Há convenções de nomenclatura e limites de caracteres específicos para diretórios e nomes de arquivo. Para obter mais informações, consulte Lógica de caminho do XGameSaveFiles.
Os salvamentos na nuvem sem código têm suporte apenas no PC. O título requer o Modelo de Usuário Simplificado. Ele garante que um usuário tenha entrado antes de o título ser iniciado. Se não for possível fazer um usuário entrar no título, ele não será iniciado. Se o usuário sair durante o jogo, o título será encerrado.
Os salvamentos na nuvem sem código exigem que o título seja iniciado como um build empacotado usando wdapp install. Iniciar o .exe diretamente não ativa o redirecionamento de salvamento na nuvem.Quando um build empacotado é executado, os salvamentos gravados por meio de NoCodePCRoot são redirecionados para o armazenamento gerenciado pelo XGameSaveFiles. Uma inicialização posterior direta do .exe lê a pasta física NoCodePCRoot, que pode estar vazia, fazendo com que os salvamentos pareçam estar ausentes. Para evitar esse problema, sempre teste os salvamentos na nuvem sem código com builds empacotados usando wdapp install.

​
Habilitando salvamentos na nuvem sem código

Para habilitar salvamentos na nuvem sem código, conclua as seguintes etapas:
  1. Modifique o arquivo MicrosoftGame.config.
  2. Habilite o modelo de usuário simplificado.
  3. Especifique a pasta raiz para os arquivos de salvamento.
  4. Forneça o SCID correspondente do título.
O exemplo de código a seguir mostra esse processo.
A pasta raiz que você especifica para NoCodePCRoot deve ser relativa a uma de um pequeno conjunto de opções.
Use SavedGames como o valor de RelativeTo. A pasta Jogos Salvos (%USERPROFILE%\Saved Games) corresponde à ID de pasta conhecida do Windows FOLDERID_SavedGames. O OneDrive não sincroniza essa pasta por padrão.Evite usar outros locais, como AppData (%APPDATA%). O OneDrive pode sincronizar esses locais e causar conflitos com a sincronização de salvamentos na nuvem.Para obter mais informações sobre FOLDERID_SavedGames, consulte SHGetKnownFolderPath.
Não é possível colocar arquivos diretamente no diretório raiz. Aninhe-os em pelo menos uma subpasta da pasta raiz. Por exemplo, usar um nome de arquivo diretamente, como <NoCodePCRoot RelativeTo="SavedGames">savegame1.sav</NoCodePCRoot>, não é válido porque savegame1.sav é ignorado. <NoCodePCRoot> destina-se a definir um caminho de diretório, não um arquivo específico.

​
Exemplos de código

​
Documentação de referência da API

​
Confira também

Sumário do Game Saves
Last modified on October 6, 2026