:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/master/../../GodotApplePlugins/doc_classes/GKLeaderboard.xml. .. _class_GKLeaderboard: GKLeaderboard ============= **Inherits:** :ref:`RefCounted` **<** :ref:`Object` Accesses Apple Game Center leaderboards and their entries. .. rst-class:: classref-introduction-group 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): .. tabs:: .. code-tab:: gdscript 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: .. tabs:: .. code-tab:: gdscript # 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()) ) .. rst-class:: classref-reftable-group Properties ---------- .. table:: :widths: auto +-------------------------------------+------------------------------------------------------------------------------+---------+ | :ref:`String` | :ref:`activity_identifier` | ``""`` | +-------------------------------------+------------------------------------------------------------------------------+---------+ | :ref:`Dictionary` | :ref:`activity_properties` | ``{}`` | +-------------------------------------+------------------------------------------------------------------------------+---------+ | :ref:`float` | :ref:`duration` | ``0.0`` | +-------------------------------------+------------------------------------------------------------------------------+---------+ | :ref:`String` | :ref:`group_identifier` | ``""`` | +-------------------------------------+------------------------------------------------------------------------------+---------+ | :ref:`float` | :ref:`next_start_date` | ``0.0`` | +-------------------------------------+------------------------------------------------------------------------------+---------+ | :ref:`float` | :ref:`start_date` | ``0.0`` | +-------------------------------------+------------------------------------------------------------------------------+---------+ | :ref:`String` | :ref:`title` | ``""`` | +-------------------------------------+------------------------------------------------------------------------------+---------+ | :ref:`int` | :ref:`type` | ``0`` | +-------------------------------------+------------------------------------------------------------------------------+---------+ .. rst-class:: classref-reftable-group Methods ------- .. table:: :widths: auto +--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`load_entries`\ (\ players\: :ref:`Array`, timeScope\: :ref:`int`, callback\: :ref:`Callable`\ ) | +--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`load_image`\ (\ callback\: :ref:`Callable`\ ) | +--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`load_leaderboards`\ (\ ids\: :ref:`PackedStringArray`, callback\: :ref:`Callable`\ ) |static| | +--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`load_local_player_entries`\ (\ playerScope\: :ref:`int`, timeScope\: :ref:`int`, rangeStart\: :ref:`int`, rangeLenght\: :ref:`int`, callback\: :ref:`Callable`\ ) | +--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`submit_score`\ (\ score\: :ref:`int`, context\: :ref:`int`, player\: :ref:`GKPlayer`, callback\: :ref:`Callable`\ ) | +--------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_GKLeaderboard_AppleLeaderboardType: .. rst-class:: classref-enumeration enum **AppleLeaderboardType**: :ref:`🔗` .. _class_GKLeaderboard_constant_classic: .. rst-class:: classref-enumeration-constant :ref:`AppleLeaderboardType` **classic** = ``0`` A leaderboard that never expires, showing all-time rankings of all players. .. _class_GKLeaderboard_constant_recurring: .. rst-class:: classref-enumeration-constant :ref:`AppleLeaderboardType` **recurring** = ``1`` A leaderboard that recurs, allowing players a fresh start to compete and earn higher ranks in each ocurrence. .. _class_GKLeaderboard_constant_unknown: .. rst-class:: classref-enumeration-constant :ref:`AppleLeaderboardType` **unknown** = ``2`` .. container:: contribute There is currently no description for this enum. Please help us by `contributing one `__! .. rst-class:: classref-item-separator ---- .. _enum_GKLeaderboard_TimeScope: .. rst-class:: classref-enumeration enum **TimeScope**: :ref:`🔗` .. _class_GKLeaderboard_constant_today: .. rst-class:: classref-enumeration-constant :ref:`TimeScope` **today** = ``0`` Scans the current day. .. _class_GKLeaderboard_constant_week: .. rst-class:: classref-enumeration-constant :ref:`TimeScope` **week** = ``1`` Restricts results to the current week. .. _class_GKLeaderboard_constant_allTime: .. rst-class:: classref-enumeration-constant :ref:`TimeScope` **allTime** = ``2`` Returns scores across the entire history of the leaderboard. .. rst-class:: classref-item-separator ---- .. _enum_GKLeaderboard_PlayerScope: .. rst-class:: classref-enumeration enum **PlayerScope**: :ref:`🔗` .. _class_GKLeaderboard_constant_global: .. rst-class:: classref-enumeration-constant :ref:`PlayerScope` **global** = ``0`` Loads data for all players of the game. .. _class_GKLeaderboard_constant_friendsOnly: .. rst-class:: classref-enumeration-constant :ref:`PlayerScope` **friendsOnly** = ``1`` Loads only data for friends of the local player. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_GKLeaderboard_property_activity_identifier: .. rst-class:: classref-property :ref:`String` **activity_identifier** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget - :ref:`String` **get_activity_identifier**\ (\ ) Beta-only identifier for activity leaderboards (empty on platforms that do not expose the value). .. rst-class:: classref-item-separator ---- .. _class_GKLeaderboard_property_activity_properties: .. rst-class:: classref-property :ref:`Dictionary` **activity_properties** = ``{}`` :ref:`🔗` .. rst-class:: classref-property-setget - :ref:`Dictionary` **get_activity_properties**\ (\ ) Dictionary copy of Apple's ``activityProperties``, containing keys such as ``eventStartDate`` when available. .. rst-class:: classref-item-separator ---- .. _class_GKLeaderboard_property_duration: .. rst-class:: classref-property :ref:`float` **duration** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget - :ref:`float` **get_duration**\ (\ ) Leaderboard duration in seconds for recurring leaderboards. .. rst-class:: classref-item-separator ---- .. _class_GKLeaderboard_property_group_identifier: .. rst-class:: classref-property :ref:`String` **group_identifier** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget - :ref:`String` **get_group_identifier**\ (\ ) Group identifier that you configured in App Store Connect, or an empty string if not grouped. .. rst-class:: classref-item-separator ---- .. _class_GKLeaderboard_property_next_start_date: .. rst-class:: classref-property :ref:`float` **next_start_date** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget - :ref:`float` **get_next_start_date**\ (\ ) .. container:: contribute There is currently no description for this property. Please help us by `contributing one `__! .. rst-class:: classref-item-separator ---- .. _class_GKLeaderboard_property_start_date: .. rst-class:: classref-property :ref:`float` **start_date** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget - :ref:`float` **get_start_date**\ (\ ) .. container:: contribute There is currently no description for this property. Please help us by `contributing one `__! .. rst-class:: classref-item-separator ---- .. _class_GKLeaderboard_property_title: .. rst-class:: classref-property :ref:`String` **title** = ``""`` :ref:`🔗` .. rst-class:: classref-property-setget - :ref:`String` **get_title**\ (\ ) Display name shown to players. .. rst-class:: classref-item-separator ---- .. _class_GKLeaderboard_property_type: .. rst-class:: classref-property :ref:`int` **type** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - :ref:`int` **get_type**\ (\ ) The Apple leaderboard type returned as an integer value: ``0`` (``classic``), ``1`` (``recurring``), or ``2`` (``unknown``). .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_GKLeaderboard_method_load_entries: .. rst-class:: classref-method |void| **load_entries**\ (\ players\: :ref:`Array`, timeScope\: :ref:`int`, callback\: :ref:`Callable`\ ) :ref:`🔗` Loads the local player's score together with the specified ``Array`` of ``GKPlayer`` objects for the given time scope (use the :ref:`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. .. rst-class:: classref-item-separator ---- .. _class_GKLeaderboard_method_load_image: .. rst-class:: classref-method |void| **load_image**\ (\ callback\: :ref:`Callable`\ ) :ref:`🔗` 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. .. rst-class:: classref-item-separator ---- .. _class_GKLeaderboard_method_load_leaderboards: .. rst-class:: classref-method |void| **load_leaderboards**\ (\ ids\: :ref:`PackedStringArray`, callback\: :ref:`Callable`\ ) |static| :ref:`🔗` 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). .. rst-class:: classref-item-separator ---- .. _class_GKLeaderboard_method_load_local_player_entries: .. rst-class:: classref-method |void| **load_local_player_entries**\ (\ playerScope\: :ref:`int`, timeScope\: :ref:`int`, rangeStart\: :ref:`int`, rangeLenght\: :ref:`int`, callback\: :ref:`Callable`\ ) :ref:`🔗` 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 :ref:`PlayerScope` and :ref:`TimeScope` integers for the first two parameters. .. rst-class:: classref-item-separator ---- .. _class_GKLeaderboard_method_submit_score: .. rst-class:: classref-method |void| **submit_score**\ (\ score\: :ref:`int`, context\: :ref:`int`, player\: :ref:`GKPlayer`, callback\: :ref:`Callable`\ ) :ref:`🔗` 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. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` .. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` .. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` .. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` .. |void| replace:: :abbr:`void (No return value.)`