Skip to Content
defold-typescript libraries
defold (official)

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)
    1. Pick a release from defold/extension-gpgs releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as gpgs from "gpgs"

Functions

gpgs.is_supported(): boolean

Check if Google Play Services are available & ready on the device.

if gpgs then
  local is_supported = gpgs.is_supported()
end

Returns

  • 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()
end

gpgs.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
end

gpgs.get_display_name(): string

Get the current GPGS player display name.

if gpgs then
  local name = gpgs.get_display_name()
end

Returns

  • 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()
end

Returns

  • 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()
end

Returns

  • 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 id gpgs.MSG_GET_SERVER_AUTH_CODE in callback set via gpgs.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()
end

Returns

  • 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
end

Parameters

  • callback: function — A callback taking the following parameters
    • self: object — The calling script
    • message_id: number — An message_id can be one of the predefined constants below
      • gpgs.MSG_SIGN_IN
      • gpgs.MSG_SILENT_SIGN_IN
      • gpgs.MSG_SHOW_SNAPSHOTS
      • gpgs.MSG_LOAD_SNAPSHOT
      • gpgs.MSG_SAVE_SNAPSHOT
      • gpgs.MSG_GET_ACHIEVEMENTS
      • gpgs.MSG_GET_TOP_SCORES
      • gpgs.MSG_GET_PLAYER_CENTERED_SCORES
      • gpgs.MSG_GET_PLAYER_SCORE
      • gpgs.MSG_GET_EVENTS
      • gpgs.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 with json.decode(). A successful player-score query returns the score fields directly. Other operations include status.
      • status?: number — Status of the current operation. It can be one of the predefined constants below
        • gpgs.STATUS_SUCCESS
        • gpgs.STATUS_FAILED
        • gpgs.STATUS_CREATE_NEW_SAVE
        • gpgs.STATUS_CONFLICT
      • error?: string — The error message. Available only if status is gpgs.STATUS_FAILED.
      • error_status?: number — The error code. Available only if status is gpgs.STATUS_FAILED and GPGS provide this code. It can be one of the predefined constants below
        • gpgs.ERROR_STATUS_SNAPSHOT_COMMIT_FAILED
        • gpgs.ERROR_STATUS_SNAPSHOT_CONFLICT_MISSING
        • gpgs.ERROR_STATUS_SNAPSHOT_CONTENTS_UNAVAILABLE
        • gpgs.ERROR_STATUS_SNAPSHOT_CREATION_FAILED
        • gpgs.ERROR_STATUS_SNAPSHOT_FOLDER_UNAVAILABLE
        • gpgs.ERROR_STATUS_SNAPSHOT_NOT_FOUND Or it can be ApiException.getStatusCode() (if ApiException was thrown)
      • code?: string — The one-time server auth code. Available only when message_id is gpgs.MSG_GET_SERVER_AUTH_CODE and status is gpgs.STATUS_SUCCESS.
      • metadata?: table — Metadata of the loaded save. Available only if message_id is gpgs.MSG_LOAD_SNAPSHOT.
      • conflictId?: string — The conflict id. Available only if status is gpgs.STATUS_CONFLICT.
      • conflictMetadata?: table — The conflicting metadata. Available only if status is gpgs.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)
end

Parameters

  • 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 default true.
  • allowDelete?: boolean — Whether or not to provide a delete overflow menu option for each snapshot in the selection UI. By default true.
  • 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)
end

Parameters

  • 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 — If true, 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 below
    • gpgs.RESOLUTION_POLICY_MANUAL
    • gpgs.RESOLUTION_POLICY_LONGEST_PLAYTIME
    • gpgs.RESOLUTION_POLICY_LAST_KNOWN_GOOD
    • gpgs.RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED
    • gpgs.RESOLUTION_POLICY_HIGHEST_PROGRESS
    Default value is 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
  })
end

Parameters

  • metadata?: table — A table with metadata for a save. It contains the fields below
    • playedTime?: 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 in png.

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
end

Returns

  • bytes: string — The byte array data of the currently opened snapshot. nil if 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
  end

Parameters

  • 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()
end

Returns

  • 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()
end

Returns

  • 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()
end

Returns

  • 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
end

Returns

  • bytes: string — The byte array data of the conflicting snapshot. nil if 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)
end

Parameters

  • conflictId: string — The conflict id that you want to resolve. Provided in message table with STATUS_CONFLICT message type.
  • snapshotId: number — Type of the snapshot you want to use for conflict solving that can be one of the predefined constants below
    • gpgs.SNAPSHOT_CURRENT
    • gpgs.SNAPSHOT_CONFLICTING

gpgs.leaderboard_submit_score(leaderboardId: string, score: number)

Submit a score to a leaderboard for the currently signed-in player.

Parameters

  • leaderboardId: string
  • score: 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: string
  • time_span: number — One of the gpgs.TIME_SPAN_ constants
  • collection: number — One of the gpgs.COLLECTION_ constants
  • max_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: string
  • time_span: number — One of the gpgs.TIME_SPAN_ constants
  • collection: number — One of the gpgs.COLLECTION_ constants
  • max_results: number — Between 1-25
  • force_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: string
  • time_span: number — One of the gpgs.TIME_SPAN_ constants
  • collection: 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: string
  • time_span: number — One of the gpgs.TIME_SPAN_ constants
  • collection: 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 name
  • description - achievement description
  • xp - how much experience points will be added when achievement will be unlocked
  • steps - current step of incremental achievement
  • total_steps - total amount of steps of incremental achievement
  • unlocked - set to true if achievement is unlocked. Otherwise field is missed.
  • hidden - set to `true if achievement is hidden. Otherwise field is missed.
  • revealed - set to true if 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 id
  • formatted_value - sum of all increments have been made to this event
  • value - the number of increments this user has made to this event
  • description - event's description
  • image - URI that can be used to load the event's image icon
  • name - event's name
  • visible - 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

On this page

Functionsgpgs.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()Constantsgpgs.RESOLUTION_POLICY_MANUALgpgs.RESOLUTION_POLICY_LONGEST_PLAYTIMEgpgs.RESOLUTION_POLICY_LAST_KNOWN_GOODgpgs.RESOLUTION_POLICY_MOST_RECENTLY_MODIFIEDgpgs.RESOLUTION_POLICY_HIGHEST_PROGRESSgpgs.TIME_SPAN_DAILYgpgs.TIME_SPAN_WEEKLYgpgs.TIME_SPAN_ALL_TIMEgpgs.COLLECTION_PUBLICgpgs.COLLECTION_FRIENDSgpgs.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_CODEgpgs.STATUS_SUCCESSgpgs.STATUS_FAILEDgpgs.STATUS_CREATE_NEW_SAVEgpgs.STATUS_CONFLICTgpgs.SNAPSHOT_CURRENTgpgs.SNAPSHOT_CONFLICTINGgpgs.ERROR_STATUS_SNAPSHOT_NOT_FOUNDgpgs.ERROR_STATUS_SNAPSHOT_CREATION_FAILEDgpgs.ERROR_STATUS_SNAPSHOT_CONTENTS_UNAVAILABLEgpgs.ERROR_STATUS_SNAPSHOT_COMMIT_FAILEDgpgs.ERROR_STATUS_SNAPSHOT_FOLDER_UNAVAILABLEgpgs.ERROR_STATUS_SNAPSHOT_CONFLICT_MISSING