: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/GKMatch.xml. .. _class_GKMatch: GKMatch ======= **Inherits:** :ref:`RefCounted` **<** :ref:`Object` Represents an active real-time Game Center match. .. rst-class:: classref-introduction-group Description ----------- ``GKMatch`` wraps Apple's realtime networking object. After starting matchmaking with ``GKMatchmakerViewController`` (see the "Realtime Matchmaking" section of ``GameCenterGuide.md``) you will receive a ``GKMatch`` instance and can send data, monitor players, and respond to disconnections via Godot signals. For platform specifics see `Apple's GKMatch reference `__. Guide sample showing matchmaking and signal hookups: .. tabs:: .. code-tab:: gdscript var request := GKMatchRequest.new() request.max_players = 2 request.min_players = 1 request.invite_message = "Join me in a quest to fun" GKMatchmakerViewController.request_match(request, func(game_match: GKMatch, error: Variant) -> void: if error: print("Could not request a match %s" % error) return print("Got a match!") game_match.data_received.connect(func(data: PackedByteArray, from_player: GKPlayer) -> void: print("Received data from %s" % from_player.display_name) ) game_match.data_received_for_recipient_from_player.connect(func(data: PackedByteArray, for_recipient: GKPlayer, from_remote_player: GKPlayer) -> void: print("Forwarded data for %s from %s" % [for_recipient.display_name, from_remote_player.display_name]) ) game_match.did_fail_with_error.connect(func(match_error: String) -> void: print("Match failed with %s" % match_error) ) game_match.should_reinvite_disconnected_player = func(player: GKPlayer) -> bool: return true game_match.player_changed.connect(func(player: GKPlayer, connected: bool) -> void: print("Player %s changed to %s" % [player.display_name, connected]) ) ) Broadcast helper from the guide (assuming you keep the reference as ``game_match``): .. tabs:: .. code-tab:: gdscript var data := "How do you do fellow kids".to_utf8_buffer() game_match.send_data_to_all_players(data, GKMatch.SendDataMode.reliable) Send to a subset of players (still using the ``game_match`` variable): .. tabs:: .. code-tab:: gdscript var payload := PackedByteArray([1, 2, 3]) var recipients := [first_player, second_player] game_match.send(payload, recipients, GKMatch.SendDataMode.reliable) .. rst-class:: classref-reftable-group Properties ---------- .. table:: :widths: auto +-------------------------------+--------------------------------------------------------------------------------------------------------+--------+ | :ref:`int` | :ref:`expected_player_count` | ``0`` | +-------------------------------+--------------------------------------------------------------------------------------------------------+--------+ | :ref:`Array` | :ref:`players` | ``[]`` | +-------------------------------+--------------------------------------------------------------------------------------------------------+--------+ | :ref:`Variant` | :ref:`should_reinvite_disconnected_player` | | +-------------------------------+--------------------------------------------------------------------------------------------------------+--------+ .. rst-class:: classref-reftable-group Methods ------- .. table:: :widths: auto +-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`disconnect`\ (\ ) | +-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`send`\ (\ data\: :ref:`PackedByteArray`, toPlayers\: :ref:`Array`, dataMode\: :ref:`int`\ ) | +-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`send_data_to_all_players`\ (\ data\: :ref:`PackedByteArray`, dataMode\: :ref:`int`\ ) | +-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Signals ------- .. _class_GKMatch_signal_data_received: .. rst-class:: classref-signal **data_received**\ (\ arg1\: :ref:`PackedByteArray`, arg2\: :ref:`GKPlayer`\ ) :ref:`🔗` Emitted when another player sends data to the local device. Provides the raw bytes and the sender. .. rst-class:: classref-item-separator ---- .. _class_GKMatch_signal_data_received_for_recipient_from_player: .. rst-class:: classref-signal **data_received_for_recipient_from_player**\ (\ arg1\: :ref:`PackedByteArray`, arg2\: :ref:`GKPlayer`, arg3\: :ref:`GKPlayer`\ ) :ref:`🔗` Emitted when the local player receives data that was addressed to a specific recipient. Arguments provide the payload, the intended recipient, and the sender. .. rst-class:: classref-item-separator ---- .. _class_GKMatch_signal_did_fail_with_error: .. rst-class:: classref-signal **did_fail_with_error**\ (\ arg1\: :ref:`String`\ ) :ref:`🔗` Fires when Apple reports a networking error. The ``String`` argument contains the localized description. .. rst-class:: classref-item-separator ---- .. _class_GKMatch_signal_player_changed: .. rst-class:: classref-signal **player_changed**\ (\ arg1\: :ref:`GKPlayer`, arg2\: :ref:`bool`\ ) :ref:`🔗` Notifies you when a player connects or disconnects. The boolean is ``true`` for connected players and ``false`` otherwise. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_GKMatch_SendDataMode: .. rst-class:: classref-enumeration enum **SendDataMode**: :ref:`🔗` .. _class_GKMatch_constant_reliable: .. rst-class:: classref-enumeration-constant :ref:`SendDataMode` **reliable** = ``0`` Uses GameKit's reliable data channel (ordered delivery with retries). .. _class_GKMatch_constant_unreliable: .. rst-class:: classref-enumeration-constant :ref:`SendDataMode` **unreliable** = ``1`` Uses GameKit's unreliable channel, useful for latency-sensitive updates. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_GKMatch_property_expected_player_count: .. rst-class:: classref-property :ref:`int` **expected_player_count** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - :ref:`int` **get_expected_player_count**\ (\ ) The number of additional players that GameKit is recruiting before the match can begin. .. rst-class:: classref-item-separator ---- .. _class_GKMatch_property_players: .. rst-class:: classref-property :ref:`Array` **players** = ``[]`` :ref:`🔗` .. rst-class:: classref-property-setget - :ref:`Array` **get_players**\ (\ ) Array of ``GKPlayer`` instances that are currently connected. .. rst-class:: classref-item-separator ---- .. _class_GKMatch_property_should_reinvite_disconnected_player: .. rst-class:: classref-property :ref:`Variant` **should_reinvite_disconnected_player** :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_should_reinvite_disconnected_player**\ (\ value\: :ref:`Variant`\ ) - :ref:`Variant` **get_should_reinvite_disconnected_player**\ (\ ) Optional ``Callable`` that receives a ``GKPlayer`` and returns ``true`` if the player should be reinvited after disconnecting (see the sample in ``GameCenterGuide.md``). .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_GKMatch_method_disconnect: .. rst-class:: classref-method |void| **disconnect**\ (\ ) :ref:`🔗` Calls ``GKMatch.disconnect()`` to leave the match immediately. .. rst-class:: classref-item-separator ---- .. _class_GKMatch_method_send: .. rst-class:: classref-method :ref:`int` **send**\ (\ data\: :ref:`PackedByteArray`, toPlayers\: :ref:`Array`, dataMode\: :ref:`int`\ ) :ref:`🔗` Sends a payload to the specified ``Array[GKPlayer]``. Returns a :ref:`Error` value (``OK`` on success, ``FAILED`` when the payload could not be converted or Apple reported an error). Choose a :ref:`SendDataMode` constant for ``dataMode``. .. rst-class:: classref-item-separator ---- .. _class_GKMatch_method_send_data_to_all_players: .. rst-class:: classref-method :ref:`int` **send_data_to_all_players**\ (\ data\: :ref:`PackedByteArray`, dataMode\: :ref:`int`\ ) :ref:`🔗` Broadcasts the packed bytes to everyone in the match. Return value matches :ref:`send()`. Use the :ref:`SendDataMode` constants. .. |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.)`