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 antigos, em que a integração da API da Nuvem Steam é mais complicada. Ela oferece uma forma fácil e rápida de começar, mas não tem o mesmo poder e a mesma flexibilidade disponíveis com a API da Nuvem Steam.

De modo geral, é aconselhável usar a API sempre que possível, já que ela possibilita uma maior integração e personalização, além de proporcionar a experiência de alta qualidade esperada por usuários Steam.

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.

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. Caso use raízes manuais, especifique [Todos os SOs] no seletor "SO raiz" acima.

Uma raiz manual consiste de 5 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. No macOS e Linux/SteamOS, os caminhos alternativos de Application.persistentDataPath são definidos no campo "Adicionar/Substituir caminho" com "Substituir caminho" ativado.

Com estas 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 uma licença complementar de desenvolvimento do 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 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.

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 Debugging the Steamworks API para mais informações.