Documentazione di Steamworks
Creazione e utilizzo degli script di installazione

Introduzione

Steam è in grado di installare automaticamente molti ridistribuibili comuni, ma la tua applicazione potrebbe presentare dei requisiti diversi per il primo avvio.
NOTA: la funzionalità dello script di installazione descritta qui sotto è intesa principalmente per i sistemi operativi Windows. Il supporto a MacOS è limitato ai permessi dei file e a ai collegamenti simbolici. Al momento, la funzionalità dello script di installazione non è disponibile su Linux/SteamOS.

Uno script di installazione è un file di configurazione che permette di eseguire certe azioni al momento dell'installazione.

I giochi, le applicazioni e i pacchetti DLC possono tutti avere script di installazione. Se decidi di integrare i tuoi script di installazione nella tua build, ne puoi integrare quanti ne vuoi. Per un'applicazione di SteamPlay, consigliamo di usare sempre i tuoi depot specifici per sistema operativo per contenere gli script di installazione.

Esempio

Uno script basico avrà questo aspetto:
"InstallScript" { "Registry" { "HKEY_LOCAL_MACHINE\\SOFTWARE\\Foo\\Bar" { "string" { "Install_Path" "%INSTALLDIR%" "Exe_Path" "%INSTALLDIR%\\foobar.exe" } "dword" { "PatchVersion" "12" } } } "Run Process" { "DirectX" { "HasRunKey" "HKEY_LOCAL_MACHINE\\Software\\Valve\\Steam\\Apps\\480" "Process 1" "%INSTALLDIR%\\DirectX\\DXSETUP.exe" "Command 1" "/silent" "NoCleanUp" "1" } } }

Il secondo nome della chiave dopo la radice descrive il tipo di azione che avverrà.

Nota: tutti i nomi delle chiavi e tutti i valori possono usare sequenze di escape, quindi se usi uno\, rendilo uno \\.

Integrazione degli script di installazione nella tua build

Innanzitutto, il file dello script di installazione deve fare parte di un depot installato con la build. Assicurati che il file risieda all'interno del ContentRoot definito dell'app o del depot.

In secondo luogo, contrassegna uno script di installazione con la direttiva InstallScript in uno script della build del depot. Un esempio è disponibile alla pagina Caricamento su Steam - regole avanzate per la mappatura dei file.

Durante il processo della build, avvengono due cose:
  • Lo script di installazione viene caricato su Steam e firmato in maniera crittografata. La firma è validata da Steam prima che gli script di installazione vengano eseguiti ed è richiesta per eseguire certe operazioni, tra cui la scrittura all'hive HKLM su Windows. Ciò potrebbe causare modifiche alla copia locale del tuo script di installazione.
  • Lo script di installazione è contrassegnato nel depot del manifesto e puoi vederlo come un 100 nel campo Flags del file generato manifest.txt.
All'avvio di un gioco da parte di un utente di Steam, Steam scansionerà tutti i depot montati per quel gioco alla ricerca di file contrassegnati come script di installazione e li eseguirà.

Registry

Il comando Registry consente di creare o modificare i valori di registro delle stringhe e delle dword. Qualunque chiave sotto il nome "Registry" sarà trattata come il percorso completo al registro della chiave che vuoi creare o aprire. Sotto quella chiave, specifica una chiave "string" o "dword". Tutti i nomi delle chiavi e i valori conservati nelle chiavi "string" o "dword" saranno i nomi di registro e i valori che verranno impostati.
Per impostare il valore predefinito per una chiave di registro, il nome della chiave dovrebbe essere (Default).

Run Process

Il comando Run Process consente alla tua applicazione di eseguire dei programmi prima che l'utente lanci il gioco per la prima volta.
Per determinare se il programma debba essere eseguito, lo script di installazione controlla il nome della chiave (sotto forma di valore di registro DWORD) nel valore HasRunKey. Se il valore non è presente o se è 0, chiamerà CreateProcess sui valori di processXX/commandXX. Se CreateProcess fallisce, sarà chiamato ShellExecuteEx. Se l'ExitCode del programma è 0, lo script di installazione lo considererà riuscito e scriverà 1 per il nome della chiave del registro.

