GKAchievement

Inherits: RefCounted < Object

Represents an Apple Game Center achievement and provides helper methods to manage progress.

Description

Use GKAchievement to mirror the player’s progress that you configured on App Store Connect. The static helpers expose the same workflows mentioned in the Achievements section of GameCenterGuide.md: listing the player’s reported achievements, resetting them during testing, and sending new completion percentages. Apple’s API reference is available at Apple’s GKAchievement reference.

List all achievements (straight from the guide):

GKAchievement.load_achievements(func(achievements: Array[GKAchievement], error: Variant) -> void:
    if error:
        print("Load achievement error %s" % error)
    else:
        for achievement in achievements:
            print("Achievement: %s" % achievement.identifier)
)

Report progress and reset utilities:

var id := "a001"
var percentage := 100.0

GKAchievement.load_achievements(func(achievements: Array[GKAchievement], error: Variant) -> void:
    if error:
        print("Load achievement error %s" % error)
        return

    for achievement in achievements:
        if achievement.identifier == id and not achievement.is_completed:
            achievement.percent_complete = percentage
            achievement.shows_completion_banner = true
            GKAchievement.report_achievement([achievement], func(submit_error: Variant) -> void:
                if submit_error:
                    print("Error submitting achievement %s" % submit_error)
                else:
                    print("Success!")
            )
)

GKAchievement.reset_achievements(func(error: Variant) -> void:
    if error:
        print("Error resetting achievements %s" % error)
    else:
        print("Reset complete")
)

Properties

String

identifier

"*uninitialized achievement identifier*"

bool

is_completed

false

float

last_reported_date

1776695700.0

float

percent_complete

0.0

GKPlayer

player

bool

shows_completion_banner

true

Methods

void

challenge_compose_controller(message: String, players: Array)

void

load_achievements(callback: Callable) static

GKAchievement

make(identifier: String) static

GKAchievement

make_for_player(identifier: String, player: GKPlayer) static

void

report_achievement(achievements: Array, callback: Callable) static

void

reset_achievements(callback: Callable) static

void

select_challengeable_players(players: Array, callback: Callable)

Property Descriptions

String identifier = "*uninitialized achievement identifier*" 🔗

  • void set_identifier(value: String)

  • String get_identifier()

The achievement identifier configured on App Store Connect.

bool is_completed = false 🔗

  • bool get_is_completed()

Read-only flag that mirrors GameKit’s isCompleted property.

float last_reported_date = 1776695700.0 🔗

  • float get_last_reported_date()

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

float percent_complete = 0.0 🔗

  • void set_percent_complete(value: float)

  • float get_percent_complete()

The player’s reported completion percentage (0-100). Update this and then call report_achievement() to submit it.

GKPlayer player 🔗

The GKPlayer owner of this achievement, if GameKit was able to resolve it.

bool shows_completion_banner = true 🔗

  • void set_shows_completion_banner(value: bool)

  • bool get_shows_completion_banner()

Matches Apple’s showsCompletionBanner flag. Set it to true when you want the system to display the stock achievement toast when the progress hits 100%.

Method Descriptions

void challenge_compose_controller(message: String, players: Array) 🔗

Opens Apple’s challenge compose UI for this achievement, prefilled with message and the players candidates.

players should contain GKPlayer objects.

void load_achievements(callback: Callable) static 🔗

Loads the achievements that the local player has already reported. The callback is invoked with Array[GKAchievement] and a Variant error argument (null on success, or a localized error string).

GKAchievement make(identifier: String) static 🔗

Creates a new achievement instance for the local player using the App Store Connect achievement identifier.

GKAchievement make_for_player(identifier: String, player: GKPlayer) static 🔗

Creates a new achievement instance for player using the App Store Connect achievement identifier.

void report_achievement(achievements: Array, callback: Callable) static 🔗

Submits the new state for the provided achievements. The callback receives a single Variant that is null on success or contains an error string reported by GameKit. This is the method used in the “Report Progress” snippet inside GameCenterGuide.md.

void reset_achievements(callback: Callable) static 🔗

Asks GameKit to clear every achievement for the local player. The callback receives null on success or a Variant with the error description, matching Apple’s resetAchievements API.

void select_challengeable_players(players: Array, callback: Callable) 🔗

Filters players to the subset that can currently be challenged for this achievement.

The callback receives (Array[GKPlayer] challengeable_players, Variant error), where error is null on success or a GKError.