# Steam launch options

Everything a single game can be given in Steam (game → Properties → General → Launch options). Variables go before
`%command%`, separated by spaces:

    MESA=26.1 XESS=latest %command%

A launch option applies to that game only and takes effect at its next start. No re-login is needed.
`install.sh` sets the system-wide defaults (`~/.config/environment.d/50-xess-xmx.conf`). A launch option overrides
them for one game.

`XESS`, `XESS_LOG`, `FSR`, `FSR_FG` and `OFLOW_FG` need the system-wide install: `install.sh` puts a small `user_settings.py` into every Proton,
which Proton runs before it starts a game (`tools/proton-hook.py`). A `user_settings.py` of your own is kept as
`user_settings.user.py` next to it and still applies. With the per-game install (`enable.sh`) the wrapper comes last,
after the variables (`MESA=26.1 /path/to/xess-xmx-linux/xmx-launch.sh %command%`), and these four are not available:
`XESS=dp4a` and `XESS_LOG=1` have their long variables (debugging.md), `FSR` and `FSR_FG=xess` have
`tools/fsr-fg.sh` ([fsr-frame-generation.md](fsr-frame-generation.md)), `XESS=latest`, `FSR_FG=inject` and `OFLOW_FG` have nothing.

## Driver

| Launch option | What it does | When |
|---|---|---|
| `MESA=26.1 %command%` | this game uses the package's Mesa 26.1.2 driver | a game misbehaves on Mesa 26.3 only (please report it) |
| `MESA=26.3 %command%` | this game uses the package's Mesa 26.3 driver | the default was changed to 26.1 and one game should keep 26.3 |
| `/path/to/package/xmx-stock.sh %command%` | **experimental**: this game runs on the system's own, unpatched Mesa ANV with the package's Vulkan layer `VK_LAYER_XESS_xmx` (`layer/`), which puts the XMX kernels in from outside the driver; the patched driver stays the default for every other game | a distribution whose own Mesa should stay (no patched driver for that game), or testing the layer against the patched driver. The layer knows Mesa 26.1, 26.3 and 27.0 (SteamOS ships 26.1.2); with another version XeSS runs on DP4a |
| `INTEL_DEBUG=no-jay %command%` | Mesa 26.3 compiles the game's own shaders with the old compiler instead of Jay (XeSS is not affected) | a rendering bug or crash that goes away with `MESA=26.1`: tells whether Jay is the cause |

**`xmx-stock.sh`** is a wrapper, not a variable: it has to set the driver list before Steam's runtime container starts
(inside it the list has already been rewritten, and a list changed there loaded two Intel drivers at once). Variables
go before it: `XESS=latest /path/to/package/xmx-stock.sh %command%`. It installs nothing and changes nothing outside the
game's environment. It needs the shim in the game's prefix and the compiler bundle (`igc/`): `install.sh` gives both;
without the system-wide install, `XMX_APPID=<app id> ./enable.sh` puts the shim in and `tools/get-igc.sh` fetches the
compiler (do not combine it with `xmx-launch.sh`, whose file points at the patched driver). What it sets:

* `VK_DRIVER_FILES`: the system's Intel ICDs (`intel_icd.x86_64.json`, then `intel_icd.i686.json`, from
  `/usr/share/vulkan/icd.d` and the loader's other folders), then every other entry of the session's list (other GPUs'
  drivers), without the package's ICD (`run/intel_icd.json`, which `install.sh` puts first). Without a session list:
  every ICD of the system. `XMX_STOCK_ICD=<json>` uses that Intel ICD instead (e.g. a Mesa built by hand);
* `VK_ADD_LAYER_PATH=<package>/layer` and `VK_LOADER_LAYERS_ENABLE=VK_LAYER_XESS_xmx`, added to values already set
  (MangoHud and other layers keep working);
* `XMX_LAYER_HELPER=<package>/tools/cm-compile.sh` and `XMX_IGC_DIR=<package>/igc`, unless already set;
* `VK_EXT_descriptor_buffer` and `VK_KHR_present_wait2` added to `VKD3D_DISABLE_EXTENSIONS`, `force_vk_vendor=0` and
  `INTC_ALT_DRIVER_EXTENSIONS_PATH` as `install.sh` sets them, unless already set. `ANV_CM_KERNEL_DIR` and
  `ANV_CM_HELPER` stay: the stock driver does not read them.

It writes one `xess-xmx: xmx-stock:` line naming the driver and the layer to Steam's output (the terminal Steam was
started from; in Game Mode the user journal), not to `PROTON_LOG`'s file. If the layer files or a 64-bit Intel ICD of
the system are missing, that line says so and the game starts unchanged (on the patched driver after `install.sh`).
`MESA` has no effect with it. The layer's own log: `XMX_LAYER_LOG=1` (stderr) or `XMX_LAYER_LOG=<file>`; its
other switches are in `layer/README.md`.

