First-Time Setup
Relevant source files
The following files were used as context for generating this wiki page:The first-time setup for SOFL (Steam Online Fix Launcher) is a critical process that configures the application to find, import, and launch games correctly. While a guided "Welcome Screen" is planned for future releases, the current setup is managed through the application's Preferences window. This process involves specifying paths for game installations, enabling import sources from other launchers, and managing Proton versions for compatibility.
Properly completing these steps ensures that SOFL can build a unified game library and apply the necessary configurations, particularly for games requiring Online-Fix.
Sources: tasklist.md, README.md
Accessing the Preferences Window
All initial configuration is handled within the SOFLPreferences dialog. It can be accessed at any time after launching the application.
- Keyboard Shortcut:
<primary>+comma - Menu: Via the application's primary menu.
The SOFLApplication class registers a "preferences" action, which creates and displays an instance of the SOFLPreferences window.
Sources: sofl/main.py:170-173, sofl/main.py:311-324, sofl/preferences.py:46-47
Core Configuration Components
The SOFLPreferences window is composed of several pages, each dedicated to a specific aspect of the application's configuration. The key pages for first-time setup are "General", "Import", and "Proton".
The diagram below shows the high-level class structure for the preferences dialog.
This diagram illustrates the relationship between the main application, the preferences window, and its key helper classes for managing Proton and import sources.
Sources: sofl/preferences.py, sofl/preferences/import_sources.py, sofl/main.py
1. General Settings
The "General" page contains basic application behavior settings. While not all are critical for the initial setup, they customize the user experience.
| Setting | Widget | Description | Schema Key |
|---|---|---|---|
| Exit After Launch | exit_after_launch_switch | Closes SOFL after a game is launched. | exit-after-launch |
| Cover Launches Game | cover_launches_game_switch | Allows launching a game by clicking its cover image. | cover-launches-game |
| Force Dark Theme | force_theme_switch | Forces the application to use a dark theme, overriding the system setting. | force-theme |
Sources: sofl/preferences.py:70-74, sofl/preferences.py:255-274
2. Import Sources Configuration
This is the most critical part of the first-time setup, where you tell SOFL where to find your games. This is managed by the ImportSourcesSection logic.
Sources: sofl/preferences/import_sources.py
Online-Fix Games Path
You must specify the main directory where your Online-Fix games are stored.
- UI Element:
online_fix_entry_row(anAdw.EntryRow). - Configuration: The path is entered manually or selected via a file chooser button (
online_fix_file_chooser_button). - Storage: The path is saved to the GSettings schema key
online-fix-install-path. If not set, it defaults to~/Games/Online-Fix.
Sources: sofl/preferences.py:534-555
Importing from Other Launchers
SOFL can import games from various launchers like Steam, Lutris, and Heroic. For each source, SOFL attempts to automatically find the installation path. If it fails, the user must set it manually.
The init_source_row method in sofl/preferences.py handles the setup for each source. It checks if the source is available, binds its settings, and resolves its location.
The resolve_locations function checks for a valid installation. If a location cannot be resolved, a warning icon is displayed next to the path selection row, prompting the user for manual configuration.
The following diagram shows the flow for resolving an import source's location.
This flowchart details the process of validating paths for game sources like Steam or Lutris within the Preferences window.
Sources: sofl/preferences.py:421-470, sofl/preferences/import_sources.py:40-62
3. Proton Management
The "Proton" page is essential for running Windows games on Linux. It contains a complete management system for GE-Proton versions, handled by the ProtonManager class.
Sources: sofl/preferences.py:655-660
Proton Manager UI
The UI is divided into two main sections:
- Installed Versions: Lists all GE-Proton versions found in the Steam compatibility tools directory. Each version can be deleted.
- Available Versions: Fetches a list of available GE-Proton releases from the GitHub API. Users can download and install any version from this list.
The refresh_installed_versions and refresh_available_versions methods populate these lists. The latter runs in a separate thread to avoid blocking the UI.
Sources: sofl/preferences.py:673-757
Downloading a New Proton Version
The sequence diagram below illustrates the process of downloading a GE-Proton version from the UI.
This diagram shows the user interaction and backend process for downloading and installing a new GE-Proton version.
Sources: sofl/preferences.py:968-1018
Proton Selection for Online-Fix
A crucial setting for Online-Fix games is selecting the Proton version they will use.
- UI Element:
online_fix_proton_combo(Adw.ComboRow). - Functionality: The dropdown is populated with the list of installed Proton versions returned by
get_proton_versions. The user's selection is saved to theonline-fix-proton-versionschema key.
Sources: sofl/preferences.py:557-562, sofl/preferences.py:596-633
Adding Your First Game
After the initial configuration, the final step is to add a game. This is done using the "Add Game" button in the main window, which opens the DetailsDialog.
Sources: sofl/main.py:341-345, sofl/details_dialog.py
DetailsDialog Workflow
When adding a new game, the user must provide a name and an executable path. A key choice is the Game Type.
- Select Game Type: The
game_typeAdw.ComboRowlets the user choose between:- Online-Fix Game (index 0)
- Regular Game (index 1)
- Fill Details: Enter the game's name, developer (optional), and executable path.
- Apply: Clicking "Add" triggers the
apply_preferencesmethod.
The following diagram shows the logic for creating a new game.
This flowchart illustrates how a new game is created and saved based on user input in the DetailsDialog.
Sources: sofl/details_dialog.py:160-221
Summary
The first-time setup in SOFL is a manual but straightforward process centered around the SOFLPreferences dialog. The user must configure the path to their Online-Fix games, enable and validate paths for other game launchers, and ensure at least one compatible GE-Proton version is installed and selected. Once these core components are configured, the user can begin adding games to their library, distinguishing between "Online-Fix" and "Regular" types to ensure they are launched with the correct settings.