Documentação do Steamworks
Steam Cloud
Resumo
A Steam Cloud armazena automaticamente ficheiros do seu jogo nos servidores do Steam para que os utilizadores possam iniciar sessão e aceder ao respetivo progresso a partir de qualquer computador.
Nível de integração
É necessária a configuração dos caminhos de ficheiros no site do Steamworks. Em alternativa, o código do jogo também pode realizar chamadas à API do Steamworks para enumerar, ler, eliminar ou gravar ficheiros na Steam Cloud.

Vista geral - Steam Cloud

A Steam Cloud oferece um sistema de armazenamento remoto fácil e transparente para o seu jogo. Os ficheiros especificados na configuração de Auto-Cloud ou gravados no disco (criados, modificados, eliminados, etc.) através da API da Steam Cloud serão replicados automaticamente para os servidores do Steam ao sair do jogo.

Se o utilizador mudar de computador, os ficheiros são transferidos automaticamente para o computador novo antes do arranque do jogo. O jogo poderá depois aceder aos ficheiros lendo-os pela API da Steam Cloud ou diretamente do disco, como habitual. Evite incluir configurações específicas de sistema, como definições de vídeo.

A aplicação Steam trata de garantir que os ficheiros fiquem sincronizados em todos os computadores acedidos pelo utilizador.

Os utilizadores podem desativar a sincronização da Steam Cloud para todos os jogos na secção "Cloud" das definições do Steam ao desmarcar a opção "Ativar a sincronização com a Steam Cloud nas aplicações que a suportam".

Os utilizadores também podem desativar a sincronização da Steam Cloud caso a caso nas propriedades de cada jogo.

Spacewar_Cloud_Properties.png

Observações e boas práticas


É importante ter em mente que o Steam vai sincronizar os ficheiros do jogo guardados na Steam Cloud do utilizador antes e depois de cada sessão. Todos os ficheiros correspondentes que forem alterados durante a sessão serão enviados para armazenamento na Steam Cloud imediatamente depois do fim da sessão. Se o seu jogo gera ficheiros muito grandes ou muitos ficheiros pequenos na Steam Cloud, isto pode ter um impacto substancial na largura de banda da internet do utilizador e também fazer com que este tenha de esperar mais antes de poder encerrar ou Steam ou voltar a iniciar o jogo.

Regra geral, ficheiros mais pequenos funcionam melhor. Se os dados guardados para um dado utilizador puderem ser divididos em categorias diferentes (coisas que mudam com frequência e coisas que podem não mudar com muita frequência), então recomendamos que use ficheiros separados para cada categoria. Desta forma, os ficheiros inalterados não precisam de voltar a ser enviados depois de cada sessão.

Tamanhos-limite de ficheiros


Os tamanhos-limite de ficheiros na Steam Cloud podem mudar com o tempo. Seguem-se os limites e limiares atuais:

TamanhoRestrição
100 MBTamanho máximo para chamar ISteamRemoteStorage::FileWrite ou ISteamRemoteStorage::FileWriteStreamWriteChunk.
256 MBPode resultar na escolha de um servidor de armazenamento que não seja o ideal para a localização do utilizador, tendo um impacto negativo no upload e download de ficheiros.

Caminhos de ficheiros de progresso

Ao decidir onde gravar os ficheiros de progresso do seu jogo, certifique-se de que o caminho é diferente para cada utilizador do Steam. Caso necessário, pode obter o SteamID único do utilizador através da função ISteamUser::GetSteamID. A partir daí, pode aceder ao ID da conta com GetAccountID(), permitindo que tenha uma variável única ao criar o caminho de gravação.

Sincronização entre plataformas


Se o seu jogo estiver disponível em várias plataformas ou se tiver planos para tal, pode ser do seu interesse seguir estes passos quando configurar a Steam Cloud para o seu jogo.

Caso queira ler/gravar ficheiros diretamente pela interface ISteamRemoteStorage, então pode controlar a sincronização com plataformas através da função ISteamRemoteStorage::SetSyncPlatforms. Por predefinição, um ficheiro novo será sincronizado entre todas as plataformas.

Caso queira usar a Steam Auto-Cloud, há alguns pontos importante a ter em mente. Em primeiro lugar, por predefinição, um ficheiro novo será sincronizado apenas com o que estiver definido na coluna OS do caminho de raiz da Auto-Cloud associado. Isto significa que, se definir raízes diferentes para cada sistema operativo, todos os ficheiros serão divididos por plataforma e não haverá sincronização de ficheiros guardados entre plataformas.