`MESA` takes a version or a prefix of one (`26.1`, `26.3`, `26.1.2`). An unknown version falls back to the default
driver; the game's stderr then says `xess-xmx: MESA=...: no such driver`. The default for all games is set with
`tools/switch-driver.sh` (no argument: list the drivers, `*` marks the default).

## XeSS

| Launch option | What it does | When |
|---|---|---|
| `XESS=latest %command%` | the game runs with the XeSS libraries of Intel's XeSS SDK (3.0.2: XeSS 2.0.2.68, XeSS-FG 1.3.1.78, XeLL 1.3.2.10) instead of its own older ones | a game with XeSS older than 2.0.2.68 (below), or one whose XeSS is simply old |
| `XESS=dp4a %command%` | XeSS without Intel's extension: super resolution on DP4a, frame generation on its generic path (2x only) | comparing XMX against DP4a, or ruling the XMX path out as the cause of a problem |
| `XESS_FG=3 %command%`, `XESS_FG=4 %command%` | XeSS frame generation produces 3x / 4x (`XESS_FG=2`: 2x), whatever the game's menu offers or chooses; frame generation stays switched on and off in the game | a game that offers only 2x, such as Cyberpunk 2077 |
| `XESS_FG=5` ... `XESS_FG=8 %command%` | 5x to 8x (the maximum): **experimental**, beyond what Intel supports (see below). All work; 7x and 8x not recommended (latency) | a high refresh rate display that 4x does not fill |
| `FSR=xess %command%` | the game's FSR 3.1+ upscaling runs on XeSS super resolution and its FSR frame generation on XeSS frame generation (with `XESS_FG`: multi-frame) | a game with FSR 3.1+ and no XeSS; a game that has XeSS should use it, this route can flicker more ([fsr-frame-generation.md](fsr-frame-generation.md)) |
| `FSR_FG=xess %command%` | only the game's FSR 3.1+ frame generation runs on XeSS frame generation; the game's FSR upscaling stays | as `FSR=xess`, when the game's own FSR upscaling is wanted |
| `FSR=xess FSR_FG=inject %command%` | XeSS frame generation for a game with FSR 3.1+ upscaling and no FSR frame generation, fed from the upscaler; choose FSR upscaling in the game. The HUD is interpolated too ([fsr-frame-generation.md](fsr-frame-generation.md)) | a game whose frame generation is DLSS-G only, such as Forza Horizon 6 |
| `OFLOW_FG=1 %command%` | **experimental**: XeSS frame generation for any DX12 game, with motion vectors from optical flow on the final image instead of the game's; `XESS_FG=<n>` sets the frames shown per rendered frame. The HUD is interpolated too, the rendered frame rate is kept even ([optical-flow-frame-generation.md](optical-flow-frame-generation.md)) | a DX12 game with neither XeSS nor FSR 3.1+, such as Resident Evil 4 (2023) or Viewfinder (`-force-d3d12` after `%command%`) |
| `FSR_VENDOR=amd %command%` | with `FSR` / `FSR_FG`: DXVK reports the GPU as AMD's to the game; XeSS-FG and XeLL still see Intel's | a game that offers FSR only on AMD GPUs, such as Wuthering Waves (which should rather use its own XeSS) |
| `IGDEXT_XELL_FIXCAP=1 %command%` | applies the XeLL frame-cap fix (30 fps with frame generation until the pause menu is opened and closed) in this game | another game shows the Wuthering Waves symptom |
| `IGDEXT_XELL_KEEPCAP=1 %command%` | turns that fix off (it is on for Wuthering Waves only) | the fix is suspected to cause a problem |
| `IGDEXT_XELL_CAP=off %command%` | turns the low latency off (below; it is on by default while XeSS frame generation runs) | comparing, or it is suspected to cost frame rate in a game |
| `IGDEXT_XELL_CAP=auto:<ms> %command%` | low latency with each frame started `<ms>` earlier (later if negative): more frame rate headroom, a little more latency | a game whose frame rate drops with the low latency on |
| `IGDEXT_XELL_CAP=<us> %command%` | instead of the low latency, at least this interval per displayed frame through XeLL's frame cap (up to 1000000; any other value turns both off) | a steady fixed frame rate |

