gameNetwork.request()

Type Function
Library gameNetwork.*
Return value none
Revision Current Public Release (2014.2393)
Keywords gameNetwork, request, gamecenter
See also gameNetwork.init()
gameNetwork.show()

Overview

Send or request information to/from the game network provider.

Syntax

gameNetwork.request( command [, params] )
command (required)

String. String value as supported by the game network. See Command Reference below.

params (optional)

Table. Table of parameters allowed by the game network.

Command Reference

Game Center

For the command parameter, Game Center supports the following values:

  • "setHighScore"
  • "loadScores"
  • "loadLocalPlayer"
  • "loadPlayers"
  • "loadFriends"
  • "loadAchievements"
  • "unlockAchievement"
  • "resetAchievements"
  • "loadAchievementDescriptions"
  • "loadFriendRequestMaxNumberOfRecipients"
  • "loadLeaderboardCategories"
  • "loadPlayerPhoto"
  • "loadAchievementImage"
  • "loadPlaceholderCompletedAchievementImage"
  • "loadIncompleteAchievementImage"
  • "loadCurrentPlayer"
  • "createMatch"
  • "quitMatch"
  • "endMatch"
  • "removeMatch"
  • "setEventListener"
  • "loadMatchData"
  • "endTurn"
  • "loadMatches"
  • "loadTurnBasedMatchMaxNumberOfParticipants"

Google Play Game Services

Valid command options for Google Play Game Services are cited in the plugin documentation.

Parameter Reference

Game Center

Depending on the specified command parameter, the contents of the params table will vary.

Listener Function

For all 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="com.appledts.EasyTapList", value=25 },
        listener = requestCallback
    }
)

Set High Score

For the command parameter of "setHighScore", this function sets a high score for the currently logged-in user for the specified leaderboard (category). If the high score is not higher than the one currently on the server, the server will keep the highest value. This function corresponds to Apple's reportScoreWithCompletionHandler but the nomenclature deviates for consistency with our existing gameNetwork APIs.

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

In the params table, localPlayerScore is a required table that corresponds to Apple's GKScore class. Within this table, the following key-values apply:

  • category — String that matches the ID of the leaderboard you want to register the score with as entered on iTunes Connect (the ID need not follow the fully qualified reverse domain style shown here).

  • value — Number representing the score. Note that Apple allows for 64-bit integers, but all numbers in Lua are of type double. This means that your maximum and minimum values are restricted to the range of double which is about 2^51 instead of 2^64.

Load Scores

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

gameNetwork.request( "loadScores",
    {
        leaderboard =
        {
            category = "com.appledts.EasyTapList",
            playerScope = "Global",  -- "Global" or "FriendsOnly"
            timeScope = "AllTime",   -- "AllTime", "Week", or "Today"
            range = { 1,5 }
        },
        listener = requestCallback
    }
)

Inside the params table, leaderboard is a required table that corresponds to Apple's GKLeaderboard class. Within this table, the following key-values apply:

  • category — Required string that matches the name of the board from which you want to fetch scores, as entered on iTunes Connect (the ID need not follow the fully qualified reverse domain style shown here).

  • playerScope — Optional string of either "Global" or "FriendsOnly". The latter setting will restrict the fetched scores to only friends.

  • 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. The first value is a start index and the second value is the number of players to retrieve (less than 100). The default range is { 1,25 }.

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

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

In addition, the event.localPlayerScore table is accessible for the logged-in player. This contains all of the properties shown above.

event.localPlayerScore.playerID
event.localPlayerScore.rank

Load Local Player

For the command parameter of "loadLocalPlayer", this function requests the GKPlayer object 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:

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 =
        {
            "G:123456789",
            "G:1234567890",
            "G:0123456789"
        },
        listener = requestCallback
    }
)

Inside the params table, playerIDs is a required table containing a comma-delimited list of player IDs (strings) to fetch data for.

When handling the results of a "loadPlayers" call, event.data in the callback listener is an array of items (tables) corresponding to each requested player. Each table 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

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

Load Achievements

For the command parameter of "loadAchievements", 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" call, event.data in the callback listener is an array of items (tables) representing each achievement. Each table contains the following properties:

event.data[4].identifier       --identifier for the fourth achievement
event.data[2].percentComplete  --completed percentage for the second achievement 

Unlock Achievement

For the command parameter of "unlockAchievement", this function unlocks/sets the specified achievement (identifier) at the specified percentage. The showsCompletionBanner only takes affect if the achievement is 100% complete. This function corresponds to Apple's reportAchievementWithCompletionHandler but the nomenclature deviates for consistency with our existing gameNetwork APIs.

gameNetwork.request( "unlockAchievement",
    {
        achievement =
        {
            identifier = "com.appletest.one_tap",
            percentComplete = 100,
            showsCompletionBanner = true
        },
        listener = requestCallback
    }
)

