O presente documento é um guia de utilização do SteamPipe, a ferramenta da Valve usada para o envio de conteúdo para o Steam. Para conhecer as boas práticas de atualização do seu jogo, consulte: Atualização do seu jogo – Boas práticas.

Introdução ao sistema de conteúdo SteamPipe

O SteamPipe é o sistema de conteúdo de jogos/aplicações por detrás do Steam. O SteamPipe inclui as seguintes funcionalidades:

• Entrega rápida e eficiente de conteúdo.
  
• Ramos "beta" públicos e privados, permitindo o teste de várias builds em paralelo.
  
• Gestão simples de builds na web: envie uma build nova ou reverta para uma anterior com alguns cliques.
  
• Visualização do tamanho de atualização de uma build antes de a colocar no ar.
  
• Partilha de conteúdo entre várias aplicações.
  
• Criação de discos de instalação a partir de conteúdo público ou beta.
  
• Os jogos e aplicações continuam disponíveis offline mesmo depois de se iniciar o download de uma atualização.
  
• O conteúdo está sempre encriptado e versões não ativas não podem ser vistas pelos utilizadores.
  
• Um SteamPipe Local Content Server que pode ser usado durante o desenvolvimento.

Estrutura de conteúdo do jogo: boas práticas

O SteamPipe foi concebido para garantir um download eficiente da instalação inicial de jogos e para aplicar atualizações de forma otimizada. De uma forma geral, o SteamPipe funciona bem com uma vasta variedade de estruturas de conteúdo de jogos. Porém, existem alguns pontos importantes a ter em mente relativamente à otimização e para evitar situações que podem causar ineficiência.

Atenção: se o seu jogo usa o Unreal Engine, consulte as notas específicas a estes ficheiros de pacote no fim desta secção.

O SteamPipe começa por dividir cada ficheiro em segmentos de cerca de 1 megabyte (MB). De seguida, cada segmento é comprimido e encriptado antes de ser enviado para o sistema de entrega de conteúdo do Steam. Estes segmentos permanecem comprimidos e encriptados até que sejam descarregados por cada cliente, onde serão desencriptados, expandidos e colocados nos diretórios necessários.

Quando o SteamPipe processa a atualização de um jogo existente, o sistema verifica se existem segmentos que correspondam aos da build anterior do jogo. Desta forma, apenas as partes novas ou modificadas de qualquer ficheiro se deverão tornar segmentos "novos" e estes segmentos novos são os únicos que um cliente terá de descarregar para atualizar o jogo.

Muitos engines de jogos usam ficheiros de "pacote" para agrupar os recursos dos jogos e para melhorar o tempo de carregamento ao permitir um acesso mais eficiente ao disco. Geralmente, este método funciona bem com o SteamPipe. Porém, alguns sistemas de ficheiros de pacote usam ou permitem implementações que podem causar problemas, levando quase sempre a atualizações muito maiores do que o necessário. Também podem resultar num download rápido, mas com um processo de atualização lento por necessitarem de uma grande quantidade de processamento no disco local.

Caso o seu jogo use ficheiros de pacote, seguem-se algumas recomendações gerais:

• Certifique-se de que as alterações de recursos estejam localizadas o máximo possível no ficheiro de pacote.
  
• Evite misturar a ordem dos recursos num ficheiro de pacote.
  
• Limite o tamanho de um ficheiro de pacote.
  
• Agrupe os recursos por nível/realm/funcionalidade nos seus próprios ficheiros de pacote e considere adicionar ficheiros de pacote novos para atualizações em vez de modificar os existentes.
  
• Não inclua os nomes originais dos ficheiros nem a data e hora originais dos ficheiros ou builds nos recursos.

O primeiro ponto acima refere-se ao conjunto de bytes alterados num ficheiro quando um único recurso é modificado. O ideal é que os dados do recurso sejam modificados e/ou aumentem ou diminuam de tamanho na mesma localização do ficheiro de pacote. O SteamPipe irá criar segmentos novos apenas para as partes do ficheiro que contêm os dados do recurso. Contudo, todos os ficheiros de pacote também requerem algum tipo de índice para que o engine possa localizar os dados dos recursos. A estrutura deste índice pode ter um grande impacto na eficácia de atualizações do SteamPipe. Idealmente, existe um índice ou uma árvore de índices perto do início ou do fim do ficheiro. Como outros recursos podem mudar de posição no ficheiro, as respetivas entradas no índice também serão alteradas. Nesta situação, o SteamPipe irá criar segmentos novos para os dados modificados do recurso e para as partes modificadas do índice.

