XGameSaveFilesGetFolderWithUIAsync. Ele também descreve o comportamento recomendado de sincronização automática na nuvem do Win32, as etapas de depuração, as orientações sobre cota e diagnóstico, as práticas recomendadas de desempenho e as respostas a perguntas comuns.
O XGameSaveFiles fornece APIs que permitem que seu título leia e grave dados do usuário, mantenha-os entre sessões e os sincronize perfeitamente com a nuvem para que os jogadores possam usar seus dados em qualquer dispositivo. Use XGameSaveFiles para jogos salvos em títulos do Microsoft Game Development Kit (GDK). Use XGameSave somente quando XGameSaveFiles não estiver disponível para o seu cenário.
Para a referência da API do sistema para XGameSaveFiles, consulte XGameSaveFiles (conteúdo da API).
Os termos a seguir aparecem com frequência no XGameSaveFiles.
- 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 os jogos salvos 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.
Lógica de caminho do XGameSaveFiles
OXGameSaveFiles fornece um caminho de arquivo que você pode usar para interagir com o sistema Game Saves. O caminho de arquivo se integra à sincronização na nuvem, de modo que os dados salvos no caminho são sincronizados automaticamente com a nuvem. Use as APIs FileIO do Win32 no caminho fornecido. Para títulos do GDK, use XGameSaveFiles como a abordagem do Game Saves. O XGameSaveFiles mapeia os conceitos de contêineres para pastas e de blobs para arquivos.
Embora o XGameSaveFiles oculte a maior parte da complexidade do sistema de salvamento na nuvem, ele ainda impõe limites de diretório e de nome de arquivo porque o recurso depende do Armazenamento de Blobs do Microsoft Azure. Considere o código de exemplo a seguir do que um título poderia usar para seu salvamento.
XGameSaveFilesGetFolderWithUiAsyncretorna o [ROOT].- Tudo o que vem depois de [ROOT], até a barra final inclusive, é mapeado para um contêiner.
- Os nomes de contêiner são limitados a letras maiúsculas (A-Z), letras minúsculas (a-z), números (0-9), sublinhados (_), pontos (.), hifens (-) e barras (/).
- Os nomes de contêiner são limitados a 256 caracteres.
- Os nomes de contêiner não podem terminar com um ponto, conter dois pontos consecutivos nem começar com um ponto ou hífen.
- Tudo o que vem depois da barra final no nome do arquivo é mapeado para um blob.
- Os nomes de arquivo são limitados a 65 caracteres, mas, fora isso, podem conter quaisquer caracteres Unicode compatíveis com o New Technology File System (NTFS).
- O caminho completo resultante, incluindo o nome do arquivo (mas não o [ROOT]), deve ter menos que
MAX_PATH(260 caracteres).
Implementação do XGameSaveFiles
As etapas a seguir mostram a implementação geral doXGameSaveFiles.
- No início ou na retomada do título, chame
XGameSaveFilesGetFolderWithUIAsyncpara inicializar o provedor e obter o caminho do arquivo. - Leia e grave livremente no caminho do arquivo durante o jogo.
XGameSaveFilesGetFolderWithUIAsync gerencia automaticamente o tempo de vida do provedor do Game Saves e configura o espaço de armazenamento local do Game Saves.
Chame
XGameSaveFilesGetFolderWithUIAsync quando o título for iniciado e quando for retomado. Essa chamada inicializa o provedor do Game Saves e o mantém ativo enquanto a sessão de jogo é executada. Se você ignorar esta etapa, o sistema poderá se comportar de forma imprevisível.Exemplo de código
Para obter um exemplo de código que mostra como usar as APIs doXGameSaveFiles para acessar pastas no XBOX, consulte GameSaveFilesCombo.
Fluxo do Game Saves
Aqui está um fluxograma do fluxo simplificado do Game Saves.
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 o processo de entrada do usuário. Essa operação também é onde você chamaXGameSaveFilesGetFolderWithUIAsync. 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, você precisará habilitar o modo offline para o 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.Sincronizar 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? Se os dados no dispositivo forem mais recentes que os dados na nuvem, o título solicitará 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 caminho da pasta fornecido porXGameSaveFilesGetFolderWithUIAsync.
Fim da sessão de jogo
Quando a sessão de jogo termina, o sistema tenta carregar automaticamente os dados para a nuvem. Esse processo ocorre cerca de 10 a 30 segundos após o término do título. 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
O tamanho máximo de arquivo que você pode salvar usandoXGameSaveFiles é 64 MB. Esse comportamento é diferente do XGameSave, que limita cada arquivo a 16 MB.
Cotas
O máximo de dados que um usuário pode salvar por título é 256 MB. Use XGameSaveFilesGetRemainingQuota para obter a cota restante. Para obter uma extensão de armazenamento para que seu título tenha um limite de armazenamento por usuário maior, entre em contato com o Gerente de Programa de Desenvolvedor (DPM).Perguntas frequentes
Posso usar XGameSaveFiles com XGameSave?
Sim. No entanto, use essa abordagem somente para migrações. Para obter informações detalhadas, consulte Interoperabilidade entre XGameSave e XGameSaveFiles.Em qual caminho de arquivo o XGameSaveFiles salva?
Console: o título fornece um caminho temporário enquanto está ativo. Não é possível acessar os arquivos do console pelo Explorador de Arquivos. PC:%AppData%\Local\Packages\<PACKAGE_NAME>\SystemAppData\xgs\<HexXuid>_<SCID>\
O caminho no PC para XGameSaveFiles é diferente do de XGameSave. Ele usa wgs.
Posso especificar o caminho em que os dados devem ser salvos?
Sim, mas somente no PC. Recomendamos essa abordagem apenas se você estiver portando sua solução de outro título. Essa solução usa salvamentos na nuvem sem código.Documentação de referência da API
Confira também
Sumário do Game Saves Sim, mas somente no PC. Portar sua solução de outro título pode exigir essa abordagem. Essa solução usa salvamentos na nuvem sem código.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. Alternar entre inicializações empacotadas e inicializações diretas do .exe pode fazer com que os dados salvos pareçam estar ausentes. Para obter mais informações, consulte Portando títulos anteriores para o Game Saves do PC com salvamentos na nuvem sem código.