Ai clienti di Steam piacciono le installazioni veloci e silenziose. Aggiungi parametri silenziosi o poco rumorosi a tutti i comandi dei processi da eseguire e aggiungi solamente gli elementi assolutamente necessari per il gioco.
Le coppie chiave/valore richieste per Run Process sono:
  • Process 1 - percorso del programma che vuoi lanciare
Le coppie chiave/valore opzionali per Run Process sono:
  • Command 1 - comando opzionale che vuoi passare al programma
  • HasRunKey - chiave di registro opzionale per verificare che i prerequisiti siano già installati
  • NoCleanUp - contrassegno opzionale che, quando impostato, fa sì che lo script di installazione non elimini il nome della chiave quando la tua app è eliminata da Steam
  • MinimumHasRunValue - opzionale, imposta il valore minimo che lo script di installazione dovrebbe cercare quando determina di lanciare il programma
  • Requirement_OS - chiave opzionale per applicare requisiti dell'OS. Vedi ridistribuibili specifici per OS per ulteriori dettagli
  • AsCurrentUser - contrassegno opzionale da impostare su 1 se è importante che il programma venga eseguito come utente attuale. In caso contrario, il client di Steam potrebbe eseguirlo come amministratore per evitare messaggi di elevazione in modalità Big Picture o ambienti VR.

Eccezioni del firewall

Se il tuo gioco fa uso della rete internet, utilizza l'eccezione del firewall per garantirne il funzionamento automatico su Windows senza che l'utente debba dare il consenso.
"Firewall" { "Space War Game" "%INSTALLDIR%\\SpaceWar.exe" }

Ridistribuibili specifici per OS

Il valore Requirement_OS è disponibile per eseguire installazioni diverse su versioni diverse di sistemi operativi e SKU. Richiede un nuovo gruppo di chiavi chiamato Requirement_OS contenente coppie di valori delle chiavi addizionali. Le opzioni disponibili per i vari sistemi operativi sono elencate in basso.
  • Is64BitWindows - specifica che il processo sarà eseguito solamente su una versione a 64 bit del sistema operativo. I valori sono 1 o 0.
  • OSType - specifica che il processo verrà eseguito solamente su una versione specifica del sistema operativo. I valori sono:
    • Windows 3.11
    • Windows 95
    • Windows 98
    • Windows ME
    • Windows NT
    • Windows 2000
    • Windows XP
    • Windows 2003
    • Windows Vista
    • Windows 7
    • Windows 2008
    • Windows 2012
    • Windows 2012 R2
    • Windows 8
    • Windows 8.1
    • Windows 10

Esempio a 64 bit:
questo esempio eseguirà lo strumento di installazione a 32 o a 64 bit corretto.
"Net32" { "Process 1" "%INSTALLDIR%\\redist\\Controller\\32bitInstaller.exe" "NoCleanUp" "1" "Requirement_OS" { "Is64BitWindows" "0" } } "Net64" { "Process 1" "%INSTALLDIR%\\redist\\Controller\\64bitInstaller.exe" "NoCleanUp" "1" "Requirement_OS" { "Is64BitWindows" "1" } }

Esempio di tipo di OS:
questo esempio funzionerà solo su Windows XP.

"Controller" { "Process 1" "%INSTALLDIR%\\redist\\WinXPInstaller.exe" "NoCleanUp" "1" "Requirement_OS" { "OSType" "Windows XP" } }

Variabili d'ambiente

Le variabili d'ambiente sono supportate in uno script di installazione. Possono essere utilizzate tutte le variabili d'ambienti standard disponibili su Windows, insieme ad alcune altre specifiche di ogni script di installazione. Queste sono:
  • %INSTALLDIR% - il percorso di installazione completo dell'applicazione, senza barra rovesciata.
  • %ROOTDRIVE% - la lettera dell'unità dove è installata l'applicazione, ad esempio C
  • %APPDATA% - la cartella \Documents and Settings\nome utente\Dati applicazione
  • %USER_MYDOCS% - ottiene la cartella utente\I miei documenti
  • %COMMON_MYDOCS% - ottiene la cartella Tutti gli utenti\Documenti
  • %LOCALAPPDATA% - cartella \Documents and Settings\nome utente\Impostazioni locali\Dati applicazioni (solo da Vista in poi)
  • %WinDir% - directory di installazione di Windows
  • %STEAMPATH% - il percorso completo della directory di installazione del client di Steam.

