galaxy.api

plugin

class galaxy.api.plugin.Plugin(platform, version, reader, writer, handshake_token)

Use and override methods of this class to create a new platform integration.

persistent_cache

The cache is only available after the handshake_complete() is called.

Return type

Dict[~KT, ~VT]

create_task(coro, description)

Wrapper around asyncio.create_task - takes care of canceling tasks on shutdown

store_credentials(credentials)

Notify the client to store authentication credentials. Credentials are passed on the next authenticate call.

Parameters

credentials (Dict[str, Any]) – credentials that client will store; they are stored locally on a user pc

Example use case of store_credentials:

1
2
3
4
5
6
7
8
9
async def pass_login_credentials(self, step, credentials, cookies):
    if self.got_everything(credentials,cookies):
        user_data = await self.parse_credentials(credentials,cookies)
    else:
        next_params = self.get_next_params(credentials,cookies)
        next_cookies = self.get_next_cookies(credentials,cookies)
        return NextStep("web_session", next_params, cookies=next_cookies)
    self.store_credentials(user_data['credentials'])
    return Authentication(user_data['userId'], user_data['username'])
Return type

None

add_game(game)

Notify the client to add game to the list of owned games of the currently authenticated user.

Parameters

game (Game) – Game to add to the list of owned games

Example use case of add_game:

1
2
3
4
5
6
async def check_for_new_games(self):
    games = await self.get_owned_games()
    for game in games:
        if game not in self.owned_games_cache:
            self.owned_games_cache.append(game)
            self.add_game(game)
Return type

None

remove_game(game_id)

Notify the client to remove game from the list of owned games of the currently authenticated user.

Parameters

game_id (str) – game id of the game to remove from the list of owned games

Example use case of remove_game:

1
2
3
4
5
6
async def check_for_removed_games(self):
    games = await self.get_owned_games()
    for game in self.owned_games_cache:
        if game not in games:
            self.owned_games_cache.remove(game)
            self.remove_game(game.game_id)
Return type

None

update_game(game)

Notify the client to update the status of a game owned by the currently authenticated user.

Parameters

game (Game) – Game to update

Return type

None

unlock_achievement(game_id, achievement)

Notify the client to unlock an achievement for a specific game.

Parameters

  • game_id (str) – game_id of the game for which to unlock an achievement.

  • achievement (Achievement) – achievement to unlock.

Return type

None

game_achievements_import_success(game_id, achievements)

Notify the client that import of achievements for a given game has succeeded. This method is called by import_games_achievements.

Parameters

  • game_id (str) – id of the game for which the achievements were imported

  • achievements (List[Achievement]) – list of imported achievements

Return type

None

game_achievements_import_failure(game_id, error)

Notify the client that import of achievements for a given game has failed. This method is called by import_games_achievements.

Parameters

  • game_id (str) – id of the game for which the achievements import failed

  • error (ApplicationError) – error which prevented the achievements import

Return type

None

update_local_game_status(local_game)

Notify the client to update the status of a local game.

Parameters

local_game (LocalGame) – the LocalGame to update

Example use case triggered by the tick() method:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
async def _check_statuses(self):
    for game in await self._get_local_games():
        if game.status == self._cached_game_statuses.get(game.id):
            continue
        self.update_local_game_status(LocalGame(game.id, game.status))
        self._cached_games_statuses[game.id] = game.status
    asyncio.sleep(5)  # interval

def tick(self):
    if self._check_statuses_task is None or self._check_statuses_task.done():
        self._check_statuses_task = asyncio.create_task(self._check_statuses())
Return type

None

add_friend(user)

Notify the client to add a user to friends list of the currently authenticated user.

Parameters

user (FriendInfo) – FriendInfo of a user that the client will add to friends list

Return type

None

remove_friend(user_id)

Notify the client to remove a user from friends list of the currently authenticated user.

Parameters

user_id (str) – id of the user to remove from friends list

Return type

None

update_game_time(game_time)

Notify the client to update game time for a game.

Parameters

game_time (GameTime) – game time to update

Return type

None

game_time_import_success(game_time)

Notify the client that import of a given game_time has succeeded. This method is called by import_game_times.

Parameters

game_time (GameTime) – game_time which was imported

Return type

None

game_time_import_failure(game_id, error)

Notify the client that import of a game time for a given game has failed. This method is called by import_game_times.

Parameters

  • game_id (str) – id of the game for which the game time could not be imported

  • error (ApplicationError) – error which prevented the game time import

Return type

None

lost_authentication()

Notify the client that integration has lost authentication for the current user and is unable to perform actions which would require it.

Return type

None

push_cache()

Push local copy of the persistent cache to the GOG Galaxy Client replacing existing one.

Return type

