<!--
{
  "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 -",
    "watchOS: 3.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "GameKit",
  "identifier" : "/documentation/GameKit/GKMatchRequest",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "GameKit"
    ],
    "preciseIdentifier" : "c:objc(cs)GKMatchRequest"
  },
  "title" : "GKMatchRequest"
}
-->

# GKMatchRequest

An object that encapsulates the parameters to create a real-time or turn-based match.

```
class GKMatchRequest
```

## Overview

To request a match, set the properties of the match request, such as the number of players, the invitation message, and whether to use automatch to fill the player slots. You’re required to set the minimum and maximum number of players allowed in the match. Then, pass the match request to the appropriate class, depending on the type of game and whether you implement your own user interface.

To use the matchmaking user interface that GameKit provides, pass the match request to the [`GKMatchmakerViewController`](/documentation/GameKit/GKMatchmakerViewController) class for real-time games, or the [`GKTurnBasedMatchmakerViewController`](/documentation/GameKit/GKTurnBasedMatchmakerViewController) class for turn-based games. GameKit sends messages to the delegates of these classes when players receive and accept invitations to the match.

If you implement your own interface for finding players, pass the match request to the [`GKMatchmaker`](/documentation/GameKit/GKMatchmaker) class for real-time games, or the [`GKTurnBasedMatch`](/documentation/GameKit/GKTurnBasedMatch) class for turn-based games. If the player selects the other players to invite in your interface, set the [`recipients`](/documentation/GameKit/GKMatchRequest/recipients), the [`inviteMessage`](/documentation/GameKit/GKMatchRequest/inviteMessage), and the [`recipientResponseHandler`](/documentation/GameKit/GKMatchRequest/recipientResponseHandler) properties before creating the match.

### Matchmaking using rules

You can refine the match results and reduce player wait times by configuring matchmaking before you present an interface. You can either find players using matchmaking rules you set up on the server, or find players from a subset of players you specify in the game.

To use matchmaking rules, set the [`queueName`](/documentation/GameKit/GKMatchRequest/queueName) property to the queue name that you configure in App Store Connect. Optionally, set [`properties`](/documentation/GameKit/GKMatchRequest/properties) and [`recipientProperties`](/documentation/GameKit/GKMatchRequest/recipientProperties) to game-specific criteria. Players in the [`recipientProperties`](/documentation/GameKit/GKMatchRequest/recipientProperties) property need to also be in the [`recipients`](/documentation/GameKit/GKMatchRequest/recipients) property — that is, be a recipient of an invitation. When using matchmaking rules, Game Center ignores the subset that you specify using the [`playerGroup`](/documentation/GameKit/GKMatchRequest/playerGroup) and [`playerAttributes`](/documentation/GameKit/GKMatchRequest/playerAttributes) properties.

If you set the request’s [`minPlayers`](/documentation/GameKit/GKMatchRequest/minPlayers) and [`maxPlayers`](/documentation/GameKit/GKMatchRequest/maxPlayers) properties, use values that are in the rule set’s player range. Otherwise, the default values for these properties are the rule set’s `minPlayers` and `maxPlayers` fields (see <doc://com.apple.documentation/documentation/AppStoreConnectAPI/POST-v1-gameCenterMatchmakingRuleSets>).

If you don’t use matchmaking rules, you can restrict finding players to a subset of players. Set the [`queueName`](/documentation/GameKit/GKMatchRequest/queueName) property to `nil`, and set the [`playerGroup`](/documentation/GameKit/GKMatchRequest/playerGroup) and [`playerAttributes`](/documentation/GameKit/GKMatchRequest/playerAttributes) properties to specify the subset. Then matchmaking ignores the rules-based [`properties`](/documentation/GameKit/GKMatchRequest/properties) and [`recipientProperties`](/documentation/GameKit/GKMatchRequest/recipientProperties) properties.

For more information, see <doc://com.apple.documentation/documentation/GameKit/finding-players-using-matchmaking-rules>.

> Important:
> Matchmaking rules are only available for peer-to-peer (``doc://com.apple.gamekit/documentation/GameKit/GKMatchType/peerToPeer``) and hosted (``doc://com.apple.gamekit/documentation/GameKit/GKMatchType/hosted``) match requests.

## Topics

### Restricting the number of players

[`+  maxPlayersAllowedForMatchOfType:`](/documentation/GameKit/GKMatchRequest/maxPlayersAllowedForMatch(of:))

Returns the maximum number of players allowed in the match request for a given match type.

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

The kind of match managed by Game Center.

[`minPlayers`](/documentation/GameKit/GKMatchRequest/minPlayers)

The minimum number of players that can join the match.

[`maxPlayers`](/documentation/GameKit/GKMatchRequest/maxPlayers)

The maximum number of players that can join the match.

[`defaultNumberOfPlayers`](/documentation/GameKit/GKMatchRequest/defaultNumberOfPlayers)

The default number of players for the match.

### Inviting players

[`inviteMessage`](/documentation/GameKit/GKMatchRequest/inviteMessage)

The message sent to other players when the local player invites them to join a match.

[`recipients`](/documentation/GameKit/GKMatchRequest/recipients)

The players to invite to the match.

[`recipientResponseHandler`](/documentation/GameKit/GKMatchRequest/recipientResponseHandler)

A method that handles when a player responds to an invitation to join a match.

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

A player’s response to an invitation to join a match.

### Matching players using rules

[`queueName`](/documentation/GameKit/GKMatchRequest/queueName)

The name of the queue that Game Center places the match request in.

[`properties`](/documentation/GameKit/GKMatchRequest/properties)

The criteria for the local player that Game Center uses to find other players when using matchmaking rules.

[`recipientProperties`](/documentation/GameKit/GKMatchRequest/recipientProperties)

The criteria for recipients of the match request that Game Center uses to find other players when using matchmaking rules.

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

A type for game-specific properties that Game Center uses to find players when using matchmaking rules.

### Matching specific players

[`playerGroup`](/documentation/GameKit/GKMatchRequest/playerGroup)

A number identifying a subset of players invited to join a match.

[`playerAttributes`](/documentation/GameKit/GKMatchRequest/playerAttributes)

A mask that specifies the role that the local player would like to play in the game.

### Deprecated methods and properties

[`inviteeResponseHandler`](/documentation/GameKit/GKMatchRequest/inviteeResponseHandler)

Handles when a player responds to an invitation.

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

Possible responses from an invitation to a remote player.

[`playersToInvite`](/documentation/GameKit/GKMatchRequest/playersToInvite)

A list of player identifiers for players to invite to the match.

[`restrictToAutomatch`](/documentation/GameKit/GKMatchRequest/restrictToAutomatch)

A Boolean value that determines whether a game uses automatch to find players or the local player invites players.

## Relationships

### Conforms To

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

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

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

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

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

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

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