Para permitir a sincronização entre plataformas, deve definir um único caminho de raiz (normalmente para o Windows) e depois criar substituições de raízes para as outras plataformas relevantes. Os ficheiros que corresponderem a um caminho de raiz que também tenha substituições de raízes de outras plataformas serão sincronizados com a original e todas as plataformas definidas. Consulte a documentação sobre a Steam Auto-Cloud para mais informações.

Configuração inicial

Para configurar a Steam Cloud, precisa também de configurar as opções Quota de bytes por utilizador e Número de ficheiros permitidos por utilizador na página de definições da Steam Cloud no painel de administração da aplicação no Steamworks.

Esta quota aplica-se a cada jogo que usa a Steam Cloud e cada jogo tem uma quota diferente. Recomendamos definir valores razoáveis para o seu jogo.

AVISO: não se esqueça de clicar no botão "Guardar" no fundo da página e de publicar as definições atualizadas. Uma vez publicadas, o ícone da Steam Cloud será visível na aplicação Steam para os utilizadores que tiverem o jogo.

Se o seu jogo já foi lançado para o público, assinale a opção Ativar Steam Cloud apenas para developers. Com esta opção, só as contas Steam com uma licença "complementar de desenvolvimento" do seu jogo poderão ver o ícone da Steam Cloud e usá-la. Isto é útil para testar a integração da Steam Cloud sem perturbar a experiência dos utilizadores. Se o seu jogo ainda não foi lançado, a opção não terá efeito, porque como ninguém vai ter o jogo, ninguém vai poder consultar ou aceder ao armazenamento de ficheiros do AppID na Steam Cloud.

Pode partilhar o mesmo armazenamento na Steam Cloud entre dois AppIDs ao preencher o campo AppID para Cloud partilhada. Isto é muito usado para partilhar o progresso entre uma demo e o jogo completo. Use o valor 0 para desativar esta funcionalidade.

API da Steam Cloud e Steam Auto-Cloud

O Steam oferece duas formas diferentes de usar a Steam Cloud. Leia sobre as diferenças entre ambos os métodos e determine qual é o melhor para a sua aplicação.

O primeiro é a API da Steam Cloud.
Esta API oferece uma série de funções que lhe permitem integrar diretamente a Steam Cloud no seu jogo. A API isola ficheiros de utilizadores do Steam individualmente e permite um maior nível de controlo sobre a Steam Cloud.

A API da Steam Cloud é exposta pela interface da API ISteamRemoteStorage e pode encontrar um exemplo de utilização no projeto Steamworks API Example Application (SpaceWar).

O segundo método é a Steam Auto-Cloud.
A Steam Auto-Cloud foi concebida para jogos nos quais não deseja integrar a API da Steam Cloud. Trata-se de uma forma fácil e rápida de começar, mas carece da mesma flexibilidade disponível na API da Steam Cloud.

Caso prefira uma integração mais profunda com a Steam Cloud (por exemplo, poder escolher os ficheiros que serão armazenados na Cloud), deve usar a API da Steam Cloud. Caso contrário, pode usar a Steam Auto-Cloud.

Steam Auto-Cloud

A Steam Auto-Cloud é uma alternativa à API da Steam Cloud que permite a aplicações usar a Steam Cloud sem ser necessário programar ou modificar o jogo para esse fim. Basta especificar os grupos de ficheiros que devem ficar armazenados na Cloud. O Steam irá sincronizar estes grupos de ficheiros automaticamente ao iniciar e ao encerrar o jogo. Evite incluir configurações específicas de sistema, como a qualidade dos gráficos.
Atenção: o ficheiro steam_autocloud.vdf será criado em cada caminho especificado nas definições da Steam Cloud no Steamworks. O ficheiro é usado pelo Steam e pode ser ignorado pelo seu jogo.

Configuração

Depois de concluir a Configuração inicial, a secção de configuração da Steam Auto-Cloud estará disponível na página de definições da Steam Cloud.

