GKMatch

Inherits: RefCounted < Object

Represents an active real-time Game Center match.

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:

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):

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):

var payload := PackedByteArray([1, 2, 3])
var recipients := [first_player, second_player]
game_match.send(payload, recipients, GKMatch.SendDataMode.reliable)

Properties

int	expected_player_count	0
Dictionary	player_properties	{}
Array	players	[]
Dictionary	properties	{}
Variant	should_reinvite_disconnected_player

Methods

void	choose_best_hosting_player(callback: Callable)
void	disconnect()
void	rematch(callback: Callable)
int	send(data: PackedByteArray, toPlayers: Array, dataMode: SendDataMode)
int	send_data_to_all_players(data: PackedByteArray, dataMode: SendDataMode)
GKVoiceChat	voice_chat(channel: String)

---

Signals

data_received(data: PackedByteArray, player: GKPlayer) 🔗

Emitted when another player sends data to the local device. Provides the raw bytes and the sender.

---

data_received_for_recipient_from_player(data: PackedByteArray, recipient: GKPlayer, from_remote_player: GKPlayer) 🔗

Emitted when the local player receives data that was addressed to a specific recipient. Arguments provide the payload, the intended recipient, and the sender.

---

did_fail_with_error(message: String) 🔗

Fires when Apple reports a networking error. The String argument contains the localized description.

---

player_changed(player: GKPlayer, connected: bool) 🔗

Notifies you when a player connects or disconnects. The boolean is true for connected players and false otherwise.

---

Enumerations

enum SendDataMode: 🔗

SendDataMode RELIABLE = 0

Uses GameKit’s reliable data channel (ordered delivery with retries).

SendDataMode UNRELIABLE = 1

Uses GameKit’s unreliable channel, useful for latency-sensitive updates.

---

Property Descriptions

int expected_player_count = 0 🔗

• int get_expected_player_count()

The number of additional players that GameKit is recruiting before the match can begin.

---

Dictionary player_properties = {} 🔗

• Dictionary get_player_properties()

Player-specific properties reported by GameKit for this match.

---

Array players = [] 🔗

• Array get_players()

Array of GKPlayer instances that are currently connected.

---

Dictionary properties = {} 🔗

• Dictionary get_properties()

Match-level custom properties provided by GameKit.

---

Variant should_reinvite_disconnected_player 🔗

• void set_should_reinvite_disconnected_player(value: Variant)

• 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).

---

Method Descriptions

void choose_best_hosting_player(callback: Callable) 🔗

Asks GameKit to choose the best host candidate for this peer-to-peer match. The callback receives (GKPlayer player, Variant error), where both values can be null if no candidate is available.

---

void disconnect() 🔗

Calls GKMatch.disconnect() to leave the match immediately.

---

void rematch(callback: Callable) 🔗

Requests a rematch with the same players. The callback receives (GKMatch match, Variant error).

---

int send(data: PackedByteArray, toPlayers: Array, dataMode: SendDataMode) 🔗

Sends a payload to the specified Array[GKPlayer]. Returns a Error value (OK on success, FAILED when the payload could not be converted or Apple reported an error). Choose a SendDataMode constant for dataMode.

---

int send_data_to_all_players(data: PackedByteArray, dataMode: SendDataMode) 🔗

Broadcasts the packed bytes to everyone in the match. Return value matches send(). Use the SendDataMode constants.

---

GKVoiceChat voice_chat(channel: String) 🔗

Returns a GKVoiceChat object for the named channel, or null if voice chat is unavailable.