GKLeaderboard¶

Inherits: RefCounted < Object

Accesses Apple Game Center leaderboards and their entries.

Description¶

GKLeaderboard lets you fetch configured leaderboards, submit scores, and read player ranks as described in the Leaderboards section of GameCenterGuide.md. All operations mirror Apple’s asynchronous APIs, so every method expects a Callable that receives the requested data plus an optional error Variant. See Apple’s reference at Apple’s GKLeaderboard documentation.

Submitting a score (guide sample):

var local_player := GameCenterManager.new().local_player

GKLeaderboard.load_leaderboards(PackedStringArray(["MyLeaderboard"]), func(leaderboards: Array[GKLeaderboard], error: Variant) -> void:
    if error:
        print("Load leaderboard error %s" % error)
        return

    var score := 100
    var context := 0
    leaderboards[0].submit_score(score, context, local_player, func(submit_error: Variant) -> void:
        if submit_error:
            print("Error submitting leaderboard %s" % submit_error)
    )
)

Loading all versus specific leaderboards:

# Loads all leaderboards configured for the app.
GKLeaderboard.load_leaderboards(PackedStringArray(), func(all_leaderboards: Array[GKLeaderboard], error: Variant) -> void:
    print("Received %d leaderboards" % all_leaderboards.size())
)

# Loads only the identifiers you pass in.
GKLeaderboard.load_leaderboards(PackedStringArray(["My leaderboard"]), func(named_leaderboards: Array[GKLeaderboard], error: Variant) -> void:
    print("Received %d specific leaderboards" % named_leaderboards.size())
)

Properties¶

String	activity_identifier	`""`
Dictionary	activity_properties	`{}`
String	base_leaderboard_id	`""`
float	duration	`0.0`
String	group_identifier	`""`
bool	is_hidden	`false`
String	leaderboard_description	`""`
float	next_start_date	`0.0`
int	release_state	`0`
float	start_date	`0.0`
String	title	`""`
int	type	`0`

Methods¶

void	load_entries(players: Array, timeScope: TimeScope, callback: Callable)
void	load_image(callback: Callable)
void	load_leaderboards(ids: PackedStringArray, callback: Callable) static
void	load_local_player_entries(playerScope: PlayerScope, timeScope: TimeScope, rangeStart: int, rangeLength: int, callback: Callable)
void	load_previous_occurrence(callback: Callable)
void	submit_score(score: int, context: int, player: GKPlayer, callback: Callable)

Enumerations¶

enum AppleLeaderboardType: 🔗

AppleLeaderboardType CLASSIC = 0

A leaderboard that never expires, showing all-time rankings of all players.

AppleLeaderboardType RECURRING = 1

A leaderboard that recurs, allowing players a fresh start to compete and earn higher ranks in each ocurrence.

AppleLeaderboardType UNKNOWN = 2

There is currently no description for this enum. Please help us by contributing one!

enum TimeScope: 🔗

TimeScope TODAY = 0

Scans the current day.

TimeScope WEEK = 1

Restricts results to the current week.

TimeScope ALL_TIME = 2

Returns scores across the entire history of the leaderboard.

enum PlayerScope: 🔗

PlayerScope GLOBAL = 0

Loads data for all players of the game.

PlayerScope FRIENDS_ONLY = 1

Loads only data for friends of the local player.

Property Descriptions¶

String activity_identifier = "" 🔗

String get_activity_identifier()

Beta-only identifier for activity leaderboards (empty on platforms that do not expose the value).

Dictionary activity_properties = {} 🔗

Dictionary get_activity_properties()

Dictionary copy of Apple’s activityProperties, containing keys such as eventStartDate when available.

String base_leaderboard_id = "" 🔗

String get_base_leaderboard_id()

Identifier of the base leaderboard that this recurring leaderboard belongs to.

float duration = 0.0 🔗

float get_duration()

Leaderboard duration in seconds for recurring leaderboards.

String group_identifier = "" 🔗

String get_group_identifier()

Group identifier that you configured in App Store Connect, or an empty string if not grouped.

bool is_hidden = false 🔗

bool get_is_hidden()

True when Apple marks this leaderboard as hidden.

Available on iOS 26, macOS 26, tvOS 26, and visionOS 26. Returns false on earlier versions.

String leaderboard_description = "" 🔗

String get_leaderboard_description()

Localized long-form description text for the leaderboard.

Available on iOS 26, macOS 26, tvOS 26, and visionOS 26. Returns an empty string on earlier versions.

float next_start_date = 0.0 🔗

float get_next_start_date()

There is currently no description for this property. Please help us by contributing one!

int release_state = 0 🔗

int get_release_state()

Raw integer value of Apple’s release state for this leaderboard.

Available on iOS 26, macOS 26, tvOS 26, and visionOS 26. Returns 0 on earlier versions.

float start_date = 0.0 🔗

float get_start_date()

There is currently no description for this property. Please help us by contributing one!

String title = "" 🔗

String get_title()

Display name shown to players.

int type = 0 🔗

int get_type()

The Apple leaderboard type returned as an integer value: 0 (classic), 1 (recurring), or 2 (unknown).

Method Descriptions¶

void load_entries(players: Array, timeScope: TimeScope, callback: Callable) 🔗

Loads the local player’s score together with the specified Array of GKPlayer objects for the given time scope (use the TimeScope values). The callback receives (GKLeaderboardEntry local, Array[GKLeaderboardEntry] scores, Variant error) where the first entry can be null if the local player has not posted a score. If error is not null, it contains a GKError.

void load_image(callback: Callable) 🔗

Downloads the leaderboard icon. The callback arguments are (Image image, Variant error) with exactly one being null, matching the load_image helper shown in the guide. error is a GKError.

void load_leaderboards(ids: PackedStringArray, callback: Callable) static 🔗

Fetches leaderboard metadata. Pass a PackedStringArray. Use PackedStringArray() to load every leaderboard configured for the app, or PackedStringArray(["leaderboard_id"]) to request specific identifiers. The callback receives Array[GKLeaderboard] and a Variant error string (null on success).

void load_local_player_entries(playerScope: PlayerScope, timeScope: TimeScope, rangeStart: int, rangeLength: int, callback: Callable) 🔗

Loads leaderboard entries for the local player. The callback receives (GKLeaderboardEntry local, Array[GKLeaderboardEntry] scores, Variant range, Variant error) where the first entry can be null if the local player has not posted a score. The value range is the number of total player count that matched the scope. Supply PlayerScope and TimeScope integers for the first two parameters. If error is not null, it is a GKError.

void load_previous_occurrence(callback: Callable) 🔗

Loads the previous occurrence for a recurring leaderboard.

The callback receives (GKLeaderboard leaderboard, Variant error). On failure leaderboard is null and error contains a GKError.

void submit_score(score: int, context: int, player: GKPlayer, callback: Callable) 🔗

Submits a score for the provided player. The callback receives a Variant with the GKError or null when the submission succeeds. See GameCenterGuide.md for an end-to-end example.