Übersicht

Steam kann zwar viele gängige Redistributables automatisch installieren, doch für den ersten Start Ihrer Anwendung können ggf. weitere Anforderungen gelten.
Eine Installationsskript-Datei ist eine Konfigurationsdatei, mit der Sie bei der Installation bestimmte Aktionen ausführen können.

Sowohl vollständige Spiele/Anwendungen als auch DLC-Pakete können Installationsskripts verwenden. Wenn Sie Ihre Installationsskripts in Ihren Build integrieren, können Sie eine beliebige Anzahl von Installationsskripts verwenden. Bei SteamPlay-Anwendungen wird empfohlen, die Installationsskripts stets in die betriebssystemspezifischen Depots einzubetten.

Beispiel

Ein einfaches Installationsskript sieht wie folgt aus:

Der zweite Schlüsselname nach der Root beschreibt die Art der auszuführenden Aktion.

Hinweis: Sie können in allen Schlüsselnamen und Werten Escape-Sequenzen verwenden. Wenn Sie also ein \ verwenden, schreiben Sie es als \\.

Integration der Installationsskripts in Ihren Build

Zunächst muss die Datei des Installationsskripts Teil des Depots sein, das mit dem Build installiert wird. Stellen Sie sicher, dass sich die Datei im definierten ContentRoot der App oder des Depots befindet.

Markieren Sie ein Installationsskript mit der InstallScript-Direktive in einem Skript des Depot-Builds. Ein Beispiel hierfür finden Sie auf der Seite Hochladen auf Steam – Erweiterte Build-Skripts.

Während der Kompilierung finden zwei Vorgänge statt:

• Das Installationsskript wird auf Steam hochgeladen und verschlüsselt signiert. Diese Signatur wird vor der Ausführung jedes Installationsskripts von Steam validiert und ist erforderlich, um bestimmte Operationen durchzuführen, beispielsweise um unter Windows in die HKLM-Struktur zu schreiben. Dies kann dazu führen, dass die lokale Kopie Ihres Installationsskripts geändert wird.
  
• Das Installationsskript wird im Depot-Manifest markiert. Dies erkennen Sie in der generierten manifest.txt-Datei am Wert 100 im Flags-Feld.

Wenn ein Steam-Benutzer ein Spiel startet, durchsucht Steam alle für dieses Spiel eingebundenen Depots nach Dateien mit dem Installationsskript-Flag und führt sie aus.

Registry

Mit dem Registry-Befehl können Sie Zeichenfolgen- oder DWORD-Werte in der Registrierung erstellen oder bearbeiten. Jeder Schlüssel unter dem Schlüsselnamen „Registry“ wird als vollständiger Pfad zu dem Registrierungsschlüssel behandelt, den Sie erstellen oder öffnen möchten. Geben Sie unter diesem Schlüssel entweder einen „String“- oder einen „Dword“-Schlüssel an. Alle in den „String“- oder „Dword“-Schlüsseln angegebenen Schlüsselnamen stehen für die in der Registrierung eingestellten Namen und Werte.
Um den Standardwert für einen Registrierungsschlüssel einzustellen, geben Sie den Schlüsselnamen als (Default) ein.

Prozessstart

Mit dem Befehl „Run Process“ kann Ihre Anwendung Programme ausführen, bevor der Benutzer Ihr Spiel erstmals startet.
Um zu bestimmen, ob das Programm ausgeführt werden muss, liest das Installationsskript im Schlüsselnamen (DWORD-Wert in der Registrierung) den Wert in „HasRunKey“. Wenn dieser Wert nicht vorhanden oder 0 ist, wird CreateProcess für die processXX/commandXX-Werte aufgerufen. Wenn CreateProcess fehlschlägt, wird ShellExecuteEx aufgerufen. Wenn der ExitCode des Programms 0 ist, geht das Installationsskript von einer erfolgreichen Ausführung des Programms aus und setzt den Wert für den Schlüsselnamen in der Registrierung auf 1.

Steam-Kunden bevorzugen eine schnelle und automatische Installation. Fügen Sie allen Run Process-Befehlen die Parameter „silent“ oder „quiet“ hinzu und beschränken Sie sich ansonsten auf das, was absolut erforderlich für Ihr Spiel ist.
Die erforderlichen Schlüssel/Werte für den Prozessstart sind folgende:

