Defold Google Play Game Services API documentation

This extension provides functions for interacting with Google Play Game Services. Supported on Android.

Usage

To use this library in your Defold project, add the following URL to your game.project dependencies:

https://github.com/defold/extension-gpgs/archive/master.zip

We recommend using a link to a zip file of a specific release.

Google App Setup

In order to use Google Play Game Services your application needs to be added to the Google Play store. It doesn’t have to be published but it must be registered. Read more about how to sign up for and use the Google Play store in the official documentation.

Once the application is registered you also need to enable Google Play Game Services for the application. Follow the official documentation to enable Google Play Game Services.

Defold Setup

game.project

Add the following section into your game.project file:

[gpgs]
app_id = 1234567890
use_saved_games = 1
request_server_auth_code = 0
request_id_token = 0

Where app_id is the 12 or 13 digit Application ID from the Google Play Console, found under Development Tools > Services & APIs and Google Play game services.</p>

Where use_saved_games indicates if the https://developers.google.com/games/services/common/concepts/savedgames should be used (0 is disabled, 1 is enabled).</p>

Source code

The source code is available on GitHub

API reference

Modules

gpgs

Functions and constants for interacting with Google Play Game Services (GPGS) APIs

Enums

gpgs.POPUP_POS_TOP_LEFT

The login popup position at the top-left corner.

gpgs.POPUP_POS_TOP_CENTER

The login popup position at the top-center.

gpgs.POPUP_POS_TOP_RIGHT

The login popup position at the top-right corner.

gpgs.POPUP_POS_CENTER_LEFT

The login popup position at the center-left.

gpgs.POPUP_POS_CENTER

The login popup position at the center of the screen.

gpgs.POPUP_POS_CENTER_RIGHT

The login popup position at the center-right.

gpgs.POPUP_POS_BOTTOM_LEFT

The login popup position at the bottom-left corner.

gpgs.POPUP_POS_BOTTOM_CENTER

The login popup position at the bottom-centre.

gpgs.POPUP_POS_BOTTOM_RIGHT

The login popup position at the bottom-right corner.

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

Official GPGS documentation

gpgs.TIME_SPAN_WEEKLY

Official GPGS documentation

gpgs.TIME_SPAN_ALL_TIME

Official GPGS documentation

gpgs.COLLECTION_PUBLIC

Official GPGS documentation

gpgs.COLLECTION_SOCIAL

Official GPGS documentation

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_SIGN_OUT

The message type that GPGS sends when finishing the asynchronous operation after calling gpgs.logout()

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_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.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


Functions

