Steamworks-dokumentation
Oprettelse og brug af installationsscripts

Oversigt

Steam kan automatisk installere mange almindelige redistributables, men din applikation kan have andre krav, som skal køres først.
BEMÆRK: Installationsscript-funktionalitet, som er beskrevet nedenfor, er primært for Windows-operativsystemer. MacOS-understøttelse er begrænset til filtilladelser og symlinks. Der er ingen funktion for Linux-/SteamOS-installationsscripts på nuværende tidspunkt.

En installationsscriptfil er en konfigurationsfil, som lader dig køre bestemte handlinger under installation.

Både hele spil/applikationer og DLC-pakker kan have installationsscripts. Hvis du integrerer dine installationsscripts i dit build, kan du have et hvilket som helst antal installationsscripts. For en SteamPlay-app anbefales det, at du altid bruger dine OS-specifikke depoter til at huse dine installationsscripts.

Eksempel

Et grundlæggende installationsscript ser således ud:
"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" } } }

Det andet nøglenavn efter roden beskriver, hvilken slags handling der finder sted.

Bemærk: Alle nøglenavne og værdier kan bruge escape-sekvenser, så hvis du bruger en \, skal det være en \\.

Integrering af installationsscripts i dit build

Først skal installationsscriptfilen være en del af et depot, som er installeret med buildet. Du skal sikre dig, at filen er inden for den definerede ContentRoot for appen eller depotet.

Derefter skal du markere et installationsscript ved at bruge InstallScript-direktivet i et depot-buildscript. Du kan se et eksempel på siden Upload til Steam – avancerede regler om filtilknytning.

To ting finder sted under build-processen:
  • Installationsscriptet uploades til Steam og signeres kryptografisk. Denne signatur bekræftes af Steam, før nogen installationsscripts udføres, og er påkrævet for at udføre bestemte handlinger, inklusive skrivning til HKLM-hive på Windows. Dette kan forårsage, at din lokale kopi af installationsscriptet bliver modificeret.
  • Installationsscriptet er markeret i depotets manifest. Du kan se dette i den genererede manifest.txt-fil som 100 i feltet Flag.
Når en Steam-bruger starter et spil, vil Steam skanne alle de tilsluttede depoter for det pågælgende spil efter filer med et installationsscriptflag og køre dem.

Registry

Registry-kommandoen tillader dig at skabe eller ændre strenge og dword-registreringsdatabaseværdier. Nøgler under "Registry"-nøglenavnet vil blive behandlet som en fuld sti til den registreringsdatabasenøgle, du ønsker at oprette eller åbne. Under den pågældende nøgle skal du specificere enten en "streng" eller "dword"-nøgle. Alle nøglenavne og værdier, som gemmes i "strengen" eller "dword"-nøgler, vil være de registreringsdatabasenavne og -værdier, som bliver indstillet.
For at indstille standardværdien for en registreringsnøgle bør du indtaste nøglenavnet som (Default).

Run Process

Run Process-kommandoen gør det muligt for din applikation at køre programmer, før brugeren starter dit spil.
For at afgøre, om programmet skal køres, kigger installationsscriptet på nøglenavnet (som en DWORD-registreringsdatabaseværdi) i HasRunKey-værdien. Hvis denne værdi ikke er til stede eller er 0, vil den kalde CreateProcess på processXXX/commandXXX-værdierne. Hvis CreateProcess fejler, kaldes ShellExecuteEx. Hvis programmets ExitCode er 0, antager installationsscriptet, at det var succesfuldt, og skriver dit nøglenavn som 1 i registreringsdatabasen.

Steam-kunder elsker en hurtig og stille installering. Tilføj lydløse eller stille parametre for at køre alle proceskommandoer, og tilføj kun, hvad du absolut har brug for til spillet.
De påkrævede Run Process-nøgleværdipar er:
  • Process 1 – Sti til programmet, du gerne vil starte
De valgfri Run Process-nøgleværdipar er:
  • Command 1 - Optional command you want to pass to the program
  • HasRunKey - Optional registry key to check that the prereq is already installed
  • NoCleanUp - Optional flag, when set install script will not delete the keyname when your app is deleted from Steam
  • MinimumHasRunValue - Optional, sets the minimum value the install script should check for when determining to launch the program
  • Requirement_OS - Optional key to apply OS requirements see OS Specific Redists for more details
  • AsCurrentUser - Optional flag, set it to 1 if it's important for that program to run as the current user. Otherwise, the Steam client might run it as Administrator to avoid elevation prompts in Big Picture or VR environments.

Firewallundtagelser

Hvis dit spil bruger netværk, skal du bruge firewallundtagelsen til at foretage en firewallundtagelse i Windows automatisk uden at tvinge brugeren til at acceptere undtagelsen.
"Firewall" { "Space War Game" "%INSTALLDIR%\\SpaceWar.exe" }

OS-specifikke redists

