gameNetwork.request()

command _^(required)

String. String value as supported by Google Play Game Services — see Command Reference below.

params _^(optional)

Table. Table of parameters allowed by Google Play Game Services — see Parameter Reference below.

gameNetwork.request( "setHighScore",
    {
        localPlayerScore = { category="Cy_sd893DEewf3", value=25 },
        listener = requestCallback
    }
)

• playerID (string)
• category (string)
• value (number)
• formattedValue (string) — The formatted value of the submitted score.

Load Scores

For the command parameter of "loadScores", this function retrieves scores based on various filters.

gameNetwork.request( "loadScores",
    {
        leaderboard =
        {
            category = "Cy_SLDWING4334h",
            playerScope = "Global",   -- Global, FriendsOnly
            timeScope = "AllTime",    -- AllTime, Week, Today
            range = { 1,5 },
            playerCentered = true
        },
        listener = requestCallback
    }
)

Inside the params table, leaderboard is a required table within which the following key-values apply:

• category — Required string that matches the name of the board from which you want to fetch scores.

• playerScope — Optional string of either "Global" or "FriendsOnly". The latter setting will restrict the fetched scores to people in the player's circles.

• timeScope — Optional string of either "AllTime", "Week", or "Today" which limits the fetched scores to a specified time range.

• range — Optional array of two integer values. For Google Play Game Services, the first value is ignored, while the second value represents the number of players to retrieve (no more than 25). The default range is { 1,25 }.

• playerCentered — Optional boolean value. If true, the call will return the scores that are centered around the currently logged-in user. If false, the call will simply return the top scores.

When handling the results of a "loadScores" call, event.data in the callback listener is an array of items (tables). Each contains the following properties:

• playerID (string)
• category (string)
• value (number)
• date (string)
• formattedValue (string)
• rank (integer)
• unixTime (integer)

event.data[1].playerID  --ID of the first player in the request
event.data[3].rank      --rank of the third player in the request

Load Local Player

For the command parameter of "loadLocalPlayer", this function requests data for the currently logged-in player.

gameNetwork.request( "loadLocalPlayer", { listener=requestCallback } )

When handling the results of a "loadLocalPlayer" call, event.data in the callback listener contains the following properties:

• playerID (string)
• alias (string)

event.data.playerID
event.data.alias

Load Players

For the command parameter of "loadPlayers", this function requests data for a list of players based on their player IDs.

gameNetwork.request( "loadPlayers",
    {
        playerIDs =
        {
            "45987354897345345",
            "32238975789573445",
            "17891241248435990"
        },
        listener = requestCallback
    }
)

When handling the results of a "loadPlayers" call, event.data in the callback listener is an array of items (tables). Each contains the following properties:

• playerID (string)
• alias (string)

event.data[1].playerID  --ID of the first player in the request
event.data[3].alias     --alias of the third player in the request

Load Friends

For the command parameter of "loadFriends", this function requests the friends of the currently logged-in player.

gameNetwork.request( "loadFriends", { listener=requestCallback } )

When handling the results of a "loadFriends" call, event.data in the callback listener is an array of items (tables) corresponding to each friend.

event.data[2].playerID
event.data[2].alias

Load Achievements / Load Achievement Descriptions

For the command parameter of "loadAchievements" or "loadAchievementDescriptions", this function loads a list of the player's completed achievements for the app.

gameNetwork.request( "loadAchievements", { listener=requestCallback } )

When handling the results of a "loadAchievements" or "loadAchievementDescriptions" call, event.data in the callback listener is an array of items (tables) representing each achievement. Each table contains the following properties:

• identifier (string)
• title (string)
• description (string)
• isCompleted (boolean)
• isHidden (boolean)
• lastReportedDate (number)

event.data[4].identifier   --identifier for the fourth achievement
event.data[2].description  --description of the second achievement 

Unlock Achievement

For the command parameter of "unlockAchievement", this function unlocks/sets the specified achievement (identifier).

gameNetwork.request( "unlockAchievement",
    {
        achievement =
        {
            identifier = "CY_w895w9w55w454"
        },
        listener = requestCallback
    }
)

Inside the params table, achievement is a required table wherein identifier (string) must match the name of the achievement you want to unlock/report, as entered in Google's developer console.

When handling the results of a "unlockAchievement" call, event.data in the callback listener contains an achievementId identifier (string).

Load Leaderboard Categories

For the command parameter of "loadLeaderboardCategories", this function requests a list of leaderboard categories for the app.

gameNetwork.request( "loadLeaderboardCategories", { listener=requestCallback } )

When handling the results of a "loadLeaderboardCategories" call, event.data is an array of items (tables). Each contains the following leaderboard properties:

• category (string)
• title (string)

event.data[1].category  --> "CY_a49t8h4t43t43t"
event.data[1].title     --> "Easy"

Is Connected

For the command parameter of "isConnected", this call checks if the user is currently logged into Google Play Game Services, returning true if the user is currently logged in and false if not. This function returns immediately with the result so there is no need to supply it with a callback listener.

Login

For the command parameter of "login", this function attempts to log the user into Google Play Game Services.

gameNetwork.request( "login",
    {
        userInitiated = true,
        listener = requestCallback
    }
)

Inside the params table, userInitated is a boolean with a default of true. When true, this call will try to resolve any problems with the login process by, for example, show the login popup. If it's set to false, this call will simply attempt to connect without trying to resolve any errors. Setting userInitated to false is useful for automatically logging the user in while avoiding a repetitive prompt for each session.

