command

OpenFeint

Strings supported by the OpenFeint provider:

• setHighScore
• unlockAchievement
• uploadBlob: (Not supported on Android)
• downloadBlob (Not supported on Android)

parms

Parmeters used in the above OpenFeint commands:

setHighScore: { leaderboardID="abc123", score=99 [, displayText="99 sec"] }
Note: Starting with Build 2012.815, for Game Center compatibility, 'category' may be used instead of 'leaderboardID' and 'value' may be used instead of 'score'.
unlockAchievement: "achievementId"
uploadBlob: "uploadBlob", key, data
downloadBlob: key, [listener] ) -- listener for "completion" event with "blob" key set.

The optional Listener for downloadBlob that is called when the "blob" string has been downloaded:

• event.name -- The name of the event, "completion".
• event.data or event.blob -- A string that contains the requested blob data. If the length of this string is 0, then the download failed. Note: In Build 2012.725, event.data was introduced as a universal generic field holding the return data. event.data and event.blob are references to the same data. Also note that starting in Build 2012.725, the event.name no longer returns "completion", but instead returns "gameNetwork" along with additional common fields for all gameNetwork event types. c

Papaya (Android)

Strings supported by the Papaya provider:

• setHighScore
• unlockAchievement

parms

Parmeters used in the above Papaya commands:

setHighScore: { leaderboardID="abc123", score=99 }
Note: Starting with Build 2012.815, for Game Center compatibility, 'category' may be used instead of 'leaderboardID' and 'value' may be used instead of 'score'.
unlockAchievement: "achievementId"

Game Center (iOS)

Strings supported by the Game Center provider:

• setHighScore
• loadScores
• loadLocalPlayer
• loadPlayers
• loadFriends
• loadAchievements
• unlockAchievement
• resetAchievements
• loadAchievementDescriptions
• loadFriendRequestMaxNumberOfRecipients
• loadLeaderboardCategories
• loadPlayerPhoto
• loadAchievementImage
• loadPlaceholderCompletedAchievementImage
• loadIncompleteAchievementImage

parms

Parmeters used in the above Game Center commands:

setHighScore:

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. The nomenclature deviates in this case to provide consistency with our existing gameNetwork APIs.

Example "setHighScore" request:

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

'localPlayerScore' is a required table that corresponds to Apple's GKScore class.

In the localPlayerScore table:

'category' must be a string that matches the name of the board you want to register the score with as entered on iTunes Connect. (The name you pick need not follow the fully qualified reverse domain style shown here.) '

'value' must be a number representing your score. Note that Apple allows for 64-bit integers, but all numbers in Lua are of type double. This means your max and min values are restricted to the range of double which is about 2^51 instead of 2^64.

loadScores:

event.data in callback listener is an array of items (tables) that have
the following properties:

• playerID (string)
• category (string)
• value (number)
• context (number, iOS 5+ only)
• date (string)
• formattedValue (string)
• rank (integer)
• shouldSetDefaultLeaderboard (boolean, iOS 5+ only)

Each item (table) in the array corresponds to Apple's GKScore class.

example:
event.data[5].formattedValue -- #event.data == 2nd value specified in range table

event.localPlayerScore also has all of the above properties (not in an array). This table also corresponds to Apple's GKScore class.

example:
event.localPlayerScore.rank

Warning: iOS 4 has a bug where event.localPlayerScore.category returns nil. This is fixed in iOS 5.

Example "loadScores" request:

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

'leaderboard' is a required table that corresponds to Apple's GKLeaderboard class.

In the leaderboard table:

'category' (required) must be a string that matches the name of the board you want to fetch the scores with as entered on iTunes Connect. (The name you pick need not follow the fully qualified reverse domain style shown here.) '

'playerScope' (optional) is a string of either "Global" or "FriendsOnly". The latter setting will restrict the fetched scores to only friends.

'timeScope' (optional) is a string of either "AllTime", "Week", "Today" which limits the fetched scores to the specified time range.

'range' (optional) is an array of two values. The first value is that start index. The second value is the number of players to retrieve. Apple says this number must be less than 100. Apple's default range is {1,25}.

loadLocalPlayer
Requests the GKPlayer object for the currently logged-in user.

event.data in callback listener includes the following properties:

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

This table corresponds to Apple's GKLocalPlayer class. Each element in the friends array is a string representing a playerID.

example:
event.data.playerID

Example "loadLocalPlayer" request:

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

Note: To guarantee the friends array is populated, Apple says you must call loadFriends before this. We have found that this necessary on iOS 4, but on iOS 5, we get the friends array regardless.

loadPlayers

Requests a list of players with the specified player IDs, and returns an array of items (tables) for each requested player in the callback listener.

event.data in callback listener is an array of items that
have the following properties:

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

Each item (table) in the array corresponds to Apple's GKPlayer class

example:
event.data[3].isFriend

Example "loadPlayers" request:

gameNetwork.request( "loadPlayers",
{
        playerIDs =
        {
                "G:123456789",
                "G:1234567890",
                "G:0123456789"
        },
        listener=requestCallback
})

loadFriends

Requests the friends of the currently logged in user, and returns and array of tables for all friends in the callback listener.

event.data in callback listener is an array of strings representing playerIDs.

example:
event.data[2].playerID

Example "loadFriends" request:

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

loadAchievements

Loads a list of the user's completed achievements for the app and returns an array of items (tables) representing each achievement in the callback listener.

event.data in callback listener is an array of items that have the
following properties (each representing an achievement):

