Overview
While Steam can automatically install many
common redistributables, your application may have other first-run requirements.
NOTE: Install script functionality described below is primarily for Windows operating systems. MacOS support is limited to file permissions and symlinks. There is no Linux/SteamOS install script functionality at this time.
An install script file is a configuration file that lets you run certain actions upon installation.
Full games/applications and DLC packages may both have install scripts. If you
integrate your install scripts into your build, you may have any number of install scripts. For a SteamPlay app, it's recommended that you always use your OS-specific depots to contain your install scripts.
Example
A basic one will look like this:
"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"
}
}
}
The second keyname after the root describes what kind of action will take place.
Note: All keynames and values can use escape sequences, so if you use a
\
, make it a
\\
.
Integrating Install Scripts into Your Build
First, the install script file must be part of a depot that is installed with the build. Ensure that the file resides within the defined ContentRoot of the App or Depot.
Second, mark an install script using the
InstallScript
directive in a depot build script. You can see an example on the
Uploading to Steam - Advanced Build Scripts page.
During the build process, two things take place:
- The install script is uploaded to Steam and cryptographically signed. This signature is validated by Steam before executing any install script, and is required to perform certain operations, including writing to the HKLM hive on Windows. This may cause your local copy of the install script to be modified.
- The install script is marked in the depot manifest. You can see this in the generated
manifest.txt
file as a 100
in the Flags
field.
When a Steam user is starting a game, Steam will scan all of the mounted depots for that game for any file with the install script flag and run them.
Registry
The Registry command allows you to create or modify string and dword registry values. Any key under the "Registry" keyname will be treated as the full path to the registry key you want to create or open. Under that key, specify either a "string" or "dword" key. Any keynames and values stored in the "string" or "dword" keys will be the registry names and values that get set.
To set the
default value for a registry key, you should enter the key name as
(Default)
.
Run Process
The Run Process command allows your application to run programs before the user first launches your game.
To determine whether the program needs to run, the install script looks at the keyname (as a registry DWORD value) in the HasRunKey value. If that value is not present or 0, then it will call CreateProcess on the processXX/commandXX values. If CreateProcess fails, then ShellExecuteEx is called. If the program's ExitCode is 0, then the install script assumes it was successful and writes your keyname as 1 in the registry.
Steam customers love a quick and silent install. Add silent or quiet parameters to all run process commands and only add what you absolutely need for the game.
The required Run Process key/values are:
- Process 1 - Path to the program you want to launch
The optional Run Process key/values are:
- 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 Requirements 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.
Firewall Exceptions
If your game uses any networking, use the firewall exception to grant the firewall exception in windows automatically without forcing the user to accept the exception.
"Firewall"
{
"Space War Game" "%INSTALLDIR%\\SpaceWar.exe"
}
OS Specific Requirements
The Requirement_OS value is available to run different installs on different OS versions / SKUs. It requires a new key group called Requirement_OS, then additional key value pairs inside. Available OS options are listed below.
- Is64BitWindows - Specifies that the process will only run on a 64 bit version of the operating system. Values are 1 or 0.
- OSType - Specifies that the process will only run on a specific version of the operating system. Values are:
- 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 ExampleThis example will run the appropriate installer for the 32 or 64 bit installer.
"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"
}
}
OS Type ExampleThis example will only run on Windows XP
"Controller"
{
"Process 1" "%INSTALLDIR%\\redist\\WinXPInstaller.exe"
"NoCleanUp" "1"
"Requirement_OS"
{
"OSType" "Windows XP"
}
}
Environment Variables
Environment variables are supported in an install script. All of the
standard environment variables available on Windows can be used, along with a few others specific to an install script. They are:
- %INSTALLDIR% - The full path to where the application is installed, without a backslash.
- %ROOTDRIVE% - The drive letter to where the application is installed, like
C
- %APPDATA% - The \Users\username\AppData\ folder
- %USER_MYDOCS% - Get the user\My Documents folder
- %COMMON_MYDOCS% - Get the All Users\Documents folder
- %LOCALAPPDATA% - \Documents and Settings\username\Local Settings\Application Data folder (only on Vista and Newer)
- %WinDir% - Windows installation directory
- %STEAMPATH% - The full path to the Steam client install directory.
Note that these are common paths, but they can be different based on what version of Windows the user is running.Language Specific Values
Both string and DWORD values can be assigned different data depending on what language the user is running Steam in. To use, create a subkey in the "string" or "dword" key with the name of the language, then assign the names and values in there. For example:
"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"
}
}
}
}
}
The install script gets the language from Steam's registry key, querying the value "Language". If that value isn't found then "english" is the default.
Uninstallation of an app
When a user deletes or verifies your app from Steam, install scripts will be called to remove any registry values it created. The install script will also remove the value used to determine if a program should execute from
Run Process
, so that it can execute the next time your app runs (unless the
NoCleanUp
flag is set).
Run Process on Uninstall
If you need to run any process at the time your app is uninstalled, add this to the install script. Please do not uninstall common redists such as DirectX, msvc run time, etc, as they are likely to be used by other games. This is only intended for game specific uninstall processes.
NOTE: Run Process On Uninstall will also be called when a user verifies the app in Steam. Do not run a process that will delete all files, as this will cause Steam to redownload everything during a verify.
"InstallScript"
{
"Run Process On Uninstall"
{
"Process_name"
{
"Process 1" "process.exe"
"Command 1" "/command"
}
}
}
Frequently Asked Questions
Q. Why does my install script keep running my redistributable every time I launch the game?A. This typically means that the redist is returning a non-zero return code. Steam checks that the return code is zero. If it sees that the return code is zero, it marks the redist as installed and doesn't run it again. If it returns any other value, Steam will attempt to run it again on next launch.
To fix this examine your redistributable paths and parameters. Some redists will return non-zero values if they already exist on the machine. This can often be fixed by using the redist's silent or quiet flag.
Q. Why doesn't my registry key get written?A. Typically this is because the install script isn't signed and you're writing to HKLM.
See the section on
build integration, and ensure that a
"kvsignatures"
key was added to your script during the build, as Steam requires this signing to be completed to write to HKLM.
This can also be caused by the Windows 64 bit virtualization on 64 bit Windows, Steam writes to the
Wow6432Node path in the registry.
Q. Why doesn't my install script seem to run at all?A. Please double check that your configuration is properly prepared.
Q. How do I add macOS redistributables? Why doesn't Run Process work in my macOS install script?A. We don't currently have support for installing Mac redistributables. You will need to put the installer into your main executable.