When handling the results of a "login" call, event.data in the callback listener contains an isError property (boolean) which indicates if there was an error with the login process.

Logout

For the command parameter of "logout", this call logs the user out of Google Play Game Services. This function does not accept a callback listener

gameNetwork.request( "logout" )

Create Room

For the command parameter of "createRoom", this function creates a real-time multiplayer match with the specified players. Specifying a listener function when calling this will override any room listener that was set via gameNetwork.setRoomListener().

local function requestCallback( event )
    print( event.data.roomID )  --ID of the room that was created
end

gameNetwork.request( "createRoom",
    {
        playerIDs =  --array of players to invite
        {
            "45987354897345345",
            "32238975789573445",
            "17891241248435990"
        },
        maxAutoMatchPlayers = 3,     --optional, defaults to 0
        minAutoMatchPlayers = 1,     --optional, defaults to 0
        listener = requestCallback   --including this will override any listener set in 'gameNetwork.setRoomListener()'
    }
)

Join Room

For the command parameter of "joinRoom", this function joins a room that has already been created. Specifying a listener function when calling this will override any room listener that was set via gameNetwork.setRoomListener().

Inside the params table, roomID is the ID which was created by gameNetwork.request( "createRoom", ... ).

local function requestCallback( event )
    print( event.data.roomID )  --ID of the room that was joined
end

gameNetwork.request( "joinRoom",
    {
        roomID = "o345t9348th",
        listener = requestCallback  --including this will override any listener set in 'gameNetwork.setRoomListener()'
    }
)

Leave Room

For the command parameter of "leaveRoom", this function leaves the room that the player is currently in and closes any connections. Specifying a listener function when calling this will override any room listener that was set via gameNetwork.setRoomListener().

local function requestCallback( event )
    print( event.data.roomID )  --ID of the room that was left
end

gameNetwork.request( "leaveRoom",
    {
        roomID = "o345t9348th",
        listener = requestCallback  --including this will override any listener set in 'gameNetwork.setRoomListener()'
    }
)

Set Room Listener

For the command parameter of "setRoomListener", this function sets the listener function that will be called when a room event occurs. Calling this will override any listener set from within a "createRoom", "joinRoom", or "leaveRoom" request. Note that this callback function may be triggered multiple times, for example if one player declines an invitation and then another person declines after that.

local function requestCallback( event )
    print( event.data.roomID )
    --print( event.data[1] )  --this will be populated if there are players involved in this event
end

gameNetwork.request( "setRoomListener",
    {
        listener = requestCallback
    }
)

When handling the results of a "setRoomListener" call, the event table is structured as follows:

• event.data (table) — Array which contains the list of players affected, for example event.data[1].alias or event.data[2].playerID.
• event.data.roomID (string) — Room ID on which this event occurred.
• event.data.isError (boolean) — Boolean indicating if there was an error.
• event.type — (see below)

In addition to the data above, event.type includes:

• createRoom — The logged in player created a room.
• joinRoom — The logged in player joined a room.
• leaveRoom — The logged in player left the room.
• connectedRoom — All invited players have accepted and the auto matchmaking has completed.
• peerAcceptedInvitation — The list of players who accepted an invitation to join the room.
• peerDeclinedInvitation — The list of players who declined an invitation to join the room.
• peerLeftRoom — The list of players who left the room.
• peerDisconnectedFromRoom — The list of players who disconnected from the room.

Send Message

For the command parameter of "sendMessage", this function sends a message to other player(s).

gameNetwork.request( "sendMessage",
    {
        roomID = "o345t9348th",
        playerIDs =
        {
            "45987354897345345",
            "32238975789573445",
            "17891241248435990"
        },
        message = "Get ready!",
        reliable = true,
        listener = requestCallback
    }
)

Inside the params table, the following key-values apply:

• roomID (string) — ID of the room that the other player(s) are in.
• playerIDs (table) — Array of players to send the message to.
• message (string) — Message to send.
• reliable (boolean) — Optional parameter which, if true, sends a reliable message. Messages can be dropped if they're not reliable but they will reach other players faster. Default is true.

Set Message Received Listener

For the command parameter of "setMessageReceivedListener", this function sets the listener function that will be called when a message has been received. This function will only be called for messages transmitted to the room that the current player is connected to.

local function requestCallback( event )
    print( event.data.participantID )
    print( event.data.message )
end

gameNetwork.request( "setMessageReceivedListener",
    {
        listener = requestCallback
    }
)

When handling the results of a "setMessageReceivedListener" call, event.data in the callback listener contains the following properties:

• participantID (string) — ID of the participant who sent the message.
• message (string) — The message that was sent from the participant.

Set Invitation Received Listener

For the command parameter of "setInvitationReceivedListener", this function sets the listener function that will be called when an invitation has been received.

local function requestCallback( event )
    print( event.data.roomID )
    print( event.data.alias )
    print( event.data.playerID )
end

gameNetwork.request( "setInvitationReceivedListener",
    {
        listener = requestCallback
    }
)

When handling the results of a "setInvitationReceivedListener" call, event.data in the callback listener contains the following properties:

• roomID (string) — Room ID associated with the invitation.
• alias (string) — Alias of the player who invited you.
• playerID (string) — ID of the player who invited you.