PROTON_LOADER_BACKEND.md

Steam Proton loader backend

The Linux manager installs a verified Proton package into a detected Steam game, configures that game's prefix when needed, and owns one reversible Steam launch option. The game still starts from Steam Play. Amethyst confirmed the updated wrapper keeps Time Stranger working as on Windows. New games still need a live check before their releases are called compatible.

Authoring a new game

Both the Windows and Linux AuthorTools can build a proton package with the shared package builder. Put the complete, pinned Windows loader, mod, Prism Windows DLL, matching Prism Wine bridge and license notices in the source folder. The tool copies the folder structure, adds file verification for launch assets, and writes the Steam setup metadata. Enter the Steam app ID and executable exactly as they appear in the game's Steam installation. The release record takes its platform from the validated ZIP. Use a separate version number for a Proton release, as Amethyst requested.

Choose a launch mode based on the loader's real startup path:

• direct: Steam launches the original game executable. Use this for a DLL proxy loader. Declare each required Wine DLL override, for example version=n,b for a verified MelonLoader version.dll or winhttp.dll=n,b for a verified BepInEx winhttp.dll. The proxy DLL must be present in the package and installed at its declared game-relative path. Most proxies sit beside the game executable; wineDllProxyPaths can name a subfolder such as app_digister/freetype.dll. A Reloaded II ASI proxy can also use this mode if its actual game import and loader startup have been verified.
• replaceExecutable: Steam's game executable argument is replaced by a bundled Windows launcher. The launcher receives the original executable as its first argument. Time Stranger uses this because its tested startup path needs its own suspended-child injection sequence. The launcher is a declared package file, not a manager branch for that game.

For a Reloaded II release, provide reloadedRoot and reloadedModId together. The manager writes the loader pointer inside that game's Proton prefix and an app configuration under the declared loader root. It refuses an existing different pointer. The wrapper marks that configuration ready on launch. Either launch mode can carry this prefix setup.

For Prism under Proton, include the matching Windows Prism DLL and placeholder DLLs beside the mod, plus the Linux .dll.so host modules in the declared bridgeDirectory. The wrapper prepends that directory to WINEDLLPATH and keeps any existing path. A release without Prism leaves bridgeDirectory empty.

For a Windows Desktop Runtime prerequisite, declare its major.minor.patch version and the official x64 installer SHA-512. The manager downloads from Microsoft's versioned builds.dotnet.microsoft.com path, verifies the exact SHA-512, runs it as the normal Unix user inside this game's Proton prefix, and verifies both .NET and Windows Desktop frameworks there. Legacy Time Stranger packages can omit the hash for their already pinned 9.0.20 runtime. Windows elevation prompts and Windows lifecycle installers are not run by the Linux manager. Put loader files in the package and describe supported prefix prerequisites instead.

For native Windows DLLs and EXEs in a verified Proton package, the manager checks their PE imports for msvcp140*.dll and vcruntime140*.dll. If needed, it checks the matching x64 or x86 Visual C++ v14 runtime in that game's prefix, installs Microsoft's pinned 14.51.36247.0 redistributable quietly, and verifies the installed version before copying mod files. This applies to explicit Proton packages and converted Windows releases on install or update. The pinned installer is verified by SHA-512. The redistributable remains in the shared game prefix after mod uninstall; removing it could break the game or another mod. An already installed mod is not retroactively checked until update or reinstall. Import inspection cannot discover a runtime loaded only with LoadLibrary, so package authors should declare and validate unusual prerequisites in an explicit Proton package.

The package manifest's existing dependency list also works in the Linux manager. A framework dependency can use a game-relative file check written with Windows or Unix separators, and a missing dependency can use the existing hash-checked extractZip or copyFile auto-install path. The manager asks for consent before downloading and supports the existing manual-dependency pause. Registry and absolute system checks cannot verify a Proton installation, and runInstaller Windows executables are refused before download. Public catalog game definitions use the same platform gate.

Dependencies can now declare targetPlatforms with any combination of windows, proton, and linux. The AuthorTool dependency editor exposes these choices. An omitted list keeps legacy behavior: try the dependency on Windows and Proton, subject to Proton's supported checks and install actions. The package builder includes only dependencies applicable to its package target. An explicit Windows-only dependency is skipped for Proton.

