<!--
{
  "availability" : [
    "iOS: 5.0.0 -",
    "iPadOS: 5.0.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/GKTurnBasedMatch",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "GameKit"
    ],
    "preciseIdentifier" : "c:objc(cs)GKTurnBasedMatch"
  },
  "title" : "GKTurnBasedMatch"
}
-->

# GKTurnBasedMatch

An object that encapsulates the match data for games where players take turns.

```
class GKTurnBasedMatch
```

## Overview

A `GKTurnBasedMatch` object represents a match in a turn-based game that Game Center stores and forwards to participants in the match. In a turn-based game, participants take turns to advance gameplay until they reach an outcome. You end the match when all participants reach an outcome or they can no longer continue.

A turn-based match object contains the status of the match, list of participants, the participant whose turn it is, a message about the last turn, and your game-specific data. You can get more details about the participants through the [`GKTurnBasedParticipant`](/documentation/GameKit/GKTurnBasedParticipant) objects in the [`participants`](/documentation/GameKit/GKTurnBasedMatch/participants) property.

You don’t create turn-based match objects directly. When a match event occurs, GameKit passes the match object to listeners that conform to the [`GKTurnBasedEventListener`](/documentation/GameKit/GKTurnBasedEventListener) protocol. Retain the match object or its match ID in the protocol methods, so you can get the latest match data later during gameplay.

Using the match object passed to `GKTurnBasedEventListener` protocol methods, you can perform these actions on behalf of the local player:

- Save game data
- End a turn
- Forfeit a match
- End a match
- Send a reminder to the participant whose turn it is
- Exchange data between participants
- Remove a completed match from Game Center

When you end a turn, forfeit a match, or end a match, you update the match data and if gameplay can continue, choose the next participant. If you end a match, you set the individual participant outcomes as well.

If you present a [`GKTurnBasedMatchmakerViewController`](/documentation/GameKit/GKTurnBasedMatchmakerViewController) object for players to manage their turn-based matches, the player can start a match, accept an invitation, open an existing match, and forfeit a match.

### Subclassing Notes

Don’t subclass the [`GKTurnBasedMatch`](/documentation/GameKit/GKTurnBasedMatch) class.

## Topics

### Creating a Match

[`+  findMatchForRequest:withCompletionHandler:`](/documentation/GameKit/GKTurnBasedMatch/find(for:withCompletionHandler:))

Creates a new match or finds an existing match that needs a player.

[`-  acceptInviteWithCompletionHandler:`](/documentation/GameKit/GKTurnBasedMatch/acceptInvite(completionHandler:))

Accepts an invitation for the local player to join a turn-based match.

[`-  declineInviteWithCompletionHandler:`](/documentation/GameKit/GKTurnBasedMatch/declineInvite(completionHandler:))

Declines an invitation for the local player to join a turn-based match.

[`-  rematchWithCompletionHandler:`](/documentation/GameKit/GKTurnBasedMatch/rematch(completionHandler:))

Creates a new turn-based match with the same participants from an existing match.

### Retrieving Match Details

[`matchID`](/documentation/GameKit/GKTurnBasedMatch/matchID)

A unique identifier for the turn-based match.

[`creationDate`](/documentation/GameKit/GKTurnBasedMatch/creationDate)

The date that Game Center created the match.

[`participants`](/documentation/GameKit/GKTurnBasedMatch/participants)

The players that participate in a turn-based match.

[`currentParticipant`](/documentation/GameKit/GKTurnBasedMatch/currentParticipant)

The participant whose turn it is.

[`status`](/documentation/GameKit/GKTurnBasedMatch/status-swift.property)

The state of the match, such as whether the match is open or has ended.

[`Status`](/documentation/GameKit/GKTurnBasedMatch/Status-swift.enum)

The states of a match from when it’s created to when it ends.

[`matchData`](/documentation/GameKit/GKTurnBasedMatch/matchData)

The game-specific data that you store in Game Center and pass between participants through a match object.

[`matchDataMaximumSize`](/documentation/GameKit/GKTurnBasedMatch/matchDataMaximumSize)

The maximum size of the match data.

[`-  loadMatchDataWithCompletionHandler:`](/documentation/GameKit/GKTurnBasedMatch/loadMatchData(completionHandler:))

Fetches your game-specific data that you store in Game Center when ending a turn, saving a turn, or leaving a match.

### Ending Turns and Saving Data

[`-  endTurnWithNextParticipants:turnTimeout:matchData:completionHandler:`](/documentation/GameKit/GKTurnBasedMatch/endTurn(withNextParticipants:turnTimeout:match:completionHandler:))

Passes the turn from the current participant to the next participant.

[`-  saveCurrentTurnWithMatchData:completionHandler:`](/documentation/GameKit/GKTurnBasedMatch/saveCurrentTurn(withMatch:completionHandler:))

Saves your match data in Game Center without ending the turn.

[Turn Timeouts](/documentation/GameKit/turn-timeouts)

A timeout for a player to take their turn.

### Forfeiting a Match

