runi-dist/docs/optiscaler.md

OptiScaler providers

Runi exposes two explicit player-facing paths. Runtime managed is recommended when the selected runner passes the complete setup, redirection and configuration probe. FSR 4.1.1 INT8 installs one pinned, validated nightly pipeline beside the game executable. They are mutually exclusive.

Providers and ownership

GE-Proton Integrated

The integrated provider is available only when the selected runner implements the complete OptiScaler contract. Runi does not infer support from the runner name or version alone. It inspects the installed runner for setup, dispatcher, DLL-redirection and structured-configuration support.

At launch Runi supplies the dedicated PROTON_USE_OPTISCALER, PROTON_OPTISCALER_NAME and, when needed, PROTON_OPTISCALER_CONFIG variables. PROTON_FSR4_UPGRADE enables the runner-managed FSR 4 path. GE-Proton owns the download cache and files placed in the Wine prefix; disabling or migrating the provider does not delete those runner-owned files.

FSR 4.1.1 INT8

The quality-first path downloads official nightly nightly-20260817, verifies the complete archive plus the loader and FSR 4.1.1 upscaler hashes, installs a selected proxy DLL beside the game executable, and explicitly sets Fsr4ForceModel=2. The validation watermark is enabled by default for the first test and can be disabled in Advanced before installation. It owns only the files it installs and its corresponding WINEDLLOVERRIDES token, so removal restores previous files and prunes only empty directories it created.

Generic stable manual injection remains available to the CLI and existing configurations for compatibility, but it is no longer a third GUI choice.

The OptiScaler tab audits the pinned loader, nested FSR 4.1.1 DLL and required INT8 INI selection separately. A missing or changed component is reported as an incomplete installation rather than silently falling back.

The integrated provider does not require player-supplied DLLs: the compatible runner owns provisioning. If the runtime probe fails, its card is unavailable and the pinned INT8 path remains explicit rather than being selected silently.

Selection and migration

The stored provider preference and the provider already applied are separate:

• Runtime managed requires a successful capability probe and is unavailable otherwise.
• FSR 4.1.1 INT8 always uses the pinned, reversible game-directory provider.
• Legacy Auto and generic Manual preferences remain readable for compatibility, but new GUI configuration does not create them.

Changing runners can change Auto's resolution. Runi blocks Play when the resolved provider no longer matches the applied provider; it never silently places or removes DLLs during launch. Use the migration action in the game tab or the CLI:

runi optiscaler status <game-id>
runi optiscaler migrate <game-id> --to ge-integrated --fsr4
runi optiscaler migrate <game-id> --to manual --version latest

Migration is explicit, transactional and receipt-backed. A manual recipe is removed through its normal rollback path before Integrated is configured, and its source, parameters and retained unrelated settings are recorded so the manual setup can be reconstructed if migration fails. Migration in the other direction disables the integrated launch path before installing the reversible manual provider.

Raw integrated-provider variables in [env] are rejected because they bypass ownership and can activate both paths. Play is also blocked if manual tracking files coexist with an integrated selection.

FSR 4 behavior

Runtime-managed FSR 4 is not an alias for the pinned FSR 4.1.1 INT8 path. The runner manifest chooses a compatible component set and may combine different component versions. The INT8 path is pinned to the exact tested nightly and checksums, so Runi does not claim that both methods are byte-for-byte or performance equivalent.

For a detected DirectX 12 game, the integrated setup selects the DX12 FSR 3.1 input path before requesting the FSR 4 upgrade. DirectX 11 and Vulkan use their corresponding DX12-interoperability input. The Vulkan-to-DX12 FSR 4 recipe path requires Proton 11 or newer.

In games with a DLSS input, select DLSS in the game and use Insert to inspect the OptiScaler overlay. The overlay is the authoritative check for the intercepted input, selected output and loaded versions.

Status and troubleshooting

The OptiScaler tab and runi optiscaler status <game-id> distinguish disabled, configured, ready, inconsistent and migration-required states. For the manual provider, JSON status also includes an fsr411 audit with its own state and the missing or invalid components. runi doctor additionally reports stale manual tracking, duplicate raw provider variables and provider migrations required after runner changes.

If a GUI process that was already open reports that schema v9 is unsupported, restart Runi so the running Python process loads the updated application code. Editable pipx installations already point at the checkout and do not need to be reinstalled for source changes.

The integrated path was validated on a real GE-Proton11-5 installation. Kusan: City of Wolves confirmed provisioning, cached reuse, DLL redirection and the disabled control. Atomic Heart then confirmed the complete gameplay path after migration from the manual recipe: the overlay loaded, DLSS input was intercepted, FSR 4 output worked and gameplay remained stable.