Documentazione di Steamworks
Caricamento su Steam
Questa è una guida all'uso di SteamPipe, lo strumento di Valve per la distribuzione dei contenuti su Steam. Per ulteriori informazioni sulle pratiche consigliate per aggiornare il tuo gioco, vedi Aggiornamento del gioco: pratiche consigliate.

Introduzione al sistema di contenuti SteamPipe

SteamPipe è il sistema di contenuti di giochi/applicazioni su cui si basa Steam. SteamPipe include le seguenti funzionalità:
  • Consegna efficiente e veloce dei contenuti.
  • Rami "beta" pubblici e privati che consentono di testare build multiple.
  • Gestione semplificata via web delle build: bastano pochi clic per rilasciare una nuova o tornare a utilizzarne una precedente.
  • Possibilità di vedere le dimensioni dell'aggiornamento di una build prima di pubblicarlo.
  • Possibilità di condividere contenuti tra più applicazioni.
  • Possibilità di creare dischi di installazione da contenuti pubblici o beta.
  • I giochi e le app rimangono disponibili offline anche dopo l'inizio del download di un aggiornamento.
  • Tutti i contenuti sono sempre codificati e le versioni non attive non sono visibili ai clienti.
  • Un Server di contenuti locale di SteamPipe che può essere utilizzato durante lo sviluppo.
NOTA: SteamPipe presenta dei concetti che ne sono una parte integrante. Prima di iniziare, ti consigliamo di familiarizzare con i concetti presentati nella documentazione Applicazioni. Avere un'idea di come i vari componenti funzionano insieme sarà molto utile quando caricherai il tuo prodotto su Steam.

Struttura del contenuto di gioco - Pratiche consigliate


SteamPipe è stato progettato sia per una efficiente installazione iniziale dei giochi che per applicare in modo ottimale le patch degli aggiornamenti. In generale, funziona bene per un'ampia varietà di strutture di contenuti di gioco. Tuttavia, ci sono alcune cose importanti da sapere in termini di ottimizzazione per evitare situazioni che possono causare inefficienza.

SteamPipe inizialmente divide ogni file in blocchi di circa un megabyte (MB). Ogni blocco viene quindi compresso e crittografato prima di essere caricato nel sistema di consegna dei contenuti di Steam. I blocchi rimangono compressi e crittografati fino a quando non sono scaricati da ciascun client, per poi essere decodificati, espansi e collocati nella corretta destinazione.

Quando SteamPipe elabora un aggiornamento per un gioco esistente, cerca di trovare blocchi di questo tipo che corrispondono alla build precedente del gioco. In questo modo, solo le parti nuove o modificate di qualsiasi file vengono opportunamente trasformate in "nuovi" blocchi, che sono gli unici pezzi che l'utente deve scaricare per aggiornare il proprio gioco.

Molti motori di gioco utilizzano file di "pacchetto" per unire le risorse di gioco e migliorare i tempi di caricamento consentendo un accesso al disco più efficiente. Generalmente, funziona bene con SteamPipe. Tuttavia, alcuni sistemi di file di pacchetto utilizzano o abilitano l'utilizzo di comportamenti che possono causare problemi, con la conseguenza che gli aggiornamenti sono quasi sempre molto più grandi del necessario. Possono anche comportare un download veloce ma un processo di aggiornamento lento poiché sono necessarie grandi quantità di IO sul disco locale.

Se il tuo gioco utilizza i file di pacchetto, ecco alcune linee guida generali:

  • Assicurati che le modifiche alle risorse siano localizzate il più possibile all'interno del file di pacchetto.
  • Evita il rimescolamento dell'ordine delle risorse con un file di pacchetto.
  • Limita la dimensione del file di pacchetto.
  • Raggruppa le risorse per livello/realm/funzione nei propri file di pacchetto e considera l'aggiunta di nuovi file di pacchetto per gli aggiornamenti invece di modificare quelli esistenti.
  • Non includere nessun filename o file/timestamp della build originale per ogni risorsa.

Il primo punto di cui sopra si riferisce a quali byte vengono modificati all'interno di un file quando viene modificata una singola risorsa. Se i dati di tale risorsa vengono modificati e/o crescono o si riducono all'interno della stessa posizione del file di pacchetto, è la situazione ottimale. SteamPipe creerà solo nuovi blocchi per le parti del file contenenti i dati delle risorse. Tuttavia, tutti i file di pacchetto richiedono anche una sorta di indice (TOC) in modo che il motore possa individuare i dati delle risorse. La struttura di questo indice può avere un grande impatto sull'efficienza delle patch di SteamPipe. È preferibile che ci sia un indice o un suo abbozzo accanto all'inizio e alla fine del file. Poiché altre risorse possono cambiare la posizione dei byte all'interno del file, anche le voci del loro indice cambieranno. In questa situazione, SteamPipe creerà nuovi blocchi per i dati degli asset modificati e le parti modificate dell'indice.

Tuttavia, quello che abbiamo visto in alcuni motori di gioco è che le informazioni dell'indice sono distribuite in tutto il file, o peggio, utilizzano valori assoluti di offset di byte. Pertanto, se una risorsa pari a 3450 byte aumenta di 8 byte, cambieranno i valori di offset per tutte le risorse successive del file. Anche se ogni valore di offset ha una dimensione di soli 4 o 8 byte, una modifica pari a 8 byte comporterà la creazione di un nuovo blocco da 1 MB da parte di SteamPipe. Questo può avere effetti davvero negativi: anche solo la modifica di alcune piccole risorse in un file di pacchetto comporterà per gli utenti la necessità di scaricare più della metà dell'intero file per l'aggiornamento. Se sei a conoscenza o sospetti che la struttura del tuo file di pacchetto stia causando questo problema, contatta Valve il prima possibile. Abbiamo un algoritmo di build alternativo che può aiutare a mitigare questo problema, anche se presenta dei compromessi.

