GOG GALAXY FAQ¶

Frequently asked questions about the GOG GALAXY SDK integration

When you run into any problem, please first update to the newest version of the GOG GALAXY SDK. Also, please make sure that you are using the latest production version of our GOG GALAXY client (after installing open it, let it update itself and then sign in). We rely on our users keeping the GOG GALAXY client up to date, as it provides the most important components of the platform.

For any questions that are not covered by this FAQ, please contact our support team, or read the SDK documentation.

Builds¶

I want to send a preview build to GOG, how should I do this?

Please refer to the Early Access article for more information.
Do you add your own installer?

Yes, we add our own installer. It will be created after you upload your game build with Build Creator or Pipeline Builder and let us know it awaits our QA process. Read more in Offline Installers.
How do build updates get delivered and published? How can I add a changelog?

You upload your build, using Build Creator or Pipeline Builder, and then publish the updated build on the Master branch. After that, you can create and add a changelog to the build. See Updates.
How do I set up downloadable content (DLC) for my game?

DLCs are either bundled with your base game during preparing game build in Build Creator or Pipeline Builder, or uploaded and released independently. See DLCs and Extras and contact your GOG Product Manager.
I have a demo version of my game. How can I set it up on GOG?

We need to set up a separate SKU for that. Please contact your Product Manager and ask about it. You will need to upload the demo build the same way you uploaded the main game.
I have a general issue with the build upload(it's too slow, hangs at a specific point etc.)

In such cases, you can try to use our new, beta version of Build Creator which uses experimental version of our Pipeline Builder Tool that may work better for you. To do that, please enable beta channel called: beta for Build Creator. More on Beta Channels here: Beta Channels. When building a game, please make sure to select: Use beta option. Feel free to report any issues related to the upload to our support team.

General SDK Questions¶

How can I invite my team members to the Devportal?

In the Devportal, click Users→Invite. More in User Management.
Do you have an example (a source code) of implementing the GOG GALAXY SDK in a game?

Yes, it’s written in C# and you will find it in our GitHub repository. See C# Demo Game.
I keep getting authorization and/or galaxy::api::SignInGalaxy() errors

Make sure you have the necessary privileges (license) for your game in the User Management section of the Developer Portal – the GOG GALAXY SDK will not initialize if your account does not have a valid license for the game. If your account is ran by your publisher, please contact its administrator. Please check whether your GOG GALAXY client is running and you are logged in. If your problems persist, please contact our support team
What are the client_id and client_secret parameters and where can I get them for my game?

Client_id is a unique identifier of your game in GOG GALAXY. Client_id and client_secret are used for initializing GOG GALAXY during the galaxy::api::Init() call. You can find them in the SDK Credentials button for a given game in the Games section of the Developer Portal.
How often should I call ProcessData()?

ProcessData should be called frequently. It is designed to impose a minimal overhead (a couple of microseconds at most). Calling it once a few seconds should be enough, although you may call it every frame, if needed.
Should I obfuscate the client_id and client_secret in the game code?

It is up to you. However, we believe that no matter how hard we obfuscate the credentials, if someone is really determined to get them, they will find a way.
Can the game run multiple processes with multiple active connections to the GOG GALAXY network at the same time? With each process having its own Init() and SignInGalaxy()?

In general it is OK but the separate client applications that were signed in to the same account will not be able to see each other’s multiplayer lobbies, messages, etc.
I couldn’t find any server-side APIs for authenticating a user. Other platforms let you authenticate a user via encrypted tickets by making API calls to verify that a user has signed in and owns the game. Is there an equivalent for GOG GALAXY?

Sure! We do have encrypted app tickets allowing authentication in a third-party backend using GOG GALAXY service.
What data does the encrypted app ticket contain?

We encrypt following data inside the ticket:
- user_id
- client_id
- timestamp of ticket generation
- some additional data that will be passed to the ticket request.
Technically, you could prevent the game from starting, if the user is not signed in to GOG GALAXY. Is this considered a bad practice and does it violate GOG’s “DRM free” principle?

The single player mode should work regardless of whether the user is using GOG GALAXY or not (or whether they are currently online or not). The current user status in our GOG GALAXY SDK can be used for example to enable/disable the multiplayer option in the main menu.
What should happen, if the user is not signed in to GOG GALAXY when the game starts?

We don’t have any mandatory GOG GALAXY messaging in-game. For example, in The Witcher Adventure Game, if you’re not using GOG GALAXY, the multiplayer option in the main menu is just disabled. Of course, if you’d like to add some more info in this case — that’s great, we’d just like to get a preview of this screen.
The game considers me logged in even after I close the GOG GALAXY client.

This is by design.
Is it necessary to check for the presence of an installed GOG GALAXY client or is it safe to call the API functions regardless?

If the GOG GALAXY client is not present (or the user is not logged in), the methods related to achievements will throw exceptions that you should catch. You can also disable all exceptions in our SDK when making the Init() call. Be sure to check that your game does not crash when making a call to any of the GOG GALAXY components when GOG GALAXY was not initialized.
Does GetError() depend on the throwExceptions flag of the Init() function or does this always work? And does it return the same error as when it’s thrown as an exception?

This flag of the Init() function is not supported anymore. If there is any error, GetError() will return it (or NULL if no error occurred).

If you want to throw exceptions, use the ThrowIfGalaxyError() function from GalaxyExceptionHelper.h.
Do I need to put the GalaxyPeer.dll file into the game?

No. In the present version of the SDK, the GalaxyPeer.dll file is loaded from the GOG GALAXY client redistributables. You have to place this file manually only in case of very old SDK versions: 1.114.12 and older. Please refer to the API documentation.
How to get the player display name? The GOG GALAXY encrypted app ticket does not contain it.

galaxy::api::Friends()->GetPersonaName() once you are logged in.
Can I use IsLoggedOn() to determine the current status of the connection with the backends?

If IsLoggedOn returns true, it means that the online authentication was successful, but it does not mean that you are still connected to the backends.

Fortunately, there’s a special method for checking the connection status: GogServicesConnectionState with its dedicated listener.
What is the difference between OPERATIONAL_STATE_SIGNED_IN and OPERATIONAL_STATE_LOGGED_ON?

We have something that is called OfflineMode. If the user was signed in previously and now they do not have an internet connection, then you can still call OnAuthSuccess, but you will get a different operational state.

OPERATIONAL_STATE_SIGNED_IN, but not OPERATIONAL_STATE_LOGGED_ON means that we know who the user is (SIGNED_IN), but is not authenticated with our backend (not LOGGED_ON). Learn more on this in the article on authorization in GOG GALAXY.

If the user has downloaded statistics, achievements and leaderboards before, while being online, and now they don’t have an internet connection, they can still:
- unlock achievements,
- update a statistics value,
- set a leaderboard score.
The data will be synchronized once you run the game again with the internet connection re-established.
Do you provide a NAT punchthrough and proxy functionality?

Yes, they are automatically handled in the SDK. If we can’t pass the NAT, then we connect the player through one of our proxy servers.
How does the galaxy::api::IsDlcInstalled() method work?

The GOG GALAXY SDK allows you to check if a DLC has been installed. You can use the galaxy::api::IsDlcInstalled() method, supplying the DLC Product ID as a parameter. This call is not dependent on the Operational State of the Galaxy Peer, provided the galaxy::api::Init() call has been made. This is regardless of if the galaxy::api::Init() call was successful or resulted in an error.
Tip

IsDlcInstalled() only requires the galaxy::api::Init() call to be made, regardless of its result. The method determines if the DLC has been installed by checking a metadata file created when the game is installed through the GOG GALAXY client.

To successfully make this call:
1. Install the GOG GALAXY client.
2. Make the game available on a branch in the GOG GALAXY client (either publish it through the developer pipeline on a beta branch or contact your Product Manager).
3. Install the game with the GOG GALAXY client.

Achievements, Stats, Leaderboards¶

Are there recommendations or restrictions to consider for the achievement icons?

You should upload the best quality achievement icons in the Developer Portal: go to Games page, click the Galaxy Features button for a particular game, select Achievements in the list. In the resulting Achievements screen, select files for Unlocked/Locked icons for a given achievement, if you have already defined achievements, or click the green Add new button, then define achievements and select their icons. Maximum single icon size is 2 MB, allowed image types: JPEG, PNG. We handle any resizing/formatting internally.

In the Achievements article you will find all details on achievements in the Developer Portal.
How should I implement offline achievements?

If you implemented achievements, offline achievements will work automatically as long as you don’t disable them. Two things to take into consideration:
- It is important not to disable GOG GALAXY Features if AuthListener returns OnAuthSuccess
- IsLoggedOn (which gives you info about backend connection) returns true for online mode and false for offline mode, so you shouldn’t disable GOG GALAXY Features based on that.
Setting Achievements does not work — I call the appropriate methods and nothing happens.
- Have you called RequestUserStatsAndAchievements() before calling any other achievement methods?
- Have you called StoreStatsAndAchievements() after calling SetAchievement() to commit the changes?
- If you did all of the above, then you can try (if you haven’t already) to set up listeners and use GetError() to see if some exception occurred. Please consult with the SDK documentation for details.
Trying to set Achievements or Statistics throws an unhandled exception and crashes the game!
- Do you use exceptions? They are available with the ThrowIfGalaxyError() method from GalaxyExceptionHelper.h.
- If so, do you catch exceptions after every GOG GALAXY method call?
- If not, do you check galaxy::api::GetError() after every GOG GALAXY method?
- Did you use the RequestUserStatsAndAchievements() method and waited for an appropriate callback? The documentation clearly states that you cannot use SetAchievement() and SetStatInt() before retrieving the achievements and statistics for the game from our backend.
Can you reset the leaderboards using a GOG GALAXY SDK call?

No. This feature would possibly allow any user to reset the entire leaderboard.
The leaderboards do not work. Why?

Please check if you implemented a proper flow for leaderboards:
1. RequestLeaderboards() — to download leaderboard definitions.
2. RequestLeaderboardEntriesAroundUser() or RequestLeaderboardEntriesForUsers() or RequestLeaderboardEntriesGlobal() — these will get you entries in an existing leaderboard, and will work only if the call from the first step was successful (check this with a callback listener).
3. GetRequestedLeaderboardEntry() — this will get you a specific entry in a leaderboard and will work only if the previous steps were successful.
Also, are you using listeners properly to check for errors and call ProcessData?
Does the GOG GALAXY SDK support creating leaderboards during runtime?

Yes! Read about the FindOrCreateLeaderboard() call in the documentation.

Multiplayer¶

I have my own back-end servers for multiplayer. Can I use them with GOG GALAXY?

Yes! We offer an encrypted app ticket feature so that you can use the GOG GALAXY SDK login and authenticate users on your own backend server.
Is the galaxy::api::Networking() the only method to send and retrieve custom packets?

Yes, you have to implement the GOG GALAXY SDK Networking() method to use our NAT punchthrough/UDP proxy servers.
Is there a way to get the remote server IP and port via GOG GALAXY, like you can in Steam?

No, there is no way to retrieve the IP/port pair internally using the SDK method calls.
What port does the GOG GALAXY remote server use?

It’s a random port from the range of 1024-65535.
Does the GOG GALAXY SDK support anonymous login?

Yes, we support anonymous login for dedicated GameServers only with the SignInAnonymous() method.
In case of Steam, we can use the SteamAPI_IsSteamRunning call to check whether Steam is running. Is there a similar call for Galaxy?

No, we only check if you’re signed in to GOG GALAXY at game startup. After that, logging out does not affect the SDK while the game is still running. We only have the IsLoggedOn() call to check for the connection status, but this does not affect the GOG GALAXY client, only the connection of the GOG GALAXY libraries to our backends.

Crossplay¶

Could you explain to me how the crossplay feature works?

Each platform has its own multiplayer environment, and it is not possible to access one from the other. The way crossplay works is that you implement the networking stack from the GOG GALAXY SDK in your game and upload the builds to GOG and other platforms via their developer pipeline. Thanks to this, game builds on different platforms use the same (GOG) environment and are able to interact with each other — for example, users on different services are able to play with each other, because GOG GALAXY servers are handling everything. In other words, even if a game is published on Steam, for instance, it uses GOG GALAXY servers for all interactions. We are able to handle Steam app tickets for users logging in to GOG GALAXY through the Valve’s client. See Crossplay.
What do you mean exactly by Steam user authentication? Do you mean GOG players being able to play with their friends on Steam?

GOG Authorization:
```
galaxy::api::Init(clientID, clientSecret)
galaxy::api::User()->SignInGalaxy();
```
It signs you in using credentials stored in the GOG GALAXY client (you need to have the client installed and be signed in).

Steam Authorization:
```
galaxy::api::Init(clientID, clientSecret)
galaxy::api::User()->SignInSteam(const char* steamAppTicket, uint32_t steamAppTicketLength, const char* personaName);
```
where steamAppTicket, steamAppTicketLength, personaName are taken from the Steam SDK.

You also need to have GalaxyPeer.dll placed along in the game folder.

In both cases you should wait (and call galaxy::api::ProcessData ) until you get the AuthListener::OnAuthSuccess (or AuthListener::OnAuthFailure) callback.

GOG Multiplayer:

After successfully signing in (to GOG or Steam), you can use the galaxy::api::Matchmaking() interface to create/list/join GOG lobbies and the galaxy::api::Networking() interface to send packets of data inside a lobby.
How do I sign in to GOG GALAXY when running the game in the Steam Client (for Crossplay purposes)?

You need to use Steam API to extract the user details and then pass them over to the GOG GALAXY SDK for creating a user account (if it doesn’t exist) or authenticating an existing user through Init() and SignInGalaxy().
Do you support Steam friend invites for games hosted using GOG GALAXY multiplayer?

Steam offers 2 types of invites:
- Invitation to a lobby, which uses the Steam Overlay:
```
SteamFriends()->ActivateGameOverlayInviteDialog( CSteamID steamIDLobby )
```
  we have no solution for this scenario yet.
- Inviting users with a connection string:
```
SteamFriends()->InviteUserToGame( CSteamID steamIDFriend, const char *pchConnectString )
```
  This will work by default, for example connect-galaxy-lobby=1234, but it requires the GUI for invitation to be done in-game.
When using the GOG GALAXY matchmaking service without an associated GOG GALAXY account (logged in through Steam, using the GOG GALAXY Crossplay), what in-game name will be displayed for me?

You have to pass the Steam nickname as a parameter when calling galaxy::api::SignInGalaxy() (as shown in the documentation).

Unity/C# Wrapper SDK¶

Which files should I use if I want to use the GOG GALAXY C# wrapper for SDK integration on Windows?

Place Galaxy64.dll or Galaxy.dll (from C++ SDK), GalaxyCSharp.dll and GalaxyCSharpGlue.dll in the game folder and it should work correctly. Just make sure all these files come from the same version of the SDK.
I can’t find some of the classes and methods of the GOG GALAXY SDK using the C# wrapper.

Try using Galaxy.Api.GalaxyInstance.
Unity on OSX allows me to only add .bundle files. How can I import the .dylibs?

Try renaming libGalaxyCSharpGlue.dylib to GalaxyCSharpGlue.bundle.
GOG GALAXY does not work for me inside the Unity debugger or in Unity standalone builds.

GOG GALAXY SDK Unity Package should take care of placing the required libraries in their place both when using the editor and when building a standalone game. GOG GALAXY SDK Unity package can be found on our Developer Portal.

If you are using the GOG GALAXY SDK Unity package and the GOG GALAXY API is not available in the Unity editor, please make sure that the Galaxy.dll or Galaxy64.dll file is in the project’s root folder.
GOG GALAXY throws an exception when calling the Init() method after stopping and starting the Unity3d debugger.

It is because Shutdown() is not called by Unity when the application is being stopped. You can fix this by adding calling GalaxyInstance.Shutdown() in OnDestroy/Dispose methods. Note that before calling Shutdown(), all the listeners should be disposed of.

Overlay¶

Can I implement the GOG GALAXY Overlay in our game?

The overlay is ready for integration. See GOG GALAXY Overlay.
The overlay behaves oddly in some Unity games on macOS. What is the reason?

Recent changes in Unity make the overlay attach to the wrong process, and — as a result — appear in the wrong window. Unfortunately, we are unable to fix this at the moment.
Overlay doesn't work in Unreal Engine game

Please make sure that the file task is configured properly in the Build Creator. For Unreal Engine games, please read section: "File Task in Unreal Engine Games" in the Build Creator Quick Start guide.
Overlay doesn't work. Game has multiple executables(not an Unreal Engine game)

If the default game.exe is a bootstrapper of some sort that then launches the game executable, please select: 'launcher' category for the default .exe and then select: 'game' category for other executables in the Build Creator.

Dev Support - Logs¶

I’m having issues with Build Creator. What should I do?

Contact our support team through the widget and make sure to attach Build Creator and CSB logs with your request so we can investigate further.

Build Creator log files are located in:
- %LocalAppData%/GOG.com/BuildCreator/BuildCreator.log on Windows,
- ~/Library/Application Support/GOG.com/BuildCreator/BuildCreator.log on MacOS.
CSB logs should be stored here:
- %LocalAppData%\temp\__gog\logs on Windows,
- $TMPDIR/__gog/logs (type 'open $TMPDIR/__gog/logs' in MacOS terminal) on MacOS.
I’m having troubles with Steam SDK Wrapper(beta)!

Please generate logs and send them with your request to our support team. In order to have logs generated, please add the following to the GalaxyConfg.json:
```
{
"enable_logs": true,
"auth_on_init": true,
"require_online": true
}
```
Remember that GalaxyConfig.json should be located in the root folder of the game installation directory, next to the game.exe. Afterwards, please reproduce the issue. SteamWrapper.log should be generated in the same directory next to the game.exe and GalaxyConfig.json.

Additionally, you can also generate GalaxyPeer logs. In order to do that, download GalaxyPeer.ini and copy-paste it next to the game.exe. Once the .ini file is in place Galaxy SDK will generate a GalaxyPeer.log file when the game is running. Please attach this file to your support request.
I’m having issues with Galaxy SDK and I’m not using Steam SDK Wrapper(beta)!

Please generate GalaxyPeer logs and send them to our support team. In order to do that, download GalaxyPeer.ini and copy-paste it next to the game.exe. Once the .ini file is in place Galaxy SDK will generate a GalaxyPeer.log file when the game is running. Make sure to attach this file to your support request.
I can’t download my game using GOG GALAXY!

Please recreate the issue and send your GOG Galaxy client log files to our support team, so we can investigate it further.

The log files can be found here:
- C:\ProgramData\GOG.com\Galaxy\logs on Windows.
- /Users/Shared/GOG.com/ on Mac.