• Process 1: Pfad zum Programm, das Sie starten möchten.

Die optionalen Schlüssel/Werte für den Prozessstart sind folgende:

• Command 1: Optionaler Befehl, den Sie an das Programm übergeben möchten.
  
• HasRunKey: Optionaler Registrierungsschlüssel zur Prüfung, ob alle Voraussetzungen installiert wurden.
  
• NoCleanUp: Optionales Flag. Falls gesetzt, löscht das Installationsskript den Schlüsselnamen nicht, wenn Ihre Anwendung aus Steam gelöscht wird.
  
• MinimumHasRunValue: Optional. Stellt den Mindestwert ein, auf den das Installationsskript prüfen soll, um zu bestimmen, ob das Programm gestartet werden soll.
  
• Requirement_OS: Optionaler Schlüssel zur Anwendung von Betriebssystemanforderungen. Weitere Informationen finden Sie in den betriebssystemspezifischen Anforderungen.
  
• AsCurrentUser: (Optional) Flag. Setzen Sie diesen auf 1, wenn es wichtig ist, dass das Programm als aktueller Benutzer läuft. Ansonsten könnte der Steam-Client als Administrator laufen, um Eingabeaufforderungen für erhöhte Rechte im Big Picture-Modus oder in VR-Umgebungen zu vermeiden.

Firewall-Ausnahmen

Wenn Ihr Spiel Netzwerkverbindungen nutzt, verwenden Sie die Firewall-Ausnahme, damit das Spiel automatisch als Ausnahme für die Windows-Firewall hinzugefügt wird, ohne dass der Benutzer dies bestätigen muss.

Betriebssystemspezifische Anforderungen

Der Requirement_OS-Wert ist verfügbar, damit verschiedene Installationen auf verschiedenen Betriebssystemversionen/SKUs ausgeführt werden können. Hierfür ist eine neue Schlüsselgruppe namens Requirement_OS mit zusätzlichem Wert/Schlüssel-Paaren erforderlich. Die verfügbaren Betriebssystemoptionen sind im Folgenden aufgelistet.

• Is64BitWindows – Gibt an, dass der Prozess nur in der 64-Bit-Version des Betriebssystems ausgeführt werden kann. Mögliche Werte sind 1 oder 0.
  
• OSType: Gibt an, dass der Prozess nur in einer bestimmten Version des Betriebssystems ausgeführt werden kann. Mögliche Werte sind:
  
  • 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

64-Bit-Beispiel:
Dieses Beispiel führt das entsprechende Installationsprogramm in der 32-Bit- oder 64-Bit-Version aus.

Betriebssystemtyp-Beispiel:
Dieses Beispiel wird nur unter Windows XP ausgeführt.

Umgebungsvariablen

Umgebungsvariablen werden in einem Installationsskript unterstützt. Sie können alle standardmäßig unter Windows verfügbaren Umgebungsvariablen sowie einige für das Installationsskript spezifische Umgebungsvariablen nutzen. Dies sind folgende:

• %INSTALLDIR%: Der vollständige Pfad, unter dem die Anwendung installiert ist, ohne umgekehrten Schrägstrich.
  
• %ROOTDRIVE%: Der Laufwerksbuchstabe, unter dem die Anwendung installiert ist, zum Beispiel C.
  
• %APPDATA%: Der Ordner „\Users\username\AppData\“
  
• %USER_MYDOCS%: Ruft den Ordner „<Benutzername>\\Meine Dokumente“ ab.
  
• %COMMON_MYDOCS%: Ruft den Ordner „Alle Nutzer\\Dokumente“ ab.
  
• %LOCALAPPDATA%: Ordner „\\Dokumente und Einstellungen\\<Benutzername>\\Lokale Einstellungen\\Anwendungsdaten“ (nur auf Vista und neuer).
  
• %WinDir%: Windows-Installationsverzeichnis.
  
• %STEAMPATH%: Vollständiger Pfad zum Steam-Client-Installationsverzeichnis.

