Install

Home · Play and verify · Steam Deck · Recovery

Experimental composed preview

v0.3.0-preview.1 is for controlled testing. A real account/game installation passed repeat menu/profile loading and a short Free Play drive with normal exit in a SteamOS Venus VM with a scoped workaround. The Hakone benchmark still stalls; a completed race, measured performance, and physical Steam Deck gameplay remain unverified. It packages a complete custom Proton tool and separates user integration from that tool's immutable payload. Evidence and limits.

Use a fresh test environment. If you already play successfully, keep your current tool and recovery records. This preview refuses an existing managed tool, user payload, or unfinished legacy transaction; it does not migrate an installed v0.2 setup. The old v0.2 fresh-download path remains blocked because stock GE lacks the required Wine changes. The old Xodus binaries also predate the dependency security fixes.

1. Check prerequisites

• Arch Linux or SteamOS x86_64, native Steam, Python 3.11+, and a working user systemd session.
• Your licensed Steam edition of Forza Motorsport, AppID 2440510, installed in one identifiable library. Additional libraries are recognized; actual microSD hot-removal is untested.
• Your own licensed Microsoft threading DLL at an absolute path. No Microsoft binaries are distributed.
• Space for the game plus at least 12 GiB free in your home and 8 GiB in the Steam root during staging. Recovery copies remain after rollback.
• KDE Wallet or another existing Secret Service provider. On SteamOS use the existing KWallet interface; keep the OS read-only.

In Desktop Mode, open Konsole. Run as your normal desktop user, without sudo:

git clone --branch v0.3.0-preview.1 --depth 1 https://github.com/volcmen/forza-motorsport-linux.git forza-preview
cd forza-preview
./setup platform-check

The diagnostic may report native GUI libraries missing on SteamOS. The Flatpak below supplies those GUI libraries. Resolve an ambiguous game/prefix layout, missing native service libraries, or duplicate DLL filenames before proceeding. Do not delete game DLLs just because a diagnostic reports case collisions.

2. Download and verify the preview inputs

Download these three assets from the preview release into a new directory. Keep the checkout and inputs for recovery:

mkdir artifacts
cd artifacts
release=https://github.com/volcmen/forza-motorsport-linux/releases/download/v0.3.0-preview.1
for asset in GE-Proton11-3-FM-composed-preview.tar.gz forza-composed-user-bundle-v1.tar.zst forza-xodus-preview.flatpak; do
  curl --fail --location --retry 3 --proto '=https' --tlsv1.2 --output "$asset" "$release/$asset" || exit
done
sha256sum --check <<'SHA256'
59792b23cfc40474764c379c4c91c255781afe8fc949f5aa614b012034784b76  GE-Proton11-3-FM-composed-preview.tar.gz
54a74fb48fccb3e6eb16cb83ff79962068f8a47cec95b9ccad8f26955a596f73  forza-composed-user-bundle-v1.tar.zst
a6c6257f4334ae65425371427f71141d46d4e13a2315e1337d0671fb67aaca61  forza-xodus-preview.flatpak
SHA256

Stop if any checksum fails. After all three pass:

tar --zstd -xf forza-composed-user-bundle-v1.tar.zst
cd ..

Do not extract the Proton archive yourself; Prepare verifies and stages it. Source archives and build provenance are available on the same release.

3. Install the SteamOS login and overlay app

On SteamOS, install these in your user account. Ensure the official Flathub remote exists for that account, then install the runtime and verified app bundle:

flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak install --user flathub org.gnome.Platform/x86_64/50
flatpak install --user artifacts/forza-xodus-preview.flatpak

The remote command preserves an existing remote of that name; it does not change the system-wide installation. See Flatpak's user/remote documentation.

The preview checks the exact app and tested runtime commits. If a newer runtime is installed, stop and report the version; do not downgrade a runtime or edit the trusted hashes just to satisfy the installer. Review the app's permissions: network, graphics, input devices, the existing Secret Service, and Xodus's socket. Do not add broad home/session-bus overrides.

Arch users may use the native applications with the matching GTK 4.22, libadwaita 1.9, SDL3 and WebKitGTK 4.1 libraries. The tested SteamOS path uses the Flatpak for the GUI and a native user service for Xodus.

4. Prepare the complete tool

./setup composed plan --tool-archive "$PWD/artifacts/GE-Proton11-3-FM-composed-preview.tar.gz" --bundle-root "$PWD/artifacts/forza-composed-user-bundle-v1"
./setup composed prepare --tool-archive "$PWD/artifacts/GE-Proton11-3-FM-composed-preview.tar.gz" --bundle-root "$PWD/artifacts/forza-composed-user-bundle-v1"

Read the plan and type its exact SHA-256 when prompted. Prepare independently copies and publishes the reviewed tool as GE-Proton11-3-FM. It does not edit Steam settings or launch the game. Full payload verification can take several minutes.

Restart Steam. Select Forza Motorsport → Properties → Compatibility → GE-Proton11-3-FM. Save any existing launch options, leave them empty for this checkpoint, start the game once to create the prefix, and stop it. A splash failure at this stage is not proof of a complete installation.

5. Finish, authenticate, then attempt the game

Replace the example path with your private licensed DLL:

./setup composed plan --threading-dll /absolute/private/path/xgameruntime.dll
./setup composed finish --threading-dll /absolute/private/path/xgameruntime.dll
./setup composed status

