Documentação do Steamworks
Nuvem Steam
Resumo
A Nuvem Steam automaticamente armazena arquivos do seu jogo nos servidores Steam para que usuários possam iniciar a sessão e acessar os jogos salvos a partir de qualquer computador.
Nível de integração
É necessária a configuração dos caminhos de arquivos no site do Steamworks. O código do jogo também pode realizar algumas chamadas à API do Steamworks para enviar, baixar, enumerar e excluir arquivos.

Visão geral da Nuvem Steam

A Nuvem Steam oferece um sistema de armazenamento remoto de arquivos fácil e transparente para o seu jogo. Arquivos especificados na configuração de nuvem automática ou gravadas em disco (criadas, modificadas, excluídas etc.) por meio da API da Nuvem Steam serão automaticamente replicadas aos servidores Steam quando o jogo for fechado.

Se o usuário trocar de computador, os arquivos são baixados automaticamente para o novo computador antes do jogo ser iniciado. O jogo então pode acessar os arquivos lendo-os pela API da nuvem ou diretamente do disco, como sempre. Evite sincronizar arquivos específicos da máquina, como configurações de vídeo.

O cliente Steam cuida da tarefa de garantir que os arquivos estejam sincronizados em todos os computadores acessados pelo usuário.

Usuários podem desativar a sincronização da Nuvem Steam para todos os jogos ao acessar as configurações do Steam, seção Nuvem, e desmarcar a caixa "Ativar sincronização com a Nuvem Steam para aplicativos compatíveis".

Usuários também podem desativar a sincronização da Nuvem Steam individualmente nas propriedades de cada jogo.

Spacewar_Cloud_Properties.png

Observações e práticas recomendadas


É importante ter em mente de que o Steam sincronizará os arquivos do jogo armazenados na Nuvem Steam do usuário antes e depois de cada sessão. Todos os arquivos correspondentes que foram alterados durante a sessão serão enviados ao armazenamento na Nuvem Steam imediatamente após o fim da sessão. Se o jogo salva arquivos muito grandes ou vários arquivos pequenos na Nuvem Steam, isto pode impactar a largura de banda da internet do usuário e também fazer com que o usuário precise esperar mais antes de poder fechar o Steam ou iniciar o jogo novamente.

De forma geral, arquivos menores funcionam melhor. Se o estado salvo para um dado usuário pode ser dividido em categorias diferentes — coisas que mudam com frequência e coisas que não mudam com frequência —, então aconselhamos que você use arquivos separados para cada categoria. Desta forma, a parte inalterada não precisará ser reenviada depois de cada sessão.

Tamanhos-limite de arquivos


Os tamanhos-limite de arquivos na Nuvem Steam podem ser alterados com o tempo. Abaixo estão os limites e limiares atuais:

TamanhoRestrição
100MBTamanho máximo para uma chamada às funções ISteamRemoteStorage::FileWrite e ISteamRemoteStorage::FileWriteStreamWriteChunk.
256MBPode fazer com que o Steam escolha um servidor de armazenamento que não seja o ideal para a localização do usuário, impactando negativamente o envio e download dos arquivos.

Caminhos de arquivos salvos

Ao decidir onde gravar os seus arquivos salvos, certifique-se de que o caminho seja único para o usuário Steam atual. Caso necessário, você pode obter o ID Steam único do usuário através da função ISteamUser::GetSteamID. A partir daí, você pode acessar o ID da conta através da função GetAccountID(), permitindo que você tenha uma variável única ao criar o caminho de salvamento.

Sincronização entre plataformas


Caso o seu jogo esteja disponível em várias plataformas — ou tenha planos para tal —, leia esta seção quando configurar a Nuvem Steam para o seu jogo.

Caso planeje ler/escrever arquivos diretamente pela interface ISteamRemoteStorage, então você pode controlar a sincronização com outras plataformas por meio da função ISteamRemoteStorage::SetSyncPlatforms. O padrão para um novo arquivo é sincronizá-lo com todas as plataformas.

Caso planeje usar a nuvem automática, aqui estão alguns pontos importantes. Primeiro, o padrão para um novo arquivo é sincronizá-lo apenas com o que estiver definido na coluna SO do caminho raiz da nuvem automática associado. Isso significa que, ao definir raízes diferentes para cada sistema operacional, os arquivos serão divididos por plataformas, portanto não haverá sincronização de jogos salvos entre plataformas.

