After the player is connected, you can begin to use the leaderboards API.

To build leaderboards into your game, that game needs to have a gameplay mechanism that allows your game to calculate a score. You are free to design your gameplay and scoring mechanism as you want. The only restriction is that your scoring mechanism must return a 64-bit integer value. When you report a score, you report this integer value to Game Center so it can be stored.

How can you make the integer into something more interesting? As part of the development process, you configure a leaderboard description in iTunes Connect so that Game Center could understand what scores in your leaderboard mean. You describe to Game Center what type of score is stored in the leaderboard and how to convert your score into a string for display. An advantage of this mechanism is that the same description is used by the Game Center app to show scores of your game.

The most critical decision to make is what kind of score is stored in the leaderboard. Game Center provides three basic formatting types:

  • An abstract number, such as an integer or a fixed point number.
  • A time value, such as minutes or seconds.
  • A monetary value, such as dollars or euros.

You also decide the order in which scores are ranked. When scores are ranked low-to-high, a lower score is considered a better score—for example, a racing game that records the time it has taken to complete the race. In this circumstance a faster time—that is, a lower score—is better, so a sorting order of low-to-high is appropriate. In contrast, a game that adds points to the player’s total for each successful action taken in the game expects that a higher score is better, so a high-to-low sorting order would be more appropriate.

Once you have the formatting type and sorting order is chosen, you also customize the final results with a localized formatting string. For example, if you chose to represent the score as an integer, you might choose “ point” and “ points” as the English localization for singular and plural values of scores stored in that leaderboard. Other games might use the same score type but use different localized strings (“ laps”, “ cars”).

When you design a scoring mechanism, make sure that you consider the range of possible (legal) score values. When you create the leaderboard description, you can also provide minimum and maximum values for scores reported to it. Providing a score range adds a layer of security onto your leaderboard because it reduces the likelihood that a player can cheat if they discover a way to report an absurdly high score.


Show leaderboards UI

You can show leaderboards UI using this method:

GameCenterManager.showLeaderBoards ();

Or you can specify a Leaderboard ID if you want to show  UI of the specific leaderboard.


Working with the current player score.

Game Center provides three basic formatting types:

  • An abstract number, such as an integer or a fixed point number.
  • A time value, such as minutes or seconds.
  • A monetary value, such as dollars or euros.

You can choose between this formats when you are creating your leaderboard in iTunes connect:

Note:  It doesn't matter what score format type will be chosen,  when you are retrieving or reporting score. It should always be represented as 64-bit integer value (long C#). Basically you are choosing how your score will be formatted in the leaderboard GUI for your player. From your perspective a score is always 64bit integer value, no matter what formatting type has been chosen for the leaderboard.

You can report new high score using ReportScore method. As soon as the score is reported, you will get


GameCenterManager.OnScoreSubmitted += OnScoreSubmitted;
GameCenterManager.ReportScore(hiScore, leaderBoardId);

