gpgs

Version: stable

FUNCTION
login()
silent_login()
logout()
get_display_name()
get_id()
get_id_token()
get_server_auth_code()
is_logged_in()
set_popup_position()
set_callback()
snapshot_display_saves()
snapshot_open()
snapshot_commit_and_close()
snapshot_get_data()
snapshot_set_data()
snapshot_is_opened()
snapshot_get_max_image_size()
snapshot_get_max_save_size()
snapshot_get_conflicting_data()
snapshot_resolve_conflict()
leaderboard_submit_score()
leaderboard_get_top_scores()
leaderboard_get_player_centered_scores()
leaderboard_show()
leaderboard_list()
leaderboard_get_player_score()
CONSTANT
POPUP_POS_TOP_LEFT
POPUP_POS_TOP_CENTER
POPUP_POS_TOP_RIGHT
POPUP_POS_CENTER_LEFT
POPUP_POS_CENTER
POPUP_POS_CENTER_RIGHT
POPUP_POS_BOTTOM_LEFT
POPUP_POS_BOTTOM_CENTER
POPUP_POS_BOTTOM_RIGHT
RESOLUTION_POLICY_MANUAL
RESOLUTION_POLICY_LONGEST_PLAYTIME
RESOLUTION_POLICY_LAST_KNOWN_GOOD
RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED
RESOLUTION_POLICY_HIGHEST_PROGRESS
MSG_SIGN_IN
MSG_SILENT_SIGN_IN
MSG_SIGN_OUT
MSG_SHOW_SNAPSHOTS
MSG_LOAD_SNAPSHOT
STATUS_SUCCESS
STATUS_FAILED
STATUS_CREATE_NEW_SAVE
STATUS_CONFLICT
SNAPSHOT_CURRENT
SNAPSHOT_CONFLICTING
ERROR_STATUS_SNAPSHOT_NOT_FOUND
ERROR_STATUS_SNAPSHOT_CREATION_FAILED
ERROR_STATUS_SNAPSHOT_CONTENTS_UNAVAILABLE
ERROR_STATUS_SNAPSHOT_COMMIT_FAILED
ERROR_STATUS_SNAPSHOT_FOLDER_UNAVAILABLE
ERROR_STATUS_SNAPSHOT_CONFLICT_MISSING

Functions

login()

login()

Login to GPGS using a button.

PARAMETERS

EXAMPLES

Log in to GPGS using a button:

if gpgs then
  gpgs.login()
end

silent_login()

silent_login()

Silent login to GPGS. This function is trying to retrieve the currently signed-in player’s account. [icon:attention] 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`.

PARAMETERS

EXAMPLES

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

logout()

logout()

Logout from GPGS

PARAMETERS

EXAMPLES

if gpgs then
  gpgs.logout()
end

get_display_name()

get_display_name()

Get the current GPGS player display name.

PARAMETERS

RETURNS

string The player's display name.

EXAMPLES

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

get_id()

get_id()

Get the current GPGS player id.

PARAMETERS

RETURNS

string The player ID.

EXAMPLES

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

get_id_token()

get_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".

PARAMETERS

RETURNS

string The player ID token.

EXAMPLES

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

get_server_auth_code()

get_server_auth_code()

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

PARAMETERS

RETURNS

string The server auth code for logged in account.

EXAMPLES

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

is_logged_in()

is_logged_in()

Check if a user is logged in currently.

PARAMETERS

RETURNS

boolean Current login state.

EXAMPLES

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

set_popup_position()

set_popup_position(position)

This method sets the position for the login popup.

PARAMETERS

position 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`

EXAMPLES

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

set_callback()

set_callback(callback)

Set callback for receiving messages from GPGS.

PARAMETERS

callback A callback taking the following parameters

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

snapshot_display_saves()

snapshot_display_saves(popupTitle,allowAddButton,allowDelete,maxNumberOfSavedGamesToShow)

Provides a default saved games selection user interface.

PARAMETERS

popupTitle The title to display in the action bar. By default "Game Saves".
allowAddButton Whether or not to display a "create new snapshot" option in the selection UI. By default `true`.
allowDelete Whether or not to provide a delete overflow menu option for each snapshot in the selection UI. By default `true`.
maxNumberOfSavedGamesToShow The maximum number of snapshots to display in the UI. By default 5.

