gpgs.script_api

- name: gpgs
  type: table
  desc: Functions and constants for interacting with Google Play Game Services (GPGS) APIs

  members:

#*****************************************************************************************************

  - name: is_supported
    type: function
    desc: Check if Google Play Services are available & ready on the device.

    returns:
      - name: is_supported
        type: boolean
        desc: Status of Google Play Services on the device.

    examples:
      - desc: |-
            ```lua
            if gpgs then
              local is_supported = gpgs.is_supported()
            end
            ```

#*****************************************************************************************************

  - name: login
    type: function
    desc: Login to GPGS using a button.

    examples:
      - desc: |-
            Log in to GPGS using a button:
            ```lua
            if gpgs then
              gpgs.login()
            end
            ```

#*****************************************************************************************************

  - name: silent_login
    type: function
    desc: 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`.

    examples:
      - desc: |-
            ```lua
            function init(self)
              if gpgs then
                gpgs.silent_login()
              end
            end
            ```

#*****************************************************************************************************

  - name: logout
    type: function
    desc: Logout from GPGS

    examples:
      - desc: |-
            ```lua
            if gpgs then
              gpgs.logout()
            end
            ```

#*****************************************************************************************************

  - name: get_display_name
    type: function
    desc: Get the current GPGS player display name.

    returns:
      - name: name
        type: string
        desc: The player's display name.

    examples:
      - desc: |-
            ```lua
            if gpgs then
              local name = gpgs.get_display_name()
            end
            ```

#*****************************************************************************************************

  - name: get_id
    type: function
    desc: Get the current GPGS player id.

    returns:
      - name: id
        type: string
        desc: The player ID.

    examples:
      - desc: |-
            ```lua
            if gpgs then
              local id = gpgs.get_id()
            end
            ```

#*****************************************************************************************************

  - name: get_id_token
    type: function
    desc: Get the current GPGS player id token. Available only if "gpgs.client_id" is configured in game.project
          and "gpgs.request_id_token = 1".

    returns:
      - name: id_token
        type: string
        desc: The player ID token.

    examples:
      - desc: |-
            ```lua
            if gpgs then
              local id_token = gpgs.get_id_token()
            end
            ```

#*****************************************************************************************************

  - name: get_server_auth_code
    type: function
    desc: Returns a one-time server auth code to send to your web server which can be exchanged for access token

    returns:
      - name: server_auth_code
        type: string
        desc: The server auth code for logged in account.

    examples:
      - desc: |-
            ```lua
            if gpgs then
              local server_auth_code = gpgs.get_server_auth_code()
            end
            ```

#*****************************************************************************************************

  - name: is_logged_in
    type: function
    desc: Check if a user is logged in currently.

    returns:
      - name: is_loggedin
        type: boolean
        desc: Current login state.

    examples:
      - desc: |-
            ```lua
            if gpgs then
              local is_loggedin = gpgs.is_logged_in()
            end
            ```

#*****************************************************************************************************

  - name: set_popup_position
    type: function
    desc: This method sets the position for the login popup.

    parameters:
      - name: position
        type: number
        desc: 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:
      - desc: |-
            ```lua
            if gpgs then
              gpgs.set_popup_position(gpgs.POPUP_POS_BOTTOM_CENTER)
            end
            ```

#*****************************************************************************************************

  - name: set_callback
    type: function
    desc: Set callback for receiving messages from GPGS.

    parameters:
      - name: callback
        type: function
        desc: A callback taking the following parameters
        parameters:
          - name: self
            type: object
            desc: The calling script

          - name: message_id
            type: number
            desc: 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`

              - `gpgs.MSG_SAVE_SNAPSHOT`


          - name: message
            type: table
            desc: Contains information that depends on message_id.
            members:
            - name: status
              type: number
              desc: 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`

            - name: error
              type: string
              optional: true
              desc: The error message. Available only if `status` is `gpgs.STATUS_FAILED`.

            - name: error_status
              type: number
              optional: true
              desc: 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)

            - name: metadata
              type: table
              optional: true
              desc: Metadata of the loaded save. Available only if `message_id` is `gpgs.MSG_LOAD_SNAPSHOT`.

            - name: conflictId
              type: string
              optional: true
              desc: The conflict id. Available only if `status` is `gpgs.STATUS_CONFLICT`.

            - name: conflictMetadata
              type: table
              optional: true
              desc: The conflicting metadata. Available only if `status` is `gpgs.STATUS_CONFLICT`.

    examples:
      - desc: |-
            ```lua
            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
            ```

#*****************************************************************************************************

  - name: snapshot_display_saves
    type: function
    desc: Provides a default saved games selection user interface.

    parameters:
      - name: popupTitle
        type: string
        optional: true
        desc: The title to display in the action bar. By default "Game Saves".

      - name: allowAddButton
        type: boolean
        optional: true
        desc: Whether or not to display a "create new snapshot" option in the selection UI. By default `true`.

      - name: allowDelete
        type: boolean
        optional: true
        desc: Whether or not to provide a delete overflow menu option for each snapshot in the selection UI. By default `true`.

      - name: maxNumberOfSavedGamesToShow
        type: number
        optional: true
        desc: The maximum number of snapshots to display in the UI. By default 5.

    examples:
      - desc: |-
            ```lua
            if gpgs then
              gpgs.snapshot_display_saves("Choose the save of the game", false, true, 10)
            end
            ```

#*****************************************************************************************************

  - name: snapshot_open
    type: function
    desc: 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:
      - name: saveName
        type: string
        desc: 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 "~").

      - name: createIfNotFound
        type: boolean
        optional: true
        desc: If `true`, the snapshot will be created if one cannot be found.

      - name: conflictPolicy
        type: number
        optional: true
        desc: 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:
      - desc: |-
            ```lua
            if gpgs then
              gpgs.snapshot_open("my_save_1", true, gpgs.RESOLUTION_POLICY_LONGEST_PLAYTIME)
            end
            ```

#*****************************************************************************************************

  - name: snapshot_commit_and_close
    type: function
    desc: Save the currently opened save on the server and close it.

    parameters:
      - name: metadata
        type: table
        optional: true
        desc: A table with metadata for a save. It contains the fields below
        members:
          - name: playedTime
            type: number
            optional: true
            desc: The new played time to set for the snapshot in ms.

          - name: progressValue
            type: number
            optional: true
            desc: The new progress value to set for the snapshot.

          - name: description
            type: string
            optional: true
            desc: The new description to set for the snapshot.

          - name: coverImage
            type: object
            optional: true
            desc: The new cover image to set for the snapshot in `png`.


    examples:
    - desc: |-
            ```lua
            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
            ```

#*****************************************************************************************************

  - name: snapshot_get_data
    type: function
    desc: Returns the currently opened snapshot data.

    returns:
      - name: bytes
        type: string
        desc: The byte array data of the currently opened snapshot. `nil` if something goes wrong.

      - name: error_message
        type: string
        desc: An error message if something goes wrong.

    examples:
      - desc: |-
            ```lua
            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
            ```

#*****************************************************************************************************

  - name: snapshot_set_data
    type: function
    desc: Sets the data for the currently opened snapshot.

    parameters:
      - name: data
        type: string
        desc: The data to set.

    returns:
      - name: success
        type: boolean
        desc: True if data was set for the currently opened snapshot.

      - name: error_message
        type: string
        desc: An error message if something goes wrong.

    examples:
      - desc: |-
            ```lua
              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
            ```

#*****************************************************************************************************

  - name: snapshot_is_opened
    type: function
    desc: Check if a snapshot was opened.

    returns:
      - name: is_opened
        type: boolean
        desc: A current snapshot state.

    examples:
      - desc: |-
            ```lua
            if gpgs then
              local is_opened = gpgs.snapshot_is_opened()
            end
            ```

#*****************************************************************************************************

  - name: snapshot_get_max_image_size
    type: function
    desc: Returns the maximum data size per snapshot cover image in bytes.

    returns:
      - name: image_size
        type: number
        desc: The maximum data size per snapshot cover image in bytes.

    examples:
      - desc: |-
            ```lua
            if gpgs then
              local image_size = gpgs.snapshot_get_max_image_size()
            end
            ```

#*****************************************************************************************************

  - name: snapshot_get_max_save_size
    type: function
    desc: Returns the maximum data size per snapshot in bytes.

    returns:
      - name: data_size
        type: number
        desc: The maximum data size per snapshot in bytes.

    examples:
      - desc: |-
            ```lua
            if gpgs then
              local data_size = gpgs.snapshot_get_max_save_size()
            end
            ```

#*****************************************************************************************************

  - name: snapshot_get_conflicting_data
    type: function
    desc: Returns the conflicting snapshot data.

    returns:
      - name: bytes
        type: string
        desc: The byte array data of the conflicting snapshot. `nil` if something goes wrong.

      - name: error_message
        type: boolean
        desc: An error message if something goes wrong.

    examples:
      - desc: |-
            ```lua
            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
            ```

#*****************************************************************************************************

  - name: snapshot_resolve_conflict
    type: function
    desc: Resolves a conflict using the data from the provided snapshot.

    parameters:
      - name: conflictId
        type: string
        desc: The conflict id that you want to resolve. Provided in `message` table with `STATUS_CONFLICT` message type.

      - name: snapshotId
        type: number
        desc: 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:
      - desc: |-
            ```lua
            if gpgs then
              gpgs.snapshot_resolve_conflict(self.conflictId, gpgs.SNAPSHOT_CONFLICTING)
            end
            ```
#*****************************************************************************************************

  - name: leaderboard_submit_score
    type: function
    desc: Submit a score to a leaderboard for the currently signed-in player.

    parameters:
      - name: leaderboardId
        type: string

      - name: score
        type: number

#*****************************************************************************************************

  - name: leaderboard_get_top_scores
    type: function
    desc: Asynchronously gets the top page of scores for a leaderboard.

    parameters:
      - name: leaderboardId
        type: string

      - name: time_span
        type: number
        desc: One of the gpgs.TIME_SPAN_ constants

      - name: collection
        type: number
        desc: One of the gpgs.COLLECTION_ constants

      - name: max_results
        type: number
        desc: Between 1-25

#*****************************************************************************************************

  - name: leaderboard_get_player_centered_scores
    type: function
    desc: Asynchronously gets a player-centered page of scores for a leaderboard.

    parameters:
      - name: leaderboardId
        type: string

      - name: time_span
        type: number
        desc: One of the gpgs.TIME_SPAN_ constants

      - name: collection
        type: number
        desc: One of the gpgs.COLLECTION_ constants

      - name: max_results
        type: number
        desc: Between 1-25

#*****************************************************************************************************

  - name: leaderboard_show
    type: function
    desc: Show a leaderboard for a game specified by a leaderboardId.

    parameters:
      - name: leaderboardId
        type: string

      - name: time_span
        type: number
        desc: One of the gpgs.TIME_SPAN_ constants

      - name: collection
        type: number
        desc: One of the gpgs.COLLECTION_ constants

#*****************************************************************************************************

  - name: leaderboard_list
    type: function
    desc: Show the list of leaderboards.

#*****************************************************************************************************
  - name: leaderboard_get_player_score
    type: function
    desc: Asynchronously gets a player-centered page of scores for a leaderboard.

    parameters:
      - name: leaderboardId
        type: string

      - name: time_span
        type: number
        desc: One of the gpgs.TIME_SPAN_ constants

      - name: collection
        type: number
        desc: One of the gpgs.COLLECTION_ constants

#*****************************************************************************************************

  - name: achievement_reveal
    type: function
    desc: Reveal achievement

    parameters:
      - name: achievementId
        type: string

#*****************************************************************************************************
  - name: achievement_unlock
    type: function
    desc: Unlock achievement

    parameters:
      - name: achievementId
        type: string

#*****************************************************************************************************
  - name: achievement_set
    type: function
    desc: Set achievement progress

    parameters:
      - name: achievementId
        type: string

      - name: steps
        type: number

#*****************************************************************************************************
  - name: achievement_increment
    type: function
    desc: Increase achievement progress

    parameters:
      - name: achievementId
        type: string

      - name: steps
        type: number

#*****************************************************************************************************
  - name: achievement_show
    type: function
    desc: Show achivements

#*****************************************************************************************************
  - name: achievement_get
    type: function

#*****************************************************************************************************
  - name: event_increment
    type: function

    parameters:
      - name: eventId
        type: string

      - name: amount
        type: number

#*****************************************************************************************************
  - name: event_get
    type: function

#*****************************************************************************************************

  - name: POPUP_POS_TOP_LEFT
    type: number
    desc: The login popup position at the top-left corner.

  - name: POPUP_POS_TOP_CENTER
    type: number
    desc: The login popup position at the top-center.

  - name: POPUP_POS_TOP_RIGHT
    type: number
    desc: The login popup position at the top-right corner.

  - name: POPUP_POS_CENTER_LEFT
    type: number
    desc: The login popup position at the center-left.

  - name: POPUP_POS_CENTER
    type: number
    desc: The login popup position at the center of the screen.

  - name: POPUP_POS_CENTER_RIGHT
    type: number
    desc: The login popup position at the center-right.

  - name: POPUP_POS_BOTTOM_LEFT
    type: number
    desc: The login popup position at the bottom-left corner.

  - name: POPUP_POS_BOTTOM_CENTER
    type: number
    desc: The login popup position at the bottom-centre.

  - name: POPUP_POS_BOTTOM_RIGHT
    type: number
    desc: The login popup position at the bottom-right corner.

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

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

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

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

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

  - name: MSG_SIGN_IN
    type: number
    desc: The message type that GPGS sends when finishing the asynchronous operation
          after calling `gpgs.login()`

  - name: MSG_SILENT_SIGN_IN
    type: number
    desc: The message type that GPGS sends when finishing the asynchronous operation
          after calling `gpgs.silent_login()`

  - name: MSG_SIGN_OUT
    type: number
    desc: The message type that GPGS sends when finishing the asynchronous operation
          after calling `gpgs.logout()`

  - name: MSG_SHOW_SNAPSHOTS
    type: number
    desc: The message type that GPGS sends when finishing the asynchronous operation
          after calling `gpgs.snapshot_display_saves()`

  - name: MSG_LOAD_SNAPSHOT
    type: number
    desc: The message type that GPGS sends when finishing the asynchronous operation
          after calling `gpgs.snapshot_open()`

  - name: MSG_SAVE_SNAPSHOT
    type: number
    desc: The message type that GPGS sends when finishing the asynchronous operation
          after calling `gpgs.snapshot_commit_and_close()`

  - name: STATUS_SUCCESS
    type: number
    desc: An operation success.

  - name: STATUS_FAILED
    type: number
    desc: An operation failed. Check the error field in the massage table.

  - name: STATUS_CREATE_NEW_SAVE
    type: number
    desc: 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.

  - name: STATUS_CONFLICT
    type: number
    desc: 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()'.

  - name: SNAPSHOT_CURRENT
    type: number
    desc: 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.

  - name: SNAPSHOT_CONFLICTING
    type: number
    desc: 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.

  - name: ERROR_STATUS_SNAPSHOT_NOT_FOUND
    type: number
    desc: 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

  - name: ERROR_STATUS_SNAPSHOT_CREATION_FAILED
    type: number
    desc: 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

  - name: ERROR_STATUS_SNAPSHOT_CONTENTS_UNAVAILABLE
    type: number
    desc: 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

  - name: ERROR_STATUS_SNAPSHOT_COMMIT_FAILED
    type: number
    desc: 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

  - name: ERROR_STATUS_SNAPSHOT_FOLDER_UNAVAILABLE
    type: number
    desc: 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

  - name: ERROR_STATUS_SNAPSHOT_CONFLICT_MISSING
    type: number
    desc: 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