Matchmaking Overview

A Match Request Must Specify the Number of Players In the Match

Listing 7-1 shows a simple match request. All match requests are required to set the minimum and maximum players for a match; Game Center respects these boundaries and always ensures that the final match has the correct number of players for the match.

Listing 7-1  A simple match request

GKMatchRequest *request = [[GKMatchRequest alloc] init];

request.minPlayers = 2;

request.maxPlayers = 2;

request.defaultNumberOfPlayers = 2;

The minimum number of players must be at least 2. The maximum number of players allowed varies depending on the kind of match being created. Table 7-2 lists the current maximum; this maximum is subject to change.

At runtime, your game calls the maxPlayersAllowedForMatchOfType: method to determine the exact number of players allowed for each kind of match.

Inviting a List of Players

By default, Game Center uses a match request to find other waiting players to fill a match. For example, if a match requires four people to be present before it can start, then Game Center finds four waiting participants, forms them into a match, and then returns that match. This scenario is useful because it allows waiting players to be quickly matched together. However, not everyone wants to play with a randomized set of players each time a match is played. Often, players want to play specifically against friends. For this reason, the standard user interface allows a player to invite specific friends to the game. However, your game can also choose to provide this support programmatically by assigning an array of player identifier strings to the match request.

Providing a list of players alters Game Center’s matching behavior. Here are a few examples of how the behavior might change:

• The standard user interface allows a player to pick a specific slot in the match and invite a specific person to fill it. Game Kit reserves places for invited players until they respond or the process times out.

• If you are using the programmatic interface for creating a real-time match and you provide a list of players to invite, Game Center only attempts to match those players into the match. It does not perform the normal matchmaking process. However, if the match needs more players, your game can create another match request that performs normal matchmaking. This separation of behaviors allows you to precisely control when randomized matchmaking occurs.

• In a turn-based match, the players are added to the match immediately, but a player is only sent an invitation to join the match when it becomes that player’s turn.

Player Groups

Game Center’s default behavior is to automatically match any player waiting to play your game into any match that needs more players. This has the advantage of matching players quickly into matches, but it may mean that a player gets into a kind of match that he or she is not interested in playing. In that case, you may want to allow the players to define the kind of matches they want to play, and then only match with like-minded players. You do that with a player group.

Here are some examples of how you might partition the list of players:

• Separate players by player skill level.

• Separate players by the set of rules used to adjudicate the match.

• Separate players based on the map the match is played on.

A player group is defined by an unsigned 32-bit integer. When you set the playerGroup property on a match request to 0, then the player can be matched into any waiting match. If you set it to a non-zero number, then the player is only matched with players whose match requests share the same player group number. Typically, if your game uses player groups, it provides a custom interface that allows the player to pick the precise options he or she is interested in. It takes the choices of the player and combines them to form a player group number.

Although it is up to you exactly how many player groups you want to create, you should not go overboard. Creating many smaller player groups may result in every player waiting for a long time to play a match. Instead, create large groups that players can identify with.

Listing 7-2 shows how you might configure a match request that uses a player group. In this example, the player group value is calculated by choosing both the map the player wants to play on and the rules set under which the player wants to play. A constant for each is chosen and the two are logically ORed together to create a unique number for the player group. Only players looking for that same map and group combination will be searched for.

Listing 7-2  Creating a player group based on the map and rule set

GKMatchRequest *request = [[GKMatchRequest alloc] init];

request.minPlayers = 2;

request.maxPlayers = 4;

request.playerGroup = MyMap_Forest | MyRulesCaptureTheFlag;

Player Attributes

A player attribute allows a player to pick the role he or she wants to play within a match. With player attributes, each player can choose a specific role and Game Center finds a proper mix of players to ensure that all of the roles are filled.

Here are some ways you might use player attributes in your game:

• A game like chess might use player attributes to determine whether a player wants to be the black or white pieces.

• A role-playing game might offer different character roles with distinct strengths, weaknesses, and abilities that player brings to the match.

• A sports game might use player attributes to allow players to specify specific positions, such as pitcher or quarterback, on the team.

• A turn-base match might assign different location on the map to distinct factions and use attributes to ensure that each location is filled.

Player attributes have a few limitations:

• Roles are checked only for auto-matched players. If the player invites friends to join the match, friends do not pick a role and do not have an attribute set.

• Roles are not displayed in the standard user interface for matchmaking provided by Game Kit. Your game must provide its own custom user interface to allow players to choose a role.

• The match object returned to your game does not tell you which roles the players selected. Your game must send the role-selection information separately after the match is created.

• Your game defines a complete set of roles; all roles defined by your game must be filled by the time the match is created. This means there is a careful coordination between the roles that you define and the number of players allowed in the match. Thus, player attributes require additional design and testing effort.

Implementing Player Attributes

Player attributes are implemented using the playerAttributes property on the match request. By default, the value of this property is 0, which means that the attributes property is ignored. If the value is non-zero, Game Center uses it to match a specific role.

To create the roles a player can play in your game, you create a 32-bit mask for each role a player can fill in your game. It is up to you to add a custom user interface in your game that allows the player to select a role. You set the playerAttributes property on the match request to the mask for the player’s selection, as shown in Listing 7-3. Then, perform the standard or custom matchmaking as you normally would.

Listing 7-3  Setting the player attributes on the match request

GKMatchRequest *request = [[GKMatchRequest alloc] init];

request.minPlayers = 4;

request.maxPlayers = 4;

request.playerAttributes = MyRole_Wizard;

If Game Center sees a non-zero player attribute in the match request, it adds players to the match intelligently so that all of the players, when combined using a logical OR operation, have a complete mask of FFFFFFFFh.

The algorithm looks roughly like this:

1. A match’s mask starts with the mask of the inviting player.

2. Game Center looks for players with match requests that have a non-zero player attributes value. Game Center searches for players whose masks include set bits that are not currently in the match’s mask.

3. After adding a player to the match, the value of the new player’s player attributes value is logically ORed into the match’s mask.

4. If the match’s mask does not equal FFFFFFFFh, then it searches for other players to join the match. If the match is complete, but the game still requires more players to reach the minimum, it continues to search for more players to add.

Player Attributes Example: A Role-playing Game

Assume that you are creating a role-playing game with four roles: Fighter, Wizard, Thief, and Cleric. Every match consists of four players, the match must have one and only one player for each role. To implement this requirement, your game creates masks for each role that matches the four-step algorithm described earlier. Listing 7-4 provides an example set of masks.

Listing 7-4  Creating the masks for the character classes

#define MyRole_Fighter 0xFF000000

#define MyRole_Cleric 0x00FF0000

#define MyRole_Wizard 0x0000FF00

#define MyRole_Thief 0x000000FF

None of the role masks overlap; if any two masks are joined by AND, the resulting value is always 00000000h. When all four role masks are logically ORed together, the entire match mask is filled (FFFFFFFFh). This ensures, in a match with four players, that each role is filled exactly once.

Player Attributes Example: Chess

For chess, you might want to allow players to choose whether he or she plays the black or white pieces. Or a player might not care at all. Listing 7-5 provides an example set of masks for this design.

Listing 7-5  Creating the masks for chess

#define MyRole_Black 0xFFFF0000

#define MyRole_White 0x0000FFFF

#define MyRole_Either 0xFFFFFFFF

A chess match always requires two players, so with these masks there are four possible combinations of players that can satisfy the condition for a completed mask:

• One black player and one white player.

• One black player and one player that doesn’t care.

• One white player and one player that doesn’t care.

• Two players that do not care which color their pieces are.