EXAMPLES

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

snapshot_open()

snapshot_open(saveName,createIfNotFound,conflictPolicy)

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.

PARAMETERS

saveName 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 If `true`, the snapshot will be created if one cannot be found.
conflictPolicy 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`

EXAMPLES

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

snapshot_commit_and_close()

snapshot_commit_and_close(metadata)

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

PARAMETERS

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

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

snapshot_get_data()

snapshot_get_data()

Returns the currently opened snapshot data.

PARAMETERS

RETURNS

string The byte array data of the currently opened snapshot. `nil` if something goes wrong.
string An error message if something goes wrong.

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

snapshot_set_data()

snapshot_set_data(data)

Sets the data for the currently opened snapshot.

PARAMETERS

data The data to set.

RETURNS

boolean True if data was set for the currently opened snapshot.
string An error message if something goes wrong.

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

snapshot_is_opened()

snapshot_is_opened()

Check if a snapshot was opened.

PARAMETERS

RETURNS

boolean A current snapshot state.

EXAMPLES

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

snapshot_get_max_image_size()

snapshot_get_max_image_size()

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

PARAMETERS

RETURNS

number The maximum data size per snapshot cover image in bytes.

EXAMPLES

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

snapshot_get_max_save_size()

snapshot_get_max_save_size()

Returns the maximum data size per snapshot in bytes.

PARAMETERS

RETURNS

number The maximum data size per snapshot in bytes.

EXAMPLES

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

snapshot_get_conflicting_data()

snapshot_get_conflicting_data()

Returns the conflicting snapshot data.

PARAMETERS

RETURNS

string The byte array data of the conflicting snapshot. `nil` if something goes wrong.
boolean An error message if something goes wrong.

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

snapshot_resolve_conflict()

snapshot_resolve_conflict(conflictId,snapshotId)

Resolves a conflict using the data from the provided snapshot.

PARAMETERS

conflictId The conflict id that you want to resolve. Provided in `message` table with `STATUS_CONFLICT` message type.
snapshotId 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`

EXAMPLES

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

leaderboard_submit_score()

leaderboard_submit_score(leaderboardId,score)

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

PARAMETERS

leaderboardId
score

leaderboard_get_top_scores()

leaderboard_get_top_scores(leaderboardId,time_span,collection,max_results)

Asynchronously gets the top page of scores for a leaderboard.

PARAMETERS

leaderboardId
time_span One of the gpgs.TIME_SPAN_ constants
collection One of the gpgs.COLLECTION_ constants
max_results Between 1-25

leaderboard_get_player_centered_scores()

leaderboard_get_player_centered_scores(leaderboardId,time_span,collection,max_results)

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

PARAMETERS

leaderboardId
time_span One of the gpgs.TIME_SPAN_ constants
collection One of the gpgs.COLLECTION_ constants
max_results Between 1-25

leaderboard_show()

leaderboard_show(leaderboardId,time_span,collection)

Show a leaderboard for a game specified by a leaderboardId.

PARAMETERS

leaderboardId
time_span One of the gpgs.TIME_SPAN_ constants
collection One of the gpgs.COLLECTION_ constants

leaderboard_list()

leaderboard_list()

Show the list of leaderboards.

PARAMETERS


leaderboard_get_player_score()

leaderboard_get_player_score(leaderboardId,time_span,collection)

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

PARAMETERS

leaderboardId
time_span One of the gpgs.TIME_SPAN_ constants
collection One of the gpgs.COLLECTION_ constants

Constants

POPUP_POS_TOP_LEFT

The login popup position at the top-left corner.


POPUP_POS_TOP_CENTER

The login popup position at the top-center.


POPUP_POS_TOP_RIGHT

The login popup position at the top-right corner.


POPUP_POS_CENTER_LEFT

The login popup position at the center-left.


POPUP_POS_CENTER

The login popup position at the center of the screen.


POPUP_POS_CENTER_RIGHT

The login popup position at the center-right.


POPUP_POS_BOTTOM_LEFT

The login popup position at the bottom-left corner.


