GOG Galaxy Integrations Python API

Integrations are delivered as Python modules and must be placed in the GOG GALAXY lookup directory. Each integration folder must contain the plugin files, a manifest.json file, and all third-party dependencies.

Lookup Directories

• Windows: %localappdata%\GOG.com\Galaxy\plugins\installed
• macOS: ~/Library/Application Support/GOG.com/Galaxy/plugins/installed

Installing Dependencies

Since the client uses a built-in Python 3.13 interpreter, you must install third-party packages directly into your integration folder using the --target flag. Use the following command structure:

pip install DEP --target DIR --implementation cp --python-version 313

The Plugin lifecycle is managed through several key hooks:

• handshake_complete(): Called immediately after the handshake with the client is finished. Use this for plugin-specific initialization. The persistent_cache is available here.
• tick(): Called periodically. Use for non-blocking background tasks.
• shutdown(): Called when the integration is shutting down. Use this to perform teardown logic.
• close() / wait_closed(): Used to stop the connection and wait for all internal and external tasks to finish.

The LocalGameState is a Flag used to represent the current state of a game on a user's machine. Because it is a bitwise flag, you can combine states using the bitwise OR operator (|).

For example, to represent a game that is both installed and currently running, use: local_game_state = LocalGameState.Running | LocalGameState.Installed

The OSCompatibility flag allows you to express which operating systems a game is compatible with. Use the bitwise OR operator (|) to combine multiple operating systems.

Example: os = OSCompatibility.Windows | OSCompatibility.MacOS

The Plugin class uses specialized Importer objects to handle batch data imports (achievements, game times, etc.). To implement these, you should follow a pattern of preparing context and then fetching data:

1. prepare_{feature}_context(game_ids): (Optional) Override this to perform optimizations, such as fetching a batch of data from your API to use as context for individual requests.
2. get_{feature}(game_id, context): Override this to return the specific data for a single game using the provided context.
3. {feature}_import_complete(): (Optional) Override this to perform cleanup or cache updates after the entire batch import finishes.

Use create_and_run_plugin as the entry point for your integration. It handles the connection to the GOG Galaxy Client via a local port and manages the plugin lifecycle.

Arguments:

• plugin_class: Your custom class that inherits from Plugin.
• argv: The command line arguments (sys.argv).

Required CLI Arguments: The script expects at least two arguments after the script name:

1. token: An authentication token.
2. port: A valid port number (1-65535).

Exit Codes:

• 1: Missing required parameters (token, port).
• 2: Port is not a valid integer.
• 3: Port is out of range (1-65535).
• 4: plugin_class is not a subclass of Plugin.
• 5: An unhandled exception occurred during execution.

def main():
    create_and_run_plugin(PlatformPlugin, sys.argv)

if __name__ == "__main__":
    main()

GOG GALAXY sets up a root logger that stores rotated log files. Plugin-specific logs follow the naming convention plugin-<platform>-<guid>.log.

Log Locations:

• Windows: %programdata%\GOG.com\Galaxy\logs
• macOS: /Users/Shared/GOG.com/Galaxy/Logs

Tip: When debugging communication issues between the plugin and the client, inspect GalaxyClient.log in the same directory.

The following dataclasses are used to represent core entities within the GOG Galaxy integration API.

@dataclass
class Authentication:
    user_id: str
    user_name: str

@dataclass
class Cookie:
    name: str
    value: str
    domain: Optional[str] = None
    path: Optional[str] = None

@dataclass
class LicenseInfo:
    license_type: LicenseType
    owner: Optional[str] = None

@dataclass
class UserInfo:
    user_id: str
    user_name: str
    avatar_url: Optional[str] = None
    profile_url: Optional[str] = None

@dataclass
class GameTime:
    game_id: str
    time_played: Optional[int]
    last_played_time: Optional[int]

@dataclass
class GameLibrarySettings:
    game_id: str
    tags: Optional[List[str]]
    hidden: Optional[bool]

@dataclass
class LocalGame:
    game_id: str
    local_game_state: LocalGameState

Subscriptions allow users to access games via a service.

Subscription fields:

• subscription_name (str): The name/identifier of the subscription.
• owned (Optional[bool]): Whether the user owns the subscription.
• end_time (Optional[int]): Unix timestamp of expiration.
• subscription_discovery (SubscriptionDiscovery): Determines how the integration handles subscription behavior. Valid values are AUTOMATIC, USER_ENABLED, or a combination of both.

SubscriptionGame fields:

• game_title (str): Title of the game.
• game_id (str): ID of the game.
• start_time (Optional[int]): Unix timestamp when the game was added to the subscription.
• end_time (Optional[int]): Unix timestamp when the game will be removed.