None

handshake_complete()

This method is called right after the handshake with the GOG Galaxy Client is complete and before any other operations are called by the GOG Galaxy Client. Persistent cache is available when this method is called. Override it if you need to do additional plugin initializations. This method is called internally.

Return type

None

tick()

This method is called periodically. Override it to implement periodical non-blocking tasks. This method is called internally.

Example of possible override of the method:

1
2
3
4
5
6
7
def tick(self):
    if not self.checking_for_new_games:
        asyncio.create_task(self.check_for_new_games())
    if not self.checking_for_removed_games:
        asyncio.create_task(self.check_for_removed_games())
    if not self.updating_game_statuses:
        asyncio.create_task(self.update_game_statuses())
Return type

None

shutdown()

This method is called on integration shutdown. Override it to implement tear down. This method is called by the GOG Galaxy Client.

Return type

None

authenticate(stored_credentials=None)

Override this method to handle user authentication. This method should either return Authentication if the authentication is finished or NextStep if it requires going to another url. This method is called by the GOG Galaxy Client.

Parameters

stored_credentials (Optional[Dict[~KT, ~VT]]) – If the client received any credentials to store locally in the previous session they will be passed here as a parameter.

Example of possible override of the method:

1
2
3
4
5
6
7
8
9
async def authenticate(self, stored_credentials=None):
    if not stored_credentials:
        return NextStep("web_session", PARAMS, cookies=COOKIES)
    else:
        try:
            user_data = self._authenticate(stored_credentials)
        except AccessDenied:
            raise InvalidCredentials()
    return Authentication(user_data['userId'], user_data['username'])
Return type

Union[NextStep, Authentication]

get_friends()

Override this method to return the friends list of the currently authenticated user. This method is called by the GOG Galaxy Client.

Example of possible override of the method:

1
2
3
4
5
6
async def get_friends(self):
    if not self._http_client.is_authenticated():
        raise AuthenticationRequired()

    friends = self.retrieve_friends()
    return friends
Return type

List[FriendInfo]

get_local_games()

Override this method to return the list of games present locally on the users pc. This method is called by the GOG Galaxy Client.

Example of possible override of the method:

1
2
3
4
5
6
7
8
async def get_local_games(self):
    local_games = []
    for game in self.games_present_on_user_pc:
        local_game = LocalGame()
        local_game.game_id = game.id
        local_game.local_game_state = game.get_installation_status()
        local_games.append(local_game)
    return local_games
Return type

List[LocalGame]

get_owned_games()

Override this method to return owned games for currently logged in user. This method is called by the GOG Galaxy Client.

Example of possible override of the method:

1
2
3
4
5
6
async def get_owned_games(self):
    if not self.authenticated():
        raise AuthenticationRequired()

    games = self.retrieve_owned_games()
    return games
Return type

List[Game]

import_game_times(game_ids)

Override this method to return game times for games owned by the currently authenticated user. Call game_time_import_success/game_time_import_failure for each game_id on the list. This method is called by GOG Galaxy Client.

Parameters

game_ids (List[str]) – ids of the games for which the game time is imported

Return type

None

import_games_achievements(game_ids)

Override this method to return the unlocked achievements of the user that is currently logged in to the plugin. Call game_achievements_import_success/game_achievements_import_failure for each game_id on the list. This method is called by the GOG Galaxy Client.

Parameters

game_ids (List[str]) – ids of the games for which to import unlocked achievements

Return type

None

install_game(game_id)

Override this method to install the game identified by the provided game_id. This method is called by the GOG Galaxy Client.

Parameters

game_id (str) – id of the game to install

Example of possible override of the method:

1
2
async def install_game(self, game_id):
    await self.open_uri(f"start client://installgame/{game_id}")
Return type

None

launch_game(game_id)

Override this method to launch the game identified by the provided game_id. This method is called by the GOG Galaxy Client.

Parameters

game_id (str) – id of the game to launch

Example of possible override of the method:

1
2
async def launch_game(self, game_id):
    await self.open_uri(f"start client://launchgame/{game_id}")
Return type

None

pass_login_credentials(step, credentials, cookies)

This method is called if we return galaxy.api.types.NextStep from authenticate or from pass_login_credentials. This method’s parameters provide the data extracted from the web page navigation that previous NextStep finished on. This method should either return galaxy.api.types.Authentication if the authentication is finished or galaxy.api.types.NextStep if it requires going to another cef url. This method is called by the GOG Galaxy Client.

Parameters

  • step (str) – deprecated.

  • credentials (Dict[str, str]) – end_uri previous NextStep finished on.

  • cookies (List[Dict[str, str]]) – cookies extracted from the end_uri site.

Example of possible override of the method:

1
2
3
4
5
6
7
8
9
async def pass_login_credentials(self, step, credentials, cookies):
    if self.got_everything(credentials,cookies):
        user_data = await self.parse_credentials(credentials,cookies)
    else:
        next_params = self.get_next_params(credentials,cookies)
        next_cookies = self.get_next_cookies(credentials,cookies)
        return NextStep("web_session", next_params, cookies=next_cookies)
    self.store_credentials(user_data['credentials'])
    return Authentication(user_data['userId'], user_data['username'])
Return type

Union[NextStep, Authentication]

run()

Plugin’s main coroutine.

shutdown_platform_client()

Override this method to gracefully terminate platform client. This method is called by the GOG Galaxy Client.

Return type

None

uninstall_game(game_id)

Override this method to uninstall the game identified by the provided game_id. This method is called by the GOG Galaxy Client.

Parameters

game_id (str) – id of the game to uninstall

Example of possible override of the method:

1
2
async def uninstall_game(self, game_id):
    await self.open_uri(f"start client://uninstallgame/{game_id}")
Return type

None

galaxy.api.plugin.create_and_run_plugin(plugin_class, argv)

Call this method as an entry point for the implemented integration.

Parameters

  • plugin_class – your plugin class.

  • argv – command line arguments with which the script was started.

Example of possible use of the method:

1
2
3
4
5
def main():
    create_and_run_plugin(PlatformPlugin, sys.argv)

if __name__ == "__main__":
    main()

types

class galaxy.api.types.Authentication(user_id, user_name)

Return this from authenticate() or pass_login_credentials() to inform the client that authentication has successfully finished.

Parameters

  • user_id (str) – id of the authenticated user

  • user_name (str) – username of the authenticated user

class galaxy.api.types.Cookie(name, value, domain=None, path=None)
Parameters

  • name (str) – name of the cookie

  • value (str) – value of the cookie

  • domain (Optional[str]) – optional domain of the cookie

  • path (Optional[str]) – optional path of the cookie

domain = None
path = None
class galaxy.api.types.NextStep(next_step, auth_params, cookies=None, js=None)

Return this from authenticate() or pass_login_credentials() to open client built-in browser with given url. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
PARAMS = {
    "window_title": "Login to platform",
    "window_width": 800,
    "window_height": 600,
    "start_uri": URL,
    "end_uri_regex": r"^https://platform_website\.com/.*"
}

JS = {r"^https://platform_website\.com/.*": [
    r'''
        location.reload();
    '''
]}

COOKIES = [Cookie("Cookie1", "ok", ".platform.com"),
    Cookie("Cookie2", "ok", ".platform.com")
    ]

async def authenticate(self, stored_credentials=None):
    if not stored_credentials:
        return NextStep("web_session", PARAMS, cookies=COOKIES, js=JS)
Parameters

  • auth_params (Dict[str, str]) – configuration options: {“window_title”: str, “window_width”: str, “window_height”: int, “start_uri”: int, “end_uri_regex”: str}

  • cookies (Optional[List[Cookie]]) – browser initial set of cookies

  • js (Optional[Dict[str, List[str]]]) – a map of the url regex patterns into the list of js scripts that should be executed on every document at given step of internal browser authentication.

cookies = None
js = None
class galaxy.api.types.LicenseInfo(license_type, owner=None)

Information about the license of related product.

Parameters

  • license_type (LicenseType) – type of license

  • owner (Optional[str]) – optional owner of the related product, defaults to currently authenticated user

owner = None
class galaxy.api.types.Dlc(dlc_id, dlc_title, license_info)

Downloadable content object.

Parameters

  • dlc_id (str) – id of the dlc

  • dlc_title (str) – title of the dlc

  • license_info (LicenseInfo) – information about the license attached to the dlc

class galaxy.api.types.Game(game_id, game_title, dlcs, license_info)

Game object.

Parameters

  • game_id (str) – unique identifier of the game, this will be passed as parameter for methods such as launch_game

  • game_title (str) – title of the game

  • dlcs (Optional[List[Dlc]]) – list of dlcs available for the game

  • license_info (LicenseInfo) – information about the license attached to the game

class galaxy.api.types.Achievement(unlock_time, achievement_id=None, achievement_name=None)

Achievement, has to be initialized with either id or name.

Parameters

  • unlock_time (int) – unlock time of the achievement

  • achievement_id (Optional[str]) – optional id of the achievement

  • achievement_name (Optional[str]) – optional name of the achievement

achievement_id = None
achievement_name = None
class galaxy.api.types.LocalGame(game_id, local_game_state)

Game locally present on the authenticated user’s computer.

Parameters

  • game_id (str) – id of the game

  • local_game_state (LocalGameState) – state of the game