Caminhos de raiz descrevem grupos de ficheiros que serão armazenados na Steam Cloud. Cada caminho de raiz pode especificar tanto um único ficheiro como todos os ficheiros de uma determinada subpasta. Use um novo caminho para cada grupo de ficheiros a sincronizar.

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

    Esta é uma lista pré-determinada de caminhos comuns para ficheiros de progresso de jogos.
    RaizSistemas operativos compatíveisCaminho correspondente
    App Install DirectoryTodos[pasta de instalação do Steam]\SteamApps\common\[pasta do jogo]\
    SteamCloudDocumentsTodosCaminho específico da plataforma. Exemplo no Linux: ~/.SteamCloud/[nome de utilizador]/[pasta do jogo]/
    WinMyDocumentsWindows%USERPROFILE%\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/

    Nota acerca dos caminhos da pasta %USERPROFILE% do Windows: os caminhos correspondentes mencionados acima são os locais predefinidos. Atualmente, os utilizadores podem configurar a sua instalação do Windows para que estas pastas fiquem em locais diferentes (não necessariamente dentro da pasta %USERPROFILE%). O Steam utiliza as APIs do Windows necessárias para encontrar o local atual dessas pastas, quer seja o predefinido ou um personalizado.

  2. Subdiretório

    O caminho do subdiretório que contém os ficheiros a guardar na Cloud, em relação à raiz. Use "." se não houver subdiretório.

    Valores especiais no caminho da Auto-Cloud
    A Auto-Cloud permite o uso de identificadores únicos de utilizador no caminho do Subdiretório. Isto permite-lhe armazenar ficheiros de progresso para cada utilizador do Steam no computador separadamente. Pode usar ISteamUser::GetSteamID no seu jogo para obter o SteamID ou o ID de conta do utilizador cujos ficheiros guardar ou ler.
    • {64BitSteamID} – Use esta variável no caminho do Steam para inserir o SteamID de 64 bits do utilizador. Um SteamID de 64 bits tem um formato semelhante ao seguinte: 76561198027391269
    • {Steam3AccountID} – Use esta variável no caminho do Steam para inserir o Steam3 ID (ID de conta) do utilizador. Um ID de conta tem um formato semelhante ao seguinte: 67125541
    Exemplo: SavesDir/{64BitSteamID}
  3. Padrão

    O padrão de nome dos ficheiros a armazenar. Pode usar * como carácter universal. Se quiser todos os ficheiros no diretório, use apenas *.

    Exemplo: *.sav
  4. S.O.

    Defina os sistemas operativos onde estes ficheiros serão sincronizados. Isto só é necessário se os ficheiros forem específicos do sistema operativo, o que esperamos que não seja o caso!
  5. Recursivo

    Inclui subdiretórios ao pesquisar por ficheiros correspondentes. Isto é útil para subdiretórios com nomes não determinísticos, como nomes de utilizador ou ID que não sejam do Steam. Se estiver a usar um SteamID, recomendamos vivamente que use os valores especiais de caminho no campo Subdiretório.

Substituições de raiz

Se a sua aplicação for para várias plataformas e necessitar de diretórios diferentes para cada sistema operativo, use a funcionalidade de substituições de raízes para substituir os caminhos de raiz que definir acima.

Os caminhos de raiz especificados acima podem ser substituídos para corresponder a um caminho diferente noutro sistema operativo. Se usar substituições de raízes, terá de especificar [Todos os S.O.] no menu pendente do "S.O." referente à raiz pretendida.

Uma substituição de raiz é composta de 5 partes.
  1. Raiz original

    Corresponde a uma das raízes definidas acima.
  2. S.O.

    O sistema operativo onde a raiz será substituída.
  3. Nova raiz

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

    Tem a opção de adicionar um caminho de subdiretório, inserido entre a nova raiz e o subdiretório original.
  5. Substituir caminho

    Se assinalar esta caixa, o caminho especificado em "Adicionar/Substituir caminho" irá substituir o subdiretório original por completo.

Exemplo: configuração da Auto-Cloud para aplicações feitas em Unity

Segue-se um exemplo de configuração da Auto-Cloud para utilização com Unity e a propriedade Application.persistentDataPath, cujo valor é diferente em cada sistema operativo. A versão para Windows está configurada com o caminho de raiz, sendo "DefaultCompany" o nome da empresa no Unity e "AutocloudSample" o nome do projeto. Nos campos para macOS e Linux/SteamOS, os caminhos alternativos de Application.persistentDataPath estão definidos no campo "Adicionar/Substituir caminho". A opção "Substituir caminho" está assinalada.

Com estas definições, os ficheiros da Auto-Cloud vão ser sincronizados entre as três pastas, como mostrado nas amostras de pré-visualização.

Cloud_Unity_Auto-Cloud_Example.png

Teste de pré-lançamento

Caso esteja a adicionar a Steam Auto-Cloud a um jogo que já foi lançado e ativou o modo para developers durante a Configuração inicial, então precisa de realizar alguns passos adicionais para testar a funcionalidade.
  1. Inicie sessão no Steam com uma conta que tenha a aplicação que pretende testar.
  2. Na barra de endereços de um browser à sua escolha, escreva steam://open/console para abrir a consola do Steam.
  3. Escreva testappcloudpaths <AppID> na consola (substitua <AppID> pelo AppID do jogo). Por exemplo: testappcloudpaths 480
  4. Escreva set_spew_level 4 4 na consola.
  5. Inicie a aplicação através do Steam.
  6. Verifique a atividade na consola. Se já existirem ficheiros nos caminhos da Auto-Cloud, então deverá conseguir vê-los a ser enviados. Caso contrário, guarde alguns ficheiros na Cloud através da sua aplicação e feche-a para que haja uma sincronização.
  7. Aceda a outro PC e repita os passos acima para testar o download de ficheiros da Steam Auto-Cloud.
  8. Teste em todos os sistemas operativos relevantes.
  9. Escreva testappcloudpaths 0 e set_spew_level 0 0 para terminar o teste. Pode reiniciar a aplicação Steam para remover o separador da consola.

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

