Since the Game Center feature is just an extension of the existing gameNetwork API, there’s no need to go over every single available request you can send to Game Center—you can view the updated gameNetwork init(), request(), and show() documentation for that.

So instead, I’ll give you a quick overview of what you need to do on the “Apple side” of things (iTunes Connect), the Corona “setup” info, as well as the special considerations that need to be taken to ensure everything works properly in your app.

iTunes Connect

Link: Visit the iTunes Connect Portal

The steps you’re required to take on Apple’s side of things are pretty straightforward, so I won’t need to go too in-depth with this section. In short, you’ll need to create Leaderboards (high score boards) and Achievements for the apps you want to enable Game Center features, and also make note of the individual Leaderboard and Achievement ID’s you’ve assigned to each one.

  1. Click the ‘Manage Your Applications’ link.
  2. Click your app’s icon.
  3. On the right, click ‘Manage Game Center’ button (blue).
  4. Click the ‘Enable’ button.
  5. Click ‘Edit’ under the Leaderboard and Achievements sections.
  6. Add Leaderboards and Achievements.
  7. Make note of each ‘Leaderboard ID’ and ‘Achievement ID’.

Of course, if you don’t want to have Achievements (or a Leaderboard) in your game, you can skip those sections. It’s recommended you add something, or your Game Center implementation might be a little bland to say the least.

System Events and initCallback

Normally, gameNetwork.init() is called at the beginning of main.lua, and is never touched again for the lifetime of your app’s runtime. With Game Center, there are two main differences in regards to gameNetwork.init().

The first difference is, because Game Center is a system-wide process in iOS, users are logged out of GameCenter (for your app) every time your app is suspended (e.g. the user presses the ‘Home’ button or switches to a different app). Therefore, you’ll want to call gameNetwork.init() every time your app receives an “applicationStart” system event.

The second difference between other providers is that with Game Center, you can specify an initCallback function that is called once the init request has completed (which gives you a chance do something when the user logs in, declines, or if the they are offline and can’t access Game Center features).

Here’s an example of how you might use gameNetwork.init() when using Game Center as a network provider:

local gameNetwork = require "gameNetwork"
local loggedIntoGC = false

-- called after the "init" request has completed
local function initCallback( event )
    if then
        loggedIntoGC = true
        native.showAlert( "Success!", "User has logged into Game Center", { "OK" } )
        loggedIntoGC = false
        native.showAlert( "Fail", "User is not logged into Game Center", { "OK" } )

-- function to listen for system events
local function onSystemEvent( event ) 
    if event.type == "applicationStart" then
        gameNetwork.init( "gamecenter", initCallback )
        return true
Runtime:addEventListener( "system", onSystemEvent )

In your initCallback listener function, the event table includes a single property,, which is set to true upon successful Game Center login, and is nil if user was not logged in. The primary use-case for this is to avoid calling gameNetwork.request() in situations where the user is not logged in. For more information, see the updated gameNetwork.init() documentation.

Game Center Requests

When using Game Center as your provider, the following strings can be used in conjunction with gameNetwork.request():

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

Please see the gameNetwork.request() API documentation to see the different kinds of data that needs to be passed with each of the above requests. Most of the above requests allow you to specify a listener which is where you’ll receive requested data. The most confusing aspect of Game Center requests is knowing what data is returned to your callback listener through the event table. As a reminder, this information can always be found in the gameNetwork.request() API documentation page and also on the individual class reference pages within the Official Game Kit Documentation. If all else fails, you could always encode the event table into a JSON string and display it on your device’s screen through a native alert. Here’s an example of how you might do that in conjunction with a “loadFriends” request:

local gameNetwork = require "gameNetwork"
local json = require "json"

-- callback listener for Game Center requests
local function requestCallback( event )
    if event.type == "loadFriends" then
        local data = json.encode( )

        -- show encoded json string via native alert
        native.showAlert( "", data, { "OK" } )

