Skip to content
Snippets Groups Projects

Document the Steam compatibility tool interface

Merged Simon McVittie requested to merge wip/smcv/document-compat-tools into master
@@ -32,7 +32,7 @@ Each compatibility tool can have these fields:
necessary files, for example
`/path/to/steamapps/common/Proton - Experimental` for Proton
`display-name`
`display_name`
: Name to display in the Steam user interface
`from_oslist`
@@ -45,8 +45,8 @@ Each compatibility tool can have these fields:
For the compatibility tools provided by Steam itself, such as
Steam Linux Runtime and Proton, the equivalent of this information is
downloaded out-of-band, so the depot downloaded into the Steam library
will not contain this file.
downloaded out-of-band and stored in `~/.steam/root/appcache/appinfo.vdf`,
so the depot downloaded into the Steam library will not contain this file.
Third-party compatibility tools can be installed in various locations
such as `~/.steam/root/compatibilitytools.d`.
@@ -117,9 +117,50 @@ is built up by taking the required tool, then appending the tool that
requires it, and finally appending the actual game: so if a compat tool
named `Inner` requires a compat tool named `Outer`, and both tools have
`/run %verb% --` as their `commandline`, then the final command line will
look something like:
look something like this:
/path/to/Outer/run waitforexitandrun -- /path/to/Inner/run waitforexitandrun -- /path/to/game.exe
/path/to/Outer/run waitforexitandrun -- \
/path/to/Inner/run waitforexitandrun -- \
/path/to/game.exe
(In reality it would all be one line, rather than having escaped newlines
as shown here.)
## Launch options
If a Steam game has user-specified launch options configured in its
Properties, and they contain the special token `%command%`, then
`%command% is replaced by the entire command-line built up from the
compatibility tools. For example, if a compat tool named `Inner` requires
a compat tool named `Outer`, both tools have `/run %verb% --` as their
`commandline`, and the user has set the Launch Options in the game's
properties to
DEBUG=yes taskset --cpu-list 0,2 %command% -console
then the final command line will look something like this:
DEBUG=yes taskset --cpu-list 0,2 \
/path/to/Outer/run waitforexitandrun -- \
/path/to/Inner/run waitforexitandrun -- \
/path/to/game.exe -console
(In reality it would all be one line, rather than having escaped newlines
as shown here.)
If the user-specified launch options for a Steam game do not contain
`%command%`, then they are simply appended to the command-line. For
example, setting the launch options to `--debug` is equivalent to
`%command% --debug`.
Shortcuts for non-Steam games do not currently implement the special
handling for `%command%`: the configured launch options are simply
appended to the command-line, regardless of whether they contain
`%command%` or not.
Please note that not all invocations of compatibility tools take the
user-specified launch options into account: they are used when running
the actual game, but they are not used for install scripts.
## Environment
@@ -196,12 +237,14 @@ pointing to mixed host and soldier libraries.
This is the simplest situation and can be considered to be the baseline.
In recent versions of Steam, the game process is wrapped in a `reaper`
process which sets itself as a subreaper using **PR_SET_CHILD_SUBREAPER**
(see **prctl**(2) for details).
process which sets itself as a subreaper using `PR_SET_CHILD_SUBREAPER`
(see
[**prctl**(2)](https://manpages.debian.org/unstable/manpages-dev/prctl.2.en.html)
for details).
Version 1 compat tools are not invoked specially.
Version 2 compat tools are invoked with a `%verb% in the `commandline`
Version 2 compat tools are invoked with a `%verb%` in the `commandline`
(if any) replaced by `waitforexitandrun`.
The game is expected to run in the usual way. Conventionally, it does not
@@ -219,13 +262,15 @@ The environment variable `STEAM_COMPAT_SESSION_ID` is not set.
The environment variable `STEAM_COMPAT_APP_ID` is set to the app-ID
of the game. The environment variable `SteamAppId` has the same value.
The [launch options](#launch-options) are used.
## Windows games with no install script
Some Windows games, such as Soldat (638490), do not have an
"install script" in their metadata. Running these games behaves much the
same as a native Linux game: it is wrapped in a subreaper, version 1
compat tools are not invoked specially, and version 2 compat tools
are invoked with a `%verb% in the `commandline` (if any) replaced by
are invoked with a `%verb%` in the `commandline` (if any) replaced by
`waitforexitandrun`.
The environment variable `STEAM_COMPAT_SESSION_ID` is not set.
@@ -238,9 +283,11 @@ of the game. The environment variable `SteamAppId` has the same value.
The current working directory is the working directory configured in the
game's Steam metadata, as usual.
The [launch options](#launch-options) are used.
## Windows games with an install script (since Steam beta 1623823138)
Other Windows games, such as Everquest (...), have an
Other Windows games, such as Everquest (205710), have an
[install script](https://partner.steamgames.com/doc/sdk/installscripts),
conventionally named `installscript.vdf`, which must be run by an
interpreter.
@@ -265,6 +312,8 @@ Since Steam beta 1623823138, these games are run like this:
(usually `~/.local/share/Steam` or `~/.steam/debian-installation`)
but this is probably not guaranteed.
The [launch options](#launch-options) are **not** used here.
* Run the actual game in the usual way.
The environment variable `STEAM_COMPAT_SESSION_ID` is not set.
@@ -275,6 +324,8 @@ Since Steam beta 1623823138, these games are run like this:
The current working directory is the working directory configured in
the game's Steam metadata, as usual.
The [launch options](#launch-options) are used, as usual.
## Historical behaviour of Windows games (session mode v2)
Before Steam beta 1623823138, each Windows game had several setup commands
@@ -299,6 +350,8 @@ to run before it could be launched. They were invoked like this:
(usually `~/.local/share/Steam` or `~/.steam/debian-installation`)
but this is probably not guaranteed.
The [launch options](#launch-options) are **not** used here.
The compat tool is expected to do any setup that it needs to do
(for example pressure-vessel must start a container), then run
the given command and exit. The compat tool may leave processes
@@ -328,18 +381,20 @@ to run before it could be launched. They were invoked like this:
The environment variables `STEAM_COMPAT_APP_ID` and `SteamAppId`
are both set to the app-ID of the game as usual.
The [launch options](#launch-options) are used, as usual.
## Non-Steam games
Version 1 compat tools are not invoked specially.
Version 2 compat tools are invoked with a `%verb% in the `commandline`
Version 2 compat tools are invoked with a `%verb%` in the `commandline`
(if any) replaced by `waitforexitandrun`.
The environment variable `STEAM_COMPAT_SESSION_ID` is not set.
Historically, it was set to a unique token that was not used in any
previous invocation.
`STEAM_COMPAT_APP_ID` is set to `0`.
`STEAM_COMPAT_APP_ID` is set to `0`. `SteamAppId` is not set.
`STEAM_COMPAT_DATA_PATH` is set to a unique directory per non-Steam game.
It is currently in the same format as Steam games' equivalent directories,
@@ -357,3 +412,6 @@ The current working directory defaults to the directory containing the
main executable, but can be reconfigured through the shortcut's properties.
Steam Linux Runtime (pressure-vessel) containers will not work as expected
unless this is set to the game's top-level directory.
Launch options are appended to the command-line. The special token
`%command%` in Steam games' launch options is not used here.
Loading