XGameSave permite gerenciar blobs e contêineres para administrar os dados do Game Saves. Recomendamos o XGameSaveFiles para o Game Saves em títulos do Microsoft Game Development Kit (GDK). Use XGameSave se XGameSaveFiles não for uma opção.
Para a referência da API do sistema para XGameSave, consulte XGameSave (conteúdo da API).
Os termos a seguir aparecem com frequência no XGameSave.
- Bloqueio: um mecanismo que concede acesso exclusivo ao Game Saves de um título para um usuário específico no dispositivo que ele está usando ativamente. Ele garante que nenhum outro dispositivo possa modificar o Game Saves do usuário enquanto o bloqueio estiver mantido.
- Por exemplo, se um usuário jogar o Título T no dispositivo A, esse dispositivo terá um bloqueio do Título T para o usuário.
- Provedor: o processo intermediário que se comunica com o sistema Game Save e é responsável por gerenciar os dados do título. O provedor também gerencia o bloqueio de um usuário em um dispositivo.
- Contêineres: análogos a pastas.
- Blobs: análogos a arquivos individuais.
Gerenciamento de provedores
Para adquirir um espaço de armazenamento, o jogo deve inicializar um provedor. Após a conexão, o título tenta adquirir um bloqueio para o armazenamento em nuvem do título chamandoXGameSaveInitializeProvider ou XGameSaveInitializeProviderAsync.
Se o título não conseguir sincronizar a partir da nuvem devido à perda de conexão, determine se os usuários podem continuar jogando no modo Offline.
O título deve fechar o provedor com XGameSaveCloseProvider quando for suspenso ou encerrado. O provedor não pode ser reutilizado entre os limites de suspensão e retomada.
Esta questão se aplica somente ao
XGameSave. O XGameSaveFiles fecha o provedor automaticamente.Gerenciamento de contêineres
Para evitar perda de dados ao acessar contêineres, como ao criar contêineres antes que a sincronização seja concluída, chameXGameSaveEnumerateContainerInfo ou XGameSaveEnumerateContainerInfoByName para ver os contêineres que um usuário tem.
Use XGameSaveCreateContainer para obter um identificador de contêiner para um contêiner novo ou existente. Se o contêiner já existir, seu identificador será fornecido. Se o contêiner não existir, um novo contêiner será criado e seu identificador será fornecido.
Use XGameSaveDeleteContainer para excluir um contêiner. Todos os blobs dentro do contêiner também são excluídos.
Para evitar vazamentos de identificadores, feche todos os identificadores de contêiner com XGameSaveCloseContainer quando o contêiner não estiver mais em uso ou quando o título for suspenso ou encerrado.
Gerenciamento de blobs
A manipulação de dados dentro de um contêiner é feita chamandoXGameSaveCreateUpdate.
Os detalhes a seguir descrevem como XGameSaveUpdate gerencia alterações de blobs dentro de um contêiner e como cada atualização é criada, modificada e enviada.
- Uma atualização se aplica a um contêiner.
- Uma atualização pode gravar no máximo GS_MAX_BLOB_SIZE (16 MB).
- Vários blobs podem ser modificados em uma única atualização.
- Um único blob só pode ter uma modificação por atualização.
-
O envio de uma atualização consome o identificador
XGameSaveUpdate. Feche o identificador, independentemente de o envio ter sido bem-sucedido ou ter falhado. - As atualizações são atômicas. Se qualquer parte falhar, toda a atualização falhará.
-
XGameSaveCreateUpdatecria um contexto de atualização para armazenar todas as suas modificações de blobs. -
XGameSaveSubmitBlobWritegrava dados em um blob novo ou existente e requer um contexto de atualização. -
XGameSaveSubmitBlobDeleteexclui o blob. -
XGameSaveSubmitUpdateenvia o contexto de atualização. -
XGameSaveCloseUpdatefecha o identificador de atualização. O título a chama após cada envio para evitar vazamentos. -
Use
XGameSaveEnumerateBlobInfoouXGameSaveEnumerateBlobInfoByNamepara acessar todos os blobs de um contêiner.
Os dados gravados em blobs são representados como
Base64 quando são exportados em XML.Implementação
As etapas a seguir mostram o fluxo geral de uma implementação doXGameSave.
- No início ou na retomada do título, inicialize o provedor.
- Enumere e crie identificadores de contêiner.
- Envie periodicamente
XGameSaveUpdatescom modificações de blobs e limpe o identificador de atualização no envio. - Feche os identificadores de contêiner e de provedor quando o título for suspenso ou encerrado.
Chame
XGameSaveInitializeProvider quando o título for iniciado e quando for retomado. Essa chamada garante que o provedor seja inicializado corretamente e permaneça ativo enquanto o título é executado. Se ela não for chamada, o título poderá se comportar de forma imprevisível.Exemplo de código
Para obter um exemplo de código que mostra como usar as APIs doXGameSave, consulte GameSaveCombo.
Fluxo do Game Saves
Aqui está um fluxograma do fluxo simplificado do Game Saves. Ele é explicado a seguir.
Início do título
O início do título ocorre quando o usuário inicia ou retoma o título.Entrada do usuário
O título inicia a entrada do usuário. Essa chamada também é onde você invocaXGameSaveInitializeProvider.
Para obter mais informações sobre a configuração do usuário, consulte Modelos de usuário.
Verificação de conexão
O título determina se pode se conectar à rede XBOX. Se não puder, cabe a você habilitar o modo offline para o seu título.Verificação de propriedade dos dados
O dispositivo verifica se o usuário está jogando atualmente em outros dispositivos. Apenas um dispositivo por vez pode acessar os dados do usuário para um título específico.Sincronizando dados com a nuvem
O dispositivo sincroniza os dados do armazenamento local do Game Saves com a nuvem. Se houver um conflito, o sistema exibirá ao usuário uma caixa de diálogo de resolução de conflitos. Caixa de diálogo: Qual você deseja usar? Quando os dados no dispositivo são mais recentes que os dados na nuvem, o título solicita que o usuário escolha entre usar os dados locais ou os dados da nuvem.Loop de jogo
O título pode ler e gravar livremente no armazenamento local do Game Saves.Fim da sessão de jogo
Quando a sessão de jogo termina, o sistema tenta carregar automaticamente os dados para a nuvem. Certifique-se de que o título chameXGameSaveUninitializeProvider durante seu fluxo de saída para evitar deixar um provedor inicializado. Um desligamento estruturado garante que os dados sejam salvos corretamente antes da saída.
Para obter informações detalhadas sobre sincronização, consulte Noções básicas sobre o fluxo de sincronização do Game Saves.
Limites e cotas
Limites
OXGameSaveUpdate limita cada atualização a 16 MB. Como resultado, o XGameSave só pode gerenciar atualizações de arquivos individuais de até 16 MB. Esse limite é diferente do XGameSaveFiles, que dá suporte a arquivos de até 64 MB.
Cotas
O máximo de dados que um usuário pode salvar por título é 256 MB. Use XGameSaveGetRemainingQuota para obter a cota restante. Para obter uma extensão de armazenamento para o seu título, entre em contato com o Gerente de Parceiros de Desenvolvedor (DPM).Práticas recomendadas
- Não salve dados e, em seguida, consulte e solicite imediatamente os mesmos dados de volta.
- As dependências de dados entre contêineres não são confiáveis. Cada chamada de
XGameSaveSubmitUpdateaplica todas as alterações de forma atômica ou não aplica nenhuma. - Quanto mais blobs você usar por chamada de atualização, mais tempo será necessário para concluir as operações atômicas do sistema de arquivos necessárias para armazenar os dados.
Perguntas frequentes
Estou atualizando minha implementação do Game Saves. Qual é a abordagem correta?
Use o XGameSaveFiles.Posso usar XGameSave com XGameSaveFiles?
Sim. No entanto, faça isso somente para migrações. Para obter informações detalhadas, consulte Interoperabilidade entre XGameSave e XGameSaveFiles.Em qual caminho de arquivo o XGameSave salva?
Console: um caminho temporário é fornecido enquanto o título está ativo. Os arquivos do console não podem ser acessados pelo Explorador de Arquivos. PC:%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\wgs\<HexXuid>_<SCID>\
Lembre-se de que o caminho no PC para XGameSave é diferente do de XGameSaveFiles. Ele usa xgs.