defold/extension-gpgs/gpgs
Functions and constants for interacting with Google Play Games Services (GPGS) APIs
- GitHub: defold/extension-gpgs — pinned to
5.0.1(released while Defold 1.13.1 was current)- Pick a release from defold/extension-gpgs releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as gpgs from "gpgs"
- Pick a release from defold/extension-gpgs releases and add its Source code (zip) URL (or a packaged
Functions
gpgs.is_supported(): booleangpgs.login()gpgs.silent_login()gpgs.get_display_name(): stringgpgs.get_id(): stringgpgs.get_server_auth_code(): string | nilgpgs.is_logged_in(): booleangpgs.set_callback(callback: function)gpgs.snapshot_display_saves(popupTitle?: string, allowAddButton?: boolean, allowDelete?: boolean, maxNumberOfSavedGamesToShow?: number)gpgs.snapshot_open(saveName: string, createIfNotFound?: boolean, conflictPolicy?: number)gpgs.snapshot_commit_and_close(metadata?: table)gpgs.snapshot_get_data(): LuaMultiReturn<[string, string]>gpgs.snapshot_set_data(data: string): LuaMultiReturn<[boolean, string]>gpgs.snapshot_is_opened(): booleangpgs.snapshot_get_max_image_size(): numbergpgs.snapshot_get_max_save_size(): numbergpgs.snapshot_get_conflicting_data(): LuaMultiReturn<[string, boolean]>gpgs.snapshot_resolve_conflict(conflictId: string, snapshotId: number)gpgs.leaderboard_submit_score(leaderboardId: string, score: number)gpgs.leaderboard_get_top_scores(leaderboardId: string, time_span: number, collection: number, max_results: number)gpgs.leaderboard_get_player_centered_scores(leaderboardId: string, time_span: number, collection: number, max_results: number, force_reload: boolean)gpgs.leaderboard_show(leaderboardId: string, time_span: number, collection: number)gpgs.leaderboard_list()gpgs.leaderboard_get_player_score(leaderboardId: string, time_span: number, collection: number)gpgs.achievement_reveal(achievementId: string)gpgs.achievement_unlock(achievementId: string)gpgs.achievement_set(achievementId: string, steps: number)gpgs.achievement_increment(achievementId: string, steps: number)gpgs.achievement_show()gpgs.achievement_get()gpgs.event_increment(eventId: string, amount: number)gpgs.event_get()
gpgs.is_supported(): boolean
Check if Google Play Services are available & ready on the device.
if gpgs then
local is_supported = gpgs.is_supported()
endReturns
is_supported:boolean— Status of Google Play Services on the device.
gpgs.login()
Login to GPGS using a button.
Log in to GPGS using a button:
if gpgs then
gpgs.login()
endgpgs.silent_login()
Silent login to GPGS. This function is trying to retrieve the currently signed-in player’s account.
function init(self)
if gpgs then
gpgs.silent_login()
end
endgpgs.get_display_name(): string
Get the current GPGS player display name.
if gpgs then
local name = gpgs.get_display_name()
endReturns
name:string— The player's display name.
gpgs.get_id(): string
Get the current GPGS player id.
if gpgs then
local id = gpgs.get_id()
endReturns
id:string— The player ID.
gpgs.get_server_auth_code(): string | nil
Returns a one-time server auth code to send to your web server which can be exchanged for access token
A code can be retrieved only if gpgs.request_server_auth_code is set to 1 and gpgs.client_id is set.
if gpgs then
local server_auth_code = gpgs.get_server_auth_code()
endReturns
server_auth_code:string | nil— The server auth code for logged in account. Can be nil if operation is not completed yet. The auth code is available after receiving a message with idgpgs.MSG_GET_SERVER_AUTH_CODEin callback set viagpgs.set_callback.
gpgs.is_logged_in(): boolean
Check if a user is logged in currently.
if gpgs then
local is_loggedin = gpgs.is_logged_in()
endReturns
is_loggedin:boolean— Current login state.
gpgs.set_callback(callback: function)
Set callback for receiving messages from GPGS.
function callback(self, message_id, message)
if message_id == gpgs.MSG_SIGN_IN or message_id == gpgs.MSG_SILENT_SIGN_IN then
if message.status == gpgs.STATUS_SUCCESS then
-- do something after login
end
elseif message_id == gpgs.MSG_LOAD_SNAPSHOT then
-- do something when a save was loaded
end
end
function init(self)
gpgs.set_callback(callback)
end
function init(self)
gpgs.set_callback(nil) -- remove callback
endParameters
callback:function— A callback taking the following parametersself:object— The calling scriptmessage_id:number— An message_id can be one of the predefined constants belowgpgs.MSG_SIGN_INgpgs.MSG_SILENT_SIGN_INgpgs.MSG_SHOW_SNAPSHOTSgpgs.MSG_LOAD_SNAPSHOTgpgs.MSG_SAVE_SNAPSHOTgpgs.MSG_GET_ACHIEVEMENTSgpgs.MSG_GET_TOP_SCORESgpgs.MSG_GET_PLAYER_CENTERED_SCORESgpgs.MSG_GET_PLAYER_SCOREgpgs.MSG_GET_EVENTSgpgs.MSG_GET_SERVER_AUTH_CODE
message:table— Contains information that depends on message_id. Successful achievement, event, top-score, and player-centered-score queries return arrays of JSON strings. Decode each string withjson.decode(). A successful player-score query returns the score fields directly. Other operations includestatus.status?:number— Status of the current operation. It can be one of the predefined constants belowgpgs.STATUS_SUCCESSgpgs.STATUS_FAILEDgpgs.STATUS_CREATE_NEW_SAVEgpgs.STATUS_CONFLICT
error?:string— The error message. Available only ifstatusisgpgs.STATUS_FAILED.error_status?:number— The error code. Available only ifstatusisgpgs.STATUS_FAILEDand GPGS provide this code. It can be one of the predefined constants belowgpgs.ERROR_STATUS_SNAPSHOT_COMMIT_FAILEDgpgs.ERROR_STATUS_SNAPSHOT_CONFLICT_MISSINGgpgs.ERROR_STATUS_SNAPSHOT_CONTENTS_UNAVAILABLEgpgs.ERROR_STATUS_SNAPSHOT_CREATION_FAILEDgpgs.ERROR_STATUS_SNAPSHOT_FOLDER_UNAVAILABLEgpgs.ERROR_STATUS_SNAPSHOT_NOT_FOUNDOr it can be ApiException.getStatusCode() (if ApiException was thrown)
code?:string— The one-time server auth code. Available only whenmessage_idisgpgs.MSG_GET_SERVER_AUTH_CODEandstatusisgpgs.STATUS_SUCCESS.metadata?:table— Metadata of the loaded save. Available only ifmessage_idisgpgs.MSG_LOAD_SNAPSHOT.conflictId?:string— The conflict id. Available only ifstatusisgpgs.STATUS_CONFLICT.conflictMetadata?:table— The conflicting metadata. Available only ifstatusisgpgs.STATUS_CONFLICT.
gpgs.snapshot_display_saves(popupTitle?: string, allowAddButton?: boolean, allowDelete?: boolean, maxNumberOfSavedGamesToShow?: number)
Provides a default saved games selection user interface.
if gpgs then
gpgs.snapshot_display_saves("Choose the save of the game", false, true, 10)
endParameters
popupTitle?:string— The title to display in the action bar. By default "Game Saves".allowAddButton?:boolean— Whether or not to display a "create new snapshot" option in the selection UI. By defaulttrue.allowDelete?:boolean— Whether or not to provide a delete overflow menu option for each snapshot in the selection UI. By defaulttrue.maxNumberOfSavedGamesToShow?:number— The maximum number of snapshots to display in the UI. By default 5.
gpgs.snapshot_open(saveName: string, createIfNotFound?: boolean, conflictPolicy?: number)
Opens a snapshot with the given saveName. If createIfNotFound is set to true, the specified snapshot will be created if it does not already exist.
if gpgs then
gpgs.snapshot_open("my_save_1", true, gpgs.RESOLUTION_POLICY_LONGEST_PLAYTIME)
endParameters
saveName:string— The name of the snapshot file to open. Must be between 1 and 100 non-URL-reserved characters (a-z, A-Z, 0-9, or the symbols "-", ".", "_", or "~").createIfNotFound?:boolean— Iftrue, the snapshot will be created if one cannot be found.conflictPolicy?:number— The conflict resolution policy to use for this snapshot that can be one of the predefined constants belowgpgs.RESOLUTION_POLICY_MANUALgpgs.RESOLUTION_POLICY_LONGEST_PLAYTIMEgpgs.RESOLUTION_POLICY_LAST_KNOWN_GOODgpgs.RESOLUTION_POLICY_MOST_RECENTLY_MODIFIEDgpgs.RESOLUTION_POLICY_HIGHEST_PROGRESS
gpgs.RESOLUTION_POLICY_LAST_KNOWN_GOOD
gpgs.snapshot_commit_and_close(metadata?: table)
Save the currently opened save on the server and close it.
if gpgs then
local png_img, w, h = screenshot.png()
gpgs.snapshot_commit_and_close({
coverImage = png_img,
description = "LEVEL 31, CAVE",
playedTime = 12345667,
progressValue = 657
})
endParameters
metadata?:table— A table with metadata for a save. It contains the fields belowplayedTime?:number— The new played time to set for the snapshot in ms.progressValue?:number— The new progress value to set for the snapshot.description?:string— The new description to set for the snapshot.coverImage?:object— The new cover image to set for the snapshot inpng.
gpgs.snapshot_get_data(): LuaMultiReturn<[string, string]>
Returns the currently opened snapshot data.
if gpgs then
local bytes, error_message = gpgs.snapshot_get_data()
if not bytes then
print("snapshot_get_data ERROR:", error_message)
else
print("snapshot_get_data",bytes)
-- Do something with your data
end
endReturns
bytes:string— The byte array data of the currently opened snapshot.nilif something goes wrong.error_message:string— An error message if something goes wrong.
gpgs.snapshot_set_data(data: string): LuaMultiReturn<[boolean, string]>
Sets the data for the currently opened snapshot.
if gpgs then
local success, error_message = gpgs.snapshot_set_data(my_data)
if not success then
print("snapshot_set_data ERROR:", error_message)
end
endParameters
data:string— The data to set.
Returns
success:boolean— True if data was set for the currently opened snapshot.error_message:string— An error message if something goes wrong.
gpgs.snapshot_is_opened(): boolean
Check if a snapshot was opened.
if gpgs then
local is_opened = gpgs.snapshot_is_opened()
endReturns
is_opened:boolean— A current snapshot state.
gpgs.snapshot_get_max_image_size(): number
Returns the maximum data size per snapshot cover image in bytes.
if gpgs then
local image_size = gpgs.snapshot_get_max_image_size()
endReturns
image_size:number— The maximum data size per snapshot cover image in bytes.
gpgs.snapshot_get_max_save_size(): number
Returns the maximum data size per snapshot in bytes.
if gpgs then
local data_size = gpgs.snapshot_get_max_save_size()
endReturns
data_size:number— The maximum data size per snapshot in bytes.
gpgs.snapshot_get_conflicting_data(): LuaMultiReturn<[string, boolean]>
Returns the conflicting snapshot data.
if gpgs then
local bytes, error_message = gpgs.snapshot_get_conflicting_data()
if not bytes then
print("snapshot_get_conflicting_data ERROR:", error_message)
else
print("snapshot_get_conflicting_data:",bytes)
-- Do something with conflicting data data
end
endReturns
bytes:string— The byte array data of the conflicting snapshot.nilif something goes wrong.error_message:boolean— An error message if something goes wrong.
gpgs.snapshot_resolve_conflict(conflictId: string, snapshotId: number)
Resolves a conflict using the data from the provided snapshot.
if gpgs then
gpgs.snapshot_resolve_conflict(self.conflictId, gpgs.SNAPSHOT_CONFLICTING)
endParameters
conflictId:string— The conflict id that you want to resolve. Provided inmessagetable withSTATUS_CONFLICTmessage type.snapshotId:number— Type of the snapshot you want to use for conflict solving that can be one of the predefined constants belowgpgs.SNAPSHOT_CURRENTgpgs.SNAPSHOT_CONFLICTING
gpgs.leaderboard_submit_score(leaderboardId: string, score: number)
Submit a score to a leaderboard for the currently signed-in player.
Parameters
leaderboardId:stringscore:number
gpgs.leaderboard_get_top_scores(leaderboardId: string, time_span: number, collection: number, max_results: number)
Asynchronously gets the top page of scores for a leaderboard. The callback receives an array of JSON strings with score data; decode each string with json.decode().
Parameters
leaderboardId:stringtime_span:number— One of the gpgs.TIME_SPAN_ constantscollection:number— One of the gpgs.COLLECTION_ constantsmax_results:number— Between 1-25
gpgs.leaderboard_get_player_centered_scores(leaderboardId: string, time_span: number, collection: number, max_results: number, force_reload: boolean)
Asynchronously gets a player-centered page of scores for a leaderboard. The callback receives an array of JSON strings with score data; decode each string with json.decode().
Parameters
leaderboardId:stringtime_span:number— One of the gpgs.TIME_SPAN_ constantscollection:number— One of the gpgs.COLLECTION_ constantsmax_results:number— Between 1-25force_reload:boolean— If true, this call will clear any locally cached data and attempt to fetch the latest data from the server
gpgs.leaderboard_show(leaderboardId: string, time_span: number, collection: number)
Show a leaderboard for a game specified by a leaderboardId.
Parameters
leaderboardId:stringtime_span:number— One of the gpgs.TIME_SPAN_ constantscollection:number— One of the gpgs.COLLECTION_ constants
gpgs.leaderboard_list()
Show the list of leaderboards.
gpgs.leaderboard_get_player_score(leaderboardId: string, time_span: number, collection: number)
Asynchronously gets the current player's score for a leaderboard. The callback receives the score fields directly in the message table.
Parameters
leaderboardId:stringtime_span:number— One of the gpgs.TIME_SPAN_ constantscollection:number— One of the gpgs.COLLECTION_ constants
gpgs.achievement_reveal(achievementId: string)
Reveals a hidden achievement to the current player.
Parameters
achievementId:string— Achievement id (from GP console)
gpgs.achievement_unlock(achievementId: string)
Unlocks an achievement for the current player.
Parameters
achievementId:string— Achievement id (from GP console)
gpgs.achievement_set(achievementId: string, steps: number)
Sets an achievement to have at least the given number of steps completed.
Parameters
achievementId:string— Achievement id (from GP console)steps:number— The number of steps to set the achievement to. Must be greater than 0.
gpgs.achievement_increment(achievementId: string, steps: number)
Increments an achievement by the given number of steps.
Parameters
achievementId:string— Achievement id (from GP console)steps:number— The number of steps to increment by. Must be greater than 0.
gpgs.achievement_show()
Show achivements
gpgs.achievement_get()
Get information about all achievement's state asynchronously. Result return to callback previously set by gpgs.set_callback with message_id == gpgs.MSG_GET_ACHIEVEMENTS. Result is an array of JSON strings. Decode each string with json.decode() to get a table containing the following fields
id- achievement id (from GP console)name- achievement namedescription- achievement descriptionxp- how much experience points will be added when achievement will be unlockedsteps- current step of incremental achievementtotal_steps- total amount of steps of incremental achievementunlocked- set totrueif achievement is unlocked. Otherwise field is missed.hidden- set to `true if achievement is hidden. Otherwise field is missed.revealed- set totrueif achievement is revealed. Otherwise field is missed.
gpgs.event_increment(eventId: string, amount: number)
Increments an event specified by eventId by the given number of steps
Parameters
eventId:string— Event id (from GP console)amount:number— The amount increment by. Must be greater than or equal to 0
gpgs.event_get()
Get information about all events asynchronously. Result returns to callback previously set by gpgs.set_callback with message_id == gpgs.MSG_GET_EVENTS. Result is an array of JSON strings. Decode each string with json.decode() to get a table containing the following fields
id- event idformatted_value- sum of all increments have been made to this eventvalue- the number of increments this user has made to this eventdescription- event's descriptionimage- URI that can be used to load the event's image iconname- event's namevisible- whether the event should be displayed to the user in any event related UIs
Constants
gpgs.RESOLUTION_POLICY_MANUAL
Official GPGS documentation for this constant
gpgs.RESOLUTION_POLICY_LONGEST_PLAYTIME
Official GPGS documentation for this constant
gpgs.RESOLUTION_POLICY_LAST_KNOWN_GOOD
Official GPGS documentation for this constant
gpgs.RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED
Official GPGS documentation for this constant
gpgs.RESOLUTION_POLICY_HIGHEST_PROGRESS
Official GPGS documentation for this constant
gpgs.TIME_SPAN_DAILY
Select leaderboard scores from the current day.
gpgs.TIME_SPAN_WEEKLY
Select leaderboard scores from the current week.
gpgs.TIME_SPAN_ALL_TIME
Select leaderboard scores from all time.
gpgs.COLLECTION_PUBLIC
Select scores from players who share their gameplay activity publicly.
gpgs.COLLECTION_FRIENDS
Select scores from players in the current player's friends list. A score query may show a Google Play consent dialog the first time this collection is used.
gpgs.MSG_SIGN_IN
The message type that GPGS sends when finishing the asynchronous operation after calling gpgs.login()
gpgs.MSG_SILENT_SIGN_IN
The message type that GPGS sends when finishing the asynchronous operation after calling gpgs.silent_login()
gpgs.MSG_SHOW_SNAPSHOTS
The message type that GPGS sends when finishing the asynchronous operation after calling gpgs.snapshot_display_saves()
gpgs.MSG_LOAD_SNAPSHOT
The message type that GPGS sends when finishing the asynchronous operation after calling gpgs.snapshot_open()
gpgs.MSG_SAVE_SNAPSHOT
The message type that GPGS sends when finishing the asynchronous operation after calling gpgs.snapshot_commit_and_close()
gpgs.MSG_GET_ACHIEVEMENTS
The message type that GPGS sends when finishing the asynchronous operation after calling gpgs.achievement_get()
gpgs.MSG_GET_TOP_SCORES
The message type that GPGS sends when finishing the asynchronous operation after calling gpgs.leaderboard_get_top_scores()
gpgs.MSG_GET_PLAYER_CENTERED_SCORES
The message type that GPGS sends when finishing the asynchronous operation after calling gpgs.leaderboard_get_player_centered_scores()
gpgs.MSG_GET_PLAYER_SCORE
The message type that GPGS sends when finishing the asynchronous operation after calling gpgs.leaderboard_get_player_score()
gpgs.MSG_GET_EVENTS
The message type that GPGS sends when finishing the asynchronous operation after calling gpgs.event_get()
gpgs.MSG_GET_SERVER_AUTH_CODE
The message type that GPGS sends when finishing the asynchronous operation of server auth code retrieval
gpgs.STATUS_SUCCESS
An operation success.
gpgs.STATUS_FAILED
An operation failed. Check the error field in the massage table.
gpgs.STATUS_CREATE_NEW_SAVE
A user wants to create new save as a result of gpgs.snapshot_display_saves() method. Turn off this button in gpgs.snapshot_display_saves() if you don't want to have this functionality.
gpgs.STATUS_CONFLICT
The result of the calling gpgs.snapshot_open() or 'gpgs.snapshot_resolve_conflict()' is a conflict. You need to make decision on how to solve this conflict using 'gpgs.snapshot_resolve_conflict()'.
gpgs.SNAPSHOT_CURRENT
The second parameter for 'gpgs.snapshot_resolve_conflict()' method, which means that you want to choose the current snapshot as a snapshot for conflict solving.
gpgs.SNAPSHOT_CONFLICTING
The second parameter for 'gpgs.snapshot_resolve_conflict()' method, which means that you want to choose the conflicting snapshot as a snapshot for conflict solving.
gpgs.ERROR_STATUS_SNAPSHOT_NOT_FOUND
This constant is used in message.error_status table when MSG_LOAD_SNAPSHOT is STATUS_FAILED. Official GPGS documentation for this constant
gpgs.ERROR_STATUS_SNAPSHOT_CREATION_FAILED
This constant is used in message.error_status table when MSG_LOAD_SNAPSHOT is STATUS_FAILED. Official GPGS documentation for this constant
gpgs.ERROR_STATUS_SNAPSHOT_CONTENTS_UNAVAILABLE
This constant is used in message.error_status table when MSG_LOAD_SNAPSHOT is STATUS_FAILED. Official GPGS documentation for this constant
gpgs.ERROR_STATUS_SNAPSHOT_COMMIT_FAILED
This constant is used in message.error_status table when MSG_LOAD_SNAPSHOT is STATUS_FAILED. Official GPGS documentation for this constant
gpgs.ERROR_STATUS_SNAPSHOT_FOLDER_UNAVAILABLE
This constant is used in message.error_status table when MSG_LOAD_SNAPSHOT is STATUS_FAILED. Official GPGS documentation for this constant
gpgs.ERROR_STATUS_SNAPSHOT_CONFLICT_MISSING
This constant is used in message.error_status table when MSG_LOAD_SNAPSHOT is STATUS_FAILED. Official GPGS documentation for this constant