Type Function Library gameNetwork.* Return value none Revision Release 2024.3703 Keywords gameNetwork, Google Play Game Services See also gameNetwork.init() gameNetwork.show()
Send or request information to/from Google Play Game Services.
gameNetwork.request( command [, params] )
String. String value as supported by Google Play Game Services — see Command Reference below.
Table. Table of parameters allowed by Google Play Game Services — see Parameter Reference below.
For the command
parameter, Google Play Game Services supports the following values:
"setHighScore"
"loadScores"
"loadLocalPlayer"
"loadPlayers"
"loadFriends"
"loadAchievements"
"unlockAchievement"
"loadAchievementDescriptions"
"loadLeaderboardCategories"
"isConnected"
"login"
"logout"
"createRoom"
"joinRoom"
"leaveRoom"
"setRoomListener"
"sendMessage"
"setMessageReceivedListener"
"setInvitationReceivedListener"
Depending on the specified command
parameter, the contents of the params
table will vary.
For most calls to gameNetwork.request()
, the params
table supports a listener
key with its value as a callback listener function to monitor the call result. In the callback listener, event.type
indicates the request that was executed, along with other data specific to each request type as outlined below.
local function requestCallback( event ) if ( event.type == "setHighScore" ) then --high score has been set end end gameNetwork.request( "setHighScore", { localPlayerScore = { category="Cy_sd893DEewf3", value=25 }, listener = requestCallback } )
For the command
parameter of "setHighScore"
, this function sets a high score for the currently category
). If the high score is not higher than the one currently on the server, the server will keep the highest value.
gameNetwork.request( "setHighScore", { localPlayerScore = { category="Cy_sd893DEewf3", value=25 }, listener = requestCallback } )
In the params
table, localPlayerScore
is a required table within which the following
category
— String that matches the ID of the leaderboard you want to register the score with as entered in Google's developer console.
value
— Number representing the score.
When handling the results of a "setHighScore"
call, event.data
in the callback listener is an array of items (tables). Each contains the following properties:
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
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 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
For the command
parameter of "loadLocalPlayer"
, this function requests data for the currently
gameNetwork.request( "loadLocalPlayer", { listener=requestCallback } )
When handling the results of a "loadLocalPlayer"
call, event.data
in the callback listener contains the following properties:
event.data.playerID event.data.alias
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:
event.data[1].playerID --ID of the first player in the request event.data[3].alias --alias of the third player in the request
For the command
parameter of "loadFriends"
, this function requests the friends of the currently
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
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
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).
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:
event.data[1].category --> "CY_a49t8h4t43t43t" event.data[1].title --> "Easy"
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.
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.
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" )
For the command
parameter of "createRoom"
, this function creates a 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()' } )
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()' } )
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()' } )
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.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
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
.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:
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.