class galaxy.api.types.FriendInfo(user_id, user_name)

Information about a friend of the currently authenticated user.

Parameters

  • user_id (str) – id of the user

  • user_name (str) – username of the user

class galaxy.api.types.GameTime(game_id, time_played, last_played_time)

Game time of a game, defines the total time spent in the game and the last time the game was played.

Parameters

  • game_id (str) – id of the related game

  • time_played (Optional[int]) – the total time spent in the game in minutes

  • last_time_played – last time the game was played (unix timestamp)

consts

class galaxy.api.consts.Platform

Bases: enum.Enum

Supported gaming platforms

Unknown = 'unknown'
Gog = 'gog'
Steam = 'steam'
Psn = 'psn'
XBoxOne = 'xboxone'
Generic = 'generic'
Origin = 'origin'
Uplay = 'uplay'
Battlenet = 'battlenet'
Epic = 'epic'
Bethesda = 'bethesda'
ParadoxPlaza = 'paradox'
HumbleBundle = 'humble'
Kartridge = 'kartridge'
ItchIo = 'itch'
NintendoSwitch = 'nswitch'
NintendoWiiU = 'nwiiu'
NintendoWii = 'nwii'
NintendoGameCube = 'ncube'
RiotGames = 'riot'
Wargaming = 'wargaming'
NintendoGameBoy = 'ngameboy'
Atari = 'atari'
Amiga = 'amiga'
SuperNintendoEntertainmentSystem = 'snes'
Beamdog = 'beamdog'
Direct2Drive = 'd2d'
Discord = 'discord'
DotEmu = 'dotemu'
GameHouse = 'gamehouse'
GreenManGaming = 'gmg'
WePlay = 'weplay'
ZxSpectrum = 'zx'
ColecoVision = 'vision'
NintendoEntertainmentSystem = 'nes'
SegaMasterSystem = 'sms'
Commodore64 = 'c64'
PcEngine = 'pce'
SegaGenesis = 'segag'
NeoGeo = 'neo'
Sega32X = 'sega32'
SegaCd = 'segacd'
SegaSaturn = 'saturn'
PlayStation = 'psx'
PlayStation2 = 'ps2'
Nintendo64 = 'n64'
AtariJaguar = 'jaguar'
SegaDreamcast = 'dc'
Xbox = 'xboxog'
Amazon = 'amazon'
GamersGate = 'gg'
Newegg = 'egg'
BestBuy = 'bb'
GameUk = 'gameuk'
Fanatical = 'fanatical'
PlayAsia = 'playasia'
Stadia = 'stadia'
Arc = 'arc'
ElderScrollsOnline = 'eso'
Glyph = 'glyph'
AionLegionsOfWar = 'aionl'
Aion = 'aion'
BladeAndSoul = 'blade'
GuildWars = 'gw'
GuildWars2 = 'gw2'
Lineage2 = 'lin2'
FinalFantasy11 = 'ffxi'
FinalFantasy14 = 'ffxiv'
TotalWar = 'totalwar'
WindowsStore = 'winstore'
EliteDangerous = 'elites'
StarCitizen = 'star'
PlayStationPortable = 'psp'
PlayStationVita = 'psvita'
NintendoDs = 'nds'
Nintendo3Ds = '3ds'
PathOfExile = 'pathofexile'
class galaxy.api.consts.LicenseType

Bases: enum.Enum

Possible game license types, understandable for the GOG Galaxy client.

Unknown = 'Unknown'
SinglePurchase = 'SinglePurchase'
FreeToPlay = 'FreeToPlay'
OtherUserLicense = 'OtherUserLicense'
class galaxy.api.consts.LocalGameState

Bases: enum.Flag

Possible states that a local game can be in. For example a game which is both installed and currently running should have its state set as a “bitwise or” of Running and Installed flags: local_game_state=<LocalGameState.Running|Installed: 3>

None_ = 0
Installed = 1
Running = 2

errors

exception galaxy.api.jsonrpc.ApplicationError(code, message, data)

Bases: galaxy.api.jsonrpc.JsonRpcError

exception galaxy.api.jsonrpc.UnknownError(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.AuthenticationRequired(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.BackendNotAvailable(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.BackendTimeout(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.BackendError(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.UnknownBackendResponse(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.TooManyRequests(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.InvalidCredentials(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.NetworkError(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.LoggedInElsewhere(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.ProtocolError(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.TemporaryBlocked(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.Banned(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.AccessDenied(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.FailedParsingManifest(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.TooManyMessagesSent(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.IncoherentLastMessage(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.MessageNotFound(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError

exception galaxy.api.errors.ImportInProgress(data=None)

Bases: galaxy.api.jsonrpc.ApplicationError