GKAchievementDescription

Inherits: RefCounted < Object

Metadata for every achievement that is defined in App Store Connect.

Description

GKAchievementDescription exposes the localized text, group assignments, and icon that you configure for each achievement. Use load_achievement_descriptions() as shown in GameCenterGuide.md to list everything the player can unlock, even before they have reported progress. Apple’s documentation lives at Apple’s GKAchievementDescription reference.

Listing descriptions (guide sample):

GKAchievementDescription.load_achievement_descriptions(func(descriptions: Array[GKAchievementDescription], error: Variant) -> void:
    if error:
        print("Load achievement description error %s" % error)
    else:
        for description in descriptions:
            print("Achievement Description ID: %s" % description.identifier)
            print("    Unachieved: %s" % description.unachieved_description)
            print("    Achieved: %s" % description.achieved_description)
)

Loading an image sample (assuming description is one of the loaded entries):

description.load_image(func(image: Image, error: Variant) -> void:
    if error == null:
        $texture_rect.texture = ImageTexture.create_from_image(image)
    else:
        print("Error loading achievement image %s" % error)
)

Properties

String	achieved_description	""
String	activity_identifier	""
Dictionary[String, String]	activity_properties	{}
String	group_identifier	""
String	identifier	""
bool	is_hidden	false
bool	is_replayable	false
int	maximum_points	0
Variant	rarity_percent
int	release_state	0
String	title	""
String	unachieved_description	""

Methods

Variant	incomplete_achievement_image() static
void	load_achievement_descriptions(callback: Callable) static
void	load_image(callback: Callable)
Variant	placeholder_completed_achievement_image() static

---

Property Descriptions

String achieved_description = "" 🔗

• String get_achieved_description()

Text shown after the player completes the achievement.

---

String activity_identifier = "" 🔗

• String get_activity_identifier()

Game activity identifier attached to this achievement description.

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

---

Dictionary[String, String] activity_properties = {} 🔗

• Dictionary[String, String] get_activity_properties()

String key/value properties for the activity associated with this achievement description.

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

---

String group_identifier = "" 🔗

• String get_group_identifier()

The optional group identifier configured on App Store Connect.

---

String identifier = "" 🔗

• String get_identifier()

Unique identifier string for this description.

---

bool is_hidden = false 🔗

• bool get_is_hidden()

Indicates whether the achievement is currently hidden from the user.

---

bool is_replayable = false 🔗

• bool get_is_replayable()

True when the achievement can be earned more than once.

---

int maximum_points = 0 🔗

• int get_maximum_points()

The point value that Apple shows when this achievement is completed.

---

Variant rarity_percent 🔗

• Variant get_rarity_percent()

Either a double with Apple’s reported rarity or null on platforms that do not expose this data.

---

int release_state = 0 🔗

• int get_release_state()

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

Available on iOS 18.4, macOS 15.4, tvOS 18.4, and visionOS 2.4. Returns 0 on earlier versions.

---

String title = "" 🔗

• String get_title()

Display title, localized according to the player’s language.

---

String unachieved_description = "" 🔗

• String get_unachieved_description()

Text shown before the player meets the completion criteria.

---

Method Descriptions

Variant incomplete_achievement_image() static 🔗

Returns Apple’s shared image for an incomplete achievement as an Image Variant.

---

void load_achievement_descriptions(callback: Callable) static 🔗

Loads the entire catalog of achievement descriptions and calls the callback with Array[GKAchievementDescription] and a Variant error (null on success, or a GKError from GameKit).

---

void load_image(callback: Callable) 🔗

Downloads the image for this description. The callback receives (Image image, Variant error) where exactly one argument is null. If an error occurs, it is returned as a GKError.

---

Variant placeholder_completed_achievement_image() static 🔗

Returns Apple’s shared placeholder image for a completed achievement as an Image Variant.