[`-  participantQuitInTurnWithOutcome:nextParticipants:turnTimeout:matchData:completionHandler:`](/documentation/GameKit/GKTurnBasedMatch/participantQuitInTurn(with:nextParticipants:turnTimeout:match:completionHandler:))

Forfeits the match on behalf of the local player when it’s their turn.

[`-  participantQuitOutOfTurnWithOutcome:withCompletionHandler:`](/documentation/GameKit/GKTurnBasedMatch/participantQuitOutOfTurn(with:withCompletionHandler:))

Forfeits the match on behalf of the local player when it’s not their turn.

[`Outcome`](/documentation/GameKit/GKTurnBasedMatch/Outcome)

The state of a participant when they forfeit a match or when a match ends.

### Ending a Match

[`-  endMatchInTurnWithMatchData:completionHandler:`](/documentation/GameKit/GKTurnBasedMatch/endMatchInTurn(withMatch:completionHandler:))

Ends the match.

[`-  endMatchInTurnWithMatchData:leaderboardScores:achievements:completionHandler:`](/documentation/GameKit/GKTurnBasedMatch/endMatchInTurn(withMatch:leaderboardScores:achievements:completionHandler:))

Ends the match while submitting scores and achievements for all of the participants.

### Sending Messages Between Participants

[`message`](/documentation/GameKit/GKTurnBasedMatch/message)

A message from the current participant to all other participants when you end a turn, forfeit a match, or end a match.

[`-  setLocalizableMessageWithKey:arguments:`](/documentation/GameKit/GKTurnBasedMatch/setLocalizableMessageWithKey(_:arguments:))

Sends a localized message from the current participant to all other participants when you end a turn, forfeit a match, or end a match.

[`-  sendReminderToParticipants:localizableMessageKey:arguments:completionHandler:`](/documentation/GameKit/GKTurnBasedMatch/sendReminder(to:localizableMessageKey:arguments:completionHandler:))

Sends a reminder from one participant to a specific set of other participants.

### Exchanging Data Between Participants

[`-  sendExchangeToParticipants:data:localizableMessageKey:arguments:timeout:completionHandler:`](/documentation/GameKit/GKTurnBasedMatch/sendExchange(to:data:localizableMessageKey:arguments:timeout:completionHandler:))

Sends an exchange request that contains your game data to one or more participants.

[Exchange Timeouts](/documentation/GameKit/exchange-timeouts)

The amount of time that passes before an exchange times out.

[`exchangeDataMaximumSize`](/documentation/GameKit/GKTurnBasedMatch/exchangeDataMaximumSize)

The maximum size of the exchange data.

[`exchangeMaxInitiatedExchangesPerPlayer`](/documentation/GameKit/GKTurnBasedMatch/exchangeMaxInitiatedExchangesPerPlayer)

The maximum number of exchanges the local player can initiate.

[`activeExchanges`](/documentation/GameKit/GKTurnBasedMatch/activeExchanges)

The exchanges that the local player needs to accept or reject.

[`completedExchanges`](/documentation/GameKit/GKTurnBasedMatch/completedExchanges)

The exchange requests that all recipients replied to and the current participant needs to save.

[`exchanges`](/documentation/GameKit/GKTurnBasedMatch/exchanges)

The exchange requests that are active or complete.

[`-  saveMergedMatchData:withResolvedExchanges:completionHandler:`](/documentation/GameKit/GKTurnBasedMatch/saveMergedMatch(_:withResolvedExchanges:completionHandler:))

Saves match data for completed exchanges without ending the turn.

### Loading Existing Matches

[`+  loadMatchWithID:withCompletionHandler:`](/documentation/GameKit/GKTurnBasedMatch/load(withID:withCompletionHandler:))

Loads a specific match with the specified identifier.

[`+  loadMatchesWithCompletionHandler:`](/documentation/GameKit/GKTurnBasedMatch/loadMatches(completionHandler:))

Fetches the turn-based matches from Game Center that the local player participates in.

### Deleting a Match from Game Center

[`-  removeWithCompletionHandler:`](/documentation/GameKit/GKTurnBasedMatch/remove(completionHandler:))

Removes a match from Game Center that the local player participants in.

### Deprecated Methods

[`-  participantQuitInTurnWithOutcome:nextParticipant:matchData:completionHandler:`](/documentation/GameKit/GKTurnBasedMatch/participantQuitInTurn(with:nextParticipant:match:completionHandler:))

Resigns the current player from the match without ending the match.

[`-  endMatchInTurnWithMatchData:scores:achievements:completionHandler:`](/documentation/GameKit/GKTurnBasedMatch/endMatchInTurn(withMatch:scores:achievements:completionHandler:))

Ends the match while submitting all of the scores and achievements.

[`-  endTurnWithNextParticipant:matchData:completionHandler:`](/documentation/GameKit/GKTurnBasedMatch/endTurn(withNextParticipant:match:completionHandler:))

Updates the data stored on Game Center for the current match.

## Relationships

### Conforms To

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

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

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

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

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

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

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