**Low latency with XeSS frame generation** is on by default. A GPU-limited or CPU-limited game queues frames, and the
wait in that queue is most of its latency. While frame generation runs, the shim starts each frame so that it reaches
the GPU when the GPU gets free (after `xellSleep`, from XeLL's own frame reports). Wuthering Waves, Arc B390, 3x,
simulation start to present end: 69 -> 35 ms GPU-limited, 76 -> 48 ms and 105 -> 67 ms CPU-limited, at the same frame
rate. A game without a queue (CONTROL) does not wait, so nothing changes there. It works for a game's own XeSS frame
generation only: with `FSR=xess`, `FSR_FG` and `OFLOW_FG` the package's frame generation DLL reports each present to XeLL
right before the next frame's sleep, so the shim never sees a queue and does not wait. It is off while frame generation is
off; `IGDEXT_XELL_LOG=1` shows its state (`low latency: on`, `auto: frame generation on ...`, `auto: waited in ...`).

**XeSS older than 2.0.2.68:** DXVK reports an Intel GPU as an AMD one to such a game, so XeSS super resolution looks
like DP4a and the game may offer no XeSS frame generation. `XESS=latest` is the way out; why, and why showing the Intel
GPU to the old libraries is not: [games.md](games.md) (Cyberpunk 2077).

**`XESS_FG`** works like the frame generation override of Intel Graphics Software on Windows. When the game creates
XeSS frame generation, `libxess_fg.dll` asks Intel's Control Library (`ControlLib.dll`) for an override of the number
of generated frames and uses it in place of the game's choice. Wine has no Control Library; `install.sh` and
`enable.sh` put a small one of this package into each prefix (`C:\windows\system32\ControlLib.dll`) that answers this
one question from `XESS_FG`. 2x to 4x is the range Intel's override has. The game still needs XeSS frame generation
switched on in its menu, and needs XeSS frame generation 1.2 or newer (with an older one, also `XESS=latest`). In a game
with its own multi-frame choice (Wuthering Waves: 2x/3x/4x), `XESS_FG` takes precedence over the menu's number, as
Intel's override does; switching frame generation off in the game still works.

Above 4x XeSS frame generation ignores the override, so the shim raises the number itself: it hands over 4x, finds where
`libxess_fg.dll` keeps the number by watching it follow a second, probe context, sets the wanted number there and checks
through the public API that the game's context now reports it. If anything does not match, the game keeps 4x. This
changes a value inside Intel's library while it runs, which Intel does not support, so 5x to 8x are **experimental**
(all four tested in Cyberpunk 2077 and Wuthering Waves on an Arc B390). Every step above 4x lowers the real frame rate
and raises the latency, so 7x and 8x are not recommended.

Whatever the multiplier, keep a frame rate limiter on (the game's own, or gamescope's): without one the generated
frames reach the screen unevenly.

With XeSS frame generation on, the game cannot use exclusive fullscreen (XeSS-FG refuses it) and runs borderless; under
gamescope that looks the same.

`XESS=latest` changes the game's files only while it runs: each `libxess.dll`, `libxess_dx11.dll`, `libxess_fg.dll`
and `libxell.dll` in the game's folder that is older than the SDK's is renamed to `<name>.xmx-orig` and replaced by a
link to the SDK's copy in the package (`xess/`, one copy for all games; `install.sh` downloads it from
github.com/intel/xess, `tools/get-xess.sh` again). When the game exits, the originals are back, so Steam updates and
"Verify integrity of game files" see the game as shipped. A file as new as the SDK's or newer is left alone. If the
game was killed so hard that nothing could clean up, the next start of that game (with or without `XESS`) puts the
originals back. The game's stderr (`PROTON_LOG=1`) lists each file with both versions.

## Logs for a bug report

| Launch option | What it writes |
|---|---|
| `XESS_LOG=1 %command%` | in the game's prefix: `C:\igdext_trace.log` (the detected GPU, every extension call, each kernel; no file at all means the shim was not loaded), `C:\igdext_xell.log` (what the game passes to XeLL, the real frame rate, the latency), `C:\igdext_xefg.log` (XeSS frame generation: its own messages, the maximum and the number of generated frames it starts with) and `C:\igcl_stub.log` (the `XESS_FG` override it was given) |
| `PROTON_LOG=1 %command%` | `~/steam-<appid>.log`: Proton's log including the game's stderr (`xess-xmx:` and `ANV CM:` lines). Makes the game slow; only for a report |
| `ANV_CM_DEBUG=1 %command%` | each kernel the driver injects, in the game's stderr (use with `PROTON_LOG=1`) |

The prefix is `~/.local/share/Steam/steamapps/compatdata/<appid>/pfx/drive_c/` (for a game on another drive, the
`steamapps` folder of that library).

## The game sees no Intel GPU

| Launch option | What it does | When |
|---|---|---|
| `force_vk_vendor=-1 %command%` | Mesa's own profile for this game again: the Intel vendor id is hidden | a game that needs Mesa's workaround; XeSS then runs on DP4a. `install.sh` sets `force_vk_vendor=0` for all games (debugging.md) |

A game with XeSS older than 2.0.2.68 does not see the Intel GPU either: `XESS=latest` (XeSS section above).

Every other switch, the tools and the logs outside the game: [debugging.md](debugging.md).