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_achivement([achievement], func(submit_error: Variant) -> void:
                if submit_error:
                    print("Error submitting achievement %s" % submit_error)
                else:
                    print("Success!")
            )
)

GKAchievement.reset_achivements(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

1765604200.0

float

percent_complete

0.0

GKPlayer

player

bool

shows_completion_banner

true

Methods

void

load_achievements(callback: Callable) static

void

report_achivement(achivements: Array, callback: Callable) static

void

reset_achivements(callback: Callable) static

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 = 1765604200.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_achivement() 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 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).

void report_achivement(achivements: 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_achivements(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.