No entanto, constatámos que alguns engines de jogos distribuem as informações do índice através do ficheiro. Pior ainda, a indexação é feita pela posição absoluta em bytes de cada recurso. Portanto, se um recurso no byte 3450 aumentar de tamanho em 8 bytes, as posições de todos os recursos depois deste no ficheiro também irão mudar. Embora cada posição ocupe apenas 4 ou 8 bytes, uma alteração a um número de 8 bytes irá resultar na criação de um segmento novo de 1 MB pelo SteamPipe. Isto pode ter efeitos catastróficos, pois até alterar alguns recursos pequenos num ficheiro de pacote fará com que os clientes tenham de descarregar mais de metade do ficheiro inteiro para atualizarem o jogo. Caso saiba ou suspeite que a estrutura dos seus ficheiros de pacote esteja a causar este problema, entre em contacto com o seu representante da Valve o mais rapidamente possível. Temos um algoritmo alternativo para compilação de builds que pode ajudar a mitigar este problema, apesar de algumas contrapartidas.

Além disso, o SteamPipe não sabe os limites de cada recurso num ficheiro de pacote. Se misturar a ordem de recursos com menos de 1 MB, é provável que o SteamPipe não detete a reordenação, já que os segmentos de 1 MB determinados anteriormente deixarão de estar presentes no ficheiro. Por isso, durante o processo de criação de uma atualização para o seu jogo, se pretender otimizar os tempos de carregamento ao reordenar os recursos no ficheiro de pacote, esteja ciente de que a atualização poderá ter um download muito grande. Recomendamos que o faça apenas se o aumento de desempenho for significativo.

Quanto ao ponto seguinte: para atualizar um ficheiro de pacote no dispositivo do cliente, o SteamPipe irá compilar a nova versão ao lado da versão antiga. Quando todos os ficheiros novos forem criados, a atualização será "consolidada" ao eliminar os ficheiros antigos e ao mover os novos. Tal significa que, para atualizar um ficheiro de 25 GB, o SteamPipe irá criar sempre um ficheiro novo de 25 GB. Se a atualização necessitar apenas de alterar 10 bytes do ficheiro, o SteamPipe terá de copiar quase todos os 25 GB do ficheiro antigo para o novo. Dependendo do tipo de armazenamento do cliente, este pode ser um processo muito lento. Por este motivo, recomendamos duas coisas:

Primeiro: limite o tamanho dos ficheiros de pacote. Provavelmente 1 ou 2 gigabytes (GB) serão mais do que o suficiente para permitir leituras eficientes do disco ao carregar o jogo.

Segundo: limite o conjunto de recursos em cada ficheiro de pacote. Por exemplo, um ficheiro por nível ou por funcionalidade desbloqueável. Desta forma, as atualizações centradas em partes específicas do jogo não fazem com que os dados de outras partes sejam copiadas de um lado para o outro no computador do cliente. Além disso, ao adicionar novas funcionalidades, níveis, entre outros, o ideal será colocá-los em ficheiros de pacote novos. Os clientes que fizerem o download desta atualização só irão descarregar os ficheiros novos, evitando os problemas mencionados acima acerca de ficheiros de pacotes modificados.

Em caso de dúvidas, pode usar uma ferramenta local de comparação binária, como Beyond Compare, para comparar as versões dos seus ficheiros de pacote. Certifique-se de que as diferenças mostradas são do tamanho esperado para os recursos alterados e de que não há dezenas (ou até centenas) de pequenas alterações espalhadas pelo ficheiro. Caso se depare com algo inesperado, verifique as definições da sua ferramenta de criação de ficheiros de pacote.

Compressão: como o Steam irá comprimir todos os dados para envio, armazenamento e download, normalmente não recomendamos que aplique compressão geral nos ficheiros de pacote. Porém, se acredita que o tamanho exato do jogo no disco possa vir a ser um problema, pode querer usar a compressão em ficheiros de pacote. A compressão irá funcionar com o SteamPipe, desde que os critérios mencionados acima sejam respeitados. Em específico, deve garantir que a compressão seja a nível de recurso individual sempre que possível. Qualquer compressão que ultrapasse os limites dos recursos irá resultar em alterações dispersas e exigir que os clientes descarreguem mais dados do que o necessário.

Encriptação: semelhante à compressão, é provavelmente desnecessária e tem os mesmos riscos mencionados acima.

Se seguir estas regras, irá minimizar o tamanho das atualizações e apenas novo conteúdo terá de ser descarregado. Os utilizadores do seu jogo ficarão gratos e poderá melhorar a qualidade do seu produto ao lançar mais atualizações.

Caso suspeite que a criação de pacotes não esteja a interagir bem com o processo de atualização do SteamPipe, entre em contacto com o seu representante da Valve de forma a podermos ativar funcionalidades avançadas para aliviar o problema.

Unreal Engine – Notas especiais

Algumas versões do Unreal Engine usam "alinhamento por preenchimento" (padding alignment) nos recursos em ficheiros de pacote, o que pode ter um grande impacto no tamanho de atualizações do SteamPipe. Este alinhamento pode causar deslocamentos em cascata de recursos so criar novas builds, especialmente se a compressão de ficheiros de pacote estiver ativa. Usar um alinhamento por preenchimento de 1 MB (1048576) irá ajudar a garantir que realinhamentos desloquem recursos em múltiplos dos mesmos tamanhos dos blocos usados pelo SteamPipe para calcular diferenças.