Sincronização dinâmica com a Cloud


A Steam Cloud agora é compatível com sincronização dinâmica, em que as alterações que aparecerem na Cloud podem ser transferidas para o computador local durante uma sessão da aplicação. A caso de exemplo, imagine uma sessão de jogo suspensa no Steam Deck. No caso de jogos compatíveis com a sincronização dinâmica com a Cloud, o Steam irá sincronizar ficheiros com a Steam Cloud quando o sistema for suspenso. Depois, o utilizador pode abrir o jogo noutro dispositivo, que irá receber as atualizações da sessão do Steam Deck antes de ser iniciado. Ao encerrar o jogo, as alterações serão enviadas para a Steam Cloud. Por fim, quando o Steam Deck for despertado, o Steam irá sincronizar as alterações com este e informar a aplicação de que os ficheiros locais foram alterados. A aplicação poderá depois iterar pelas alterações e realizar a ação mais apropriada. Por exemplo, o jogo pode simplesmente carregar o progresso atualizado do disco e permitir que o utilizador continue de onde estava no outro dispositivo.

Consulte o nosso anúncio para obter ainda mais informações sobre o que levou à criação desta funcionalidade e como a usar.

Tenha em atenção que esta funcionalidade é compatível tanto com aplicações que usam a API ISteamRemoteStorage para gerir ficheiros como com as que usam a Auto-Cloud.

Para mais detalhes, consulte a documentação sobre ISteamRemoteStorage, especialmente as secções sobre ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount e ISteamRemoteStorage::GetLocalFileChange.

Consulte também ISteamRemoteStorage::BeginFileWriteBatch e ISteamRemoteStorage::EndFileWriteBatch: estes wrappers devem ser usados para ajudar o Steam a enviar ficheiros para a Steam Cloud de forma segura quando o utilizador suspende o sistema.

Teste de pré-lançamento


Caso queira testar as suas builds, pode ativar localmente a sincronização dinâmica com a Cloud. Recomendamos que faça isto no caso de jogos que já foram lançados, uma vez que ativar a sincronização dinâmica para todos os utilizadores poderá resultar na perda de dados ao executar builds que não usam os novos métodos e callbacks específicos da API.

Para testar localmente com um PC:

  1. Inicie sessão no Steam com uma conta que tenha a aplicação que pretende testar.
  2. Na barra de endereços de um browser à sua escolha, escreva steam://open/console para abrir a consola do Steam. (Também pode criar um atalho para o Steam e adicionar -console ao fim do caminho em "Destino", nas propriedades do atalho, para ter acesso à secção da consola).
  3. Escreva @cloud_testdynamicsyncapp <AppID> na consola (substitua <AppID> pelo AppID do jogo). Por exemplo: @cloud_testdynamicsyncapp 480
  4. Inicie a aplicação através do Steam.
  5. Avance no jogo até ao ponto pretendido.
  6. Na consola do Steam, escreva prepare_for_suspend. O Steam irá suspender o processo do jogo e enviar para a Steam Cloud todos os ficheiros que foram alterados.
  7. Opcional: jogue o jogo noutro dispositivo e avance ainda mais no jogo. Depois, feche-o e deixe que a aplicação Steam envie o progresso para a Steam Cloud.
  8. No dispositivo original, na consola do Steam, escreva resume_suspended_games para sincronizar todos os ficheiros necessários da Steam Cloud, enviar as chamadas relevantes à API no seu jogo e retirar o processo do jogo da suspensão.

Para testar localmente com um Steam Deck:

  1. Conecte o seu Steam Deck por meio de um Devkit.
  2. Para usar o "CEF Console", clique aqui.
  3. Na consola de JS, escreva SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <o seu AppID>”) para permitir testes. Para desativar, escreva SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”).

Depuração

Primeiro, certifique-se de que publicou as suas alterações no site de parceiros Steamworks e de que esperou até 10 minutos ou reiniciou a aplicação Steam para receber as alterações publicadas.

Em caso de problemas com a Steam Cloud, consulte o ficheiro de relatório situado em %Pasta de instalação do Steam%\logs\cloud_log.txt.

Consulte Debugging the Steamworks API para mais informações.