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

When creating a new match request, you are required to set the minimum and maximum players allowed for the match. Do this my setting the minPlayers and maxPlayers properties after creating the match. Game Center enforces these boundaries and always ensures that the final match has the correct number of players.

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 6-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 changes:

• 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 attempts to add only 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 sent an invitation to join the match only 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 also means that players can be added to matches that they are not interested in playing. In that case, you can allow the players to define the kind of matches they want to play, and then match them only with like-minded players. This is accomplished with a player group.

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. When you set the playerGroup property to a nonzero number, then the player is matched only 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.

Here are some examples of how you can partition a list of players:

• Separate players by 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.

Although it is up to you to determine exactly how many player groups you want to create, don’t create groups just to create them. Creating many smaller player groups can result in every player waiting for a long time to play a match. Instead, create large groups that players can identify with.

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 can use player attributes in your game:

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

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

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

• A turn-based match can assign different locations 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. Because this calls for 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 property’s 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. 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 6-1. Then, perform the standard or custom matchmaking as you normally would.

Listing 6-1  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 nonzero player attribute in the match request, it adds players to the match intelligently so that all of the players, when combined using a bitwise 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 a player is added to the match, the value of the new player’s player attributes value is bitwise ORed into the match’s mask.

4. If the match’s mask does not equal FFFFFFFFh, Game Center searches for other players to join the match. If the match is complete, but the game still requires more players to reach the minimum, Game Center 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, and 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 6-2 provides an example set of masks.

Listing 6-2  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 bitwise 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 they want to play the black pieces, the white pieces, or they don’t care what color they start with. Listing 6-3 provides an example set of masks for this design.

Listing 6-3  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 white player and one player that doesn’t care

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

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