POPUP_POS_BOTTOM_CENTER

The login popup position at the bottom-centre.


POPUP_POS_BOTTOM_RIGHT

The login popup position at the bottom-right corner.


RESOLUTION_POLICY_MANUAL

Official [GPGS documentation](https://developers.google.com/android/reference/com/google/android/gms/games/SnapshotsClient.html#RESOLUTION_POLICY_MANUAL) for this constant


RESOLUTION_POLICY_LONGEST_PLAYTIME

Official [GPGS documentation](https://developers.google.com/android/reference/com/google/android/gms/games/SnapshotsClient.html#RESOLUTION_POLICY_LONGEST_PLAYTIME) for this constant


RESOLUTION_POLICY_LAST_KNOWN_GOOD

Official [GPGS documentation](https://developers.google.com/android/reference/com/google/android/gms/games/SnapshotsClient.html#RESOLUTION_POLICY_LAST_KNOWN_GOOD) for this constant


RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED

Official [GPGS documentation](https://developers.google.com/android/reference/com/google/android/gms/games/SnapshotsClient.html#RESOLUTION_POLICY_MOST_RECENTLY_MODIFIED) for this constant


RESOLUTION_POLICY_HIGHEST_PROGRESS

Official [GPGS documentation](https://developers.google.com/android/reference/com/google/android/gms/games/SnapshotsClient.html#RESOLUTION_POLICY_HIGHEST_PROGRESS) for this constant


MSG_SIGN_IN

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


MSG_SILENT_SIGN_IN

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


MSG_SIGN_OUT

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


MSG_SHOW_SNAPSHOTS

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


MSG_LOAD_SNAPSHOT

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


STATUS_SUCCESS

An operation success.


STATUS_FAILED

An operation failed. Check the error field in the massage table.


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.


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()'.


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.


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.


ERROR_STATUS_SNAPSHOT_NOT_FOUND

This constant is used in `message.error_status` table when `MSG_LOAD_SNAPSHOT` is `STATUS_FAILED`. [Official GPGS documentation](https://developers.google.com/android/reference/com/google/android/gms/games/GamesStatusCodes.html#STATUS_SNAPSHOT_NOT_FOUND) for this constant


ERROR_STATUS_SNAPSHOT_CREATION_FAILED

This constant is used in `message.error_status` table when `MSG_LOAD_SNAPSHOT` is `STATUS_FAILED`. [Official GPGS documentation](https://developers.google.com/android/reference/com/google/android/gms/games/GamesStatusCodes.html#STATUS_SNAPSHOT_CREATION_FAILED) for this constant


ERROR_STATUS_SNAPSHOT_CONTENTS_UNAVAILABLE

This constant is used in `message.error_status` table when `MSG_LOAD_SNAPSHOT` is `STATUS_FAILED`. [Official GPGS documentation](https://developers.google.com/android/reference/com/google/android/gms/games/GamesStatusCodes.html#STATUS_SNAPSHOT_CONTENTS_UNAVAILABLE) for this constant


ERROR_STATUS_SNAPSHOT_COMMIT_FAILED

This constant is used in `message.error_status` table when `MSG_LOAD_SNAPSHOT` is `STATUS_FAILED`. [Official GPGS documentation](https://developers.google.com/android/reference/com/google/android/gms/games/GamesStatusCodes.html#STATUS_SNAPSHOT_COMMIT_FAILED) for this constant


ERROR_STATUS_SNAPSHOT_FOLDER_UNAVAILABLE

This constant is used in `message.error_status` table when `MSG_LOAD_SNAPSHOT` is `STATUS_FAILED`. [Official GPGS documentation](https://developers.google.com/android/reference/com/google/android/gms/games/GamesStatusCodes.html#STATUS_SNAPSHOT_FOLDER_UNAVAILABLE) for this constant


ERROR_STATUS_SNAPSHOT_CONFLICT_MISSING

This constant is used in `message.error_status` table when `MSG_LOAD_SNAPSHOT` is `STATUS_FAILED`. [Official GPGS documentation](https://developers.google.com/android/reference/com/google/android/gms/games/GamesStatusCodes.html#STATUS_SNAPSHOT_CONFLICT_MISSING) for this constant