void OnScoreSubmitted (GK_LeaderboardResult result) {
		if(result.IsSucceeded) {
			GK_Score score = result.Leaderboard.GetCurrentPlayerScore(GK_TimeSpan.ALL_TIME, GK_CollectionType.GLOBAL);
			IOSNativePopUpManager.showMessage("Leaderboard " + score.LongScore, "Score: " + score.LongScore + "\n" + "Rank:" + score.Rank);

Note: You should use score report even if the user gets result lower than his top score, his top result will not be overridden. Good practice is to report the score after a player completes the level. In this case Game Center will be able to track not only top player results but also daily and weekly charts.

Note: If score is submitted successfully, current player score will be available right after the submission.

If you want to get user scores before submiting anything to the Game Center, you should use LoadLeaderboardInfo method and subscribe to the OnLeadrboardInfoLoaded action.

GameCenterManager.OnLeadrboardInfoLoaded += OnLeadrboardInfoLoaded ;

private void OnLeadrboardInfoLoaded (GK_LeaderboardResult result) {
    GameCenterManager.OnLeadrboardInfoLoaded -= OnLeadrboardInfoLoaded ;

	if(result.IsSucceeded) {
		GK_Score score = result.Leaderboard.GetCurrentPlayerScore(GK_TimeSpan.ALL_TIME, GK_CollectionType.GLOBAL);
		IOSNativePopUpManager.showMessage("Leaderboard " + score.LeaderboardId, "Score: " + score.LongScore + "\n" + "Rank:" + score.Rank);
		Debug.Log("double score representation: " + score.DecimalFloat_2);
		Debug.Log("long score representation: " + score.LongScore);

Note: It's recommended always to keep local copy of player scores using PlayerPrefs, for example. In case Game Center data is not available due to broken internet connection, etc.

Loading other player scores

This can be useful if you want to create your own UI to display leaderboard scores in your game. For loading score list from the leaderboard you can use the LoadScore method. As soon as requested scores are loaded, the OnScoresListLoaded action will be fired.


GameCenterManager.OnScoresListLoaded += OnScoresListLoaded;
GameCenterManager.LoadScore(leaderBoardId, 1, 10, GCBoardTimeSpan.ALL_TIME, GCCollectionType.FRIENDS);

private void OnScoresListLoaded (ISN_Result res) {
	if(res.IsSucceeded) {

		loadedLeaderboard = GameCenterManager.GetLeaderboard(leaderboardId_1);
		IOSMessage.Create("Success", "Scores loaded");
	} else  {
		IOSMessage.Create("Fail", "Failed to load scores");

In the code above we are trying to retrieve 10 results of the player friends starting from 1st place. If the request succeeds, we can update our GUI with the loaded results. 

Here is an example of using Unity GUI:

GUI.Label(new Rect(10,  90, 100, 40), "rank", boardStyle);
GUI.Label(new Rect(100, 90, 100, 40), "score", boardStyle);
GUI.Label(new Rect(200, 90, 100, 40), "playerId", boardStyle);
GUI.Label(new Rect(400, 90, 100, 40), "name ", boardStyle);
GUI.Label(new Rect(550, 90, 100, 40), "avatar ", boardStyle);

if(loadedLeaderboard != null) {
	for(int i = 1; i < 10; i++) {
		GK_Score score = loadedLeaderboard.GetScore(i, GK_TimeSpan.ALL_TIME, displayCollection);
		if(score != null) {
			GUI.Label(new Rect(10,  90 + 70 * i, 100, 40), i.ToString(), boardStyle);
			GUI.Label(new Rect(100, 90 + 70 * i, 100, 40), score.LongScore.ToString() , boardStyle);
			GUI.Label(new Rect(200, 90 + 70 * i, 100, 40), score.PlayerId, boardStyle);

			GK_Player player = GameCenterManager.GetPlayerById(score.PlayerId);
			if(player != null) {
				GUI.Label(new Rect(400, 90 + 70 * i , 100, 40), player.Alias, boardStyle);
				if(player.SmallPhoto != null) {
					GUI.DrawTexture(new Rect(550, 75 + 70 * i, 50, 50), player.SmallPhoto);
				} else  {
					GUI.Label(new Rect(550, 90 + 70 * i, 100, 40), "no photo ", boardStyle);

			if(GUI.Button(new Rect(650, 90 + 70 * i, 100, 30), "Challenge")) {
				GameCenterManager.IssueLeaderboardChallenge(leaderboardId_1, "Your message here", score.PlayerId);



Warning: While requesting score range the start position should be > 1 and the end range should  be <= 100.

GameCenterManager.loadScore(leaderBoardId, 1, 10); // correct
GameCenterManager.loadScore(leaderBoardId, 10, 50); // correct
GameCenterManager.loadScore(leaderBoardId, 2, 20); // correct

GameCenterManager.loadScore(leaderBoardId, 50, 150); // wrong
GameCenterManager.loadScore(leaderBoardId, -5, 10); // wrong
GameCenterManager.loadScore(leaderBoardId, 0, 101); // wrong

Getting leaderboard range

You can get the total scores number posted to the leaderboard as showed bellow:

string leaderBoardId =  "your.ios.leaderbord1.id";
GCLeaderboard lb =  GameCenterManager.GetLeaderboard(leaderBoardId);

Warning: This property is invalid until a call to LoadLeaderboardInfo, ReportScore or LoadScore  is completed. Afterward, it contains the total number of entries available to return to your game given the filters you applied to the query.

Score Properties

The context property is stored and returned to your game but otherwise it is ignored by Game Center. It allows your game to associate an arbitrary 64-bit unsigned integer value with the score data reported to Game Center. You decide how this integer value is interpreted by your game. For example, you might use the context property to store flags that provide game-specific details about a player’s score, or you might use the context as a key to other data stored on the device or on your own server. The context is the most useful when your game displays a custom leaderboard user interface.


Available in iOS 5.0 and later.

long context = 5;
GameCenterManager.ReportScore(your_score, your_leaderboard_id, context);

Context stored in GameCenter and returned to the game. For example, if the score has been done using a "wood table", the context can be 1. If the context has been done using a "steel table", the context can be 2 and so on. This can be used to limit score challenges to certain game modes and configurations, so that the challenged player will have the same game environment.

Examples Scenes

The full example of using API can be found in the following example scenes:

  • GameCenterGeneral 
  • CustomLeaderBoardGUIExample