Game Center's Auto-match and endTurnWithNextParticipants

Question

I am developing a turn-based game with two Game Center players, and I want to allow auto-matching.

I've read that, for an invitation to be actually sent out to a player, the inviting player must end his/her turn. This means calling this method:

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

Now, what I don't understand is the meaning of the "nextParticipants" array in case the match is started in auto-match mode, which, as I read, is done by setting the participants to nil, e.g.:

 GKMatchRequest *request = [[GKMatchRequest alloc] init];
 request.minPlayers = 2;
 request.maxPlayers = 2;
 request.playersToInvite = nil;
 request.inviteMessage = @"Let’s play";
 [GKTurnBasedMatch findMatchForRequest: request
                 withCompletionHandler: ^(GKTurnBasedMatch *match,
                                          NSError *error) {
                     NSLog(@"%@", match);
                 }];

If the array is nil, and I don't know who's going to join the match, how can I possibly pass the turn to the next player? If I use nil in the nextParticipants argument, of course I get an 'invalid list of nextParticipants' error.

Apple's doc seems to be silent about this.

So, what I also don't understand is how auto-matching actually works. Is it going to match any two players who have started a new match with auto-match, unconditionally? Can't I somehow select what kind of matches I want to be auto-matched with? (suppose, e.g., the game allows several difficulty levels, and I don't want to be auto-matched with someone playing at a lower level).

EDIT (as per xcodegirl's comment):

To address this last point, it suffices to extend the above code by adding something that encodes the desired kind of match in the playerGroup property of the request:

request.playerGroup = [Utils myEncodingAsNSUIntegerOfGameTypeGivenSomeParameters:...];

The bad thing, though, is that the playerGroup does not seem to be an available property of GKTurnBasedMatch. So, if you are listing your matches, including the pending auto-matches, and want to display information regarding the kind of game you want to play, you should store this info in some other way.

Answer 1

After some attempts, it seems that the answer to the first part of this question is as follows. As soon as the match is started, even if no one has matched the automatch invitation, the array of participants is populated with as many players as requested (one of which is the inviting player), and every missing player is a GKTurnBasedParticipant whose status is GKTurnBasedParticipantStatusMatching. So, the inviting player could play the first turn even without waiting for the invited (auto-match) players to accept, by simply creating an array of next participants where the inviting player is placed at the end of the array.

NSMutableArray *nextParticipants = [NSMutableArray new];
for (GKTurnBasedParticipant *participant in match.participants) {
    if ([participant.playerID isEqualToString:[GKLocalPlayer localPlayer].playerID]) {
        [nextParticipants addObject:participant];
    } else {
        [nextParticipants insertObject:participant atIndex:0];
    }
}

NSData *matchData = [@"some data" dataUsingEncoding:NSUTF8StringEncoding];

// Send new game state to Game Center & pass turn to next participant
[self.invitation.match endTurnWithNextParticipants: nextParticipants
                                       turnTimeout: GKTurnTimeoutDefault
                                         matchData: matchData
                                 completionHandler: ^(NSError *error) {
                                       // do something like refreshing UI
                                 } ];

Yet, the second part of my question still stands. It's unclear to me how to make auto-matching work conditionally (like: I'm willing to auto-match with someone who wants to race with Formula 1 cars, but not with Rally cars).

Answer 2

Regarding the second (unanswered) part, I think the purpose of the GKMatchRequest.playerAttributes is to achieve what you want. You set some value identifying the properties of the selected match and game centre ensures that matched participants are interested in the same game options. SO if you had a racing game where you can race cars, bikes and boats in different weather conditions, you might have this:

typedef enum GameType {
    GameTypeRaceCars = 0;
    GameTypeMotorbikes = 1;
    GameTypeBoats = 2;
};
typedef enum GameOptionWeather {
    GameOptionWeatherSunny = 0;
    GameOptionWeatherRainy = 1;
};
GKMatchRequest *request = /* boilerplate */
// bit 0-1 = GameType.
// bit 3   = Weather option.
request.playerAttributes = (uint32_t)GameTypeBoats;
request.playerAttributes |= (uint32_t)(GameOptionWeatherRainy) << 2;

/* boilerplate to create the match with the request */

That would ensure that any matched player also wants to race boats in the rain (who doesn't?).

At least, I think that's how you're supposed to do it. Though to be honest i have failed so far to get Game Center turn based matchmaking working in the sandbox myself.