• identifier (string)
• percentComplete (number)
• isCompleted (boolean)
• isHidden (boolean)
• lastReportedDate (string)
• showsCompletionBanner (boolean, iOS 5+ only, will be nil otherwise)

Each item (table) in the array corresponds to Apple's GKAchievement class.

example:
event.data[4].identifier

Example "loadAchievements" request:

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

unlockAchievement

Unlocks the specified achievement (identifier) at the specified percentage. The showsCompletionBanner only takes affect if the achievement is 100% complete, and if the device is running iOS5 or higher.

This function corresponds to Apple's reportAchievementWithCompletionHandler. The nomenclature deviates in this case to provide consistency with our existing gameNetwork APIs.

Example "unlockAchievement" request.

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

'achievement' is a required table that corresponds to Apple's GKAchievement class.

In the "achievement" table:

'identifier' (required) must be a string that matches the name of the achievement you want to unlock/report as entered on iTunes Connect. (The name you pick need not follow the fully qualified reverse domain style shown here.) '

'percentComplete' (optional) must be a number representing the completion percentage of the achievement. 100 will fully unlock the achievement. If this field is omitted, it is assumed this value is 100.

'showsCompletionBanner' (optional, iOS 5+ only) is a boolean which if set to true, will cause Apple to automatically show a completion banner for you in your app when the percentComplete reaches 100. This field is ignored on pre-iOS 5 OS's.

The listener callback will fill event.data with a table that corresponds to the Apple GKAchievement class that you just unlocked. You may use this information to help identify which/any achievements that were successfully reported to the Game Center servers and which ones might have failed due to network timeouts.

resetAchievements

Resets all achievements for the currently logged-in user. Be careful, as there is no undoing this request. Once called, the user will have all achievements for this app reset to 0%.

Example "resetAchievements" request:

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

loadAchievementDescriptions

Requests a list of all descriptions associated with the achievements for the app and returns an array of items (tables) representing each achievement description object in the callback listener.

Each item (table) in the array corresponds to Apple's GKAchievementDescription class.

event.data in callback listener is an array of items which are the
descriptions of your achievements.

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

Example "loadAchievementDescriptions" request:

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

loadFriendRequestMaxNumberOfRecipients

Apple imposes a maximum number of people you may invite in a single friendRequest. This function will allow you to retrieve that number so you may dynamically adapt your code to accommodate this value if it changes. As of this writing, this number is 3. The value will be returned through the callback listener (via event.data).

Example "loadFriendRequestMaxNumberOfRecipients" request:

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

loadLeaderboardCategories

Requests a list of leaderboard categories for the app and returns an array of tables with each table containing description information of a leaderboard in the callback listener.

event.data in callback listener is an array of items (tables) where each table contains the keys 'category' and 'title', both of which are strings.

Example "loadLeaderboardCategories" request:

gameNetwork.request( "loadLeaderboardCategories", { listener=requestCallback } )
 
-- example of what an event.data table returned via callback listener looks like
event.data =
{
        [1] = {
                category = "com.appledts.EasyTapList",
                title = "Easy"
        },
        [2] = {
                category = "com.appledts.HardTapList",
                title = "Hard"
        },
        [3] = {
                category = "com.appledts.AwesomeTapList",
                title = "Awesome"
        },
}

loadPlayerPhoto (available starting with Build 2012.730, iOS5+ only)

Retrieves the image of the requested player and creates a display object for it.

Example "loadPlayerPhoto" request.

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

'playerID' (required) is the Game Center player ID (string) of the player you want to fetch the image for.

'size' (optional) represents the size of the image you want to get back. Supported values are "Small" and "Normal". "Small" is the default.

The listener callback will fill event.data with a table that corresponds to the Apple GKPlayer class as you've seen with other APIs documented above. But unlike the other APIs one additional property is added, 'photo', which is the display object of the retrieved image.

event.data in callback listener includes the following properties:

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

If called on pre-iOS5, the callback will be invoked and return errorCode=1 and errorMessage="This API is not available on this version of iOS."

loadAchievementImage (available starting with Build 2012.730)

Retrieves the image of the requested achievement and creates a display object for it.

Example "loadAchievementImage" request.

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

'achievementDescription' is a required table that corresponds to Apple's GKAchievementDescription class.

In the "achievementDescription" table:

'identifier' (required) must be a string that matches the name of the achievement you want to retrieve the image for. (The name you pick need not follow the fully qualified reverse domain style shown here.) '

The listener callback will fill event.data with a table that corresponds to the Apple GKAchievementDescription class as you've seen with other APIs documented above. But unlike the other APIs one additional property is added, 'image', which is the display object of the retrieved image.

event.data in callback listener includes the following properties:

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

Remember to upload images to iTunes Connect that are compatible with Corona (e.g. don't used indexed color pngs, etc.)

loadPlaceholderCompletedAchievementImage (available starting with Build 2012.730)

Retrieves the Apple placeholder image of a completed achievement and creates a display object for it.

Example "loadPlaceholderCompletedAchievementImage" request.

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

The listener callback will fill event.data with the display object of the image.

loadIncompleteAchievementImage (available starting with Build 2012.730)

Retrieves the Apple placeholder image of an incomplete achievement and creates a display object for it.

Example "loadIncompleteAchievementImage" request.

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

The listener callback will fill event.data with the display object of the image.

For further property reference for the different objects (GKLeaderboard, GKAchievement, GKAchievementDescription, GKScore, GKPlayer, and GKLocalPlayer), please see the Official Game Kit Framework Reference.