GKMatchmakerViewController

Inherits: RefCounted < Object

Presents Apple’s Game Center matchmaking UI.

Description

Use this helper to show the stock GKMatchmakerViewController workflow described in GameCenterGuide.md. You can either create and present the controller manually for full control or call request_match() for the convenience flow demonstrated in the guide. See Apple’s GKMatchmakerViewController reference for Apple’s API documentation.

Convenience usage from the guide:

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)
    else:
        print("Match ready")
        # Store game_match and connect to its signals as needed.
)

Properties

bool	can_start_with_minimum_players	false
Variant	get_match_properties_for_recipient
bool	is_hosted	false
GKMatchRequest	match_request	null
int	matchmaking_mode	0

Methods

void	add_players_to_match(match: GKMatch)
GKMatchmakerViewController	create_controller(request: GKMatchRequest) static
GKMatchmakerViewController	create_controller_from_invite(invite: GKInvite) static
void	present()
void	request_match(request: GKMatchRequest, callback: Callable) static
void	set_hosted_player_did_connect(player: GKPlayer, didConnect: bool)

---

Signals

cancelled(detail: String) 🔗

Emitted when the user cancels the matchmaking UI. The string is empty on UIKit and contains an informational message on macOS.

---

did_find_hosted_players(players: Array) 🔗

Fired when GameKit returns players for a hosted-server scenario. The array contains GKPlayer instances.

---

did_find_match(match: GKMatch) 🔗

Triggered when a peer-to-peer match has been found and is ready to start.

---

failed_with_error(message: String) 🔗

Emitted if Apple reports an error while matchmaking. The string contains localizedDescription.

---

hosted_player_did_accept(player: GKPlayer) 🔗

Emitted when a hosted player accepts the match invitation.

---

Property Descriptions

bool can_start_with_minimum_players = false 🔗

• void set_can_start_with_minimum_players(value: bool)

• bool get_can_start_with_minimum_players()

When supported, allows starting the match once minimum player count is met.

---

Variant get_match_properties_for_recipient 🔗

• void set_get_match_properties_for_recipient(value: Variant)

• Variant get_get_match_properties_for_recipient()

Optional Callable used for hosted matches. It receives a GKPlayer recipient and should return a Dictionary of match properties.

---

bool is_hosted = false 🔗

• void set_is_hosted(value: bool)

• bool get_is_hosted()

If true, matchmaking is configured for hosted/server scenarios.

---

GKMatchRequest match_request = null 🔗

• GKMatchRequest get_match_request()

The underlying match request used to configure this controller.

---

int matchmaking_mode = 0 🔗

• void set_matchmaking_mode(value: int)

• int get_matchmaking_mode()

Controls matchmaking strategy. Raw values map to default/nearby-only/automatch-only/invite-only modes.

---

Method Descriptions

void add_players_to_match(match: GKMatch) 🔗

Adds additional players to an existing GKMatch.

---

GKMatchmakerViewController create_controller(request: GKMatchRequest) static 🔗

Builds a wrapper around Apple’s view controller for the supplied GKMatchRequest. Configure the returned object and call present() to display it.

---

GKMatchmakerViewController create_controller_from_invite(invite: GKInvite) static 🔗

Creates a matchmaking controller configured from an accepted GKInvite.

---

void present() 🔗

Presents the previously created view controller, handling both UIKit and AppKit dialog flows.

---

void request_match(request: GKMatchRequest, callback: Callable) static 🔗

Shows the matchmaking UI and invokes the callback with (GKMatch match, Variant error) where only one argument is non-null. Errors are reported as GKError objects.

---

void set_hosted_player_did_connect(player: GKPlayer, didConnect: bool) 🔗

Notifies GameKit that a hosted player has connected or disconnected.