gpgs.login() Login to GPGS using a button.
gpgs.silent_login() Silent login to GPGS. This function is trying to retrieve the currently signe...
gpgs.logout() Logout from GPGS
gpgs.get_display_name() Get the current GPGS player display name.
gpgs.get_id() Get the current GPGS player id.
gpgs.get_id_token() Get the current GPGS player id token. Available only if "gpgs.client_id" is c...
gpgs.get_server_auth_code() Returns a one-time server auth code to send to your web server which can be e...
gpgs.is_logged_in() Check if a user is logged in currently.
gpgs.set_popup_position() This method sets the position for the login popup.
gpgs.set_callback() Set callback for receiving messages from GPGS.
gpgs.snapshot_display_saves() Provides a default saved games selection user interface.
gpgs.snapshot_open() Opens a snapshot with the given `saveName`. If `createIfNotFound` is set to `...
gpgs.snapshot_commit_and_close() Save the currently opened save on the server and close it.
gpgs.snapshot_get_data() Returns the currently opened snapshot data.
gpgs.snapshot_set_data() Sets the data for the currently opened snapshot.
gpgs.snapshot_is_opened() Check if a snapshot was opened.
gpgs.snapshot_get_max_image_size() Returns the maximum data size per snapshot cover image in bytes.
gpgs.snapshot_get_max_save_size() Returns the maximum data size per snapshot in bytes.
gpgs.snapshot_get_conflicting_data() Returns the conflicting snapshot data.
gpgs.snapshot_resolve_conflict() Resolves a conflict using the data from the provided snapshot.
gpgs.achievement_reveal() Reveals a hidden achievement to the currently signed-in player.
gpgs.achievement_unlock() Unlocks an achievement for the currently signed in player.
gpgs.achievement_set() Sets an achievement to have at least the given number of steps completed.
gpgs.achievement_increment() Increments an achievement by the given number of steps.
gpgs.achievement_show() Show all achievements for the currently signed-in player.
gpgs.achievement_get() Asynchronously gets all achievements for the currently signed-in player.
gpgs.leaderboard_submit_score() Submit a score to a leaderboard for the currently signed-in player.
gpgs.leaderboard_get_top_scores() Asynchronously gets the top page of scores for a leaderboard.
gpgs.leaderboard_get_player_centered_scores() Asynchronously gets a player-centered page of scores for a leaderboard.
gpgs.leaderboard_show() Show a leaderboard for a game specified by a leaderboardId.
gpgs.leaderboard_get_player_score() Asynchronously gets a player-centered page of scores for a leaderboard.
gpgs.event_increment() Increments an event specified by eventId by the given amount.
gpgs.event_get() Asynchronously gets all events.

gpgs.login()

Login to GPGS using a button.

Examples

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.

⚠️ By default login methods request GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN. But if you use Disk, we have to request extra scope Drive.SCOPE_APPFOLDER. Or if you use ID token, we have to request ID token with provided client_id. If so it causes the first time silent sign-in to fail, except for users who have already signed in successfully on a different device. Turn off GPGS features you don’t want to use in game.project.

Examples

function init(self)
  if gpgs then
    gpgs.silent_login()
  end
end

gpgs.logout()

Logout from GPGS

Examples

if gpgs then
  gpgs.logout()
end

gpgs.get_display_name()

Returns

Return value Type Description
name string

The player’s display name.

Get the current GPGS player display name.

Examples

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

gpgs.get_id()

Returns

Return value Type Description
id string

The player ID.

Get the current GPGS player id.

Examples

if gpgs then
  local id = gpgs.get_id()
end

gpgs.get_id_token()

Returns

Return value Type Description
id_token string

The player ID token.

Get the current GPGS player id token. Available only if “gpgs.client_id” is configured in game.project and “gpgs.request_id_token = 1”.

Examples

if gpgs then
  local id_token = gpgs.get_id_token()
end

gpgs.get_server_auth_code()

Returns

Return value Type Description
server_auth_code string

The server auth code for logged in account.

Returns a one-time server auth code to send to your web server which can be exchanged for access token

Examples

if gpgs then
  local server_auth_code = gpgs.get_server_auth_code()
end

gpgs.is_logged_in()

Returns

Return value Type Description
is_loggedin boolean

Current login state.

Check if a user is logged in currently.

Examples

if gpgs then
  local is_loggedin = gpgs.is_logged_in()
end

gpgs.set_popup_position(position)

Parameter Type Description
position number

An position can be one of the predefined constants below

  • gpgs.POPUP_POS_TOP_LEFT
  • gpgs.POPUP_POS_TOP_CENTER
  • gpgs.POPUP_POS_TOP_RIGHT
  • gpgs.POPUP_POS_CENTER_LEFT
  • gpgs.POPUP_POS_CENTER
  • gpgs.POPUP_POS_CENTER_RIGHT
  • gpgs.POPUP_POS_BOTTOM_LEFT
  • gpgs.POPUP_POS_BOTTOM_CENTER
  • gpgs.POPUP_POS_BOTTOM_RIGHT

Default value is gpgs.POPUP_POS_TOP_CENTER

This method sets the position for the login popup.

Examples

if gpgs then
  gpgs.set_popup_position(gpgs.POPUP_POS_BOTTOM_CENTER)
end

gpgs.set_callback(callback)

Parameter Type Description
callback function

A callback taking the following parameters

Parameter Type Description
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_SIGN_OUT
  • gpgs.MSG_SHOW_SNAPSHOTS
  • gpgs.MSG_LOAD_SNAPSHOT
message table

Contains information that depends on message_id.

  • 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 (optional) string -

    The error message. Available only if status is gpgs.STATUS_FAILED.

  • error_status (optional) 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
  • metadata (optional) table -

    Metadata of the loaded save. Available only if message_id is gpgs.MSG_LOAD_SNAPSHOT.

  • conflictId (optional) string -

    The conflict id. Available only if status is gpgs.STATUS_CONFLICT.

  • conflictMetadata (optional) table -

    The conflicting metadata. Available only if status is gpgs.STATUS_CONFLICT.

Set callback for receiving messages from GPGS.

Examples

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_SIGN_OUT then
  -- do something after logout
  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

gpgs.snapshot_display_saves(popupTitle, allowAddButton, allowDelete, maxNumberOfSavedGamesToShow)

Parameter Type Description
popupTitle (optional) string

The title to display in the action bar. By default “Game Saves”.

allowAddButton (optional) boolean

Whether or not to display a “create new snapshot” option in the selection UI. By default true.

allowDelete (optional) boolean

Whether or not to provide a delete overflow menu option for each snapshot in the selection UI. By default true.

maxNumberOfSavedGamesToShow (optional) number

The maximum number of snapshots to display in the UI. By default 5.

Provides a default saved games selection user interface.

Examples

if gpgs then
  gpgs.snapshot_display_saves("Choose the save of the game", false, true, 10)
end

gpgs.snapshot_open(saveName, createIfNotFound, conflictPolicy)

Parameter Type Description
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 (optional) boolean

If true, the snapshot will be created if one cannot be found.

conflictPolicy (optional) 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

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.

Examples

if gpgs then
  gpgs.snapshot_open("my_save_1", true, gpgs.RESOLUTION_POLICY_LONGEST_PLAYTIME)
end

gpgs.snapshot_commit_and_close(metadata)

Parameter Type Description
metadata (optional) table

A table with metadata for a save. It contains the fields below

  • playedTime (optional) number -

    The new played time to set for the snapshot in ms.

  • progressValue (optional) number -

    The new progress value to set for the snapshot.

  • description (optional) string -

    The new description to set for the snapshot.

  • coverImage (optional) object -

    The new cover image to set for the snapshot in png.

Save the currently opened save on the server and close it.

Examples

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

gpgs.snapshot_get_data()

Returns

Return value Type Description
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.

Returns the currently opened snapshot data.

Examples

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

gpgs.snapshot_set_data(data)

Parameter Type Description
data string

The data to set.

Returns

Return value Type Description
success boolean

True if data was set for the currently opened snapshot.

error_message string

An error message if something goes wrong.

Sets the data for the currently opened snapshot.

Examples

  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

gpgs.snapshot_is_opened()

Returns

Return value Type Description
is_opened boolean

A current snapshot state.

Check if a snapshot was opened.

Examples

if gpgs then
  local is_opened = gpgs.snapshot_is_opened()
end

gpgs.snapshot_get_max_image_size()

Returns

Return value Type Description
image_size number

The maximum data size per snapshot cover image in bytes.

Returns the maximum data size per snapshot cover image in bytes.

Examples

if gpgs then
  local image_size = gpgs.snapshot_get_max_image_size()
end

gpgs.snapshot_get_max_save_size()

Returns

Return value Type Description
data_size number

The maximum data size per snapshot in bytes.

Returns the maximum data size per snapshot in bytes.

Examples

if gpgs then
  local data_size = gpgs.snapshot_get_max_save_size()
end

gpgs.snapshot_get_conflicting_data()

Returns

Return value Type Description
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.

Returns the conflicting snapshot data.

Examples

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

gpgs.snapshot_resolve_conflict(conflictId, snapshotId)

Parameter Type Description
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

Resolves a conflict using the data from the provided snapshot.

Examples

if gpgs then
  gpgs.snapshot_resolve_conflict(self.conflictId, gpgs.SNAPSHOT_CONFLICTING)
end

gpgs.achievement_reveal(achievementId)

Parameter Type Description
achievementId string

Reveals a hidden achievement to the currently signed-in player.

gpgs.achievement_unlock(achievementId)

Parameter Type Description
achievementId string

Unlocks an achievement for the currently signed in player.

gpgs.achievement_set(value)

Parameter Type Description
value string

Sets an achievement to have at least the given number of steps completed.

gpgs.achievement_increment(value)

Parameter Type Description
value string

Increments an achievement by the given number of steps.

gpgs.achievement_show()

Show all achievements for the currently signed-in player.

gpgs.achievement_get()

Asynchronously gets all achievements for the currently signed-in player.

gpgs.leaderboard_submit_score(leaderboardId, score)

Parameter Type Description
leaderboardId string
score number

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

gpgs.leaderboard_get_top_scores(leaderboardId, time_span, collection, max_results)

Parameter Type Description
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

Asynchronously gets the top page of scores for a leaderboard.

gpgs.leaderboard_get_player_centered_scores(leaderboardId, time_span, collection, max_results)

Parameter Type Description
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

Asynchronously gets a player-centered page of scores for a leaderboard.

gpgs.leaderboard_show(leaderboardId, time_span, collection)

Parameter Type Description
leaderboardId string
time_span number

One of the gpgs.TIME_SPAN_ constants

collection number

One of the gpgs.COLLECTION_ constants

Show a leaderboard for a game specified by a leaderboardId.

gpgs.leaderboard_get_player_score(leaderboardId, time_span, collection)

Parameter Type Description
leaderboardId string
time_span number

One of the gpgs.TIME_SPAN_ constants

collection number

One of the gpgs.COLLECTION_ constants

Asynchronously gets a player-centered page of scores for a leaderboard.

gpgs.event_increment(eventId, amount)

Parameter Type Description
eventId string
amount number

Increments an event specified by eventId by the given amount.

gpgs.event_get()

Asynchronously gets all events.