Por exemplo, para alterar ou especificar o alinhamento por preenchimento durante o processo de conversão (cooking) dos ficheiros de pacote do seu jogo, terá de alterar uma linha dentro do ficheiro UnrealEngine/Engine/Source/Programs/AutomationTool/Win/WinPlatform.Automation.cs. Este ficheiro contém uma função denominada GetPlatformPakCommandLine. Dentro desta função, altere a seguinte linha:


para:


Com esta alteração, poderá ativar a compressão de ficheiros de pacote e tirar partido mesmo assim da otimização das atualizações do SteamPipe.

Unreal Engine é uma marca e/ou marca registada da Epic nos EUA e noutros países.

Tutorial em vídeo do Steamworks – Criação de builds no SteamPipe

Este tutorial apresenta o SteamPipe e os passos para a criação de uma aplicação de exemplo para o Steam através das ferramentas do Steamworks.
https://www.youtube.com/watch?v=SoNH-v6aU9Q

Tutorial em vídeo do Steamworks – Adição de novas plataformas e idiomas

Este tutorial mostra-lhe os passos necessários para adicionar novas plataformas e idiomas ao seu jogo através da criação de depots.
https://www.youtube.com/watch?v=PShS32hcing

Detalhes técnicos do SteamPipe

O SteamPipe usa o protocolo HTTP para a entrega de conteúdo. Uma vez que downloads não são nada mais do que tráfego web, qualquer cache HTTP externa entre o utilizador e os servidores do Steam irá aumentar a velocidade do download. O conteúdo pode ser hospedado por fornecedores de CDN externos, que podem ser adicionados facilmente à nossa rede de conteúdo. A maioria das firewalls dos utilizadores permite tráfego HTTP e não irá bloquear downloads.

O SteamPipe tem um algoritmo eficiente de atualização com base em deltas binários, que altera apenas as partes modificadas de ficheiros de conteúdo existentes. Quando o conteúdo é atualizado, apenas estes deltas precisam de ser enviados. Isto significa que as transferências tanto do developer como do utilizador são mais pequenas e mais rápidas. Para a maioria dos parceiros, não será necessário usar um SteamPipe Local Content Server, uma vez que podem atualizar builds de forma eficaz em ramos privados.

Conta Steam para criação de builds

Antes de poder criar builds no Steam, deverá ter uma conta Steam na sua conta Steamworks com as permissões "Editar metadados da aplicação" e "Publicar alterações à aplicação no Steam". Por motivos de segurança, recomendamos que tenha uma conta dedicada para builds com apenas essas permissões. Pode criar uma conta Steam nova exclusivamente para esta finalidade em https://store.steampowered.com/join.

Qualquer administrador da sua conta Steamworks pode adicionar uma conta Steam e conceder as permissões necessárias. Mais informações sobre este processo estão disponíveis em Gestão da conta Steamworks. Segue-se um exemplo de uma conta deste tipo:

Configuração inicial para novas aplicações SteamPipe

Siga os seguintes passos para configurar novas aplicações SteamPipe:

1. Encontre o AppID da sua aplicação (para tal, selecione a aplicação na página inicial do Steamworks).
   
2. Aceda à página de definições gerais de instalação da sua aplicação.
   
3. Defina, pelo menos, uma opção de arranque (o caminho e, opcionalmente, os argumentos necessários para iniciar o jogo). Passe o cursor do rato sobre o (?) para obter mais informações sobre cada campo.
   
   O exemplo abaixo demonstra 5 opções de arranque (2 para Windows, 2 para macOS e 1 para Linux).
   A opção de arranque 3 só irá aparecer no Windows se o utilizador também tiver o DLC especificado.
   
   
   
4. Aceda à página de depots e adicione depots conforme necessário para esta aplicação. Um depot pode já ter sido predefinido para a aplicação.
   
   1. Clique no depot predefinido e altere o nome para um adequado e reconhecível (como "Conteúdo base" ou "Conteúdo para Windows").
      
   2. Deixe o idioma como [Todos os idiomas], a não ser que este depot seja para um idioma específico.
      
   3. Deixe o sistema operativo como [Todos os S.O.], a não ser que este depot seja para sistemas operativos específicos (se a aplicação for "tudo em um", só para Windows ou só para macOS, deixe como [Todos os S.O.]). Altere este campo apenas para depots do jogo destinados a sistemas operativos específicos.
      
   4. Clique em Adicionar depot novo para criar depots adicionais.
      
   5. Clique em Guardar para guardar quaisquer alterações efetuadas.
      
5. Assim que tiver definido os depots, publique as alterações a partir da página Publicar.
   