Para ativar a sincronização entre plataformas, defina um único caminho raiz (normalmente para Windows) e depois crie redirecionamentos de raízes para as outras plataformas. Os arquivos que correspondam a um caminho raiz que contenha redirecionamentos para outras plataformas serão sincronizados com as plataformas definidas na raiz original e nos redirecionamentos. Consulte a seção sobre a nuvem automática para mais detalhes.

Configuração inicial

Para configurar a Nuvem Steam, é necessário definir as opções Cota de bytes por usuário e Quantidade de arquivos permitidos por usuário na página de configurações da Nuvem Steam no painel de administração de aplicativo do Steamworks.

Esta cota é aplicada a todo jogo que usa a Nuvem Steam e é separada por jogo e usuário. É aconselhável definir valores razoáveis para o seu título.

AVISO: não se esqueça de clicar no botão "Salvar" no final da página e de publicar as configurações atualizadas. Uma vez publicadas, o ícone de nuvem será exibido no cliente Steam a todos os usuários que possuírem o jogo.

Se o jogo já tiver sido lançado ao público, assinalar a opção Ativar nuvem apenas para desenvolvedores fará com que o ícone de nuvem e o uso da Nuvem Steam só fiquem disponíveis para contas Steam com uma licença "Developer Comp" ("Complementar de desenvolvimento") do título. Assim, você poderá testar a integração com a Nuvem Steam em segurança, sem afetar a experiência dos usuários comuns. Se o jogo não tiver sido lançado, a opção não faz diferença, já que ninguém terá o jogo, logo ninguém terá como consultar ou acessar o armazenamento em nuvem do AppID.

É possível compartilhar o mesmo armazenamento em nuvem entre dois AppIDs preenchendo o campo AppID para nuvem compartilhada. Esse recurso costuma ser usado para compartilhar o progresso entre uma demonstração e o jogo completo. Um valor 0 desativa o recurso.

API da Nuvem Steam e nuvem automática

O Steam oferece duas formas diferentes de usar a Nuvem Steam. Leia sobre as diferenças entre cada uma e determine qual é a melhor para o seu aplicativo.

Primeiro, a API da Nuvem Steam.
A API oferece uma série de funções que permite a integração da Nuvem Steam ao jogo. A API isola arquivos de usuários Steam e permite um maior controle sobre a Nuvem Steam.

A API da Nuvem Steam é exposta pela interface da API ISteamRemoteStorage, e um exemplo de uso está disponível no projeto Aplicativo de exemplo da API do Steamworks (SpaceWar).

A segunda é a nuvem automática.
A nuvem automática foi projetada para jogos aos quais você escolhe não integrar a API da Nuvem Steam. Ela oferece uma forma fácil e rápida de começar, mas não tem a mesma flexibilidade disponível na API da Nuvem Steam.

Se você prefere uma integração mais profunda com a Nuvem Steam (por exemplo, permitir escolher quais arquivos salvos serão armazenados na nuvem), então você deve usar a API da Nuvem Steam. Caso contrário, você pode usar a nuvem automática.

Nuvem automática

A nuvem automática é uma alternativa à API da Nuvem Steam que permite que aplicativos façam uso da Nuvem Steam sem precisar escrever código ou modificar o jogo; basta especificar os grupos de arquivos que devem ser armazenados em nuvem. O Steam sincronizará esses grupos automaticamente ao iniciar e encerrar o jogo. Evite sincronizar configurações da máquina, como qualidade de vídeo.
Aviso: o arquivo steam_autocloud.vdf será criado em cada caminho especificado nas configurações da Nuvem Steam no Steamworks. O arquivo é usado pelo Steam e pode ser ignorado pelo jogo.

Configuração

Depois de realizar a Configuração inicial, a configuração da nuvem automática estará disponível na página de configurações da Nuvem Steam.

Caminhos raiz descrevem grupos de arquivos que serão armazenados na Nuvem Steam. Cada caminho raiz pode especificar tanto um arquivo específico quanto todos os arquivos de uma subpasta. Use um novo caminho para cada grupo de arquivos a serem sincronizados.