Inside the params table, achievement is a required table wherein the following key-values apply:

  • identifier — Required string that matches the name of the achievement you want to unlock/report, as entered on iTunes Connect (this need not follow the fully qualified reverse domain style shown here).

  • percentComplete — Optional number representing the completion percentage of the achievement. Setting this value to 100 will fully unlock the achievement. If this field is omitted, it's assumed this value is 100.

  • showsCompletionBanner — Optional boolean which, if set to true, will cause Apple to automatically show a completion banner when percentComplete reaches 100.

When handling the results of a "unlockAchievement" call, event.data is a table that corresponds to the Apple GKAchievement class that you just unlocked. You may use this information to help identify which/any achievements were successfully reported to the Game Center servers and which ones might have failed due to network timeouts.

Reset Achievements

For the command parameter of "resetAchievements", this function resets all achievements for the currently logged-in player. Use this with caution because there is no undoing this request — once called, all of the player's achievements for the app are reset to 0%.

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

Load Achievement Descriptions

For the command parameter of "loadAchievementDescriptions", this function requests a list of all descriptions associated with the achievements for the app.

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

When handling the results of a "loadAchievementDescriptions" call, event.data is an array of items (tables) which indicate the descriptions of the currently logged-in player's achievements. Each table in the array corresponds to Apple's GKAchievementDescription class.

Load Max Friend Request Recipients

For the command parameter of "loadFriendRequestMaxNumberOfRecipients", this function retrieves the maximum number of people that may be invited in a single friend request. The value is returned through the callback listener via event.data.

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

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:

event.data[1].category  --> "com.appledts.EasyTapList"
event.data[1].title     --> "Easy"

Load Player Photo

For the command parameter of "loadPlayerPhoto", this function retrieves the image of the requested player and creates a display object for it.

gameNetwork.request( "loadPlayerPhoto",
    {
        playerID = "G:0123456789",
        size = "Small",  -- "Small" or "Normal"
        listener = requestCallback
    }
)

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

  • playerID — Game Center player ID (string) to fetch the image for.

  • size — Optional value representing the size of the image to get back. Supported values are "Small" (default) or "Normal".

When handling the results of a "loadPlayerPhoto" call, event.data is a table which corresponds to Apple's GKPlayer class and contains the properties listed below. Note that the additional photo property is the display object created by a successful request.

Load Achievement Image

For the command parameter of "loadAchievementImage", this function retrieves the image of the requested achievement and creates a display object for it.

gameNetwork.request( "loadAchievementImage",
    {
        achievementDescription =
        {
            identifier = "com.appledts.twenty_taps"
        },
        listener = requestCallback
    }
)

Inside the params table, achievementDescription is a required table wherein the following key-values apply:

  • identifier — Required string that matches the name of the achievement to retrieve the image for (this need not follow the fully qualified reverse domain style shown here).

When handling the results of a "loadAchievementImage" call, event.data is a table that corresponds to Apple's GKAchievementDescription class and contains the properties listed below. Note that the additional image property is the display object created by a successful request.

Note

Achievement images uploaded to iTunes Connect should be fully compatible with Corona (see Image Guidelines for display.newImage()).

Load Completed Achievement Placeholder Image

For the command parameter of "loadPlaceholderCompletedAchievementImage", this function retrieves the Apple placeholder image of a completed achievement and creates a display object for it, accessible via event.data in the callback listener.

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

Load Incomplete Achievement Image

For the command parameter of "loadIncompleteAchievementImage", this function retrieves the Apple placeholder image of an incomplete achievement and creates a display object for it, accessible via event.data in the callback listener.

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

Load Current Player

For the command parameter of "loadCurrentPlayer", this function retrieves the current player who is scheduled to take his/her turn in a match.

gameNetwork.request( "loadCurrentPlayer",
    {
        matchID = "w4o98y3498hg349h",
        listener = requestCallback
    }
)

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

  • matchID — Match ID (string) of the match from which you want to fetch the current participant.

When handling the results of a "loadCurrentPlayer" call, event.data in the callback listener includes the participant object.

Create Match

For the command parameter of "createMatch", this function creates a turn-based match with the specified players.

Unlike gameNetwork.show( "createMatch", ... ) (reference), this simply creates a match object and lets you show a custom user interface.

gameNetwork.request( "createMatch",
    {
        playerIDs = { "w4o98y3498hg349h", "wrighfq547hg543" },
        minPlayers = 2,
        maxPlayers = 3,
        playerGroup = 1,
        playerAttributes = { 1, 4, 6 },
        inviteMessage = "Hi, please join our match!",
        listener = requestCallback
    }
)
  • playerIDs — Optional array of strings representing the player IDs of people to invite to the match.

  • minPlayers — Optional value for the minimum number of players required in the match.

  • maxPlayers — Optional value for the maximum number of players allowed in the match.

  • playerGroup — The game type which will be created, for example a quick game or long game. Only players whose requests share the same playerGroup value are auto-matched by Game Center.

  • playerAttributes — Mask that specifies the role that the local player would like to play in the game. See the Game Center Programming Guide for more information.

  • inviteMessage — Custom invitation message for the match.