Inoltre, SteamPipe non conosce i limiti delle risorse all'interno di un file di pacchetto. Se le risorse di dimensioni inferiori a 1 MB vengono mescolate, molto probabilmente Steam Pipe non sarà in grado di rilevare questo riordino poiché i blocchi da 1 MB, precedentemente determinati, non saranno più presenti all'interno del file. Quindi, se durante la creazione di un aggiornamento per il tuo gioco desideri ottimizzare i tempi di caricamento riordinando le risorse all'interno del file di pacchetto, sappi che questo potrebbe comportare un download molto grande per l'aggiornamento. Si consiglia di eseguire questa operazione solo se i miglioramenti delle prestazioni sono significativi.

A seguire: per aggiornare il file del pacchetto sul dispositivo di un utente, SteamPipe crea la nuova versione accanto alla precedente. Quando tutti i nuovi file sono stati creati, si esegue il "commit" dell'aggiornamento cancellando i vecchi file e aggiungendo quelli nuovi. Ciò significa che per aggiornare un file di pacchetto da 25 GB, SteamPipe creerà sempre un nuovo file da 25 GB. Se l'aggiornamento richiede solo 10 byte di modifiche a quel file, SteamPipe dovrà copiare quasi tutti i 25 GB dal vecchio al nuovo file. A seconda dello spazio di archiviazione dell'hardware del client, questo può essere un processo molto lento. Per questo motivo, consigliamo due cose:

Primo - limita le dimensioni dei file di pacchetto. Probabilmente 1 o 2 gigabyte (GB) sono più che sufficienti per consentire una lettura efficiente del disco durante il caricamento del gioco.

Secondo - mantieni la portata delle risorse piuttosto limitata all'interno di un singolo file di pacchetto, magari a un singolo livello di gioco o a una funzione sbloccabile. In questo modo, gli aggiornamenti che riguardano parti specifiche del gioco non fanno sì che i dati presenti in altre parti del gioco vengano copiati sul dispositivo dell'utente. Inoltre, quando si aggiungono nuove funzionalità/livelli/ecc., questi possono e dovrebbero essere inseriti nei loro nuovi file di pacchetto. Gli utenti che scaricano questo aggiornamento effettueranno un comune download di nuovi file, evitando i problemi menzionati in precedenza con le modifiche ai file di pacchetto.

In caso di dubbio, si può usare uno strumento di comparazione dei file binari locali come Beyond Compare per confrontare le versioni dei file del pacchetto. Verifica che le differenze mostrate siano della dimensione prevista per le risorse modificate e che non ci siano decine o centinaia di piccole modifiche sparse nel file. Se ottieni risultati inattesi, controlla le impostazioni dello strumento di comparazione dei file di pacchetto.

Compressione: poiché Steam comprime tutti i dati per il caricamento, l'archiviazione e il download, non ti consigliamo di utilizzare gli strumenti comuni di compressione per i file di pacchetto. Ad ogni modo, se sei preoccupato per le dimensioni su disco del tuo gioco, puoi sempre decidere di comprimere i file di pacchetto. Funzionerà bene con SteamPipe purché siano soddisfatti i criteri che abbiamo elencato nei punti precedenti. In particolare, è necessario assicurarsi che la compressione sia il più possibile per risorsa. Qualsiasi compressione che oltrepassi i confini delle risorse estenderà le modifiche altrove, richiedendo agli utenti di scaricare più dati del necessario.

Codifica: si tratta di un'operazione simile alla compressione, probabilmente non necessaria e con gli stessi rischi menzionati precedentemente.

Seguendo queste regole, le dimensioni delle patch saranno ridotte e sarà necessario scaricare solo i nuovi contenuti. I tuoi clienti te ne saranno grati e sarai in grado di aggiornare il gioco più spesso, aumentandone la qualità.

Se credi che il tuo pacchetto di gioco non interagisca bene con il processo di aggiornamento di SteamPipe, contatta Valve e potremo abilitare funzionalità avanzate per aiutarti a riguardo.

Tutorial video di Steamworks: come integrare il tuo gioco con Steampipe

Questo tutorial rappresenta un'introduzione a SteamPipe e presenta i passaggi da seguire per creare un'applicazione per Steam attraverso gli strumenti di Steamworks.
https://www.youtube.com/watch?v=SoNH-v6aU9Q

Tutorial video di Steamworks: aggiungere nuove lingue e piattaforme

Questo tutorial ti guiderà nell'aggiunta di nuove piattaforme e lingue al tuo gioco attraverso l'aggiunta di nuovi depot alla tua app.
https://www.youtube.com/watch?v=PShS32hcing

Dettagli tecnici di SteamPipe

Steampipe utilizza il protocollo HTTP per la distribuzione di contenuti. I download fanno parte del normale traffico web, quindi qualunque cache HTTP di terze parti presente tra il client e i server di Steam aumenterà la velocità di download. I contenuti possono essere caricati su provider di CDN esterni, che possono essere facilmente aggiunti alla nostra rete di contenuti. La maggior parte dei firewall consente il traffico HTTP e non bloccherà i download.