Requirement_OS-værdien kan køre på forskellige installationer på forskellige OS-versioner/SKU'er. Det kræver en ny nøglegruppe kaldet Requirement_OS. Derefter er yderligere nøgleværdier indeni. Tilgængelige OS-muligheder fremgår af listen nedenfor.
  • Is64BitWindows – Angiver, at processen kun vil køre på en 64-bit version af operativsystemet. Værdierne er 1 eller 0.
  • OSType – Angiver, at processen kun vil køre på en specifik version af operativsystemet. Værdierne er:
    • 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

Eksempel på 64-bit
Dette eksempel vil køre det passende installationsprogram for 32- eller 64-bit systemer.
"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" } }

Eksempel på OS-type
Dette eksempel vil kun køre på Windows XP

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

Miljøvariabler

Miljøvariablerne understøttes i et installationsscript. Alle standardmiljøvariablerne, som er tilgængelige på Windows, kan bruges sammen med et par andre, som er specifikke for et installationsscript. De er som følger:
  • %INSTALLDIR% – Den fulde sti til, hvor applikationen er installeret, uden en omvendt skråstreg.
  • %ROOTDRIVE% – Drevbogstavet til, hvor applikationen er installeret, som C
  • %APPDATA% – Mappen \Documents and Settings\\Brugernavn\\Application Data
  • %USER_MYDOCS% – Henter mappen user\Mine dokumenter
  • %COMMON_MYDOCS% – Henter mappen Alle Brugere\Dokumenter
  • %LOCALAPPDATA% – Mappen \Documents and Settings\\Brugernavn\\Application Data (kun på Vista og nyere)
  • %WinDir% – Windows-installationsmappe
  • %STEAMPATH% – Den fulde sti til installationsmappen for Steam-klienten.

Sprogspecifikke værdier

Både strenge og DWORD-værdier kan få tildelt forskellige data afhængigt af, hvilke sprog brugeren kører Steam i. For at bruge dette skal du oprette en undernøgle i "string" eller "dword"-nøglen med navnet på sproget, og derefter skal du tildele navnene og værdierne deri. For eksempel:
"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" } } } } }

Installationsscriptet får sproget fra Steams registreringsdatabasenøgle og forespørger om "Language" for værdien. Hvis denne værdi ikke findes, er "engelsk" standard.

Afinstallering af en app

Når en bruger sletter eller bekræfter din app fra Steam, vil installationsscripts blive kaldet for at fjerne alle registreringsdatabaseværdier, som den oprettede. Installationsscriptet vil også fjerne værdien, som bruges til at afgøre, om et program bør eksekvere fra Run Process[code-inline], så den kan eksekveres næste gang, din app kører (medmindre [code-inline]NoCleanUp-flaget er indstillet).

Run Process ved afinstallering

Hvis du har behov for at køre en proces, når din app afinstalleres, skal du tilføje dette til installationsscriptet. Afinstaller ikke almindelige redistributables såsom DirectX, msvc run time osv., da de sandsynligvis skal bruges af andre spil. Dette er kun beregnet til spilspecifikke afinstalleringsprocesser.
BEMÆRK: Run Process ved afinstallering vil også blive kaldt, når en bruger bekræfter appen i Steam. Kør ikke en proces, som sletter alle filer, da dette vil forårsagde, at Steam vil downloade alt igen under en bekræftelse.
"InstallScript" { "Run Process On Uninstall" { "Process_name" { "Process 1" "process.exe" "Command 1" "/command" } } }

Ofte stillede spørgsmål

Sp. Hvorfor bliver mit installationsscript ved med at køre min redistributable, hver gang jeg starter spillet?
Sv. Dette betyder typisk, at den redistributable-komponenten returnerer en ikke-nul-kode. Steam tjekker, at returkoden er nul. Hvis Steam ser, at returkoden er nul, markerer den redist-komponenten som installeret og kører den ikke igen. Hvis der returneres andre værdier, vil Steam forsøge at køre den igen ved næste opstart.

For at løse dette skal du undersøge dine redistributable stier og parametre. Nogle redistributables returnerer værdier, som ikke er nul, hvis de allerede eksisterer på maskinen. Dette kan ofte løses ved at bruge redistributable-komponentens lydløse eller stille flag.

Sp. Hvorfor skrives min registreringsdatabasenøgle ikke?
Sv. Typisk er dette, fordi installationsscriptet ikke er signeret, og du skriver til HKLM.
Se sektionen om build-integration, og kontrollér, at der blev tilføjet en "kvsignatures"-nøgle til dit script under buildet, da Steam kræver, at signeringen er udført for at skrive til HKLM.

Dette kan også forårsages af Windows 64-bit virtualisering på 64-bit Windows, fordi Steam skriver til Wow6432Node-stien i registreringsdatabasen.

Sp. Hvorfor kører mit installationsscript angiveligt slet ikke?
Sv. Dobbelttjek, at din konfiguration er ordentligt forberedt.

Sp. Hvordan tilføjer jeg Mac-redistributables? Eller hvorfor virker Run Process ikke i mit Mac-installationsscript?
Sv. Vi har i øjeblikket ikke understøttelse af installation af Mac-redistributables. Du skal placere installationsprogrammet i din primære eksekverbare fil.
[/code-inline][/code-inline]