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.
I want to send a preview build to GOG, how should I do this?
Please refer to the Games in Development 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.
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?
I keep getting authorization and/or
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_secretparameters and where can I get them for my game?
Client_idis a unique identifier of your game in GOG GALAXY.
client_secretare 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
ProcessDatashould 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_secretin 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
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:
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.
GetError()depend on the
throwExceptionsflag 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
NULLif 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.
Can I use
IsLoggedOn()to determine the current status of the connection with the backends?
true, it means that the online authentication was successful, but it does not mean that you are still connected to the backends.
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:
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
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.
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:
- Install the GOG GALAXY client.
- 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).
- 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
IsLoggedOn(which gives you info about backend connection) returns
truefor online mode and
falsefor offline mode, so you shouldn’t disable GOG GALAXY Features based on that.
- It is important not to disable GOG GALAXY Features if
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
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.
- Have you called
Trying to set Achievements or Statistics throws an unhandled exception and crashes the game!
- Do you use exceptions? They are available with the
- 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
SetStatInt()before retrieving the achievements and statistics for the game from our backend.
- Do you use exceptions? They are available with the
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:
RequestLeaderboards()— to download leaderboard definitions.
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).
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
Does the GOG GALAXY SDK support creating leaderboards during runtime?
Yes! Read about the
FindOrCreateLeaderboard()call in the documentation.
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.
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?
In case of Steam, we can use the
SteamAPI_IsSteamRunningcall 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.
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?
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).
galaxy::api::Init(clientID, clientSecret) galaxy::api::User()->SignInSteam(const char* steamAppTicket, uint32_t steamAppTicketLength, const char* personaName);
personaNameare taken from the Steam SDK.
You also need to have GalaxyPeer.dll placed along in the game folder.
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
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.
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.
You have to put the GOG GALAXY libraries in the appropriate directory. You can achieve this by using the linked script. It might be necessary to modify the script to match your application structure.
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
OnDestroy/Disposemethods. Note that before calling
Shutdown(), all the listeners should be disposed of.
GOG GALAXY does not work for me in Unity standalone builds.
You have to copy the Galaxy libraries to appropriate folders inside the standalone project. You can achieve this by using the linked script. It might be necessary to modify the script to match your application structure.
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.