Valori specifici per lingua

Diversi dati possono essere assegnati ai valori sia delle stringhe che DWORD, a seconda della lingua in cui l'utente sta utilizzando Steam. Per l'utilizzo, crea una sottochiave nella chiave "string" o "dword" con il nome della lingua, quindi assegna i nomi e i valori al suo interno. Ad esempio:
"InstallScript" { "Registry" { "HKEY_LOCAL_MACHINE\\SOFTWARE\\MonkeyDime Studios\\Killer Banana Peel" { "dword" { "english" { "Language" "1" } "french" { "Language" "2" } "german" { "Language" "3" } "italian" { "Language" "4" } "spanish" { "Language" "5" } } } } }

Lo script di installazione ottiene la lingua dalla chiave di registro di Steam, consultando il valore "Language". Se il valore non viene trovato, quello predefinito è "english".

Disinstallazione di un'applicazione

Quando un utente elimina o verifica la tua app da Steam, gli script di installazione saranno chiamati per eliminare tutti i valori di registro creati dall'app. Lo script di installazione rimuoverà anche il valore usato per determinare se un programma dovrebbe essere eseguito da Run Process[code-inline], in modo da poterlo eseguire la prossima volta che la tua app viene lanciata (a meno che non sia stato impostato il contrassegno [code-inline]NoCleanUp).

Run Process On Uninstall

Se hai bisogno di eseguire un processo quando la tua app viene disinstallata, aggiungi questo elemento allo script di installazione. Non disinstallare ridistribuibili comuni come DirectX, runtime di msvc, ecc., poiché è probabile che vengano usati anche da altri giochi. Usalo solo per processi di disinstallazione specifici per il tuo gioco.
NOTA: Run Process On Unistall sarà chiamato anche quando un utente verifica l'applicazione su Steam. Non eseguire un processo che eliminerà tutti i file, poiché Steam in quel caso dovrà scaricare nuovamente tutti i file durante una verifica.
"InstallScript" { "Run Process On Uninstall" { "Process_name" { "Process 1" "process.exe" "Command 1" "/command" } } }

Domande frequenti

D: perché il mio script di installazione continua a eseguire il mio ridistribuibile ogni volta che lancio il gioco?
R: di solito significa che il ridistribuibile sta restituendo un codice di ritorno diverso da zero. Steam verifica che il codice di ritorno sia zero. Se lo è, contrassegna il ridistribuibile come installato e non lo esegue nuovamente. Se viene restituito un valore diverso, Steam cercherà di eseguirlo di nuovo al lancio successivo.

Per risolvere questo problema, verifica i percorsi e i parametri del tuo ridistribuibile. Alcuni ridistribuibili restituiranno valori diversi da zero se esistono già su quel computer. Ciò è spesso risolvibile utilizzando i contrassegni "silent" o "quiet" del ridistribuibile.

D: perché la mia chiave di registro non viene scritta?
R: di solito succede perché lo script di installazione non è firmato e stai scrivendo a HKLM.
Vedi la sezione sull'integrazione nella build e assicurati che una chiave "kvsignatures" sia stata aggiunta al tuo script durante la build, poiché Steam richiede che questa firma sia completata prima di scrivere a HKLM.

Questo errore può essere causato dalla virtualizzazione di Windows a 64 bit su Windows a 64 bit, con il quale Steam scrive al percorso di registro Wow6432Node.

D: perché il mio script di installazione non viene eseguito?
R: verifica la corretta preparazione della tua configurazione.

D: come posso aggiungere ridistribuibili per Mac? Perché Run Process non funziona nel mio script di installazione per Mac?
R: al momento, l'installazione di ridistribuibili per Mac non è supportata. Dovrai quindi collocare lo strumento di installazione nel tuo eseguibile principale.
[/code-inline][/code-inline]