Instance Method

endTurnWithNextParticipants:turnTimeout:matchData:completionHandler:

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

Declaration

- (void)endTurnWithNextParticipants:(NSArray<GKTurnBasedParticipant *> *)nextParticipants turnTimeout:(NSTimeInterval)timeout matchData:(NSData *)matchData completionHandler:(void (^)(NSError *error))completionHandler;

Parameters

nextParticipants

An array of GKTurnBasedParticipant objects reflecting the order in which the players should act next. Each object in the array must be one of the objects stored in the match’s participants property.

timeout

The length of time the next player has to complete their turn.

matchData

A serialized blob of data reflecting the game-specific state for the match. Do not pass nil as an argument.

completionHandler

A block to be called after the data is uploaded to Game Center.

The block receives the following parameters:

error

If an error occurred, this error object describes the error. If the operation was completed successfully, the value is nil.

Discussion

If the next player to act does not take their turn in the specified interval, the next player in the array receives a notification to act. This process continues until a player takes a turn or the last player in the list is notified.

Listing 1 shows a typical structure for this code, deferring some of the specific steps to app-specific routines that are based on your game’s actual structure. Those methods represent the places where you need to provide specific implementations in your game. The advanceTurn method first sets a new message, then encodes the current match data as before. Finally, it calculates the order in which participants should act and calls this method to actually pass control to that list of players.

Listing 1

Advancing to the next participant in a match

- (void) advanceTurn
{
    NSData *updatedMatchData = [this.gameData encodeMatchData];
    NSArray *sortedPlayerOrder = [this.gameData encodePlayerOrder];
    this.MyMatch.message = [this.gameData matchAppropriateMessage];
    [this.myMatch endTurnWithNextParticipants: sortedPlayerOrder turnTimeOut: GKTurnTimeoutDefault
                  matchData: updatedMatchData completionHandler ^(NSError *error) {
        if (error)
        {
            // Handle the error.
        }
      }];
}

When this method is called, it creates a new background task to handle the request. The method then returns control to your game. Later, when the task is complete, Game Kit calls your completion handler. The completion handler is always called on the main thread.

See Also

Handling the Current Player’s Turn

- saveCurrentTurnWithMatchData:completionHandler:

Update the match data without advancing the game to another player.