gameNetwork.request( "loadFriends", { listener=requestCallback } )
  1. I see that you said that you include
    components = { “openfeint” }
    in build.settings, but is that for both GC and OF, just GC within OF?

  2. Jonathan Beebe says:

    @Peter9221: You have two three options when it comes to OpenFeint and Game Center:

    1. Standalone GameCenter
    2. Standalone OpenFeint
    3. Standalone OpenFeint (with included GameCenter features)

    For the first option, you’ll include the empty components table in your build.settings.

    For the second and third option, you’ll include “openfeint” as the only item in build.settings (see example in article above).

    With the third option, you’ll call gameNetwork.init( “openfeint” ) and all of your gameNetwork requests will be to OpenFeint. OpenFeint has integrated Game Center features that allow you to submit to both OpenFeint and Game Center when it comes to setting a new high score or unlocking an achievement (but the requests will go through OpenFeint).

    You cannot init both OpenFeint and Game Center as a *standalone* provider in your app. If you want both of them, you have to go with the third option in the list (which provides only a very limited Game Center implementation).

  3. Since Game Center is already built-in to all iOS devices, we don’t make you specify it as a “component”. It is always there regardless if you use it or not.

    OpenFeint is a large 3rd party framework which adds several megabytes to your build. We originally tried to be smart about whether we included it by detecting if you did “require(‘gameNetwork’)” in your code. But this won’t work anymore since we can’t tell if you are using OpenFeint or Game Center from this. So we need you to tell us explicitly now in your build.settings what you really want.

  4. Kiel McDonald says:

    Thanks for the info, looking forward to adding this to my current project!

    Are there any plans to extend Game Center support to include the turn based items released in iOS 5?

  5. This is fantastic! Thanks Ansca, and thanks for the tutorial Jon! I have an implementation question and I’m not sure if this is the best place to ask, but I’ll try it:

    I originally submitted my game to Apple using a wildcard App ID. It’s my understanding that I can’t use GameCenter with an app using the wildcard. Will Apple allow my update to use a different App ID for the same app so that I can add Game Center?

  6. How do we show the leaderboards? I am trying to call it from a button event and the call I am using is: “leaderboards”, { listener=dismissCallback } )

    This shoud work correct?

  7. Nm I think the call actually is: “leaderboards”, { leaderboard = {category=”com.appledts.GKTapper.aggregate”, timeScope=”Week”}, listener=dismissCallback } )

  8. Jonathan Beebe says:

    @Alan / Falcon: You can build using a different provisioning profile (that doesn’t use a wildcard), but in either case, your bundle ID should actually be the same. As long as the provisioning profile you created is using the same bundle ID as what you have in iTunes Connect, then everything will be fine.

  9. OpenFeint is a large 3rd party framework which adds several megabytes to your build. We originally tried to be smart about whether we included it by detecting if you did “require(‘gameNetwork’)” in your code. But this won’t work anymore since we can’t tell if you are using OpenFeint or Game Center from this. So we need you to tell us explicitly now in your build.settings what you really want.

    This is not working in last build: 2012.726
    I didnt include components=openfient but my app has OF bundle files in it. (~300files / 2mb)

  10. Can: If you don’t put the components line in your build.settings, we revert to our old behavior which will always include OpenFeint if you have require(‘gameNetwork’) in your code.

  11. Hey Jonathan,

    I’m currently using only game center and insured that build.settings is set correctly, as well as made sure my user is logged in before posting.

    When I set a highscore, my callback listener gets fired correctly, and when I JSON encode my I see that there indeed has been a score submission.

    The problem is that when I check the leader board on game center, I see that I am ranked, BUT, no scores are visible. I get nothing but “No Scores” for all tabs (Today, This Week and All Time).

    Is there anything else I need to be doing? Is there a certain naming convention?

    P.S: When I hard coded Apple’s GK Tapper Bundle ID I was able to see actual scores.

  12. Jonathan Beebe says:

    @Shehab: Ensure you are using a non-wildcard provisioning profile that uses the same bundleId that your app is set up to use in iTunes Connect. Also ensure that the leaderboardId in the ‘category’ parameter matches the leaderboardId of one of your leaderboards for your app (also created in iTunes Connect).

  13. Can I test my not-yet-submitted-to-the-appstore app with Game Center in ad-hoc disti only using its leaderboard following these steps? or do I nedd to do something else?

  14. I was quite excited to see Game Center support for Corona. I was wondering if there will be any support for its turn-based game API? This is a huge boon of the 5.x API, in that devs no longer need to run their own servers to support turn based games.

  15. Is it possible to change the language of Game Center Popup? (Title, button, and tap to rate) I have seen it in other games but not sure how to make it in Corona.

  16. Does“leaderboards”) display a list of all my leaderboards that the user can select? My app will have a few different leaderboards. Same with achievements.

  17. Hi, I just finishing my first app for iPhone and using corona sdk doind it. I already implemented gamecenter support througth openfeint, so all data goes to game center too, througth openfeint function calls.

    But in the some games I saw what you can select between game center and openfeint and depending on this selection show dashboard of the game center or openfeint if user press on some button.

    Or in Slam Dunk app in options screen we have openfeint dashboard, gamecenter achievements, gamecenter leaderboards at one time, and it works.

    How it is possible? If you called gameNetwork.init() and passed openfeint how you can show the gamecenter leaderboards and achievements after that? I tried calling gameNetwork.init() once again with different parameter but it doesn’t work.

    Can you help me with this?

  18. I’m trying to run the GKTapper example in build 799, and for some reason it’s not able to connect to the network on the device. I’m just building with team provisioning profile and running it. Am I missing some step?

    Also, if I try to replicate the steps with ‘com.appledts.GKTapper’ as my bundle id, do I actually have to setup the achievements in iTunes Connect and create a bundle id to match in my provisioning portal?

  19. Nice work!

    Now, when I prepare my own Leaderboards and Achievements What do I have to change?

    Should I change just this line in Build.settings file:

    CFBundleIdentifier = “com.appledts.GKTapper”,

    To something like

    CFBundleIdentifier = “com.appledts.MyGameName”,

    Is there any thing else????

  20. I downloaded your example file, Jonathan, but when I click on Submit High Score or Show Leaderboards, it keeps telling me “GameCenter Offline Please check your internet connection.” is it supposed to work out of the box? thanks!

  21. Is highest score per level supported directly? Doesn’t seem to be…

    If not explicitly supported is the a technique people use to do per level highest scoreboard?

  22. With gamecenter, is there a way to use it to sync/add up scores between devices. For example, someone downloads my app on there ipad and gets 300 points on a leaderboard counting the total points they have. Then, they download my app for there iphone, and get 200 points. The issue is, 300 is higher then 200, so the points on there iphone don’t really add to there total points in gamecenter, because gamecenter does not combine the scores, it just takes the best score. Is there a way I can add points from Game Center scores, instead of from the local device Json file, and set the combined score as the Gamecenter score each time the user plays, on any of there devices. That way, points from all there different devices would add up, not just override each other.

  23. I’m new on cordova and ios advancement, I emulated the this excercise yet I’m not ready to check whether there was an auth achievement or if the scores are being submited, would somebody be able to provide for me more detail on the most proficient method to utilize this plugin or where might I be able to discover more data?

  24. I downloaded your case document, Jonathan, however when I click on Submit High Score or Show Leaderboards, it continues letting me know “Gamecenter Offline Please check your web association.” would it say it should work out of the crate? much obliged!

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title="" rel=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>