Sending messages to players in turn-based games

Notify players of match events by sending messages and game data.

Overview

GameKit provides several APIs for you to communicate events and send messages in your turn-based games. You can include a message and custom game data in the GKTurnBasedMatch object passed between active participants. You can also send a notification to other participants when they’re not running your game.

To send other types of data between players when they’re not taking their turn, see the GKTurnBasedExchange class.

Pass messages from the current participant

You can send localized or non-localized messages from the current participant to others in a turn-based match using the GKTurnBasedMatch object. If the game isn’t running or is in the background, the message you provide appears immediately at the top of the screen as a notification. If the game is in the foreground, get the message from the match object GameKit passes to participants and display it in your own interface.

Before you perform an action such as ending a turn, set the message property of the match object. Alternatively, set a message that GameKit localizes using the receiving participant’s language and region settings using the setLocalizableMessageWithKey(_:arguments:) method.

match.message = "We're all counting on you!"
try await match.endTurn(withNextParticipants: nextParticipants, turnTimeout: GKTurnTimeoutDefault, match: gameData)

If a participant taps the notification when it appears, GameKit launches the game or brings it to the foreground. GameKit invokes the GKTurnBasedEventListener player(_:receivedTurnEventFor:didBecomeActive:) protocol method passing true as the active parameter. Implement this method to join the match. For more information on handling turn-based events, see Starting turn-based matches and passing turns between players.

If the game is in the foreground, GameKit invokes this method but passes false as the active parameter. You can then present the message in your own interface by getting the message from the match object using the message property.

To localize a message, add the key you pass to the setLocalizableMessageWithKey(_:arguments:) method and a placeholder translation to a .strings file in your project (for example, the default Localizable.strings file). For more information on adapting your game for different languages and regions, see Localization.

Send messages from any participant

Send a localized message from any participant to others using a Game Center notification. For example, send a reminder to the current participant from another participant who is waiting for them to take their turn. GameKit sends the reminder to the participants as a push notification that doesn’t interrupt their gameplay. The notification only appears when the game isn’t running — it doesn’t appear if the participant runs the game in either the foreground or background.

[Image]

To display the GameKit notification:

Invoke the GKTurnBasedMatch sendReminder(to:localizableMessageKey:arguments:completionHandler:) method passing the participants and a localized message key:

// Create an array that contains the current participant.
let participants = match.participants.filter {
    $0 == match.currentParticipant
}

// Send a reminder to the current participant.
try await match.sendReminder(to: participants, localizableMessageKey: "It's your turn to play.", arguments: [])

Add the localized message key and placeholder translation to a .strings file in your project. If necessary, add a .strings file (for example, the default Localizable.strings file) to your project and make it localizable. For the Xcode steps, see Adding resources to localizations and Editing XLIFF and strings files.

"It's your turn to play." = "It's your turn to play.";

When the player taps the notification, GameKit invokes the GKTurnBasedEventListener player(_:receivedTurnEventFor:didBecomeActive:) protocol method passing true as the active parameter. Implement this method to join the existing match. For more information on handling turn-based events, see Starting turn-based matches and passing turns between players.