SteamPipe è dotato di un efficiente algoritmo di patching basato su delta binari che cambia solo le sezioni modificate dei file dei contenuti. Quando i contenuti vengono aggiornati, basterà inviare queste delta. In questo modo, sia i trasferimenti degli sviluppatori che quelli degli utenti saranno più piccoli e veloci. Per la maggior parte dei partner non sarà necessario utilizzare un Server di contenuti locale di SteamPipe, poiché potranno applicare patch alle build su rami privati.

Account per le build di Steam

Per creare una build su Steam, dovrai avere un account di Steam all'interno del tuo account di Steamworks con i permessi "Modifica i metadati dell'app" e "Pubblica modifiche all'app su Steam". Per motivi di sicurezza, consigliamo di avere un account dedicato alle build solo con quei permessi. Puoi creare un account di Steam per questo scopo qui: https://store.steampowered.com/join.

Tutti gli amministratori del tuo account di Steamworks possono aggiungere un account di Steam e fornire i permessi necessari. Maggiori informazioni su questo processo sono disponibili qui: Gestione dell'account Steamworks. Ecco un esempio dell'aspetto di questo account:

create_build_account.png

Configurazione iniziale per le nuove app di SteamPipe

Segui questi passaggi per configurare nuove app su SteamPipe:
  1. Trova l'appID della tua applicazione selezionandola sulla tua pagina principale di Steamworks.
  2. Vai alla pagina Impostazioni generali per l'installazione per la tua app.
  3. Definisci almeno una opzione di lancio (il percorso e, in maniera opzionale, gli argomenti necessari per lanciare il gioco). Passa con il mouse sopra il (?) per visualizzare maggiori informazioni su ogni campo.

    L'esempio sottostante mostra 5 opzioni di avvio, 2 per Windows, 2 per macOS e 1 per Linux.
    L'opzione di avvio 3 verrà visualizzata su Windows solo se l'utente possiede anche il DLC specificato.

    updatedlaunchoptions_3.png
  4. Vai alla pagina Depots e aggiungi i depot necessari per quest'app. Per impostazione predefinita, potrebbe già essere presente un depot configurato per la tua applicazione.
    1. Clicca sul depot predefinito e cambiane il nome in uno appropriato e riconoscibile (ad esempio "Contenuto di base" o "Contenuto per Windows").
    2. A meno che non si tratti di un depot per una lingua in particolare, lascia l'impostazione della lingua su [All languages].
    3. A meno che non si tratti di un depot per un OS in particolare, lascia l'impostazione dell'OS su [All OSes]. Se l'app è unica per tutti gli OS o se è esclusivamente per PC o per Mac, lascia lo stesso l'impostazione su [All OSes]. Specifica questo parametro solo per depot di giochi destinati un OS specifico.
    4. Clicca su Aggiungi nuovo Depot per creare depot addizionali.
    5. Clicca su Salva modifiche per salvare le modifiche effettuate.
  5. Una volta che avrai finito di definire i tuoi depot, pubblica i cambiamenti effettuati tramite la pagina Pubblica.
  6. I tuoi depot appena definiti dovranno essere inclusi in un pacchetto per assegnarne la proprietà. Ogni gioco su Steam dovrebbe avere un pacchetto per sviluppatori automaticamente assegnato agli account elencati nel tuo gruppo da editore.
    Puoi aggiungere i nuovi depot a quel pacchetto (e altri pacchetti che dovrebbero avere quei depot) dalla pagina Pacchetti associati e DLC.
Nota: se il tuo eseguibile è in una sottocartella della cartella di installazione principale, aggiungi il nome della sottocartella nel campo Eseguibile. Non usare barre o punti.
Nota sulla piattaforma: Come sopra mostrato, le applicazioni macOS possono essere avviate specificando un bundle dell'app (Game.app) o uno script/file binario (Game.app/Contents/MacOS/Game). In generale, il formato bundle dell'app è preferibile, poiché consente a macOS di determinare più correttamente i parametri di avvio come farebbe se venisse avviato manualmente al di fuori di Steam.

Un esempio da tenere presente è che le applicazioni attualmente avviate tramite un bundle dell'app sui dispositivi Apple Silicon avvierà l'architettura migliore disponibile nell'applicazione, mentre gli avvii diretti con file binario useranno la stessa architettura del processo di Steam (attualmente x86_64).

Impostazione dell'SDK per i caricamenti su SteamPipe

Scarica e decomprimi la versione più recente dell'SDK di Steam sul computer su cui caricherai le build.

Gli strumenti di SteamPipe si trovano nella cartella tools dell'SDK, che contiene 2 sottodirectory rilevanti.

I contenuti del tuo gioco e gli strumenti per le build di SteamPipe si trovano nella directory ContentBuilder. Questa directory contiene le seguenti sottodirectory:
  • builder: inizialmente conterrà solo steamcmd.exe, la versione in linea di comando di Steam.
  • builder_linux: la versione Linux di steamcmd.
  • builder_osx: la versione macOS di steamcmd.
  • content: contiene tutti i file di gioco che faranno parte dei depot.
  • output: contiene i registri delle build, la cache dei frammenti e l'output intermedio. NOTE: questa cartella può essere eliminata o svuotata in qualunque momento ma il caricamento successivo all'eliminazione impiegherà più tempo.
  • scripts: uas questa directory per gli script delle build necessari a creare i depot del tuo gioco.
