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. Avoid machine-specific configurations such as video settings.

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".

Users can also disable the Cloud synchronization on a per-game basis in each game's properties.

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:

Tamanho	Restrição
100MB	Tamanho máximo para uma chamada às funções ISteamRemoteStorage::FileWrite e ISteamRemoteStorage::FileWriteStreamWriteChunk.
256MB	Pode 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. Files matching a given Root path which also has platform Root Overrides will sync to all platforms in both the original Root and all Overrides. 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; It only requires that you specify the file groups which you want persisting to the Cloud. O Steam sincronizará esses grupos automaticamente ao iniciar e encerrar o jogo. Avoid machine-specific configurations such as video quality.

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.

Root Paths describe groups of files that will be persisted to the Steam Cloud. 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.
   

   Raiz	SOs compatíveis	Caminho correspondente
   App Install Directory	Todos	[Instalação do Steam]\SteamApps\common\[Pasta do jogo]\
   SteamCloudDocuments	Todos	Caminho específico da plataforma; exemplo no Linux: ~/.SteamCloud/[nome de usuario]/[pasta do jogo]/
   WinMyDocuments	Windows	%USERPROFILE%\My Documents\
   WinAppDataLocal	Windows	%USERPROFILE%\AppData\Local\
   WinAppDataLocalLow	Windows	%USERPROFILE%\AppData\LocalLow\
   WinAppDataRoaming	Windows	%USERPROFILE%\AppData\Roaming\
   WinSavedGames	Windows	%USERPROFILE%\Saved Games\
   MacHome	macOS	~/
   MacAppSupport	macOS	~/Library/Application Support/
   MacDocuments	macOS	~/Documents/
   LinuxHome	Linux	~/
   LinuxXdgDataHome	Linux	$XDG\_DATA\_HOME/

   
   A note regarding the Windows %USERPROFILE% paths: The corresponding paths listed above are the default locations. It is now possible for the user to configure their Windows installation so that these folders are in different locations (not necessarily under %USERPROFILE%). Steam uses the necessary Windows APIs to find the current location of these folders, whether they are default or customized.
   
   

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 this variable in the Steam path to insert the user's 64bit Steam ID. Um ID Steam de 64 bits é similar a: 76561198027391269.
     
   • {Steam3AccountID} - Use this variable in the Steam path to insert the user's Steam3 Account ID. 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

If your application is cross-platform and requires different directories for each OS, you can use the Root Overrides functionality to specify an override for the Root Paths that you set above.

Os caminhos raiz especificados acima podem ser sobrescritos para usar um caminho diferente em outro SO. If you use Root Overrides, you must specify [All OSes] in the Root OS drop-down above.

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.

Teste de pré-lançamento

If you are adding Steam Auto-Cloud to a game which has already been released and you have enabled developer-only mode during the Configuração inicial then you must complete some additional steps to test the functionality.

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.