gameNetwork.request()

command _^(required)

String. String value as supported by Game Center — see Command Reference below.

params _^(optional)

Table. Table of parameters allowed by Game Center — see Parameter Reference below.

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.

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

In the params table, localPlayerScore is a required table inside which the following key-values apply:

• category — String that matches the leaderboard ID for which you want to register the score, as configured in iTunes Connect.

• 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 inside which the following key-values apply:

• category — Required string that matches the leaderboard ID from which you want to fetch scores, as configured in iTunes Connect.

• 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), each of which contains the following properties:

• playerID (string)
• category (string)
• value (number)
• context (number)
• date (string)
• formattedValue (string)
• rank (integer)
• shouldSetDefaultLeaderboard (boolean)
• 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

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 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)
• isFriend (boolean)
• isAuthenticated (boolean)
• isUnderage (boolean)
• friends (array) — Array of player IDs (strings) representing the friends of the local player.

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:

• playerID (string)
• alias (string)
• isFriend (boolean)

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:

• identifier (string)
• percentComplete (number)
• isCompleted (boolean)
• isHidden (boolean)
• lastReportedDate (string)
• showsCompletionBanner (boolean)

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.

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

Inside the params table, achievement is a required table inside which 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 achievement 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.

• identifier (string)
• title (string)
• achievedDescription (string)
• unachievedDescription (string)
• maximumPoints (integer)
• isHidden (boolean)

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:

• category (string)
• title (string)

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 contains the properties listed below. Note that the additional photo property is the display object created by a successful request.

• playerID (string)
• alias (string)
• isFriend (boolean)
• isAuthenticated (boolean)
• isUnderage (boolean)
• friends (array)
• photo (display object)

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 inside which 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 contains the properties listed below. Note that the additional image property is the display object created by a successful request.

• identifier (string)
• title (string)
• achievedDescription (string)
• unachievedDescription (string)
• maximumPoints (integer)
• isHidden (boolean)
• image (display object)

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.

Note that this call assumes the currently logged-in player will be part of the match. Thus, you should not include the current player’s ID in the playerIDs table. In addition, ensure that maxPlayers is set to a value which accommodates both the requested number of players and the current player. For example, if you request a match with two players in the playerIDs table, maxPlayers should be set to 3 or higher.

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.

• 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.

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 Match 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’s the current player’s turn in a match, following the gameNetwork.request( "endTurn", ... ) call for the previous player.

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, assuming the match has been established.

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.

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 } )