How It Works - Shin-Aska/DosboxStagingReplacerForGOGGalaxy GitHub Wiki

Definition of Terms

Here are a list of terms that must be acquainted to a developer when contributing to this project.

  1. PlayTask - The term used internally on Gog Galaxy for Custom Executable and Arguments

πŸ“‚ Project Structure

The codebase is organized into the following main components:

Module Responsibility
main.cpp Entry point. Handles CLI parsing and orchestration.
services/ Logic for editing configs, updating databases, and managing backups.
interfaces/ SQL models, result parsing, and abstract interfaces.
helpers/ Utilities for file scanning, install locating, and backup handling.
libs/ External/third-party dependencies (if any).

πŸ“¦ Core Components

GogGalaxyService

Handles reading from and writing to the GOG Galaxy SQLite database.

  • Disables original PlayTasks
  • Inserts new DOSBox Staging launch tasks
  • Retrieves game and user metadata

ScriptEditService

Modifies .conf files for compatibility with DOSBox Staging.

  • Disables fullscreen
  • Resolves autoexec relative paths

FileBackupService

Creates .bak backups of important files and supports restoration.

🧰 Helpers

  • DirectoryScanner – Lists and filters files in directories
  • InstallationFinder – Locates GOG Galaxy and DOSBox installations
  • InstallationVerifier – Verifies installation paths are valid
  • DataExporter – Exports results (e.g., JSON)

🧠 SQL Abstraction Layer

SqlService (abstract base)

Defines a generic database interface, connection management, and query execution.

SqlLiteService

SQLite-specific implementation using sqlite3, includes query binding and execution.

StatementParser and SqliteStatementParserFactory

Map SQL statement results into typed C++ model objects.

πŸ“Š Class Diagram

Class Diagram For an editable version, you can download the .drawio Diagram here

Gog Galaxy database structure

Gog Galaxy stores its settings and information in an SQLite database. This is stored on C:\ProgramData\GOG.com\Galaxy\storage folder as galaxy-2-0.db.

The following tables are what this project considers important for its purpose:

  • User - The ID for GOG User. This is inferred to be created when the user has logged in
  • PlayTaskTypes - Represent Play Task Type for the PlayTask. We normally need this table to determine the value of the Task Type that signifies it is a Custom Type (which is the one used when you create a custom executable or argument)
  • PlayTasks - Represents the Custom executable or arguments. This table just maps the game and the number of custom arguments
  • PlayTaskLaunchParameters - This is where it is stored the path of the executable and the arguments of that custom executable or arguments.
  • ProductSettings - This is where settings of a Product is stored. This table is important particularly because of the customLaunchParameters column because by settings this to true, the Gog galaxy client expects that the user has set new custom executable or argument for the game

Flow: Replacing GOG’s DOSBox

When you run the tool with --replace, it performs the following operations:

  1. Scan Installation
    • Uses InstallationFinder to locate DOSBox Staging or any other DOSBox builds
    • Confirms the validity of the applications by checking if specific executables exists for the application in question
    • Once verified, will save the path of the executables for reference later
  2. Connect to Database
    • Loads the galaxy.db SQLite file using GogGalaxyService
    • Does checking if the game exists by checking if it is installed
  3. Update PlayTask
    • Inserts new launcher entries using GogGalaxyService
    • Points launch paths to DOSBox Staging
  4. Patch Configuration
    • Finds each game’s .conf file via DirectoryScanner
    • ScriptEditService disables fullscreen, cleans up autoexec paths
  5. Save and Exit
    • Finalizes all changes

πŸ“ File Modification Process

The tool edits the configuration files typically located at <game_install_dir>/dosbox*.conf

The editing logic includes:

  • Disabling fullscreen=true
  • Cleaning autoexec lines to work with DOSBox Staging. This is done by replacing relative links such as .. to its absolute path value

The way it verifies if the files are AutoExecConfig and Config files is that it reads the files in question and searches for the following content

  • For Dosbox Config, it searches if both [sdl] and [dosbox] exists in the file
  • For Dosbox AutoExec, it searches if [autoexec] exists in the file

The search is case insensitive.

The logic is centralized in ScriptEditService.

πŸ›  Cross-Platform Considerations

  • Primary target: Windows (GOG Galaxy)
  • Development tested on: Linux (for analysis, file editing)
  • File path separators and filesystem logic are abstracted for cross-platform compatibility

Although this project is mainly targeted to Windows, it has been abstracted enough that it can be compiled on Linux. I strongly believe that this can also be compiled on MacOS but I currently do not have a Mac machines that can run the latest version of MacOS.

I just did it this way in an event that GOG releases a Linux version of their Galaxy launcher. 🀞