steampipebuilddir.png

Consigliamo di eseguire una volta steamcmd.exe direttamente nella cartella builder della tua piattaforma per effettuare il bootstrap del tuo sistema di build. Farlo dovrebbe popolare la tua cartella builder con tutti i file necessari per creare depot.

La directory ContentServer contiene gli strumenti necessari per gestire il tuo stesso Server di contenuti locale di SteamPipe, se volessi farlo.

SteamCmd su macOS

Per abilitare SteamCmd su macOS, segui i seguenti passaggi:
  1. Dal terminale, recati alla cartella \ContentBuilder\builder_osx\
  2. Esegui chmod +x steamcmd
  3. Digita bash ./steamcmd.sh
  4. SteamCmd verrà eseguito e aggiornerà alla build più recente, lasciandoti nel prompt di SteamCmd
  5. Digita "exit" e premi invio per uscire dal prompt
Ora puoi seguire il resto di questo documento (sostituendo i percorsi quando necessario) per creare depot e file di configurazione dell'app per caricare i tuoi contenuti su Steam.

Creazione dei file di configurazione per le build di SteamPipe

Per caricare la tua app con SteamPipe, devi prima creare gli script che descrivono la tua build e ogni depot in essa incluso. Gli script di esempio mostrati qui si trovano nella cartella Tools\ContentBuilder\scripts dell'SDK di Steamworks.

Strumento per la GUI di SteamPipe

Se utilizzi Windows e preferisci utilizzare uno strumento GUI (con interfaccia grafica) per creare questi file di configurazione e caricare le tue build, puoi usare la SteamPipeGUI, disponibile nella cartella Strumenti dell'SDK di Steamworks. Nel file .zip sono incluse istruzioni aggiuntive su come iniziare.

Ti consigliamo di leggere la seguente sezione anche se utilizzerai la GUI, poiché ti aiuterà a familiarizzarti con il funzionamento del sistema SteamPipe.

Semplice script per le build


Iniziamo con uno script per la build molto basilare. Nel nostro esempio abbiamo un gioco (il cui appID è 1000) che ha un depot (il cui ID è 1001) e vogliamo caricare tutti i file da una cartella dei contenuti e le sue sottocartelle. Per farlo, basta uno singolo script per build. Dai un'occhiata a "simple_app_build.vdf", incluso nell'SDK:

