Pular para o conteúdo principal
O Steam habilita o armazenamento em nuvem de uma de duas formas. Você pode fazer todas as leituras e gravações usando os métodos da API ISteamRemoteStorage, que gravam arquivos na pasta de armazenamento do jogo no disco rígido local e os sincronizam com a nuvem. Como alternativa, você pode fazer todas as leituras e gravações diretamente no sistema de arquivos do computador e, em seguida, usar o Steam Auto-Cloud para sincronizar a pasta local que contém os dados do jogo com a nuvem. O Microsoft Game Development Kit (GDK) oferece suporte às duas abordagens:
Os salvamentos em nuvem sem código não têm suporte em consoles XBOX nem no XBOX Cloud Gaming. Se o seu título se destina a console ou nuvem, além do PC com Windows, use o wrapper XGameSave ou a API XGameSave completa.
O wrapper baseado em código é o caminho recomendado para títulos lançados em console ou na nuvem. Ele corresponde de perto à gravação de arquivos localmente ou ao uso da API Steam Remote Storage. Este tópico se concentra no wrapper simplificado.
A API XGameSave completa, sem wrapper, oferece mais funcionalidade e flexibilidade do que o wrapper simples. Se você precisar de alguma dessas funcionalidades, não use o wrapper. Os jogos não devem alternar entre os dois nem misturar chamadas de API de ambos. Para obter mais informações sobre a API XGameSave, consulte Salvamentos de jogos.
Os exemplos de código a seguir mostram como as operações básicas de arquivo funcionam no SDK do Steamworks e no Microsoft Game Development Kit (GDK), além de algumas diferenças sutis entre as duas APIs.

Comparações de operações de arquivo

Os exemplos de código a seguir mostram como realizar operações básicas de arquivo na API Steamworks Remote Storage e no equivalente do GDK. Eles presumem que a variável provider contém um ponteiro para um objeto Microsoft::Xbox::Wrappers::GameSave::Provider inicializado. Se você não estiver usando a API Steam Remote Storage, mas tiver optado por usar o Steam Auto-Cloud, substitua as chamadas da API Remote Storage pelas equivalentes da API do sistema de arquivos.

Ler um arquivo

Steamworks

ou

GDK

Documentação de referência

Microsoft.Xbox.Wrappers.XGameSave.Provider.Load

Gravar um arquivo

Steamworks

ou

GDK

Documentação de referência

Microsoft.Xbox.Wrappers.XGameSave.Provider.Save

Excluir um arquivo

No Steam, você pode excluir um arquivo na nuvem, mas manter a cópia local (FileForget), ou excluir um arquivo dos dois locais (FileDelete). A API do wrapper XGameSave não tem um equivalente a FileForget. A função Delete dela funciona como FileDelete no Steamworks.

Steamworks

ou

GDK

ou
ou

Documentação de referência

Obter todos os arquivos

Steamworks

GDK

Documentação de referência

Verificar o espaço disponível

Nos exemplos a seguir, totalBytes é a quantidade de espaço que seu jogo recebe no provedor de armazenamento em nuvem. availableBytes é a quantidade de espaço livre restante (ou seja, availableBytes = totalBytes – bytesUsed).

Steamworks

GDK

Documentação de referência

Microsoft.Xbox.Wrappers.XGameSave.Provider.GetQuota

Diferenças de terminologia

No Steam, os dados do armazenamento remoto são gerenciados como arquivos, que funcionam como arquivos em um disco rígido local. Para ler ou gravar, você especifica o arquivo e, em seguida, obtém ou define os bytes que ele contém. No Microsoft Game Development Kit (GDK), o equivalente aos arquivos do Steam são os blobs. Os blobs são agrupados em uma estrutura chamada contêiner. Um contêiner é um grupo nomeado de blobs. Por exemplo, você pode usar contêineres para oferecer suporte a vários slots de salvamento por usuário, com os mesmos nomes de arquivo em cada slot. Se você não precisar da camada organizacional extra que os contêineres fornecem, coloque todos os seus blobs (arquivos) no mesmo contêiner.
Os nomes de contêiner não podem incluir espaços. Tentar acessar ou criar um nome de contêiner que inclua um espaço faz com que o método do provedor retorne um HRESULT 0x80830001: o volume especificado não oferece suporte a camadas de armazenamento.

Limites de armazenamento

O Microsoft Game Development Kit (GDK) tem um tamanho máximo de gravação de blob ou arquivo e um limite geral de armazenamento menores que os do Steam. No Steam, cada operação de gravação de arquivo é limitada a 100 mebibytes (MiB), e cada arquivo não pode ter mais de 200 MiB. Por outro lado, a API XGameSave e seu wrapper limitam cada blob a 16 MB e permitem no máximo 256 MB por usuário por jogo. Se você precisar armazenar mais de 16 MB de dados em um blob, divida os dados em vários blobs. Em seguida, implemente uma função de leitura e gravação sequencial para processar os dados um blob por vez.

As funções do wrapper são bloqueantes

A interface ISteamRemoteStorage oferece duas versões das funções de leitura e gravação: FileRead e FileWrite, além de FileReadAsync e FileWriteAsync. As versões Async fazem um retorno de chamada quando o arquivo é lido ou gravado. As funções do wrapper simplificado XGameSave não oferecem versões assíncronas de seus equivalentes a FileRead e FileWrite. Provider::Load e Provider::Save são bloqueantes, portanto, tenha esse comportamento em mente ao usá-las no seu jogo. Por esse motivo, Provider::Initialize gera uma exceção se você a chamar a partir do thread da interface do usuário.

Inicialização

Inclua o arquivo de cabeçalho do wrapper na solução do seu jogo antes de usar qualquer método do wrapper. Você pode encontrá-lo em %GRDKLatest%\GameKit\Include\xgamesavewrappers.hpp. Antes de usar os métodos do wrapper XGameSave, crie uma instância da classe Provider e chame o método Provider::Initialize. Mantenha um ponteiro para a instância de Provider durante todo o tempo de vida do seu jogo. Chame Provider::Initialize a partir de um thread diferente do thread da interface do usuário. O método gera uma exceção se você o chamar a partir do thread da interface do usuário. Para inicializar o provedor do wrapper, você precisa de um XUserHandle para o usuário atual e do identificador de configuração de serviço (SCID) do seu jogo.

Documentação de referência

Microsoft.Xbox.Wrappers.XGameSave.Provider.Initialize
Última modificação em 6 de outubro de 2026