6. Os depots que acabou de criar terão de ser incluídos num pacote para que possam ser da sua posse. Cada jogo no Steam deverá ter um pacote complementar de desenvolvimento, o qual é concedido automaticamente às contas listadas no grupo da editora.
   Pode adicionar os depots novos ao pacote (e/ou outros pacotes que deveriam ter estes depots) na página Pacotes e DLCs associados.

Configuração do SDK para envios pelo SteamPipe

Descarregue e extraia a versão mais recente do SDK do Steamworks no computador que pretende usar para enviar builds.

As ferramentas do SteamPipe podem ser encontradas dentro do SDK na pasta tools, que contém dois subdiretórios relevantes.

O conteúdo do jogo e as ferramentas da build do SteamPipe irão ficar no diretório ContentBuilder, que contém os seguintes subdiretórios:

• builder – Inicialmente, este diretório contém apenas steamcmd.exe, que é a versão em linha de comandos do Steam.
  
• builder_linux – A versão do steamcmd para Linux.
  
• builder_osx – A versão do steamcmd para macOS.
  
• content – Este diretório contém todos os ficheiros do jogo que serão colocados em depots.
  
• output – Este diretório será o local para relatórios, cache de segmentos e ficheiros intermediários de saída. ATENÇÃO: esta pasta pode ser eliminada ou esvaziada sempre que quiser, mas depois de ser eliminada, envios subsequentes serão mais longos.
  
• scripts – Este diretório é onde os seus scripts de criação de depots deverão ficar.

Recomendamos que execute steamcmd.exe diretamente na pasta "builder" da plataforma uma vez para inicializar o sistema de criação de builds. Esta ação deverá popular a pasta "builder" com todos os ficheiros necessários para criar depots.

O diretório ContentServer contém as ferramentas para hospedar o seu próprio SteamPipe Local Content Server se o quiser fazer.

SteamCmd no macOS

Para ativar o SteamCmd no macOS, siga os seguintes passos:

1. No terminal, navegue até tools\ContentBuilder\builder_osx.
   
2. Execute "chmod +x steamcmd".
   
3. Escreva "bash ./steamcmd.sh".
   
4. O SteamCmd será executado e atualizado para a build mais recente. O prompt do SteamCmd será apresentado.
   
5. Escreva "exit" e prima Return para fechar o prompt.

De seguida, pode seguir o resto desta documentação (substituindo caminhos conforme apropriado) para criar ficheiros de configuração de aplicações e depots para enviar o seu conteúdo para o Steam.

Criação de ficheiros de configuração de build no SteamPipe

De forma a enviar ficheiros para a sua aplicação com o SteamPipe, deve criar scripts que descrevam a sua build e cada depot incluído. Os scripts de exemplo aqui mostrados estão na pasta Tools\ContentBuilder\scripts do SDK do Steamworks.

Ferramenta de interface gráfica do SteamPipe

Caso esteja a usar o Windows e prefira que uma ferramenta de interface gráfica ajude a criar estes ficheiros de configuração e a enviar as suas builds, pode usar o SteamPipeGUI, disponível na pasta "tools" do SDK do Steamworks. O ficheiro zip inclui instruções adicionais sobre como começar.

Se decidir utilizar a ferramenta de interface gráfica, recomendamos consultar as seguintes secções para se familiarizar com o funcionamento do sistema SteamPipe.

Script simples de criação de build

Vamos começar com o script de criação de build mais básico possível. Neste exemplo, temos um jogo (AppID 1000) com um depot (DepotID 1001) e queremos enviar todos os ficheiros a partir de uma pasta de conteúdo e das respetivas subpastas. Para tal, basta um script de criação de build simples. Consulte o ficheiro "simple_app_build.vdf", que está incluído no SDK:


Ajuste o AppID e o DepotID do seu jogo conforme necessário. Para iniciar a criação de uma build, é necessário executar o steamcmd e passar alguns parâmetros:

Os seguintes passos ocorrem durante a criação de uma build do SteamPipe:

1. O steamcmd.exe irá atualizar-se para a versão mais recente.
   
2. O steamcmd.exe inicia sessão no back‑end do Steam com a conta Steam introduzida.
   
3. O início da criação da build é registado junto do servidor mestre de depots (MDS), o que irá garantir que o utilizador tenha os privilégios corretos para modificar esta aplicação.
   
4. Para cada depot incluído na build da aplicação, uma lista de ficheiros é gerada com base nos ficheiros na pasta de conteúdo e nas regras de filtragem definidas no ficheiro de configuração de criação de build do depot.
   
5. Cada ficheiro é lido e dividido em segmentos pequenos de 1 MB. Se o depot já foi criado, este particionamento irá preservar o máximo possível de segmentos inalterados.
   
6. Novos segmentos de ficheiros são comprimidos e enviados para o MDS.
   