When handling the results of a "createMatch" call, event.data in the callback listener includes the match object.

Quit Match

For the command parameter of "quitMatch", this function removes the currently logged-in player from the specified match and sets his/her match outcome.

gameNetwork.request( "quitMatch",
    {
        matchID = "adsfawerg4",
        outcome = "lost",
        data = "dsfa4wt4t",
        nextParticipant = { "34tgergae5rtg5" },
        listener = requestCallback
    }
)
  • matchID — String identifying the match that the player will quit.

  • outcome — Result of the match for the player that quit.

  • data — Data of the match for the next player. This is only necessary if it's the local player's turn.

  • nextParticipant — The next player that is scheduled to take a turn, wrapped in an array. This can be the player ID or the index value of the participant. This is only necessary if it's the local player's turn.

When handling the results of a "quitMatch" call, event.data in the callback listener includes the match object.

End Match

For the command parameter of "endMatch", this function ends the match and sets the outcome for all players.

gameNetwork.request( "endMatch",
    {
        matchID = "adsfawerg4",
        outcome =
        {
            ["G:0123456789"] = "first",
            ["G:1234567890"] = "second",
            ["G:9876543210"] = "third"
        },
        data = "dsfa4wt4t",
        listener = requestCallback
    }
)

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

  • matchID — String identifying the match to end.

  • outcome — Required array containing the player IDs and the match outcome for each.

  • data — The final data of the match.

Remove Match

For the command parameter of "removeMatch", this function removes the match from the list of matches in Game Center. This should only be called after gameNetwork.request( "endMatch", ... ) has been executed. Within the params table, matchID is a string identifying the match to remove.

gameNetwork.request( "removeMatch",
    {
        matchID = "adsfawerg4",
        listener = requestCallback
    }
)

Set Event Listener

For the command parameter of "setEventListener", this function sets the event listener for all matches.

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

When handling the results of a "setEventListener" call, event.type in the callback listener will be one of the following:

  • invitationReceived — The value when the player has received an invitation to join a match.

  • matchEnded — The value when another player has called gameNetwork.request( "endMatch", ... ), ending the match for all the players.

  • playerTurn — The value when it is the current player's turn in a match.

In turn, event.data in the callback listener will vary depending on the value of event.type:

  • When event.type is invitationReceived, event.data is an array of strings representing the IDs of all players invited to the match.

  • When event.type is matchEnded or playerTurn, event.data contains the match object.

Load Match Data

For the command parameter of "loadMatchData", this function retrieves the data of a match. Within the params table, matchID is a string identifying the match for which data will be retrieved.

gameNetwork.request( "loadMatchData",
    {
        matchID = "adsfawerg4",
        listener = requestCallback
    }
)

When handling the results of a "loadMatchData" call, event.data in the callback listener includes the match object.

End Turn

For the command parameter of "endTurn", this function ends the current player's turn and lets the next player start their turn.

gameNetwork.request( "endTurn",
    {
        matchID = "adsfawerg4",
        data = "dsfa4wt4t",
        nextParticipant = { "34tgergae5rtg5" },
        listener = requestCallback
    }
)

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

  • matchID — String identifying the match for which the player will end their turn.

  • data — The data of the match for the next player.

  • nextParticipant — The next player that is supposed to take a turn, wrapped in an array. This can be the player ID or the index value of the participant.

When handling the results of a "endTurn" call, event.data in the callback listener includes the match object.

Load Matches

For the command parameter of "loadMatches", this function loads the matches involving the currently logged-in player and creates a match object for each.

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

When handling the results of a "loadMatches" call, event.data in the callback listener is an array of match objects.

Load Max Turn-Based Participants

For the command parameter of "loadTurnBasedMatchMaxNumberOfParticipants", this function retrieves the maximum number of players that may be invited to a turn-based match. The value is returned through the callback listener via event.data.

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

Example

Game Center
-- Request callback function
local function requestCallback( event )

    if ( event.type == "setHighScore" ) then
        --high score has been set
    elseif ( event.type == "resetAchievements" ) then
        --achievements have been reset
    end
end

-- Update the player's high score
gameNetwork.request( "setHighScore",
    {
        localPlayerScore = { category="com.appledts.EasyTapList", value=25 },
        listener = requestCallback
    }
)

-- Reset the player's achievement list
gameNetwork.request( "resetAchievements", { listener=requestCallback } )