"AppBuild" { "AppID" "1000" // il tuo AppID "Desc" "Questo è un semplice script per build" // descrizione interna di questa build "ContentRoot" "..\content\" // cartella principale dei contenuti, in relazione alla posizione di questo file "BuildOutput" "..\output\" // cartella di output della build per i registri della build e i suoi file di cache "Depots" { "1001" // il tuo ID del depot { "FileMapping" { "LocalPath" "*" // tutti i file dalla cartella contentroot "DepotPath" "." // mappato nella cartella principale del depot "recursive" "1" // includi tutte le sottocartelle } } }

Modifica l'appID e l'ID del depot del tuo gioco se necessario. Per avviare una build dovrai eseguire steamcmd e passare un paio di parametri:
tools\ContentBuilder\builder\steamcmd.exe +login <account_name> <password> +run_app_build ..\scripts\simple_app_build.vdf +quit

NOTA: Il tuo primo tentativo di eseguire una build potrebbe fallire a causa di Steam Guard. Se l'accesso non dovesse riuscire per via di Steam Guard, recupera il codice di Steam Guard nell'e-mail ed esegui steamcmd come: steamcmd.exe "set_steam_guard_code <code>", quindi riprova. Dopo aver effettuato una volta l'accesso con Steam Guard viene usato un file sentinella per verificare che l'accesso sia legittimo.

Se stai usando steamcmd su un computer o una macchina virtuale su cui viene eseguito spesso l'imaging, ti consigliamo di includere il file di configurazione nella tua immagine, in modo da non fare intervenire Steam Guard ogni volta. Il file di configurazione si trova in <Steam>\config\config.vdf.

Durante una build SteamPipe avvengono i seguenti passaggi:
  1. Steamcmd.exe si aggiornerà da solo alla versione più recente.
  2. Steamcmd.exe effettua l'accesso al backend di Steam utilizzando l'account per le build di Steam.
  3. La build dell'app viene registrata con il MDS (Master Depot Server, server del depot principale), concedendo all'utente i permessi necessari per modificare questa app.
  4. Per ogni depot incluso nella build dell'app viene generata una lista di file basata sui file nella cartella dei contenuti e sui filtri definiti nel file di configurazione della build del depot.
  5. Ogni file viene scansionato e diviso in frammenti di circa 1 MB. Se il depot è già stato parte di una build, effettuare questa partizione preserverà il maggior numero possibile di frammenti non modificati.
  6. I nuovi frammenti dei file sono compressi, codificati e caricati sull'MDS.
  7. Viene generato un manifesto finale per la versione del depot. Ogni manifesto è identificato da un ID del manifesto unico a 64 bit.
  8. Una volta che tutti i depot sono stati processati, l'MDS completa la build dell'app e le assegna un buildID globale.
  9. Dopo che la build è completata, potrebbero esserci file *.csm and *.csd nella cartella di output della build. Questi file sono temporanei e possono essere eliminati, ma rendono più veloce il procedimento per le build successive.


Quando la build è completa, la vedrai sulla tua pagina delle build dell'applicazione (in questo caso: https://partner.steamgames.com/apps/builds/1000). Lì potrai pubblicare quella build per il ramo predefinito o per qualunque ramo beta e gli utenti saranno in grado di scaricare l'aggiornamento entro un paio di minuti.

Script avanzati per le build


Se la tua applicazione ha molti depot con complesse regole di mappatura dei file, puoi creare uno script per la build del depot per ciascun depot. Lo script sarà utilizzato dallo script per le build dell'applicazione. Innanzitutto, diamo un'occhiata ai parametri disponibili nello script per la build dell'applicazione:

  • AppID - L'appID del tuo gioco. L'account da partner di Steam che effettua il caricamento deve avere il permesso "Modifica i metadati dell'applicazione".
  • Desc - La descrizione è visibile solo a te nella sezione "Le tue build" del tuo pannello da Amministratore dell'applicazione. Può essere modificata in qualunque momento dopo aver caricato una build sulla pagina "Le tue build".
  • ContentRoot - La cartella principale dei tuoi file di gioco. Può essere un percorso completo o quello relativo al file dello script della build.
  • BuildOutput - In questa directory andranno i registri della build, i manifesti del depot, i frammenti della cache e gli output intermedi. Per le prestazioni migliori, usa un disco separato per l'output della tua build. In questo modo suddividerai il carico di lavoro di IO, lasciando che il tuo disco principale dei contenuti gestisca le richieste di lettura e il tuo disco di output gestisca quelle di scrittura.
  • Preview - Questo tipo di build ha come output solo registri e un file di manifesto nella cartella di output della build. Le build di anteprima sono un buon modo per iterare sui tuoi script di caricamento e assicurarti che le mappature, i filtri e le proprietà dei tuoi file funzionino a dovere.
  • Local - Impostalo sul percorso htdocs del tuo Server di contenuti locale di SteamPipe (LCS). Le build per server dei contenuti locali caricano i contenuti solo sul tuo server HTTP e ti consentono di testare l'installazione del tuo gioco utilizzando il client di Steam.
  • SetLive - Il nome del ramo beta da impostare automaticamente come pubblico se la build ha esito positivo. Se vuoto, non viene impostato un nome. Nota che il ramo "default" non può essere impostato automaticamente come pubblico. Ciò va fatto attraverso il pannello da Amministrate dell'applicazione.
  • Depots - Questa sezione contiene tutte le mappature, i filtri e le proprietà di ciascun file di ogni depot, oppure fa riferimento a un file di script separato per ciascun depot.

Lo script di esempio per la build dell'applicazione "app_build_1000.vdf" usa tutte le opzioni:
"AppBuild" { "AppID" "1000" // Il tuo AppID "Desc" "qui va la descrizione della build" //descrizione interna per questa build "Preview" "1" // rendi questa build una di anteprima, non verrà caricato nulla "Local" "..\..\ContentServer\htdocs" // inserisci i contenuti su un server di contenuti locale invece che su Steam "SetLive" "AlphaTest" // rendi pubblica questa build su un ramo beta "ContentRoot" "..\content\" // la cartella principale dei contenuti relativa a questo file di script "BuildOutput" "D:\build_output\" //inserisci la cache e i file di registro della build su un disco diverso per prestazioni migliori "Depots" { // le istruzioni per la mappatura dei file di ciascun depot sono in file di script separati "1001" "depot_build_1001.vdf" "1002" "depot_build_1002.vdf" } }

Questo script per la build dell'applicazione fa riferimento a due file di script per la build del depot che specificano tutte le mappature dei file e le loro proprietà. Le seguenti istruzioni sono disponibili in uno script per la build del depot (e anche se la sezione è inclusa direttamente in uno script per la build dell'applicazione).

  • DepotID - L'ID del depot per questa sezione.
  • ContentRoot - Consente di sovrascrivere facoltativamente la cartella ContentRoot dello script per la build dell'applicazione per i depot desiderati.
  • FileMapping: esegue la mappatura di un singolo file o di un insieme di file dalla cartella principale locale dei contenuti nel tuo depot. Possono esistere multiple mappature di file che aggiungono file al depot. Il parametro LocalPath è un percorso relativo alla cartella principale dei contenuti e può contenere caratteri speciali come "?" o "*". Si applicherà anche ai file corrispondenti nelle sottocartelle, se Recursive è abilitato. Il parametro DepotPath specifica dove i file selezionati dovrebbero apparire nel depot (usa semplicemente "." se non vuoi una mappatura particolare).
  • FileExclusion - Escluderà i file già mappati. Può contenere caratteri speciali quali "?" o "*".
  • InstallScript - Contrassegnerà un file come script di installazione e lo firmerà durante il processo della build. Il client di Steam sa di doverli eseguire per qualunque applicazione che contiene questo depot.
  • FileProperties Caratterizzerà un file con dei contrassegni speciali:
    • userconfig - Questo file è modificato dall'utente o dal gioco. Non può essere sovrascritto da un aggiornamento e non provocherà un errore nella verifica se è diverso dalla sua versione precedente.
    • versionedconfig - Simile a userconfig, ma se il file viene aggiornato nel depot verrà sovrascritto localmente quando il gioco dell'utente viene aggiornato. Aggiorna il file nel depot solo in caso di una modifica di formato o correzione di un bug necessaria.

Esempio dello script per la build del depot depot_build_1002.vdf che dimostra l'uso di tutte le opzioni:
"DepotBuild" { "DepotID" "1002" "ContentRoot" "C:\content\depot1002" // Sovrascrivi ContentRoot dallo script per la build dell'applicazione "FileMapping" { // Tutti i file e le cartelle di origine in ".\bin" saranno mappati nella cartella ".\executables" nel depot "LocalPath" "bin\*" "DepotPath" "executables\" "Recursive" "1" // includi tutte le sottocartelle } "FileMapping" { // sovrascrivi tutti i file audio in \\audio con le loro versioni in tedesco "LocalPath" "localization\german\audio\*" "DepotPath" "audio\" } "FileMapping" { // copia lo script di installazione per la versione tedesca nella cartella principale del depot "LocalPath" "localization\german\german_installscript.vdf" "DepotPath" "." } "FileExclusion" "bin\server.exe" // escludi questo file "FileExclusion" "*.pdb" //escludi tutti i file .PBD in qualunque posizione "FileExclusion" "bin\tools*" // escludi tutti i file in bin\tools\ "InstallScript" "localization\german\german_installscript.vdf" "FileProperties" { "LocalPath" "bin\setup.cfg" "Attributes" "userconfig" // questo file verrà modificato durante il runtime } }

NOTA: Puoi chiamare questi script in qualunque modo, ma qui li chiameremo app_build_<AppID> e depot_build_<DepotID> per coerenza. Se sai che andrai a creare applicazioni su questo computer, potrebbe essere una buona idea creare sottodirectory per ogni applicazione nella tua directory degli script, in modo da organizzare gli script per le build di ogni applicazione.

Gestione degli aggiornamenti

Dopo il rilascio della tua applicazione, i clienti riceveranno la build contrassegnata come Predefinita. Quando si carica una nuova build, è sempre una buona idea testarla prima di renderla disponibile ai clienti. Per maggiori informazioni su come testarla, vedi: Testare su Steam.

Risoluzione dei problemi delle build

Se la build non ha avuto esito positivo, recupera le informazioni sugli errori nella cartella di output, non nella console usata per eseguire lo script della build. La maggior parte delle informazioni sugli errori può essere trovata nei file *.log.
Puoi usare questi comandi del client di Steam e i file dal lato client per indagare sugli errori:
  • "app_status [appid]": mostra lo stato corrente dell'applicazione su questo client.
  • "app_info_print [appid]": mostra la configurazione corrente di Steamworks per questo gioco (depot, opzioni di lancio, ecc.).
  • "app_config_print [appid]": mostra la configurazione corrente dell'utente per questo gioco (lingua, directory di installazione, ecc.).
  • file "logs\content_log.txt" - Elenca tutte le operazioni e gli errori registrati da SteamPipe.
  • file "steamapps\appmanifest_[appid].acf": mostra lo stato di installazione corrente di questa applicazione (KeyValues).

Creazione di dischi di installazione per il commercio al dettaglio

Per creare dischi di installazione per il commercio al dettaglio per i giochi di SteamPipe, dovrai prima configurare un file di progetto della build.
In questo esempio, il file SKU è chiamato "sku_goldmaster.txt":
"sku" { "name" "Test Game Installer" "appid" "202930" "disk_size_mb" "640" "included_depots" { "1" "202931" "2" "202932" } }
Alcuni suggerimenti da tenere a mente:
  • Crea una nuova cartella dove saranno scritte le immagini del disco, ad esempio "D:\retail_disks". Vengono aggiunti solo i depot contenuti nelle sezioni included_depots. Non è più presente una sezione per quelli esclusi.
  • Puoi utilizzare Steam.exe (con i parametri -dev e -console) o steamcmd.exe per creare immagini dello strumento di installazione. In entrambi i casi, usa il comando "build_installer".
  • Accedi a Steam con un account che possiede il gioco e tutti i depot che vuoi includere sul disco. L'account non richiede ulteriori permessi e tutti possono creare dischi di installazione.
  • Se utilizzi Steam.exe, ferma tutti gli altri download.
  • Vai alla pagina della console ed esegui il comando build_installer:
    build_installer sku_goldmaster.txt "D:\retail_disks"
    La build può impiegare del tempo, poiché la prima volta tutti i depot sono scaricati nuovamente.
  • Sei stai creando un GM utilizzando un server di contenuti locale, esegui:
    @localcontentserver "webserver"
    build_installer sku_goldmaster.txt "D:\retail_disks" local
    Il testo nella console fa riferimento a "backup", dato che il disco di installazione e i backup locali del gioco sono praticamente identici.
  • Le immagini del disco saranno pronte quando vedrai "backup finished for AppID". Maggiori informazioni sulla build di backup sono disponibili nel file logs\backup_log.txt.
  • In "D:\retail_disks" sono presenti delle nuove cartelle (Disk_1, Disk_2, eccetera), ognuna non più grande di 640 MB, come specificato con "disk_size_mb". Ogni cartella del disco contiene un file "sku.sis", nonché un .csd e un .csm per ogni depot. I depot più grandi occuperanno diversi dischi. Tutti contenuti dei dischi di installazione sono codificati (al contrario dei file di backup locali). Copia i file di installazione del GM dell'SDK (setup.exe, setup.in, ecc.) nella cartella del tuo primo disco e lo strumento di installazione del disco sarà completato.
  • Quando crei un GM per macOS, assicurati di aprire l'immagine goldmaster/disk_assets/SteamRetailInstaller.dmg su un Mac. Quindi, seleziona l'applicazione in esso contenuta e copiala nella radice del tuo supporto. Vorrai probabilmente cambiare il nome dell'applicazione di installazione, includere un logo nell'icona e decorare la finestra per mostrare solo lo strumento di installazione.
  • Quando crei un GM con più dischi per macOS, assicurati che i nomi del volume di ogni disco combacino. Il nome del volume diventa parte del percorso di montaggio e se i nomi non combaciano lo strumento di installazione non sarà in grado di trovare il disco successivo.

Creazione opzionale di uno strumento di installazione al dettaglio da un ramo beta

Il processo appena spiegato creerà uno strumento di installazione al dettaglio basato sul ramo predefinito. Se ne devi creare uno basato su un ramo beta, dovrai prima creare un ramo beta chiamato "baseline". Quindi, usa il seguente comando per creare lo strumento dal ramo baseline:
build_installer <project file> <target folder> <beta key> <beta pwd> steamcmd ex: build_installer sku_goldmaster.txt "D:\retail_disks" baseline superSecret script ex: steamcmd.exe +login user_name password +build_installer "..\Build\GameDataSku.txt" c:\destination beta_key beta_password +exit

Installazione di DLC da uno strumento di installazione su disco

In alcune circostanze, potresti voler creare uno strumento di installazione per il commercio al dettaglio che includa i tuoi pacchetti DLC. In questi casi, il processo di creazione del programma di installazione richiede solo alcune modifiche.
In "sku_goldmaster.txt", includi l'appID del DLC sotto "included_depots" la sezione. Una volta eseguito il processo "build_installer", trova il file sku.sis che è stato generato per lo strumento di installazione e aprilo con un editor di testo.
Aggiungi l'appID del DLC alla sezione "apps". Ad esempio, per un gioco il cui appID è 1000 e l'appID del DLC è 1010, la sezione "apps" va modificata così:
"apps" { "0" "1000" "1" "1010" }
Ciò garantirà che Steam verifichi la proprietà del DLC e chieda all'utente un codice da immettere se il DLC non è di proprietà dell'account che ha effettuato l'accesso a Steam.

Creazione di uno strumento di installazione al dettaglio per AppID multipli su di un singolo disco/pacchetto di installazione

Per creare un GM contenente applicazioni multiple di SteamPipe, crea separatamente ciascuno strumento di installazione dell'applicazione, ma indica per tutti la stessa cartella di output. Ogni build si unirà da sola all'immagine di installazione già esistente.

Personalizzare un disco di installazione al dettaglio

Vedi Personalizzazione di un gold master per maggiori dettagli sulla personalizzazione del tuo disco di installazione per il commercio al dettaglio.

Prescaricamento dei giochi prima del rilascio

Per impostazione predefinita, tutti i contenuti presenti sui dischi di installazione e sui server dei contenuti sono sempre crittografati. Abilitare il prescaricamento di un gioco significa che il proprietario può scaricarne i contenuti, che però rimarranno crittografati sul computer dell'utente e non potranno essere usati. Una volta che il gioco viene ufficialmente pubblicato, Steam decodificherà i contenuti prescaricati e l'utente potrà giocare.

Abilitare il gioco al prescaricamento è consigliato nei seguenti casi:
  • Invio di dischi al dettaglio con codici prodotto prima che il gioco sia effettivamente disponibile (pirateria del giorno zero).
  • Giochi offerti in preacquisto dalle dimensioni superiori a 20 GB.

Se ritieni che il tuo gioco necessiti del prescaricamento, invia un ticket di assistenza agli editori di Steam.

Creazione di DLC

I DLC sono strutturati come un depot del gioco di base. Per maggiori informazioni, vedi: Contenuti scaricabili (DLC).

Risoluzione dei problemi di SteamPipe

"Login Failure: Account Logon Denied Failed" (errore di accesso: errore con l'accesso negato all'account), quando si effettua l'accesso tramite steamcmd

Causa: SteamGuard sta probabilmente impedendo l'accesso. Risoluzione:
  • L'indirizzo e-mail associato all'account con cui stai cercando di effettuare l'accesso riceverà un'e-mail dall'Assistenza di Steam. Copia il codice contenuto nell'e-mail.
  • Esegui il seguente steamcmd: set_steam_guard_code <code>
  • Effettua di nuovo l'accesso tramite steamcmd: Steam>login <buildaccount> <password>

Risoluzione generale di problemi con il download

  • Riavvia il computer, il modem, il router, ecc.
  • Verifica le impostazioni del firewall. Il nuovo sistema richiede la porta 80 (HTTP) in aggiunta alle altre porte utilizzate da Steam, elencate qui.
  • Disabilita temporaneamente i programmi antivirus o antispam installati localmente.
  • Verifica la regione di download di Steam in Impostazioni->Download. La regione dovrebbe corrispondere a dove ti trovi.
  • Interrompi il download, disinstalla e reinstalla il gioco (svuota la cache del manifesto).
  • Esci da Steam ed elimina le due cartelle appcache e depotcache dalla tua cartella di installazione di Steam.
  • Prova a impostare la regione di download di Steam a una località lontana. Potrebbe funzionare se il server dei contenuti vicino alla tua località sta distribuendo dati difettosi.

Le mie build per Mac e/o Linux non stanno installando file. Perché?

Se stai testando su Steam l'installazione del tuo gioco su più piattaforme, potrebbero verificarsi situazioni in cui la build viene installata su Windows ma non su Mac o Linux, nonostante il processo di SteamPipe sia stato configurato per caricare depot di Mac e Linux. Uno dei passaggi viene spesso saltato e consiste nell'aggiungere i tuoi depot alternativi al pacchetto di installazione. Puoi verificare quali depot sono inclusi in un pacchetto seguendo questi passaggi:
  1. Vai alla tua pagina di amministrazione dell'app
  2. Dalla sezione "Mostra gli elementi associati", clicca su Tutti i pacchetti, DLC, demo e strumenti associati.
  3. Fai clic sul titolo del pacchetto che stai cercando di scaricare
  4. Controlla la sezione Depot inclusi
  5. Utilizza il pulsante Aggiungi/rimuovi depot per assicurarti che l'insieme corretto di depot sia assegnato al pacchetto
Vi sono anche diverse discussioni su questo argomento che potrebbero aiutarti:

Eseguire steamcmd.exe ricevo risulta nel seguente errore: "SteamUpdater: Error: Steam needs to be online to update. Please confirm your network connection and try again." (Per eseguire l'aggiornamento, Steam deve essere online. Verifica la connessione alla rete e riprova)

Risoluzione: vai su Opzioni internet->,Connessioni->,Impostazioni Lan e fai clic su Rileva impostazioni automaticamente.

Eseguire la build dell'app risulta nel seguente errore: "ERROR! Failed 'DepotBuild for scriptname.vdf' - status = 6." (ERRORE! "DepotBuild for scriptname.vdf" fallito - stato = 6)

Possibili cause:
  • L'account non ha i permessi per l'applicazione.
    • Verifica che l'appID sia corretto in app_build.vdf.
    • Verifica che l'account della build abbia i permessi necessari per l'appID.
  • Steamcmd non riesce a trovare i contenuti del depot.
    • Verifica che il valore "contentroot" nello script app_build sia un percorso valido in relazione a dove si trova il file dello script.
    • Verifica che il valore "LocalPath" nello script depot_build sia un percorso valido in relazione a dove si trova lo script app_build. Verifica che il percorso presenti contenuti al suo interno.

Eseguire la build dell'app risulta nel seguente errore: "ERROR! Failed to get application info for app NNNNN (check login and subscription)" (ERRORE! Impossibile recuperare le informazioni dell'applicazione per l'app NNNNN (controlla l'accesso e la sottoscrizione)

Questo errore significa che Steam non è in grado di recuperare informazioni sull'applicazione, perché l'applicazione non esiste o perché l'utente non vi ha accesso.
  • Verifica che l'NNNNN sia l'appID che ti è stato assegnato per l'applicazione.
  • Verifica che l'appID sia corretto in app_build.vdf.
  • Se si tratta di un nuovo appID, verifica che la configurazione dell'amministrazione dell'applicazione di Steamworks sia stata pubblicata. Le nuove applicazioni dovrebbero avere una directory di installazione di SteamPipe nella scheda Configurazione, un depot nella scheda Depot e tutti i cambiamenti pubblicati nella scheda Pubblica.
  • Se tutte le informazioni ti sembrano corrette, assicurati che il tuo account sia in possesso dell'appID.

Al momento del lancio, "An error occurred while installing [AppName] (Invalid content configuration)" (si è verificato un errore nell'installazione di [AppName] - configurazione dei contenuti non valida)

Possibili cause:
  • Non è stata impostata una build funzionante sul ramo da cui stai cercando di installare.
    Risoluzione: imposta una build su un ramo attraverso https://partner.steamgames.com/apps/builds/<YourGameAppId> e seleziona quel ramo nel client di Steam (come descritto qui).
  • Opzioni di lancio non valide.
    Risoluzione: verifica le opzioni di lancio nella scheda Installazione dell'amministratore dell'applicazione del tuo gioco https://partner.steamgames.com/apps/config/<YourGameAppId>.
  • Non sei in possesso degli ID del depot che costituiscono il gioco.
    Risoluzione: assicurati che i depot necessari vengano aggiunti alla sottoscrizione della fase di sviluppo (vedi Modificare i pacchetti per ulteriori dettagli).

Al momento del lancio si verifica l'errore "Error code 15"

Si tratta dei server CEG che rifiutano la richiesta di CEG per l'eseguibile. Verifica lo stato di rilascio sulla pagina del gioco. Se non è "giocabile", dovrai richiedere dei codici di Steam per ignorare lo stato di rilascio.

Al momento del lancio si verifica l'errore "The Steam Servers are too busy to handle your request... Error Code (2)" (I server di Steam sono troppo impegnati per gestire la tua richiesta... codice errore (2)

Si tratta dei server CEG che non riescono a trovare un eseguibile CEG corrispondente. Verifica di avere un eseguibile CEG funzionante nella scheda CEG del tuo amministratore dell'app. Clicca sul pulsante "stato" per essere sicuro che sia pronto.

Non ricordo il nome o la funzione di un comando steamcmd

Utilizza il comando "find" su steamcmd per cercare tutti i comandi steamcmd. Verranno trovate corrispondenze parziali del nome del comando e ne sarà elencata la sintassi.
Steam>find build_installer ConVars: Commands: build_installer : <project file> <target folder> <beta key> <beta pwd>