7. Um manifesto final é gerado para a versão do depot; cada manifesto é identificado por um ID de 64 bits.
   
8. Assim que todos os depots tiverem sido processados, o MDS termina a criação da build da aplicação e associa-a a um BuildID global.
   
9. Uma vez concluída a criação da build, poderão existir ficheiros *.csm e *.csd na pasta de saída. Estes ficheiros são temporários e podem ser eliminados, mas agilizam futuros processos de criação de builds.

Quando a criação da build estiver concluída, poderá vê-la na página de builds da aplicação. Neste caso, seria: https://partner.steamgames.com/apps/builds/1000. Na página, poderá publicar a build no ramo "default" ou em qualquer ramo beta (os utilizadores poderão fazer o download desta atualização alguns minutos depois).

Scripts avançados de criação de build

Se a sua aplicação tiver muitos depots com regras complexas de mapeamento de ficheiros, pode criar um script de criação de build para cada depot que será referenciado pelo script de criação de build da aplicação. Seguem-se os parâmetros disponíveis no script de criação de build da aplicação:

• AppID – O AppID do seu jogo. A conta Steam de parceiro utilizada para realizar o envio precisa de ter a permissão "Editar metadados da aplicação".
  
• Desc – A descrição, visível apenas para si na secção "As suas builds" no painel de administração da aplicação. Pode ser alterada a qualquer momento nesta secção após o envio da build.
  
• ContentRoot – A pasta raiz dos ficheiros do jogo; pode ser um caminho absoluto ou relativo ao ficheiro do script de criação de build.
  
• BuildOutput – Este diretório irá conter os relatórios (logs) da criação da build, manifestos de depots, caches de segmentos e ficheiros intermediários de saída. Para o melhor desempenho possível, use um disco separado para os ficheiros resultantes da criação da build. Desta forma, a carga de E/S do disco é dividida ao meio, permitindo que o disco com a pasta raiz dos ficheiros do jogo trate dos pedidos de leitura e que o disco com a pasta dos ficheiros resultantes trate dos pedidos de escrita.
  
• Preview – Este tipo de criação de build só guarda relatórios e um manifesto na pasta de saída. A criação de builds "preview" é uma boa forma de testar os seus scripts de envio e garantir que os mapeamentos, filtros e propriedades de ficheiros funcionam como pretendido.
  
• Local – Defina aqui o caminho até à pasta htdocs do seu SteamPipe Local Content Server (LCS). Builds para o LCS armazenam conteúdo apenas no seu servidor HTTP e permitem-lhe testar a instalação do jogo pela aplicação Steam.
  
• SetLive – O nome do ramo beta no qual a build será publicada automaticamente após uma criação de build bem-sucedida. Deixe vazio para não publicar em nenhum ramo. Tenha em atenção que não é possível publicar no ramo "default" automaticamente. Tal ação deve ser realizada através do painel de administração da aplicação.
  
• Depots – Esta secção contém todos os mapeamentos, filtros e propriedades de ficheiros de cada depot ou uma referência a um ficheiro de script separado para cada depot.

(Exemplo) O script de criação de build de aplicação "app_build_1000.vdf" está a usar todas as opções:

Este script de criação de build da aplicação faz referência a dois ficheiros que especificam todos os mapeamentos e propriedades de ficheiros. As seguintes instruções estão disponíveis num script de criação de build de depot (e também se a secção estiver incluída diretamente no script de criação de build da aplicação).

• DepotID – O ID do depot desta secção.
  
• ContentRoot – (Opcional) Permite-lhe substituir a pasta raiz de conteúdo (ContentRoot) do script de criação de build da aplicação para um depot específico.
  
• FileMapping – Mapeia um ficheiro ou um conjunto de ficheiros da raiz de conteúdo local para o seu depot. Podem existir vários mapeamentos que adicionam ficheiros ao depot. O parâmetro LocalPath é um caminho relativo à pasta raiz de conteúdo e pode conter caracteres universais, como "?" ou "*". Também se aplicará a ficheiros correspondentes em subpastas se a opção Recursive estiver ativa. O parâmetro DepotPath especifica onde os ficheiros selecionados deverão aparecer no depot (use apenas "." para não usar um mapeamento especial).
  
• FileExclusion – Irá excluir ficheiros mapeados. Também pode conter caracteres universais, como "?" ou "*".
  
• InstallScript – Irá marcar um ficheiro como um script de instalação e irá assinar o ficheiro durante o processo de criação de build. A aplicação Steam irá executá-lo ao iniciar qualquer aplicação que tenha este depot.
  
• FileProperties – Irá marcar um ficheiro com sinalizadores especiais:
  
  • userconfig – Este ficheiro é modificado pelo utilizador ou pelo jogo. Não pode ser substituído devido a uma atualização e não levará a um erro de verificação se for diferente da versão anterior do ficheiro.
    
  • versionedconfig – Semelhante a userconfig. Porém, se o ficheiro for atualizado no depot, será substituído localmente quando o jogo do utilizador for atualizado. Atualize apenas o ficheiro no depot quando houver uma correção de bugs ou uma alteração de formato necessária.