Um caminho raiz é composto de cinco partes:
  1. Raiz

    Uma lista pré-determinada de caminhos comuns para arquivos salvos de jogos.
    RaizSOs compatíveisCaminho correspondente
    App Install DirectoryTodos[Instalação do Steam]\SteamApps\common\[Pasta do jogo]\
    SteamCloudDocumentsTodosCaminho específico da plataforma; exemplo no Linux: ~/.SteamCloud/[nome de usuario]/[pasta do jogo]/
    WinMyDocumentsWindows%USERPROFILE%\My Documents\
    WinAppDataLocalWindows%USERPROFILE%\AppData\Local\
    WinAppDataLocalLowWindows%USERPROFILE%\AppData\LocalLow\
    WinAppDataRoamingWindows%USERPROFILE%\AppData\Roaming\
    WinSavedGamesWindows%USERPROFILE%\Saved Games\
    MacHomemacOS~/
    MacAppSupportmacOS~/Library/Application Support/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/
  2. Subdiretório

    Caminho do subdiretório que contém os arquivos a armazenar, em relação à raiz. Use "." se não houver subdiretório.

    Valores especiais no caminho da nuvem automática
    A nuvem automática permite o uso de identificadores únicos de usuário no caminho do Subdiretório, permitindo o armazenamento de arquivos salvos para cada usuário Steam do computador separadamente. Use a função ISteamUser::GetSteamID no jogo para recuperar o ID Steam ou ID de conta do usuário atual cujos arquivos salvar ou ler.
    • {64BitSteamID} — Use esta variável no caminho do Steam para inserir o ID Steam de 64 bits do usuário. Um ID Steam de 64 bits é similar a: 76561198027391269.
    • {Steam3AccountID} — Use esta variável no caminho do Steam para inserir ID de conta Steam 3 do usuário. Um ID de conta é similar a: 67125541.
    Exemplo: JogosSalvos/{64BitSteamID}
  3. Padrão

    Padrão de nome dos arquivos a armazenar. Use * como coringa. Se quiser todos os arquivos no diretório, basta usar *.

    Exemplo: *.sav
  4. SO

    Define os sistemas operacionais para os quais os arquivos serão sincronizados. Necessário apenas se os arquivos forem específicos do SO, o que esperamos que não seja o caso!
  5. Recursivo

    Inclui subdiretórios ao buscar por arquivos correspondentes. Útil para subdiretórios com nomes não determinísticos, como um nome de usuário ou ID que não seja do Steam. Se estiver usando um ID Steam, aconselhamos o uso dos valores especiais de caminho no campo Subdiretório.

Redirecionamento de raízes

Se o aplicativo for multiplataforma e exigir diretórios diferentes para cada SO, use o recurso de redirecionamento de raízes para redirecionar os caminhos raiz definidos acima.

Os caminhos raiz especificados acima podem ser sobrescritos para usar um caminho diferente em outro SO. Se usar o redirecionamento de raízes, você deverá especificar [Todos os SOs] no menu "SO" da raiz que será redirecionada.

Um redirecionamento de raiz consiste de cinco partes:
  1. Raiz original

    Igual a uma das raízes definidas acima.
  2. SO

    O sistema operacional no qual aplicar a raiz manual.
  3. Nova raiz

    O novo local mapeado pela raiz original no SO especificado.
  4. Adicionar/Substituir caminho

    (Opcional) Permite adicionar um caminho de subdiretório, inserido entre a nova raiz e o subdiretório original.
  5. Substituir caminho

    Se verdadeiro, faz com que o caminho especificado no campo "Adicionar/Substituir caminho" substitua o subdiretório original por completo.

Exemplo: configuração de nuvem automática para aplicativos Unity

Segue abaixo um exemplo de configuração de nuvem automática para uso com Unity e a propriedade Application.persistentDataPath, cujo valor depende do SO. A versão para Windows está configurada com o caminho raiz, em que o nome da empresa no Unity é DefaultCompany e o projeto é chamado de AutocloudSample. Nos sistemas macOS e Linux/SteamOS, os caminhos alternativos de Application.persistentDataPath são definidos no campo "Adicionar/Substituir caminho" com "Substituir caminho" ativado.

Com essas configurações, os arquivos da nuvem automática serão sincronizados entre as três pastas, como exibido nas amostras de pré-visualização.

Cloud_Unity_Auto-Cloud_Example.png

Teste de pré-lançamento

Se você estiver adicionando a nuvem automática a um jogo já lançado e ativou o modo apenas para desenvolvedores durante a Configuração inicial, então são necessários alguns passos a mais para testar a funcionalidade.
  1. Inicie a sessão no Steam com uma conta que possua o aplicativo que testará.
  2. Digite steam://open/console em um navegador para abrir o console do Steam.
  3. Digite testappcloudpaths <AppId> no console com o AppID que testará. Ex.: testappcloudpaths 480.
  4. Digite set_spew_level 4 4 no console.
  5. Inicie o aplicativo pelo Steam.
  6. Fique de olho na atividade do console. Se já houver arquivos nos caminhos da nuvem automática, então os verá sendo enviados para a Nuvem. Caso contrário, salve alguns arquivos pelo aplicativo e encerre-o para disparar uma sincronização.
  7. Acesse outro computador e repita os passos acima para testar o download de arquivos da nuvem automática.
  8. Teste em todos os sistemas operacionais.
  9. Digite testappcloudpaths 0 e depois set_spew_level 0 0 para finalizar o teste. Reinicie o cliente Steam para remover a aba Console.

