|
GOG GALAXY SDK Documentation
|
Developing a game with Galaxy needs to start from linking your application to the following libraries:
All libraries are loaded dynamically, so they have to be placed in the same folder as your executable.
In order to use the Galaxy API, you should request special client credentials from GOG.com for each game you develop. You will be provided with a pair of Client ID and Client Secret that are to be used when calling Init().
Client credentials identify your game within Galaxy. Only Galaxy Peers that use the same Client ID can interact with each other.
The Galaxy API is divided into multiple header files. You can either include only the header files with the data structures and interfaces you need, or simply include the file called GalaxyApi.h that includes all the other files.
You can control your Galaxy Peer through interfaces for specific feature sets, e.g. IUser, IMatchmaking, INetworking, IFriends, IListenerRegistrar, ILogger. They can be accessed with global functions called User(), Matchmaking(), Networking(), ListenerRegistrar(), etc.
For every frame you should call ProcessData() to process input and output streams.
Error occurred on call to Galaxy API can be obtain by calling GetError(), which returns NULL if there was no error. Every call to an API method resets last stored error, therefore you should check for errors after each call.
Global function ThrowIfGalaxyError() can translate errors to C++ exceptions. It calls GetError() and throws appropriate exception if there was an error during the last API call.
Since many method calls are asynchronous, there is a mechanism for receiving responses within a callback that is based on implementing special interfaces called listeners that derive from the IGalaxyListener interface.
There is two kind of listeners:
All listeners are called during the phase of processing data, i.e. during the call to ProcessData().
You need to authenticate the Galaxy Peer by signing in the user. To do that, you need to get an instance of IUser interface and call one of IUser::SignIn...() methods, depending of your platform.
As with any other asynchronous call, you will get the information about the result of your request via a dedicated listener. For that to happen, you already need to call ProcessData() in a loop as mentioned earlier.
In case of limited availability of Galaxy backend services it might happen that the user gets signed in within local Galaxy Service, yet still does not manage to log on to Galaxy backend services. In that case the Galaxy Peer offers only some of its functionality.
Having successfully signed in the user, you may want to check that the user is logged on to Galaxy backend services by calling IUser::IsLoggedOn().
Information about being signed in or signed out, as well as information about being logged on or logged off, determine the operational state of Galaxy Peer and both come to the IOperationalStateChangeListener.
To play a match with other users, the users needs to join them in a so called lobby. The user can either join an existing lobby or create one. All this is done with the IMatchmaking interface.
Typically you will set appropriate filters by calling e.g. IMatchmaking::AddRequestLobbyListStringFilter() or IMatchmaking::AddRequestLobbyListNumericalFilter(), then retrieve the list of available lobbies by calling IMatchmaking::RequestLobbyList(), and than make the user join one of the lobbies by calling IMatchmaking::JoinLobby(). Alternatively the user might want to create a lobby, in which case you will need to call IMatchmaking::CreateLobby().
Users need to stay present in the lobby for the whole match, until it ends.
When the user is the owner of a lobby, its Galaxy Peer needs to act as the game host.
You can broadcast messages to all Galaxy Peers in the lobby by calling IMatchmaking::SendLobbyMessage(). Each recipient should be registered for notifications about incoming messages with dedicated listener, and on the occurrence of such notification call IMatchmaking::GetLobbyMessage().
You can communicate with other Galaxy Peers that are in the same lobby using the INetworking interface. This way of communication is meant to be used for sending data that is directed to certain Galaxy Peers, especially for sending large amount of date in case of audio and video communication. Use it also for sending any other game data that is not crucial, yet needs to be delivered quickly.
To send a P2P packet call INetworking::SendP2PPacket().
You can send packets to specific users by explicitly providing their IDs, or implicitly to the lobby owner (game host) by providing the ID of the lobby as the recipient.
To receive the packets that come to your Galaxy Peer get the instance of INetworking by calling GetNetworking().
The Game Server API allows for creating a lightweight dedicated servers, that does not require Galaxy Client installed.
For the detailed description of the Game Server interfaces refer to the GameServer.
The Galaxy API allows you to store information about statistic counters and unlocked achievements using the IStats interface.
You can retrieve statistics and achievements of the user who is currently signed in, or other user that he interacts with, by calling IStats::RequestUserStatsAndAchievements().
Having retrieved statistics and achievement of your user, you can both read and update them. After making edits to statistics and achievements you will need to store them by calling IStats::StoreStatsAndAchievements().
You can retrieve leaderboards by calling IStats::RequestLeaderboards().
Having retrieved leaderboard definitions you can change user's score by using IStats::SetLeaderboardScore() and retrieve leaderboard entries with scores and ranks of competing users by calling IStats::RequestLeaderboardEntriesGlobal(), IStats::RequestLeaderboardEntriesAroundUser(), or IStats::RequestLeaderboardEntriesForUsers().
The Galaxy API allows you to download the list of your friends by calling IFriends::RequestFriendList().
Having retrieved the friend list you can browse it by calling IFriends::GetFriendCount() and IFriends::GetFriendByIndex().
The Galaxy API allows you to browse information about other users.
You can retrieve information about a specific user by calling IFriends::RequestUserInformation().
Having retrieved other user information you can read it by calling IFriends::GetFriendPersonaName() and IFriends::GetFriendAvatarUrl().
Some operations, e.g. entering a lobby or requesting for the friend list, automatically retrieve information about lobby members or friends accordingly.
The Galaxy API allows you to invite your friends to play together by calling IFriends::ShowOverlayInviteDialog(). This require the connectionString which will allow other users to join your game.
Typically the connectionString looks like "-connect-lobby-<id>".
After the invitation receiver gets the notification, he can click the JOIN button, which will fire IGameJoinRequestedListener with connectionString, or will start the game with connectionString as a parameter.
The Galaxy API allows you to set the RichPresence "status" and "connect" keys. "status" key will be visible to your friends inside the Galaxy Client chat and friend list. "connect" key will be visible to your friends as a JOIN button, which works exactly the same way as like the player would receive the game invitation.
The Galaxy API allows to embed the GOG Galaxy chat, available for the GOG users on the website, in the GOG Galaxy Client and in the in-game overlay, directly into the game.
A chat room with a user can be created explicitly by calling IChat::RequestChatRoomWithUser(), or implicitly by new messages incoming to the IChatRoomMessagesListener::OnChatRoomMessagesReceived() callback listener. In this chat room, you can get the number of unread messages, by calling IChat::GetChatRoomUnreadMessageCount(), or iterate over chat room participants by calling IChat::GetChatRoomMemberUserIDByIndex(), up to the IChat::GetChatRoomMemberCount() participants.
If you need to retrieve the chat room history, call IChat::RequestChatRoomMessages() method. By omitting the optional parameter referenceMessageID, only the latest messages will be retrieved. Retrieved messages will be available in the IChatRoomMessagesListener::OnChatRoomMessagesReceived() call, during which they can be read by calling IChat::GetChatRoomMessageByIndex(). Once all messages has been processed and rendered to the user, they can be marked as read by calling the IChat::MarkChatRoomAsRead() method.
Sending messages is possible only to the existing (see above) chat rooms by calling IChat::SendChatRoomMessage(). Every participant of a chat room will receive messages coming to the IChatRoomMessagesListener::OnChatRoomMessagesReceived() callback method.
The Galaxy API allows you to store files in Galaxy's backend services. The files are automatically synchronized by the Galaxy Client application.
The easiest way to add Cloud Saves functionality to your game is to use the Automatic Cloud Saves syncing mechanism. In this solution GOG Galaxy only needs to know the path, where the save games are stored and will handle sync between the local folder and cloud storage automatically. The sync is performed before the game is launched, after the game quits, after the installation and before the uninstallation. To enable Automatic Cloud Saves syncing contact your Product Manager.
If your game requires more complex managing of local and remote files or you don't want to interact with the file system directly you can use the IStorage interface. It provides the abstraction over the file system (read/write/delete files and the metadata). You can also share the files created this way with other gog users. The folder will be synchronized automatically like mentioned in the previous section.
There is an easy way of checking if a DLC has been installed by calling IApps::IsDlcInstalled() with the Product ID of the particular DLC. This feature does not require the user to be online, or Galaxy Client to be installed, or even Galaxy API to be fully initialized, however you still need to call Init() first.
There is an easy way of retrieving game or DLC language by calling IApps::GetCurrentGameLanguage() with the Product ID of the game (0 can be used to retrieve base game language) or particular DLC. This feature does not require the user to be online, or Galaxy Client to be installed, or even Galaxy API to be fully initialized, however you still need to call Init() first.
The Galaxy API is thread-safe in general, however there are some methods that return pointers and therefore cannot be used in multi-threaded environments. In order to address the issue the similar methods of names with a suffix of "Copy" were introduced, e.g. compare IFriends::GetPersonaName() and IFriends::GetPersonaNameCopy().