<!--
{
  "availability" : [
    "iOS: 4.1.0 -",
    "iPadOS: 4.1.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.8.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "GameKit",
  "identifier" : "/documentation/GameKit/GKMatchmaker",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "GameKit"
    ],
    "preciseIdentifier" : "c:objc(cs)GKMatchmaker"
  },
  "title" : "GKMatchmaker"
}
-->

# GKMatchmaker

An object that creates matches with other players without presenting an interface to the players.

```
class GKMatchmaker
```

## Overview

Use the `GKMatchmaker` class to auto-match players for a quicker game start, programmatically invite specific players, or implement your own interface for players to invite other players. If you want to present a familiar matchmaking GameKit interface to players, instead use either the [`GKMatchmakerViewController`](/documentation/GameKit/GKMatchmakerViewController) or [`GKTurnBasedMatchmakerViewController`](/documentation/GameKit/GKTurnBasedMatchmakerViewController) class.

If you host a game on your own server, you can also use this class to find Game Center players. That is, you implement the networking and communication between the players through your own servers not Game Center.

To find players using this class, create a [`GKMatchRequest`](/documentation/GameKit/GKMatchRequest) object and configure it according to the parameters of your game. Then, pass the match request and a handler using the [`findMatch(for:withCompletionHandler:)`](/documentation/GameKit/GKMatchmaker/findMatch(for:withCompletionHandler:)) method, or the [`findPlayers(forHostedMatchRequest:withCompletionHandler:)`](/documentation/GameKit/GKMatchmaker/findPlayers(forHostedMatchRequest:withCompletionHandler:)) method for hosted games, to the shared `GKMatchmaker` object.

GameKit calls the handler when players accept their invitations. Implement the handler to set the delegate of the [`GKMatch`](/documentation/GameKit/GKMatch) object that GameKit sends and start the game when there are enough players.

If the match doesn’t have enough players (for example, some players decline their invitations), you can create another match request and call the [`addPlayers(to:matchRequest:completionHandler:)`](/documentation/GameKit/GKMatchmaker/addPlayers(to:matchRequest:completionHandler:)) method repeatedly until the match’s [`expectedPlayerCount`](/documentation/GameKit/GKMatch/expectedPlayerCount) property is zero. When you have enough players to start the match, call the [`finishMatchmaking(for:)`](/documentation/GameKit/GKMatchmaker/finishMatchmaking(for:)) method to end the matchmaking process.

If you provide a SharePlay interface for inviting players, use the [`startGroupActivity(playerHandler:)`](/documentation/GameKit/GKMatchmaker/startGroupActivity(playerHandler:)) and [`stopGroupActivity()`](/documentation/GameKit/GKMatchmaker/stopGroupActivity()) methods to create a group activity on behalf of the player.

## Topics

### Retrieving the shared matchmaker

[`+  sharedMatchmaker`](/documentation/GameKit/GKMatchmaker/shared())

Returns the singleton matchmaker instance.

### Receiving invitations from other players

[`-  matchForInvite:completionHandler:`](/documentation/GameKit/GKMatchmaker/match(for:completionHandler:))

Creates a match from an invitation that the local player accepts.

### Matching players

[`-  findMatchForRequest:withCompletionHandler:`](/documentation/GameKit/GKMatchmaker/findMatch(for:withCompletionHandler:))

Initiates a request to find players for a peer-to-peer match.

[`-  findPlayersForHostedRequest:withCompletionHandler:`](/documentation/GameKit/GKMatchmaker/findPlayers(forHostedRequest:withCompletionHandler:))

Initiates a request to find players for a hosted match.

[`-  findMatchedPlayers:withCompletionHandler:`](/documentation/GameKit/GKMatchmaker/findMatchedPlayers(_:withCompletionHandler:))

Initiates a request to find players for a hosted match that uses matchmaking rules.

[`GKMatchedPlayers`](/documentation/GameKit/GKMatchedPlayers)

An object that represents matchmaking results, including the players that join the match and their properties that matchmaking rules uses.

[`-  addPlayersToMatch:matchRequest:completionHandler:`](/documentation/GameKit/GKMatchmaker/addPlayers(to:matchRequest:completionHandler:))

Invites additional players to an existing match.

[`-  finishMatchmakingForMatch:`](/documentation/GameKit/GKMatchmaker/finishMatchmaking(for:))

Informs the server when programmatic matchmaking finishes.

[`-  cancel`](/documentation/GameKit/GKMatchmaker/cancel())

Cancels a matchmaking request.

[`-  cancelPendingInviteToPlayer:`](/documentation/GameKit/GKMatchmaker/cancelPendingInvite(to:))

Cancels a pending invitation to another player.

### Finding players who request matches

[`-  queryActivityWithCompletionHandler:`](/documentation/GameKit/GKMatchmaker/queryActivity(completionHandler:))

Finds the number of players, across player groups, who recently requested a match.

[`-  queryPlayerGroupActivity:withCompletionHandler:`](/documentation/GameKit/GKMatchmaker/queryPlayerGroupActivity(_:withCompletionHandler:))

Finds the number of players in a player group who recently requested a match.

[`-  queryQueueActivity:withCompletionHandler:`](/documentation/GameKit/GKMatchmaker/queryQueueActivity(_:withCompletionHandler:))

Finds the number of players in a specific queue who recently requested a match.

### Looking for nearby players

[`-  startBrowsingForNearbyPlayersWithHandler:`](/documentation/GameKit/GKMatchmaker/startBrowsingForNearbyPlayers(handler:))

Finds nearby players through Bluetooth or WiFi on the same subnet.

[`-  stopBrowsingForNearbyPlayers`](/documentation/GameKit/GKMatchmaker/stopBrowsingForNearbyPlayers())

Stops finding nearby players.

### Starting matches using SharePlay

[`-  startGroupActivityWithPlayerHandler:`](/documentation/GameKit/GKMatchmaker/startGroupActivity(playerHandler:))

Begins a SharePlay activity for your game when a FaceTime call is active.

[`-  stopGroupActivity`](/documentation/GameKit/GKMatchmaker/stopGroupActivity())

Ends a SharePlay activity for the entire group, which the local player activates.

### Deprecated

[Deprecated Symbols](/documentation/GameKit/gkmatchmaker-deprecated-symbols)

## Relationships

### Conforms To

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`Equatable`](/documentation/Swift/Equatable)

[`CVarArg`](/documentation/Swift/CVarArg)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`Hashable`](/documentation/Swift/Hashable)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

### Inherits From

[`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)