The backend can also adapt a verified Windows release into a temporary Proton package when its install actions bundle a recognized BepInEx winhttp.dll, MelonLoader version.dll, or DSCSModLoader freetype.dll proxy and the corresponding loader DLL, when that matching loader is already installed beside the game, or when a matching pinned extractZip framework dependency in the verified author catalog supplies both files. It checks the package and dependency hashes, manifest, file destinations, proxy architecture, and installed game executable before setting the DLL override. The dependency is installed with the normal consent, verification, receipt and uninstall flow; the manager checks the resulting proxy before changing Steam launch options. An already installed loader remains outside this mod's file ownership. Supported Prism 0.18.3 x64 builds gain matching Wine host modules and PE placeholders. The published Cyber Sleuth plugin is the verified exception: its Prism 0.17.3 Windows DLL registers no Orca or Speech Dispatcher backend. The adapter keeps that plugin's older Prism configuration ABI through a small verified DLL, stages pinned Prism 0.18.3 as prism-core.dll, and places the 0.18.3 placeholders beside both DLLs in resources/plugins. Other Prism 0.17.3 consumers fail closed because their API use has not been audited. When a package carries the verified legacy Tolk x64 DLL, the temporary Proton package replaces that DLL with Prism's official Tolk compatibility shim and adds the matching Prism DLL and bridge. The published Windows ZIP and mod DLL remain unchanged.

Wine DLL override names may include .dll or omit it. WineDllProxy resolves both spellings to one module name and the same default module.dll path for package checks, authoring, conversion and installed-proxy verification. The Steam override retains the package's original spelling and native-first order.

The ABI DLL's source is src/AccessibilityModManager.Infrastructure/Assets/Prism0173Compat/prism_compat.c. It implements the 15 Prism exports used by the published Cyber Sleuth plugin, translates the 48-byte version 3 configuration into Prism 0.18.3's 56-byte version 4 configuration, and loads prism-core.dll from its own directory. The embedded PE has SHA-256 f2f234b8ec3b0f6c0df5f4e501232e8e9c20a1299c885ffc7e19ef90559ab6ec; installer/linux/check-prism-0173-compat.sh rebuilds it with the pinned LLVM MinGW toolchain and checks byte identity. An offline Proton probe using the published version 3 header selected Orca and received Prism's already-initialized result, which the plugin treats as success. This probe did not emit speech or launch the game.

For a bundled Reloaded II release, the adapter verifies one x64 launcher, bootstrapper, loader, game AppConfig, mod DLL and a supported Windows Desktop Runtime. It uses the manager's replaceExecutable Steam wrapper and prefix-local Reloaded II setup. The package's Windows AppConfig has a fixed C: path, so the converted ZIP omits that file; the prefix setup creates a Z: path for the actual game and restores the previous file on uninstall. The audited Time Stranger installer binary, SHA-256 64c7721bba7a2a1070b3fceb80e8b7b28c45fba223213a720a705d80af8f0c2e, only writes the IFEO launch registry value. Its post-install invocation is removed from the converted manifest because the Steam launch option supplies that same role. No Windows setup executable is run. The exact legacy Prism DLL, SHA-256 3b02d1d9b2d44066604be1a6acf751c8c3c7f109c19035646aab21542083b02f, is replaced with official Prism 0.18.3 plus its matched Orca Wine bridge. The source mod uses Prism's C entry points, all 42 exports from the legacy build remain present in 0.18.3, and the newer build was already accepted in the Time Stranger Proton pilot. The adapter refuses other lifecycle binaries, unsupported runtime and speech builds, ambiguous loaders and direct NVDA-only speech. A new installer with different behavior needs its own verified Proton equivalent; the script's prose alone does not authorize skipping it. The Linux Mods list shows public and entitled Patreon releases from the signed registry, verified author indexes, and user-added sources. It also supports native Linux releases when the catalog declares a Linux executable.

Ownership and updates

The manager verifies the package SHA-256 and manifest before installing files. It saves the old Steam option and Reloaded II configuration in a tamper-checked setup record before changing them. Uninstall restores only those owned values and uses the normal file receipt to restore overwritten game files. Updates keep the Steam option and prefix configuration; a release that changes those launch settings requires uninstall and fresh install. This port does not add a new policy for multiple mods on one game.

The wrapper keeps Steam's Proton command and game arguments intact, checks that the exact expected game executable occurs once, applies declared environment settings, and then executes Proton. It supports both the existing Time Stranger argument format and the new declarative format.

Checked here

• Portable tests install, update and uninstall disposable direct-loader and legacy Reloaded II packages, including Steam option restoration and prefix config ownership.
• A portable dependency test installs a hash-checked BepInEx-style ZIP with Windows path separators, verifies its game-relative check, and removes its files via the existing receipt. Windows installer dependencies fail before download.
• Portable tests cover target-specific dependency filtering, BepInEx and MelonLoader proxy recognition, Windows-package adaptation with bundled, existing and pinned catalog dependency loaders, disposable installs and uninstalls that restore Steam's prior option, automatic matching Prism and Tolk shim bridge packaging and receipt removal, refusal of unknown speech builds, and a native Linux package install and uninstall. BepInEx winhttp.dll=n,b now passes full install and uninstall checks with a pinned dependency or a preinstalled loader; the latter remains outside mod ownership. The exact published Next Order 1.2.0 and Master Duel 1.8 ZIPs were also adapted, installed and uninstalled against disposable game and Steam files with local verified upstream archives. These are offline checks, not a claim that either real game is working yet.
• All 85 portable tests pass. The exact signed Cyber Sleuth 1.0-beta24 ZIP is detected as requiring x64 Visual C++ v14 and converts to the verified Prism compatibility DLL plus Prism 0.18.3 core. Both official pinned redistributables installed and passed version checks in a disposable Proton prefix. The live Cyber Sleuth prefix was backed up before upgrading its x64 runtime from 14.10.25008.0 to 14.51.36247.0. An offline Proton probe selected Orca through the Prism adapter. After reinstalling the same published release, Amethyst confirmed speech, mod audio, navigation and controller input in game.
• installer/linux/check-wrapper.sh compiles the native wrapper and checks direct launch, replacement launch, legacy syntax, environment preservation, conflicts and wrong-game refusal using a harmless capture program.
• The manager, Linux AuthorTool and full Windows solution build on Linux with EnableWindowsTargeting=true. A disposable AuthorTool project exposed its project, release and package-build controls through AT-SPI. The WPF authoring UI has not had an NVDA test on Windows in this work.