(Exemplo) O script de criação de build de depot depot_build_1002.vdf está a usar todas as opções:

ATENÇÃO: pode atribuir os nomes que quiser a estes scripts, mas, por consistência, usámos os nomes app_build_<AppID> e depot_build_<DepotID>. Caso saiba que irá criar builds de aplicações no computador atual, recomendamos que crie subdiretórios no diretório dos scripts para cada aplicação para ajudar a organizar os scrips de criação de build de cada aplicação.

Utilização do SteamPipe num ambiente de CI/CD

De forma a configurar o steamcmd para integração contínua (ou se estiver a usar o steamcmd a partir de um computador ou máquina virtual que é frequentemente restaurada a partir de uma imagem), terá de incluir o ficheiro de configuração que contém o token de autenticação. Siga os seguintes passos para que o seu token de autenticação inicial seja armazenado devidamente:

1. Execute "steamcmd.exe +login <nome de utilizador>" na máquina que irá criar a build.
   
2. Introduza a palavra-passe e o token do Steam Guard.
   
3. Escreva "info". A sua conta deverá aparecer listada como conectada.
   
4. Escreva "quit".
   
5. Para cada sessão futura, não introduza uma palavra-passe. Basta executar "steamcmd.exe +login <nome de utilizador>".
   
6. Assegure-se de que o ficheiro de configuração em <Steam>\config\config.vdf é guardado e preservado entre sessões, já que este ficheiro pode ser atualizado após um acesso bem-sucedido.

ATENÇÃO: se iniciar sessão novamente e fornecer a palavra-passe, será emitido um novo token do Steam Guard, o qual será necessário para iniciar sessão.

Gestão de atualizações

Assim que lançar a sua aplicação para os utilizadores, estes irão receber a build publicada no ramo "default". Recomendamos que teste sempre builds novas antes de as disponibilizar para os utilizadores. Para mais informações sobre como realizar testes bem-sucedidos, consulte: Testes no Steam.

Depuração de problemas com builds

Se a criação da build não foi bem-sucedida, procure por relatórios de erro na pasta de ficheiros resultantes e não na consola onde o script foi executado. A maioria das informações sobre erros pode ser encontrada em ficheiros *.log.
Use estes comandos da aplicação Steam e ficheiros de cliente para fins de depuração:

• "app_status [AppID]" – Mostra o estado atual da aplicação neste cliente.
  
• "app_info_print [AppID]" – Mostra a configuração atual do Steamworks para este jogo (depots, opções de arranque, etc.).
  
• "app_config_print [AppID]" – Mostra a configuração do utilizador atual para este jogo (idioma atual, diretório de instalação, etc.).
  
• file "logs\content_log.txt" – Lista todas as operações e erros do SteamPipe em registo.
  
• file "steamapps\appmanifest_[AppID].acf" – Mostra o estado atual de instalação desta aplicação (KeyValues).

Criação de discos de instalação comerciais

De forma a criar discos de instalação comerciais para jogos SteamPipe, é necessário criar um ficheiro de projeto da build.
Neste exemplo, o ficheiro SKU chama-se "sku_goldmaster.txt":
Alguns pontos a ter em mente:

• Crie uma pasta nova onde as imagens do disco comercial serão guardadas (por exemplo, "D:\retail_disks"). Só são adicionados depots nas secções included_depots; já não existe uma secção de exclusão.
  
• Use Steam.exe (com os parâmetros de linha de comandos -dev e -console) ou steamcmd.exe para criar imagens do instalador. Em ambos os casos, use o comando "build_installer".
  
• Inicie sessão com uma conta Steam que tenha o jogo e todos os depots que pretende adicionar ao disco comercial. A conta não precisa de permissões especiais, logo qualquer conta pode criar discos.
  
• Se usar Steam.exe, interrompa todos os outros downloads.
  
• Aceda à página da consola e execute o comando build_installer:
  
  build_installer sku_goldmaster.txt "D:\retail_disks"
  Este processo pode demorar um pouco, uma vez que todos os depots serão descarregados novamente na primeira execução.
  
• Caso esteja a criar uma versão GM através de um servidor de conteúdo local, execute:
  @localcontentserver "webserver"
build_installer sku_goldmaster.txt "D:\retail_disks" local
  O texto na consola pode mencionar "Backup" porque discos de instalação comerciais e backups (cópias de segurança) são basicamente o mesmo.
  
• Assim que a mensagem "Backup finished for AppID...", aparecer, as imagens do disco de instalação estarão prontas. Mais detalhes sobre a criação dos ficheiros do disco estão disponíveis em logs\backup_log.txt.
  