Não se esqueça de desativar o modo para desenvolvedores e publicar as alterações depois de terminar de testar.

Sincronização dinâmica com a nuvem


A Nuvem Steam é compatível com sincronização dinâmica — em que alterações enviadas para a nuvem por outro dispositivo podem ser baixadas na máquina local durante uma sessão do aplicativo. O exemplo atual é uma sessão de jogo suspensa no Steam Deck. Para jogos compatíveis com a sincronização dinâmica com a nuvem, o Steam sincronizará arquivos com a Nuvem Steam quando o sistema for suspenso. Depois, o usuário roda o mesmo jogo em outro dispositivo, que receberá as atualizações da sessão do Steam Deck antes de ser inicializado. Ao encerrar o jogo, as alterações serão enviadas à Nuvem Steam. Finalmente, quando o Steam Deck sair do repouso, o Steam sincronizará as alterações com ele e notificará o aplicativo que os arquivos locais foram alterados. Então, o aplicativo pode iterar pelas alterações e tomar a ação mais apropriada. Por exemplo, o jogo pode simplesmente carregar o progresso atualizado, permitindo que o usuário continue de onde pararam no outro dispositivo.

Consulte o nosso anúncio para obter ainda mais informações sobre a razão desse recurso existir e como usá-lo.

Obs.: esse recurso é compatível tanto com aplicativos que usam a nuvem automática ou que usam a API ISteamRemoteStorage para gerenciar os arquivos.

Para mais detalhes, consulte a documentação da interface ISteamRemoteStorage, em especial do retorno de chamada ISteamRemoteStorage::RemoteStorageLocalFileChange_t e das funções ISteamRemoteStorage::GetLocalFileChangeCount e ISteamRemoteStorage::GetLocalFileChange.

Consulte também as funções ISteamRemoteStorage::BeginFileWriteBatch e ISteamRemoteStorage::EndFileWriteBatch — elas servem para indicar ao Steam quando é seguro enviar arquivos atualizados à Nuvem Steam no momento que o usuário colocar o sistema em suspensão.

Teste de pré-lançamento


Você pode ativar a sincronização dinâmica para o seu aplicativo localmente para testar as suas versões — aconselhamos que isso seja feito em jogos já lançados, já que a ativação do recurso para todos os usuários pode resultar em perda de dados ao executar versões que não usam os métodos e retornos de chamada específicos da API.

Para testar localmente usando um computador:

  1. Inicie a sessão no Steam com uma conta que posui o aplicativo que você está testando.
  2. Digite steam://open/console em um navegador para abrir o console do Steam. (Caso esteja em um sistema Linux, como o SteamOS, também é possível iniciar o Steam digitando steam -console no Terminal e navegando diretamente para a seção Console).
  3. Digite @cloud_testdynamicsyncapp <AppID> no console com o AppID que testará. Ex.: @cloud_testdynamicsyncapp 480.
  4. Inicie o aplicativo pelo Steam.
  5. Avance no jogo o quanto for desejado.
  6. No console do cliente Steam, digite prepare_for_suspend. O Steam suspenderá o processo do jogo e enviará quaisquer arquivos alterados para a Nuvem Steam.
  7. Opcional: jogue o jogo em outro dispositivo, avançando mais ainda no jogo, depois feche o jogo lá e deixe que o cliente Steam do outro dispositivo envie o progresso para a Nuvem Steam.
  8. De volta ao dispositivo original, digite resume_suspended_games no console do cliente Steam. Isso sincronizará quaisquer arquivos necessários da Nuvem Steam, disparará as chamadas relevantes à API no seu jogo e tirará o processo do jogo da suspensão.

Para testar localmente usando um Steam Deck:

  1. Conecte o seu Steam Deck usando as ferramentas de desenvolvimento.
  2. Para saber como usar o "CEF Console", clique aqui.
  3. No console de JavaScript, digite SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppID>”) para permitir testes. Para desativar, digite SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”).

Depuração

Primeiro, confirme que publicou as alterações no site de parceiros Steamworks e aguardou até 10 minutos ou reiniciou o cliente Steam para receber as alterações publicadas.

Caso enfrente problemas com a Nuvem Steam, verifique o relatório localizado em %Pasta de instalação do Steam%\\logs\\cloud_log.txt.

Consulte Depuração da API do Steamworks para mais informações.