GKTurnBasedEventListener Protocol Reference

Framework
/System/Library/Frameworks/GameKit.framework
Availability
Available in iOS 7.0 and later.
Companion guide
Declared in
GKTurnBasedMatch.h

Overview

Handles events for turn-based games. Provides methods for responding to exchanges and match events.

Do not implement GKTurnBasedEventListener directly, instead use GKLocalPlayerListener. The GKLocalPlayerListener protocol inherits methods from GKTurnBasedEventListener, GKInviteEventListener, and GKChallengeListener in order to handle multiple events.

Tasks

Handling Exchanges

Handling Match Related Events

Instance Methods

player:didRequestMatchWithPlayers:

Initiates a match from Game Center with the requested players. (required)

- (void)player:(GKPlayer *)player didRequestMatchWithPlayers:(NSArray *)playerIDsToInvite
Parameters
player

The GKPlayer object containing the current player’s information.

playerIDsToInvite

An array of NSString objects containing the player identifiers to invite to the match.

Discussion

When this method is called, you should create a new match using the player identifiers provided and present a GKTurnBasedMatchmakerViewController.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKTurnBasedMatch.h

player:matchEnded:

Called when the match has ended. (required)

- (void)player:(GKPlayer *)player matchEnded:(GKTurnBasedMatch *)match
Parameters
player

The GKPlayer object containing the current player’s information.

match

The GKTurnBasedMatch object containing the current game data.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKTurnBasedMatch.h

player:receivedExchangeCancellation:forMatch:

Called when the exchange is cancelled by the sender. (required)

- (void)player:(GKPlayer *)player receivedExchangeCancellation:(GKTurnBasedExchange *)exchange forMatch:(GKTurnBasedMatch *)match
Parameters
player

The GKPlayer object containing the current player’s information.

exchange

A GKTurnBasedExchange object containing the exchange that is cancelled.

match

The GKTurnBasedMatch object containing the current match information.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKTurnBasedMatch.h

player:receivedExchangeReplies:forCompletedExchange:forMatch:

Called when the exchange is completed. (required)

- (void)player:(GKPlayer *)player receivedExchangeReplies:(NSArray *)replies forCompletedExchange:(GKTurnBasedExchange *)exchange forMatch:(GKTurnBasedMatch *)match
Parameters
player

The GKPlayer object containing the current player’s information.

replies

An array of GKTurnBasedExchange objects containing the replies from other players.

exchange

A GKTurnBasedExchange object containing the exchange that is completed.

match

The GKTurnBasedMatch object containing the current game data.

Discussion

This method is called when all of the players have either responded to the exchange or timed-out. The result is then sent to the current player and the initiator of the exchange.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKTurnBasedMatch.h

player:receivedExchangeRequest:forMatch:

Called when a player receives an exchange request from another player. (required)

- (void)player:(GKPlayer *)player receivedExchangeRequest:(GKTurnBasedExchange *)exchange forMatch:(GKTurnBasedMatch *)match
Parameters
player

The GKPlayer object containing the current player’s information.

exchange

A GKTurnBasedExchange object containing the requested exchange.

match

The GKTurnBasedMatch object containing the current game data.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKTurnBasedMatch.h

player:receivedTurnEventForMatch:didBecomeActive:

Activates the player’s turn. (required)

- (void)player:(GKPlayer *)player receivedTurnEventForMatch:(GKTurnBasedMatch *)match didBecomeActive:(BOOL)didBecomeActive
Parameters
player

The GKPlayer object containing the current player’s information.

match

The GKTurnBasedMatch object containing the current game data.

didBecomeActive

Denotes whether the app should be launched or brought to the foreground.

Discussion

This method is called when the it becomes the player’s turn. It is also called when any of the following events happen:

  • The current turn has a time-out associated with it and the turn is about to expire.

  • Player accepts an invite from another player.

  • Turn was passed to another player. In this case, didBecomeActive is false.

  • Match data is saved by another player.

  • Player receives a reminder.

Availability
  • Available in iOS 7.0 and later.
Declared In
GKTurnBasedMatch.h