• Deverão existir pastas novas (Disk_1, Disk_2, etc.) na pasta "D:\retail_disks", cada uma com até 640 MB, conforme especificado em "disk_size_mb". Cada uma destas pastas contém um ficheiro "sku.sis" e ficheiros .csd e .csm por cada depot. Depots maiores podem precisar de vários discos. Todo o conteúdo do disco de instalação comercial é sempre encriptado (ao contrário dos ficheiros de cópias de segurança locais). Copie os ficheiros de instalação do GM do SDK (setup.exe, setup.ini, etc.) para a pasta do primeiro disco e o instalador do disco comercial estará completo.
  
• Ao criar uma versão GM para o macOS, abra a imagem goldmaster/disk_assets/SteamRetailInstaller.dmg num Mac. De seguida, copie a aplicação contida (ficheiro .app) para a raiz do seu dispositivo. Recomendamos que altere o nome da aplicação de instalação, personalize o ícone e decore a janela para apresentar apenas o instalador.
  
• Ao criar uma versão GM multidiscos para macOS, assegure-se de que o nome do volume de todos os discos é o mesmo. O nome do volume faz parte do caminho de montagem e, se os nomes não corresponderem, o instalador não poderá encontrar o disco seguinte.

(Opcional) Criação de um instalador a partir de um ramo beta

O processo acima irá criar um instalador com base no ramo "default". Caso precise de criar um instalador com base num ramo beta, deve criar primeiro um ramo beta com o nome "baseline". De seguida, use o comando seguinte para criar o instalador a partir do ramo "baseline".

Instalação de DLC a partir de um instalador

Por vezes, pode querer criar um instalador que inclua pacotes de DLC. Nesses casos, o processo de criação do instalador requer apenas algumas poucas alterações.
No ficheiro "sku_goldmaster.txt", inclua os AppIDs do DLC na secção "included_depots". Assim que tiver executado o processo "build_installer", encontre o ficheiro sku.sis gerado para o instalador e abra-o com um editor de texto.
Adicione o AppID do DLC na secção "apps". Por exemplo: no caso de um jogo com o AppID 1000 e um DLC com o AppID 1010, a secção "apps" teria de ser ajustada da seguinte forma:
Isto irá garantir que o Steam verifique a posse do DLC e solicite ao utilizador um código de produto se a conta usada para iniciar sessão não tiver o DLC.

Criação de um instalador para vários AppIDs num só disco ou pacote de instalação

Para criar uma versão GM que contenha várias aplicações SteamPipe, crie instaladores de aplicações um a um, mas encaminhe-os todos para a mesma pasta de destino. Cada instalador será combinado com a imagem de instalação existente.

Personalização de um disco de instalação comercial

Consulte este artigo para mais detalhes sobre como personalizar o disco de instalação comercial.

Pré-carregamento de jogos antes do lançamento

Por predefinição, todo o conteúdo é encriptado em todos os discos comerciais e servidores de conteúdo. Mudar um jogo para o modo de pré-carregamento significa que os utilizadores que tiverem o jogo poderão fazer o download do conteúdo, embora continue encriptado no computador dos utilizadores e não possa ser jogado. Assim que o jogo for lançado oficialmente, o Steam irá desencriptar o conteúdo pré-carregado para que o utilizador possa jogar o jogo.

Mudar um jogo para o modo de pré-carregamento é recomendado nos seguintes casos:

• Distribuição de discos comerciais com códigos de produto antes de o jogo estar disponível (para evitar pirataria antes do lançamento).
  
• Jogos em fase de pré-reserva que ultrapassem os 20 GB.

Envie um pedido de ajuda à equipa de publicação no Steam caso acredite que o jogo precisa de pré-carregamento.

Criação de build de DLC

Cada DLC é criado como um depot do jogo base. Consulte a documentação sobre DLC (conteúdo transferível) para mais informações.

Resolução de problemas com o SteamPipe

"Login Failure: Account Login Denied Failed" ao iniciar sessão através do steamcmd

Causa: provavelmente, o Steam Guard está a impedir o início de sessão. Solução:

• Verifique o e-mail associado à conta com que está a iniciar sessão e procure por uma mensagem do Suporte Steam. Copie o código incluído na mensagem de e-mail.
  
• Execute o seguinte comando no steamcmd: set_steam_guard_code <código>
  
• Volte a tentar iniciar sessão pelo steamcmd: Steam>login <nome de utilizador> <palavra-passe>

Resolução de problemas gerais com downloads

• Reinicie o computador, modem, router, etc.
  
• Verifique as definições da firewall. O novo sistema requer a porta 80 (HTTP) e todas as outras portas do Steam, listadas aqui.
  
• Desative temporariamente todos os programas antivírus e bloqueadores de spam.
  
• Verifique a região de download do Steam em Definições->Downloads. A região deve corresponder ao seu local.
  
