Launching Games

Relevant source files

The following files were used as context for generating this wiki page:

• sofl/utils/steam_launcher.py
• sofl/game.py
• sofl/main.py
• sofl/details_dialog.py
• sofl/preferences.py
• sofl/dialogs/install_dialog.py

The game launching system is a core component of SOFL, providing multiple methods to execute games, with specialized support for "Online-Fix" titles that require a compatibility layer like Proton. The system is designed to handle different launch contexts, including execution from the main user interface and directly from the command line.

The primary logic for complex launches is encapsulated within the SteamLauncher utility, which prepares a tailored environment, constructs the launch command, and executes the game process. Game-specific parameters, such as the executable path, are managed through the Game object and can be configured via the Details and Install dialogs. User preferences, such as the selected Proton version and DLL overrides, directly influence the launch environment.

Game Launch Flows

There are two primary pathways for launching a game in SOFL: through the graphical user interface (UI) or via a command-line interface (CLI) argument. The UI path is a comprehensive flow that involves process tracking, while the CLI path provides a quick-launch mechanism.

The following diagram illustrates the two main launch flows.

UI-Initiated Launch

This is the standard method for launching games from the SOFL library. It involves a series of interactions between the UI widgets, the main window, and the SteamLauncher utility to ensure the game is launched with the correct environment and its process is tracked.

The sequence diagram below details the interactions for a UI-initiated launch.

Command-Line Launch

SOFL supports a "quick launch" feature via the command line, which is handled at application startup. This method is designed for speed and bypasses the main UI and the extensive environment setup of SteamLauncher.

• Argument: --launch <GAME_ID>
• Handler: SOFLApplication.do_handle_local_options

The process is as follows:

1. The application parses the --launch argument.
2. It directly reads the corresponding <GAME_ID>.json file from the games directory.
3. It extracts the executable and name from the JSON data.
4. The run_executable() utility is called to start the game process.
5. The last_played timestamp in the JSON file is updated.
6. A system notification is sent to confirm the launch.
7. The application exits after a short delay.

This flow does not use the SteamLauncher and therefore does not apply the specialized Proton environment, DLL overrides, or Steam Overlay.

Sources: sofl/main.py:213-241

The SteamLauncher Utility

The SteamLauncher class is the engine behind launching games that require a compatibility layer, such as Proton for Online-Fix titles. It is responsible for creating a sandboxed environment that mimics Steam's own launch process.

Sources: sofl/utils/steam_launcher.py

Environment Preparation

Before launching a game, SteamLauncher.prepare_environment() constructs a dictionary of environment variables. These variables are crucial for Proton and Online-Fix functionality. Many of these are configured by the user in the Preferences window.

| Environment Variable | Description | Configuration Source |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| WINEDLLOVERRIDES | Sets DLL overrides for Wine/Proton. Essential for making online fixes work. | online-fix-dll-overrides setting in Preferences. |
| WINEDEBUG | Controls Wine's debug output. | online-fix-debug-mode setting in Preferences. |
| STEAM_COMPAT_DATA_PATH | Specifies the path for the game's Wine prefix. | Hardcoded path to the game's prefix. |
| STEAM_COMPAT_CLIENT_INSTALL_PATH | Points to the Steam client installation directory. | Hardcoded path. |
| LD_PRELOAD | Injects the Steam Overlay libraries (gameoverlayrenderer.so) if enabled. | online-fix-use-steam-overlay setting in Preferences. |
Sources: sofl/utils/steam_launcher.py:126-151, sofl/preferences.py:465-470, 481-486

Command Construction

The build_launch_command() method assembles the final command that will be executed. It combines the Proton executable, the game executable, and any user-defined arguments. It can also prepend a Steam Runtime if one is found. The use of shlex.split ensures that arguments with spaces are parsed safely.

Sources: sofl/utils/steam_launcher.py:154-179

Process Execution

The launch_game_with_tracking() method is responsible for executing the final command. It handles a critical distinction between a native and a Flatpak installation of SOFL:

• Native: It uses subprocess.Popen to launch the game directly, passing the prepared environment and setting the game's directory as the current working directory (cwd).
• Flatpak: It uses flatpak-spawn --host to break out of the sandbox. The environment variables are passed via --env flags, and the command is wrapped in a shell command (sh -c 'cd ... && exec "$@"') to correctly set the working directory on the host.

In both cases, it returns a subprocess.Popen object, which the main window uses to monitor and manage the running game process.

Sources: sofl/utils/steam_launcher.py:182-211

Game Configuration for Launch

A game cannot be launched without a correctly defined executable. This information is stored as part of the game's data and is set when a game is first added or installed.

Defining the Executable

The executable property of a game is a string containing the command or path to the file to be run. This is configured through two main dialogs:

1. InstallDialog: When installing a game from an archive (e.g., a .rar file from Online-Fix), the OnlineFixInstaller attempts to unpack the game and find a suitable executable. This path is then passed to the DetailsDialog.
   Sources: sofl/dialogs/install_dialog.py:302-311, 329-354

2. DetailsDialog: This dialog is used for both adding new games manually and for editing existing ones. It features an Adw.EntryRow for the executable path and a file chooser button that allows the user to browse for the executable file. The dialog validates that the executable path is not empty before saving the game.
   Sources: sofl/details_dialog.py:65, 150-153, 230-244, 401-404

Launch-Related Settings

Several settings in the SOFLPreferences window allow users to customize the launch behavior, especially for Online-Fix games.

Setting	UI Control	Description	File
online-fix-install-path	Adw.EntryRow	Sets the default directory where games installed via the InstallDialog are placed.	sofl/preferences.py
online-fix-proton-version	Adw.ComboRow	Allows the user to select which installed Proton version to use for launching Online-Fix games.	sofl/preferences.py
online-fix-dll-overrides	Adw.EntryRow	A string of DLLs to be added to the WINEDLLOVERRIDES environment variable.	sofl/preferences.py
cover-launches-game	Adw.SwitchRow	Toggles whether clicking a game's cover art launches the game directly or opens its details page.	sofl/preferences.py
exit-after-launch	Adw.SwitchRow	If enabled, the SOFL application will close after a game is launched.	sofl/preferences.py

Sources: sofl/preferences.py:118-120, 121-123, 448-463, 472-475