Proton Management
Relevant source files
The following files were used as context for generating this wiki page:
The Proton Management system is a core feature of SOFL that allows users to download, install, and manage GE-Proton versions directly from within the application. Its primary purpose is to provide the necessary compatibility layers for running Windows games, particularly those requiring Online-Fix, without needing external tools. This system centralizes the handling of Proton, from fetching the latest releases from GitHub to making them available for game launches.
The development plan for this feature included creating a ProtonManager class for backend logic and a corresponding UI for user interaction, with the goal of making GE-Proton installation and usage seamless.
Sources: tasklist.md:14-29, sofl/proton/proton_manager.py, CHANGELOG.md:12
Architecture
The Proton Management feature is split into two main parts: a backend service class (ProtonManager) that handles all logic, and a frontend UI component (ProtonSectionMixin) integrated into the application's preferences window.
Sources: sofl/proton/proton_manager.py, sofl/preferences/proton_section.py, sofl/preferences.py
Component Relationship
The ProtonManager provides the core functionality. The ProtonSectionMixin (and its implementation within SOFLPreferences) consumes this functionality to build the user interface in the "Proton" tab of the settings. Other parts of the application, like OnlineFixGameData, also use ProtonManager to locate Proton executables for launching games.
The diagram below shows the class relationships.
Backend: ProtonManager
The ProtonManager class is the heart of the Proton management system. It is responsible for all interactions with the GitHub API and the local filesystem.
Sources: sofl/proton/proton_manager.py:27-31, sofl/proton/init.py
Key Responsibilities and Methods
| Method | Description |
|---|---|
get_steam_compat_path() | Determines the correct Steam compatibilitytools.d directory path, handling both native and Flatpak installations. |
get_installed_versions() | Scans standard Steam directories (compatibilitytools.d and steamapps/common) to find all locally installed and valid Proton versions. |
get_available_versions() | Fetches a list of the latest GE-Proton releases from the GloriousEggroll GitHub repository API. Results are cached. |
download_version() | Downloads a specified GE-Proton version .tar.gz archive, reports progress via a callback, and extracts it to the compatibilitytools.d directory. |
delete_version() | Removes a specified Proton version directory from the filesystem. |
get_proton_path() | Returns the full path to the proton executable script for a given version name. |
check_proton_exists() | A convenience method to verify if a specific Proton version is installed and valid. |
Sources: sofl/proton/proton_manager.py:33-210
Detecting Installed Versions
The manager identifies installed versions by scanning multiple standard Steam directories. A version is considered valid if its directory contains a proton executable file.
The process is as follows:
- Get the user's
compatibilitytools.dpath usingget_steam_compat_path(). - Scan this path and the system-wide
/usr/share/steam/compatibilitytools.dfor directories starting with "GE-Proton" or "Proton". - Scan Steam's
steamapps/commondirectory for official Proton versions. - For each found directory, check for the existence of a
protonfile. - Collect all valid version names, remove duplicates, and sort them.
This diagram illustrates the logic for finding all installed Proton versions.
Sources: sofl/proton/proton_manager.py:73-122
Fetching and Downloading Versions
Available versions are fetched from the GitHub API. The download_version method then handles downloading the .tar.gz archive and extracting it.
This flowchart shows the steps involved in downloading and installing a new Proton version.
Sources: sofl/proton/proton_manager.py:158-191
UI Integration
The user interface for Proton management is located in the "Proton" page of the SOFLPreferences dialog. It is implemented in ProtonSectionMixin and preferences.py.
Sources: sofl/preferences/proton_section.py, sofl/preferences.py:612-970
UI Components
The UI consists of two main expandable sections:
- Installed Versions (
proton_installed_expander): AnAdw.ExpanderRowthat lists all Proton versions found byProtonManager.get_installed_versions(). Each version has a "Delete" button. - Available Versions (
proton_available_expander): AnAdw.ExpanderRowthat lists GE-Proton releases fetched from GitHub. Each version has a "Download" button.
Sources: sofl/preferences/proton_section.py:19-30, sofl/preferences.py:620-632
Asynchronous Data Loading
To avoid blocking the UI, the list of available versions is fetched in a separate thread. A spinner is shown while the data is loading.
The sequence diagram below illustrates this process.
This diagram shows how the UI asynchronously fetches available Proton versions without freezing.
Sources: sofl/preferences/proton_section.py:93-122, sofl/preferences.py:674-709
User Actions
- Delete: Clicking the delete button next to an installed version calls
on_delete_proton_version, which shows a confirmation dialog. If confirmed, it callsProtonManager.delete_version()and refreshes the UI and the Proton version dropdown for Online-Fix games. - Download: Clicking the download button calls
on_download_proton_version. This method updates the UI to show a progress bar and starts the download in a background thread by callingProtonManager.download_version(). Callbacks are used to update the progress bar. Upon completion or failure, the UI is refreshed.
Sources: sofl/preferences.py:898-920, 922-970
Usage in Game Launch
The ProtonManager is essential for launching Online-Fix games. The OnlineFixGameData class uses it to find the path to the selected Proton version's executable.
When a user launches an Online-Fix game:
- The
_launch_with_direct_steam_apimethod is called. - It retrieves the selected
online-fix-proton-versionfrom settings. - If no version is selected, it uses
ProtonManagerto find the first available installed version. - If no versions are installed at all, it prompts the user to open the Proton Manager.
- It uses
ProtonManager.get_proton_path()to get the full path to theprotonscript. - This path is then used to construct the final command to launch the game.
Sources: sofl/onlinefix_game.py:82-104