• Interrompa o download, desinstale e volte a instalar o jogo (para limpar as caches de manifesto).
  
• Saia do Steam e elimine as pastas "appcache" e "depotcache" na pasta de instalação do Steam.
  
• Experimente mudar a sua região de download do Steam para outro local mais distante. Isto pode funcionar se um servidor de conteúdo próximo estiver a enviar dados corrompidos.

As minhas builds para macOS e/ou Linux não estão a instalar ficheiros. Porquê?

Caso esteja a testar a instalação do seu jogo ou aplicação em várias plataformas através do Steam, pode ocorrer uma situação em que a build é instalada no Windows, mas não instala ficheiros no macOS ou no Linux, apesar de o processo do SteamPipe estar configurado para enviar depots para macOS e/ou Linux. Existe um passo, muitas vezes ignorado, que envolve a adição de depots alternativos ao pacote que deve ser instalado. Siga os seguintes passos para verificar os depots que estão incluídos num pacote:

1. Aceda à página de administração da aplicação.
   
2. Na secção "Ver itens associados", clique em Todos os pacotes, DLCs, demos e ferramentas associados.
   
3. Clique no título do pacote que pretende descarregar.
   
4. Reveja a secção Depots incluídos.
   
5. Use a opção Adicionar/Remover depots para garantir que o conjunto correto de depots está associado ao pacote.

Há vários tópicos de discussão sobre este assunto que também podem ajudar:

• "Pasta vazia depois de instalar o jogo"
  
• "Builds em Unity para PC/Mac/Linux"
  
• "Preparação de conteúdo para Mac"

Executar steamcmd.exe resulta no seguinte erro: "SteamUpdater: Error: Steam needs to be online to update. Please confirm your network connection and try again." ou "O Steam necessita de estar online para ser atualizado. Verifica a tua ligação de rede e tenta de novo."

Solução: Aceda a Opções da Internet->Ligações->Definições de LAN e assinale Detetar definições automaticamente.

Ao tentar criar a build da aplicação, deparo-me com o seguinte erro: "ERROR! Failed 'DepotBuild for scriptname.vdf' - status = 6."

Causas possíveis:

• A conta não tem permissões para a aplicação.
  
  • Certifique-se de que o AppID está correto no ficheiro app_build.vdf.
    
  • Certifique-se de que a conta usada tem as permissões apropriadas para o AppID.
    
• O steamcmd não consegue encontrar os conteúdos do depot.
  
  • Certifique-se de que o valor de "contentroot" no script app_build é um caminho válido relativo ao local do ficheiro do script.
    
  • Certifique-se de que o valor de "LocalPath" no script depot_build é um caminho válido relativo ao caminho no script app_build. Assegure-se de que o diretório contém conteúdo.
    

Ao tentar criar a build da aplicação, deparo-me com o seguinte erro: "ERROR! Failed to get application info for app NNNNN (check login and subscription)"

Isto significa que o Steam não pode obter informações sobre a aplicação, ou porque não existem ou porque o utilizador não tem acesso à aplicação.

• Certifique-se de que "NNNNN" é o AppID associado à aplicação.
  
• Certifique-se de que o AppID é o correto no ficheiro app_build.vdf.
  
• Caso se trate de um AppID novo, certifique-se de que a configuração da página de administração da aplicação no Steamworks foi publicada. Aplicações novas devem ter um diretório de instalação do SteamPipe, assim como um depot. Para confirmar, aceda à página "Editar definições do Steamworks"; o diretório de instalação pode ser visto na secção "Instalação: geral" do separador "Instalação" e o depot na secção "Depots" do separador "SteamPipe". Todas as alterações deverão ser publicadas através do separador "Publicar".
  
• Se estiver tudo como esperado, assegure-se de que a sua conta tem o AppID.

"An error occurred while installing [nome da aplicação] (Invalid content configuration)" ou "Ocorreu um erro ao instalar [nome da aplicação] (configuração de conteúdo inválida)" ao iniciar.

Causas possíveis:

• Nenhuma build foi publicada no ramo usado para a instalação.
  Solução: publique a build num ramo em https://partner.steamgames.com/apps/builds/<AppID do jogo> e selecione o ramo na aplicação Steam (como descrito aqui).
  
• Opções de arranque inválidas.
  Solução: confirme se as opções de arranque no separador "Instalação" da página de administração do seu jogo estão corretas: https://partner.steamgames.com/apps/config/<AppID do jogo>.
  
• Não tem os depots que constituem o jogo.
  Solução: certifique-se de que os depots necessários foram adicionados à subscrição de desenvolvimento (consulte Edição de pacotes para obter mais detalhes).

Não me lembro do nome nem do comportamento de um determinado comando do steamcmd

Use o comando "find" no steamcmd para pesquisar por qualquer comando disponível. A pesquisa irá efetuar correspondências parciais do nome do comando e irá listar a respetiva sintaxe.