Release checks still needed

• Next Order: its public 1.2.0 Windows package declares a pinned MelonLoader 0.7.2 ZIP, which the generic loader adapter recognizes. Its verified Tolk build is converted to Prism's Tolk shim; a standalone probe in the installed Proton reports Orca and speech support. Check Steam Play, controller, custom audio and audible mod speech in game before calling this release fully compatible.
• Master Duel: its public 1.8 Windows package omits the MelonLoader 0.7.3 dependency that its author catalog declares. The adapter uses that pinned catalog dependency and converts the same verified Tolk build. Check the real game and Orca before calling it compatible.
• Survive: the signed 1.0-beta03 release was verified and its pinned BepInEx 5.4.23.5 dependency installed, but the old final check formed winhttp.dll.dll from the valid winhttp.dll=n,b override and rolled the install back before Steam setup. A shared Wine DLL module/path resolver now handles both winhttp.dll=n,b and winhttp=n,b without changing the override sent to Wine. A headless Wine probe using the project's version-one Prism config and staged 0.18.3 bridge initialized Orca with result zero. Amethyst retried the published release installation and reported no issues. In-game speech, controls, audio and uninstall still need a live check; the gated ZIP was not retained for a full disposable replay.
• Cyber Sleuth: the downloaded dscs-v1.0-beta24-amm.zip matches its signed catalog SHA-256 fc96dce6eaaf01c63dce6d7b41d8e4d174d471bd404e3747f7a83430f9cf92e6. The real x64 game EXE imports freetype.dll. The verified DSCSModLoader v0.1.1 ZIP (SHA-256 9b45023c7746b97dff15d971d6e8dc7da8823ab8d93c0a0ab0c683dd741cb427) contains x64 app_digister/freetype.dll and app_digister/DSCSModLoader.dll; the adapter maps freetype=n,b to the executable's subfolder. The package copies its plugin, SDL3, Prism 0.17.3, navigation and audio assets into resources. Its Prism DLL SHA-256 is 287cd79e5d6cac5204605ba23e73bd043f48192ade54ddadf50ac4fcd9b94aae. The game's Proton prefix was upgraded from Visual C++ runtime 14.10 to 14.51. The original plugin log showed no Orca or Speech Dispatcher in Prism's backend registry, so speech was absent. The adapter for this exact plugin stages a verified Prism 0.17.3 ABI DLL and pinned Prism 0.18.3 core. An offline Proton probe using the old Prism header selected Orca through that pairing. Amethyst reinstalled the same release and confirmed speech, audio, navigation and controller input in game. The published ZIP is unchanged. The exact ZIP passed disposable install and uninstall, including restoration of the original freetype.dll and Steam option; unmodded game launching after a live removal remains untested.
• Time Stranger: the earlier local setup was recorded as digimon-story-time-stranger, while the public catalog uses dsts. The record was imported and later uninstalled through the manager. Both published public Windows releases, 1.0 and 1.1, now pass a disposable Proton install and uninstall using their original catalog hashes. The manager replaces the audited IFEO-only script, Windows AppConfig and legacy Prism as described above. Amethyst still needs to install 1.1 from the catalog and check its actual game behavior and Orca speech; the published mod DLL differs from the accepted Proton pilot.
• Final Fantasy X: its Patreon release also declares an administrator installer, but the source shows it patches the game's Large Address Aware flag and redirects both the game and the title chooser. Skipping that installer as though it only registered a Steam launcher would lose required work. The exact gated release has not been downloaded or checked; this adapter refuses its script until those operations have a verified, reversible Proton implementation.
• Native Linux mods can be built and installed with a declared native executable. A real native game and mod still need an in-game check. XIVLauncher's Wine environment needs its own release/provider; XIVLauncher is not an ordinary Steam Proton game.
• Amethyst confirmed Patreon sign-in and installation of the gated Cyber Sleuth release. Other gated releases, user-added catalogs, native Linux packages and Linux AuthorTool publishing still need live checks. Existing bundled files and dependency declarations are the release workflow; no new loader recipe system is planned.