# Encourage progress and competition with leaderboards Let players measure their own progress and compare their skills with friends and others. ## Discussion Use leaderboards to record player scores, which they can view in their Game Center account and directly in your game using built-in Game Center or custom interfaces. Game Center even encourages engagement by notifying players when their friends pass their scores.  You configure a classic or recurring leaderboard in Xcode and submit scores from your code. A *classic leaderboard* retains the scores until you delete the leaderboard. A *recurring leaderboard* automatically resets the board on the intervals you specify. For example, use a classic leaderboard for the best all-time scores and a recurring leaderboard for periodic competitions. You can also combine individual leaderboards into sets, creating a hierarchy of leaderboards. For example, use leaderboard sets to aggregate the scores from different levels and configurations in your game. However, once you add a leaderboard set, you need to organize all other individual leaderboards into sets. For design guidance on all types of leaderboards, see [Human Interface Guidelines > Technologies > Game Center > Leaderboards](https://developer.apple.com/design/human-interface-guidelines/game-center#Leaderboards). For additional information on recurring leaderboards, see [Creating recurring leaderboards](/documentation/GameKit/creating-recurring-leaderboards). ## Configure and test leaderboards and leaderboard sets Configure leaderboards in Xcode before accessing them in your code and testing locally with Game Progress Manager. When you’re ready to deploy your configuration, sync your updates with App Store Connect. For more information about configuring and testing Game Center features, see [Initializing and configuring Game Center](/documentation/GameKit/initializing-and-configuring-game-center). For each leaderboard you configure, you specify details like the score format, submission type, and whether the data resets and starts again after a period of time. Decide on a style for your leaderboard identifiers, because you won’t be able to change them at a later time. Before you begin, have at least one localized name and image, which Game Center presents to the player, ready to upload for a language.  A leaderboard set organizes many leaderboards into a single unit. For example, for a game with many levels, use a leaderboard set to organize the leaderboards for each level. You can have up to 100 leaderboards without using leaderboard sets. When you use leaderboard sets, you can have up to 500 leaderboards across 100 leaderboard sets. > Important: You must have at least one leaderboard for your app before you can > create a leaderboard set. If you choose to use leaderboard sets, you must include > all future leaderboards in a leaderboard set. If you add a leaderboard to an unreleased version of your game or sign the game with a development certificate, Game Center annotates the leaderboard with a prerelease indicator. To change a leaderboard’s app version, see [Add leaderboards to an app version](https://developer.apple.com/help/app-store-connect/configure-game-center/add-leaderboards-to-your-app-version). > Note: If you’ve already pushed your configuration changes to App Store Connect, > removing a leaderboard or leaderboard set from the local configuration file > doesn’t remove the leaderboard or leaderboard set from App Store Connect. Use the Game Progress Manager to test leaderboards on your local device before you push the configuration update to App Store Connect. After selecting a leaderboard, you can add players to the leaderboard with score value. You can also test deep-linking behavior that you associate with a leaderboard.  For more information about the leaderboard properties you can configure, see [Leaderboard properties](https://developer.apple.com/help/app-store-connect/reference/leaderboards#leaderboard-properties). ## Choose a score format Game Center formats the scores that you submit as integer values depending on the leaderboard configuration you enter in Xcode. On the Add Leaderboard page, choose a score format — such as fixed points, elapsed time, or money — that makes sense for your game. For example, if you choose these formats, Game Center formats the values as follows: |Score format type |Score value |Format result| |-------------------------------------------|-----------------------|-------------| |Fixed Point - To 1 Decimal |`1234` |`123.4` | |Fixed Point - To 2 Decimals |`5678` |`56.78` | |Fixed Point - To 3 Decimals |`10,000` |`10.000` | |Elapsed Time - To the Minute |`3623` (seconds) |`60:23` | |Elapsed Time - To the Second |`10,000` (seconds) |`2:46:40` | |Elapsed Time - To the Hundredth of a Second|`10,000` (centiseconds)|`0:01:40:00` | |Money - Whole Numbers |`123` |`$123` | |Money - To 2 Decimals |`141` |`$1.41` | Optionally, enter a range of allowable values in the Score Range fields that matches the score format. For elapsed time values, enter a range in seconds or centiseconds (Elapsed Time - To the Hundredth of a Second). For example, if you choose Elapsed Time - To the Minute and want the maximum value to be 10 minutes, enter `600` seconds in the To field. Then check whether the formatted range values that appear below the range text fields are in the score format you want.  ## Add a unit to the score format or choose a currency symbol You can further format the scores when you add a language to the leaderboard configuration in Xcode. You need to add at least one language to save the leaderboard configuration. On the Add Language page, append a unit to the score that Game Center formats, such as `pts,` `lbs`, or `meters`, by entering the localized strings for the units in the Score Format Suffix text fields. For money values, you can choose a localized currency symbol from the Score Format menu. ## Submit scores to leaderboards To submit a score to one or more leaderboards, use the `GKLeaderboard` [`submitScore(_:context:player:leaderboardIDs:completionHandler:)`](/documentation/GameKit/GKLeaderboard/submitScore(_:context:player:leaderboardIDs:completionHandler:)) class method. Pass one or more leaderboard IDs, as well as the score, context, and player. ```swift // Submit a score to one or more leaderboards. try await GKLeaderboard.submitScore(points, context: 0, player: GKLocalPlayer.local, leaderboardIDs: ["my.leaderboard.id"]) ``` If you load all leaderboards using the `GKLeaderboard` [`loadLeaderboards(IDs:completionHandler:)`](/documentation/GameKit/GKLeaderboard/loadLeaderboards(IDs:completionHandler:)) class method, as the next section describes, you can submit the score to specific leaderboards using the [`submitScore(_:context:player:completionHandler:)`](/documentation/GameKit/GKLeaderboard/submitScore(_:context:player:completionHandler:)) instance method. Optionally, use the `context` parameter in both of these methods to store game-specific information. For example, pass a flag that contains information about how the player earned the score, such as the vehicle they drive in a racing game. If you prefer to submit scores through your own server, see . ## Fetch leaderboards and leaderboard sets To fetch one or more individual leaderboards, pass the leaderboard IDs to the `GKLeaderboard` [`loadLeaderboards(IDs:completionHandler:)`](/documentation/GameKit/GKLeaderboard/loadLeaderboards(IDs:completionHandler:)) class method. ```swift // Fetch the leaderboards. let leaderboards = try await GKLeaderboard.loadLeaderboards(IDs: ["my.leaderboard.id"]) ``` To fetch specific occurrences of a recurring leaderboard, use the [`loadPreviousOccurrence(completionHandler:)`](/documentation/GameKit/GKLeaderboard/loadPreviousOccurrence(completionHandler:)) instance method. To fetch leaderboard sets, use the `GKLeaderboardSet` [`loadLeaderboardSets(completionHandler:)`](/documentation/GameKit/GKLeaderboardSet/loadLeaderboardSets(completionHandler:)) class method. Then to fetch individual leaderboards in a set, use the [`loadLeaderboards(handler:)`](/documentation/GameKit/GKLeaderboardSet/loadLeaderboards(handler:)) instance method. ## Get the scores from leaderboards To load the scores that the local player and others earn from a leaderboard, use the `GKLeaderboard` [`loadEntries(for:timeScope:range:completionHandler:)`](/documentation/GameKit/GKLeaderboard/loadEntries(for:timeScope:range:completionHandler:)) method. Filter the scores using the `playerScope`, `timeScope`, and `range` parameters you pass to this method. For example, to get scores that friends of the local player earned in the past week, pass [`GKLeaderboard.PlayerScope.friendsOnly`](/documentation/GameKit/GKLeaderboard/PlayerScope-swift.enum/friendsOnly) as the `for` parameter and [`GKLeaderboard.TimeScope.week`](/documentation/GameKit/GKLeaderboard/TimeScope-swift.enum/week) as the `timeScope` parameter. ```swift // Fetch the friend scores. let result = try await leaderboard.loadEntries(for: GKLeaderboard.PlayerScope.friendsOnly, timeScope: GKLeaderboard.TimeScope.week, range: NSMakeRange(1, 100)) ``` To get all player scores in that time period, pass [`GKLeaderboard.PlayerScope.global`](/documentation/GameKit/GKLeaderboard/PlayerScope-swift.enum/global) as the `for` parameter instead. Then use the properties of the [`GKLeaderboard.Entry`](/documentation/GameKit/GKLeaderboard/Entry) instances that this method returns to get details about the individual scores, including the players who earned them. ## Display leaderboards To display a leaderboard or leaderboard set in your custom game interface, load the leaderboard or leaderboard set and use the [`title`](/documentation/GameKit/GKLeaderboard/title) property to get the localized name. To get the image representation that you upload to App Store Connect, use the [`loadImage(completionHandler:)`](/documentation/GameKit/GKLeaderboard/loadImage(completionHandler:)) method. ```swift // Load the leaderboard image. let image = try await leaderboard.loadImage() ``` Alternatively, display the leaderboard in the familiar Game Center interface. To learn more, see [Display a single leaderboard](/documentation/GameKit/displaying-the-game-center-dashboard#Display-a-single-leaderboard). ## Set the default leaderboard You can set the default leaderboard for an individual player during your game. For example, change the default leaderboard when the player advances to a different level in your game. To change the local player’s default leaderboard, use the `GKLocalPlayer` [`setDefaultLeaderboardIdentifier(_:completionHandler:)`](/documentation/GameKit/GKLocalPlayer/setDefaultLeaderboardIdentifier(_:completionHandler:)) method. To get the identifier for the default leaderboard in your code, use the [`loadDefaultLeaderboardIdentifier(completionHandler:)`](/documentation/GameKit/GKLocalPlayer/loadDefaultLeaderboardIdentifier(completionHandler:)) method. Otherwise, you set the default leaderboard for all players in App Store Connect when you configure leaderboards. Xcode doesn’t support setting a default leaderboard. For the steps to change the default leaderboard in App Store Connect, see [Configure leaderboards and achievements > Set a default leaderboard](https://developer.apple.com/help/app-store-connect/configure-game-center/configure-leaderboards-and-achievements). --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)