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.

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 ID de aplicativo para nuvem compartilhada. Este 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 mais 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 que arquivos salvos sejam 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á estes 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.

Raiz manual

Se o aplicativo for multiplataforma e exigir diretórios diferentes para cada SO, use o recurso de raiz manual para especificar um caminho manual aos caminhos-raiz definidos acima.

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

Uma raiz manual 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. Em 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 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 testcloudapppaths 0 e depois set_spew_level 0 0 ao terminar de testar. 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.

Dynamic Cloud Sync


Steam Cloud now supports dynamic sync - where changes appearing in the Cloud can be downloaded to the local machine during an application session. The current example is a suspended game session on the Steam Deck. For apps marked as supporting dynamic Cloud sync, Steam will synchronize files up to the Steam Cloud at the suspend time. Then, the user may run the game on another device, which will receive the updates from the Steam Deck session at launch. At exit, those changes will be uploaded to the Steam Cloud. Finally, when the Steam Deck device is awakened, Steam will synchronize the changes down to that device, and post a notification to the application that local files have changed. The application can then iterate those changes and take appropriate action. For instance, the game may be able to simply load the updated progress from disk and allow the user to pick up right where they left off on the other device.

Currently, the ability to flag an application as supporting dynamic Cloud sync is only available to Valve admins. Get in touch with your Valve contacts for more detail.

Note that this feature supports applications whether they use the ISteamRemoteStorage API to manage files, or AutoCloud.

For more details, see the ISteamRemoteStorage documentation, specifically ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount, and ISteamRemoteStorage::GetLocalFileChange.

See also ISteamRemoteStorage::BeginFileWriteBatch and ISteamRemoteStorage::EndFileWriteBatch - these wrappers should be used to provide hints to Steam which will help it safely sync up to the Steam Cloud at the time when the user initiates a system suspend.

Debugging

First, always ensure that you have published your changes on the Steam partner website and have waited up to 10 minutes or restarted your Steam client to receive the published changes.

If you run into issues with Steam Cloud you should check the log file located at %Steam Install%\logs\cloud_log.txt.

See Depuração da API do Steamworks for additional information.