Hinweis: Dies sind übliche Pfade, können sich aber je nach Windows-Version des Nutzers unterscheiden.

Sprachspezifische Werte

Sie können sowohl Zeichenfolge- als auch DWORD-Schlüsseln je nach der Sprache, in der der Benutzer Steam ausführt, unterschiedliche Werte zuweisen. Erstellen Sie hierfür im „String“- oder „DWORD“-Schlüssel einen Unterschlüssel mit dem Namen der Sprache und weisen Sie dort die Namen und Werte zu. Beispiel:

Das Installationsskript ruft die Sprache aus dem Registrierungsschlüssel für Steam ab, indem der Wert „Language“ abgefragt wird. Wenn dieser Wert nicht gefunden wird, wird standardmäßig „english“ verwendet.

Deinstallieren einer App

Wenn ein Benutzer Ihre App aus Steam löscht oder verifiziert, wird das Installationsskript aufgerufen, um alle von ihm erstellten Registrierungsschlüssel zu löschen. Das Installationsskript löscht auch den Wert, mit dem bestimmt wird, ob ein Programm von Run Process ausgeführt werden soll, damit das Installationsskript bei der nächsten Ausführung der Anwendung ausgeführt werden kann (es sei denn, das NoCleanUp-Flag wurde gesetzt).

Run Process on Uninstall

Wenn Sie bei der Deinstallation Ihrer App einen Prozess ausführen müssen, fügen Sie ihn dem Installationsskript hinzu. Deinstallieren Sie keine gängigen Redistributables wie DirectX, msvc-Runtime usw., da diese wahrscheinlich von anderen Spielen verwendet werden. Dieses Verfahren ist lediglich für spielspezifische Deinstallationsprozesse gedacht.
HINWEIS: „Run Process On Uninstall“ wird auch aufgerufen, wenn ein Benutzer die Anwendung in Steam verifiziert. Führen Sie keinen Prozess aus, der alle Dateien löscht, da dies dazu führt, dass Steam während einer Verifizierung alles erneut herunterlädt.

Häufig gestellte Fragen

Frage: Warum führt mein Installationsskript bei jedem Start des Spiels meine Redistributable aus?
Antwort: Dies liegt in der Regel daran, dass die Redistributable einen Rückgabecode zurückgibt, der nicht Null ist. Steam prüft, ob der Rückgabecode Null ist. Wenn der Rückgabecode Null ist, wird die Redistributable als installiert markiert und nicht mehr ausgeführt. Wenn ein anderer Wert zurückgegeben wird, versucht Steam, die Redistributable beim nächsten Start wieder auszuführen.

Um dieses Problem zu beheben, prüfen Sie die Pfade und Parameter der Redistributable. Einige Redistributables geben Werte zurück, die nicht Null sind, obwohl sie bereits auf dem Computer vorhanden sind. Dies können Sie häufig dadurch beheben, dass Sie das Flag „silent“ oder „quiet“ für die Redistributable setzen.

Frage: Warum wird mein Registrierungsschlüssel nicht erstellt?
Antwort: Dies liegt in der Regel daran, dass das Installationsskript nicht signiert ist und Sie nach HKLM schreiben.
Lesen Sie den Abschnitt zur Build-Integration und stellen Sie sicher, dass Ihrem Skript während der Kompilierung ein „kvsignatures“-Schlüssel hinzugefügt wurde. Steam benötigt diese Signatur, damit der Schreibvorgang in HKLM abgeschlossen werden kann.

Eine andere mögliche Ursache ist die Windows 64-Bit-Virtualisierung in 64-Bit-Versionen von Windows, die Steam in der Registrierung in den Pfad Wow6432Node schreibt.

Frage: Warum wird mein Installationsskript anscheinend überhaupt nicht ausgeführt?
Antwort: Überprüfen Sie, ob Ihre Konfiguration ordnungsgemäß vorbereitet ist.

Frage: Wie füge ich Mac-Redistributables hinzu? Warum läuft „Run Process“ in meinem macOS-Installationsskript nicht?
Antwort: Derzeit bieten wir keine Unterstützung für die Installation von Mac-Redistributables. Sie müssen das Installationsprogramm in die ausführbare Datei des Hauptprogramms integrieren.