Finish verifies the prefix's custom Wine modules, installs only the private threading DLL and user integration, runs Doctor, and rechecks the whole tool. READY_TO_ATTEMPT means those installer checks passed. It is not a gameplay or account-success result. Keep the exact checkout; recovery plans bind their inputs.

On SteamOS, open Microsoft sign-in with:

flatpak run io.github.volcmen.ForzaXodus login

Complete any wallet unlock and sign-in yourself. Use xodus-cli login from the installed native path on a suitable Arch desktop. Do not post authentication logs or tokens. Apply the exact Steam launch options printed by Finish; print them again with ./scripts/print-steam-options. Then follow Play and verify.

After reboot, the tagged v0.3.0-preview.1 native launcher can encounter an inactive KDE Secret Service. Use the tested wallet-activation workaround before launching. The later launcher correction is described there; preserve your accepted installation instead of replacing managed files by hand.

For the SteamOS overlay, start it while the game/Xodus service is running:

flatpak run io.github.volcmen.ForzaXodus overlay

Close and reopen the overlay after restarting the game/service: its socket bind mount refers to the earlier socket until the Flatpak restarts. Incoming invite notifications, Gaming Mode integration, and physical controller behavior are not validated by this preview.

If a step fails, stop and read Recovery. Never remove a journal, bypass a hash, or use legacy patch commands on the composed tool.

Historical v0.2.0 workflow and checkpoint reference — not a fresh-install recommendation

The steps below describe the shipped v0.2.0 workflow so existing installation and recovery records remain understandable. They do not resolve the blockers above.

1. Check the requirements

Requirement	Check before continuing
System	Arch Linux, x86_64, a working user systemd session
Game	Licensed Steam edition, AppID 2440510, installed in native Steam's primary library
Tools	Python 3.11 or newer, uv, and zstd
Native libraries	Arch packages gtk4, libadwaita, sdl3, and webkit2gtk-4.1, with dependencies
Credential storage	KDE Wallet providing org.freedesktop.secrets in your user session
Microsoft runtime	Your own licensed xgameruntime.dll, available at a known absolute path

The installer does not support Flatpak Steam or additional Steam libraries. It does not install system packages. The bundle needs the native libraries above; it is not a self-contained AppImage. Do not install GNOME Keyring just for this workflow or add a second Secret Service daemon alongside KDE Wallet.

Microsoft binaries are not distributed. Obtain the runtime from your own licensed Windows installation, not a DLL download site. Do not attach it to an issue.

2. Get a separate checkout

Run without sudo:

git clone --branch v0.2.0 --depth 1 https://github.com/volcmen/forza-motorsport-linux.git forza-motorsport-linux-v0.2.0
cd forza-motorsport-linux-v0.2.0
./setup bootstrap --check

Checkpoint: required system packages must be installed before continuing; bootstrap does not install them. Project components may still be absent on a fresh setup. Resolve an unsupported host or an existing recovery problem first. Keep an existing working installation and its recovery records. The tag's bundled documentation is a historical snapshot; this wiki explains the workflow.

3. Start bootstrap and follow its Steam checkpoint

./setup bootstrap

Bootstrap acquires the pinned Proton base, prepares a dedicated GE-Proton11-3-FM, and verifies the component bundle. Public bundle downloads do not require a GitHub login. Review the printed plan before confirming it.

When prompted:

1. Restart Steam so it discovers the new compatibility tool.
2. Open Forza Motorsport → Properties → Compatibility and select GE-Proton11-3-FM.
3. Leave Steam launch options empty for this prefix-creation launch. Save any existing custom line before clearing it.
4. Start and close the game to let Steam create its Windows environment (the prefix).

Checkpoint: complete the steps requested by bootstrap, then resume in the same checkout. A stop at a manual checkpoint is not a completed installation. If this handoff fails, see Troubleshooting.

4. Supply the licensed runtime and finish

Replace the example path with the location of your own DLL:

./setup bootstrap --threading-dll /absolute/path/to/licensed/xgameruntime.dll

Bootstrap copies the supplied licensed DLL to the required prefix location and coordinates the recoverable installation and exact-build patches. You do not need to copy or rename it yourself in this workflow. Its destination is steamapps/compatdata/2440510/pfx/drive_c/windows/system32/xgameruntime.dll.threading beneath the Steam root. Keep that proprietary file out of public evidence.

Checkpoint: setup must finish without an unresolved failure. If a command is cancelled, run ./setup bootstrap --check before resuming; cancellation does not undo completed stages. Do not remove journals or backups to force a retry.

5. Configure Steam, then play

After bootstrap reports READY TO ATTEMPT, print the launch options:

./setup steam-options

Paste the generated line into Properties → General → Launch Options. Keep GE-Proton11-3-FM selected and disable Steam Input for the tested controller path. Use the generated line without extra Proton or hardware-profiler flags.

Setup does not edit Steam, launch the game, or sign in to Microsoft for you. READY TO ATTEMPT means the setup checks passed. Continue with Play and verify → to check the actual game session.

Other ways to acquire the bundle

Have the release archive already?

./setup bootstrap --bundle /absolute/path/to/forza-bootstrap-bundle-v1.tar.zst

Only the archive matching the shipped trust manifest is accepted. This does not make the whole installation offline: an uncached Proton base still needs downloading.

To build the open-source bundle yourself:

./setup bootstrap --build-from-source

This requires rootless Docker on x86_64. Source and dependency acquisition use the network; compilation runs offline with read-only source mounts. Build workspaces and caches are retained for diagnosis, and their locations are printed. This path still enforces the approved artifact hashes.

Need to undo bootstrap? Use the bootstrap recovery path.