GKLeaderboard¶

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(["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([], 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(["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	`{}`
float	duration	`0.0`
String	group_identifier	`""`
float	next_start_date	`0.0`
float	start_date	`0.0`
String	title	`""`
int	type	`0`

Methods¶

void	load_entries(players: Array, timeScope: int, callback: Callable)
void	load_image(callback: Callable)
void	load_leaderboards(ids: PackedStringArray, callback: Callable) static
void	load_local_player_entries(playerScope: int, timeScope: int, rangeStart: int, rangeLenght: int, 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 allTime = 2

Returns scores across the entire history of the leaderboard.

enum PlayerScope: 🔗

PlayerScope global = 0

Loads data for all players of the game.

PlayerScope friendsOnly = 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.

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.

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!

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: int, 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.

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.

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

Fetches leaderboard metadata. Pass an empty array to load every leaderboard configured for the app, or provide specific identifiers. The callback receives Array[GKLeaderboard] and a Variant error string (null on success).

void load_local_player_entries(playerScope: int, timeScope: int, rangeStart: int, rangeLenght: 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.

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 error string or null when the submission succeeds. See GameCenterGuide.md for an end-to-end example.