The GOG GALAXY SDK Storage interface can be used in variety of cases. The most common one would be to create save files that are automatically synchronized with the cloud, but you can also use it to share files with members of an online lobby or with friends.
Please note that the GOG GALAXY client has support for cloud saves that doesn’t require the use of the IStorage interface, or any other interference in your game code. We highly recommend using the automatic cloud saves feature unless your game contains features that require the use of the IStorage interface. For more details, please contact your Product Manager.
The Storage interface uses two listeners:
SharedFileDownloadListener, which retrieves callbacks from the
FileShareListenerused to retrieve callbacks for the
Please note that the
FileShare methods will not function properly without their respective listeners.
Implementing cloud saves using the Storage interface is pretty simple. In fact, all you need is the
FileWrite() method, and as it does not require any listeners, you don’t have to register any of them before proceeding.
fileName parameter of the
FileWrite() method must be provided in the form of a path relative to local storage, and can use slashes to create subfolders as long as it is a valid UTF-8 string.
FileWrite() method writes the data provided as a byte array to a specified path, including file name and extension, in local storage. All files located inside local storage are synchronized with the cloud every time the game is opened and closed. Local storage is located on the end user’s machine in:
- %LocalAppData%\GOG.com\Galaxy\Applications\%ClientID%\Storage on Windows, and
- ~/Library/Application Support/GOG.com/Galaxy/Applications/%ClientID%/Storage on macOS.
It is advised not to manipulate files inside local storage outside of the GOG GALAXY SDK.
Therefore, to implement cloud saves in a game using the Storage interface, all you would need to do is to write data into save files using the
FileWrite() method. Then the GOG GALAXY client would take care of synchronizing the saves for you.
Sharing a File¶
This case requires few more steps. Usually, you would start with the same setup as in the Cloud Saves scenario above, since the file you want to share has to be in your local storage. When writing a file to local storage using the
FileWrite() method, you will be able to give it a name using the
fileName parameter. This
fileName is important as it will be used as a reference to this particular file by other Storage methods.
Next, you will need to register the
FileShareListener. This is a very important step, as the only way to get the shared file ID is from the
Once you’ve written the file to local storage and registered the listener, you can use the
FileShare method in order to share the file. It is important to use the same
fileName as in the
FileWrite() method before.
FileShare() is an asynchronous method and therefore you will need to wait for the callback before proceeding. Once this call is finished and successful, you will receive the
FileShareListener::OnFileShareSuccess() callback, which comes with two parameters:
sharedFileID can be used by other users to download the file — in fact, if one user wants to download a file from another user, they will need to have the
sharedFileID of the file.
Downloading a Shared File¶
Once a file is shared and you have the
sharedFileID, you can start downloading it.
First, you will need to register the
SharedFileDownloadListener. This is quite useful, as you can use the
SharedFileDownloadListener::OnSharedFileDownloadSuccess() to trigger the process of writing the downloaded file in the local storage.
Now you are ready to download the file. To start downloading the file, you should use the
DownloadSharedFile() method and provide the
sharedFileID of the file you want to be downloaded. This call is asynchronous, and the completion of the download is signaled by the
SharedFileDownloadListener::OnSharedFileDownloadSuccess() callback. As mentioned before, you can use this callback to write the byte array of the downloaded data to the file in local storage.
To write a downloaded file to your local storage, you should use three methods:
SharedFileRead()to read the downloaded file content into a buffer. Please note that you will need to provide a buffer for the content.
FileWrite()to write the file to your local storage.
SharedFileClose()to close the downloaded file and free up memory.
You can also use the
GetSharedFileOwner() method to determine from whom this file was downloaded. Moreover, you can use the
GalaxyID returned by this method, and the
fileName parameter of the
FileWrite() method, to separate files downloaded from different users.
Example: Sharing a File With Other Lobby Members¶
Let’s say your game has a multiplayer mode and it allows players to create their own custom emblems that will be visible to other players in said multiplayer mode.
- The player creates their own emblem. Once the player has finished the emblem, you’ll need to write it to local storage using the
- Now register the
FileShareListenerand share the file using the
- When the file is uploaded, the player will receive the
FileShareListener::OnFileShareSuccess()callback containing the
SharedFileIDof the file with the player’s emblem. This
SharedFileIDis needed to share the file with other players later, so it has to be saved locally among other player data.
- After the actions in step #3 are performed, you can safely unregister the
As soon as a player joins the lobby, you should register the
LobbyDataListenerinforms about the event of a lobby or lobby member data update.
LobbyDataListener.OnLobbyDataUpdated()has two parameters:
lobbyMemberIDis empty, ie.
lobbyMemberIDis equal to
GalaxyID(0), it means that the lobby data was updated; otherwise it means that the lobby member data was updated.
Next, you may use the
Matchmaking::SetLobbyMemberData()method to write the
SharedFileIDof the player’s emblem in a place accessible for other players. Let’s use a string “emblem” as a key, and the
SharedFileIDof the emblem as a value parameter of the
- Lastly, you call
Matchmaking::GetLobbyMemberData()to get the
SharedFileIDof other players’ emblems, and then use the said
SharedFileIDto download the file using the
DownloadSharedFile()method. You may write down these other players’ emblems in local storage using the
SharedFileClose()methods. You may also use the
GetSharedFileOwner()method to separate the files downloaded from different users.
Please note that before using any of the following methods you need to call
DownloadSharedFile() and wait for the callback on