Game Center Programming Guide

Transcription

1 Game Center Programming Guide

2 Contents About Game Center 8 At a Glance 9 Some Game Resources Are Provided at Runtime by the Game Center Service 9 Your Game Displays Game Center s User Interface Elements 10 Game Center Features Require an Authenticated Player 10 Leaderboards Require Your Game to Have a Scoring Mechanism 10 Leaderboard Sets Allow You to Manage Your Leaderboards 11 Achievements Require Your Game to Measure Player s Progress 11 Challenges Allow Players to Challenge Each Other 11 Matchmaking Requires Your Game Design to Incorporate Multiplayer Gaming 11 How to Use This Document 12 Prerequisites 13 See Also 13 Developing a Game Center-Aware Game 14 Supporting Game Center in Your User Interface 14 Adapting Your Game Design 18 Customizing the Game Center Sounds 19 Creating and Managing Game Center Resources 20 Game Groups 22 Incorporating Game Center into Your Game 23 Requiring Game Center in Your Game (ios only) 24 Optionally Supporting Game Center in Your Game 24 Displaying Game Center User Interface Elements 25 Game Center UI Is Displayed by Your View Controller (ios) 25 Game Center UI Is Displayed by Your Window (OS X) 26 Displaying Notification Banners 26 Working with Players in Game Center 27 Game Center Manages Player Accounts 27 Player Identifier Strings Uniquely Identify Players 28 The Local Player Is the Player Signed in to the Device 28 Player Objects Provide Details About Players 29 2

3 Contents Common Tasks When Working with Players 30 Authenticating a Local Player on the Device 30 Retrieving the Local Player s Friends 33 Allowing the Local Player to Invite Other Players to Be Friends 34 Leaderboards, Achievements, and Challenges 35 Achievements 35 Checklist for Supporting Achievements 36 Designing an Achievement 36 Configuring Achievements in itunes Connect 39 Adding Achievement Support to Your Game 40 Leaderboards 42 Checklist for Supporting Leaderboards 42 Leaderboards Require a Scoring Mechanism 42 A Game Can Have Multiple Leaderboards 43 One Leaderboard Is the Default Leaderboard 44 Combined Leaderboards Gather Scores from Multiple Single Leaderboards 44 Working with Leaderboards in itunes Connect 45 Reporting Scores to Game Center 46 Working with the Default Leaderboard 47 Displaying the Standard Leaderboard 47 Retrieving Score Data 48 Extending Leaderboards Using Score Contexts 49 Leaderboard Sets 50 Checklist for Supporting Leaderboard Sets 51 A Game Can Have Multiple Leaderboard Sets 52 Game Group Leaderboard and Leaderboard Set Limits 52 Working with Leaderboard Sets in itunes Connect 52 Adding Leaderboard Set Support to Your Game 53 Challenges 54 Checklist for Supporting Challenges 54 Issuing Challenges from Your Game 55 Saving A Game 59 General information about saved games 59 icloud Requirements 60 Saving a Game 60 Saving the game data 60 Retrieving a saved game 61 Conflicting saved games 61 3

4 Contents Matchmaking Overview 62 Game Center Supports Multiple Kinds of Matches 62 Game Center Provides Multiple Ways to Connect Players into a Match 63 Matchmaking and Gameplay Are Separate Tasks 64 You Can Match Across Different Versions of Your Game 64 Creating Any Kind of Match Starts with a Match Request 65 A Match Request Must Specify the Number of Players in the Match 66 Inviting a List of Players 66 Player Groups 67 Player Attributes 67 Real-Time Matches 72 Checklist for Adding Real-Time Matchmaking to Your Game 72 Getting Started 73 Finding Players for a Match 73 Exchanging Data Between Match Participants 73 Adding Voice Chat to a Match 74 Overview of Real-Time Matches in Game Center 75 Finding Players for a Match 75 Using the Standard Matchmaking User Interface 76 Implementing a Custom Match User Interface 77 Finding Player Activity in Your Game 80 Exchanging Data Between Match Participants 80 Designing Your Network Game 80 Starting the Match 82 Determining the Best Server 83 Sending Data to Other Players 83 Receiving Data from Other Players 83 Disconnecting from a Match 83 Adding Voice Chat to a Match 83 Creating an Audio Session (ios only) 84 Creating Voice Channels 84 Starting and Stopping Voice Chat 84 Enabling and Disabling the Microphone 85 Controlling the Volume of a Voice Chat 85 Seeing When a Player s State Changes 85 Hosted Matches 86 Matching Players for a Hosted Match 86 Hosted Matches Overview 87 4

5 Contents Creating a Hosted Match Using the Matchmaker View Controller 88 Dismissing the MatchMaking View Controller 88 Turn-Based Matches 89 Checklist for Implementing a Turn-Based Match 90 Every Match Has a List of Participants 90 The Match Data Represents the State of the Match 91 Your Game Decides the Rules of Play 93 Save the Match Data Whenever Important Events Occur 95 Implementing a Turn-Based Match Using Game Kit 95 Game Center Imposes Limits on the Match 96 Joining a New Match 96 Working with Existing Matches 98 Retrieving Information About a Match 98 Working with Match Data 100 Advancing the State of the Match 101 Setting the Match Outcome When a Participant Leaves a Match 102 Ending a Match 103 Responding to Match Notifications 103 Adding Exchanges to a Turn-Based Match 105 Anatomy of an Exchange 105 Sending an Exchange Request 106 Responding to an Exchange Request 107 Testing Your Game Center-Aware Game 108 Testing a Game Center-Aware Game 109 Testing Your Game in ios Simulator 111 Document Revision History 112 5

6 Figures, Tables, and Listings Developing a Game Center-Aware Game 14 Figure 1-1 A game user interface screen flow 15 Figure 1-2 Game Center-enabled UI 17 Figure 1-3 Publishing an app on the App Store 20 Figure 1-4 Developing and distributing Game Center assets 21 Table 1-1 Game Center feature summary 19 Working with Players in Game Center 27 Figure 3-1 Local and remote players 29 Table 3-1 Important Player Object Properties 30 Table 3-2 Local Player Object Properties 30 Leaderboards, Achievements, and Challenges 35 Figure 4-1 Leaderboard data is filtered, sorted, and returned to your game 48 Figure 4-2 Combined leaderboards include scores from the single leaderboards 49 Figure 4-3 Leaderboards combined into a leaderboard set 51 Table 4-1 Achievement properties 39 Table 4-2 Achievement language properties 39 Table 4-3 Classes in Game Kit used to implement achievement support 40 Table 4-4 Properties for a single leaderboard 45 Table 4-5 Leaderboard language properties 45 Table 4-6 Game Kit classes used to implement leaderboard set support 53 Table 4-7 Challenge subclasses 55 Listing 4-1 Displaying the challenge user interface 56 Listing 4-2 Preparing the challenge view controller 56 Listing 4-3 Dismissing the challenge view controller 57 Listing 4-4 Retrieving the list of players with lower scores than the one just earned 57 Listing 4-5 Determining the list of players who can complete an achievement challenge 58 Saving A Game 59 Table 5-1 Common saved game properties 59 Matchmaking Overview 62 Figure 6-1 Possible mask combinations 71 6

7 Figures, Tables, and Listings Table 6-1 Game Center match types 62 Table 6-2 Important match request properties 65 Table 6-3 Maximum number of players for each kind of match 66 Listing 6-1 Setting the player attributes on the match request 68 Listing 6-2 Creating the masks for the character classes 69 Listing 6-3 Creating the masks for chess 70 Real-Time Matches 72 Figure 7-1 Network topologies 82 Table 7-1 Classes used to implement real-time matches 75 Hosted Matches 86 Table 8-1 Methods to implement hosted matchmaking 86 Turn-Based Matches 89 Figure 9-1 Mary starts a new match 90 Figure 9-2 The current player wants to view the match 92 Figure 9-3 A turn flowchart for a hypothetical 4X game 94 Figure 9-4 Bob has been eliminated from the match 102 Figure 9-5 Initializing a trade through an exchange 106 Figure 9-6 Accepting a trade through an exchange 107 Table 9-1 Classes in Game Kit used to implement turn-based match support 95 Table 9-2 Important match limits 96 Table 9-3 Common actions to perform on a match 98 Table 9-4 Important properties of a match object 99 Table 9-5 Important properties of a participant object 99 Table 9-6 Turn-based event handler methods 104 Testing Your Game Center-Aware Game 108 Figure 10-1 Enabling the sandbox option 110 Table 10-1 Different kinds of app builds 111 7

8 About Game Center People love to play games. Games on the App Store are no exception games continue to be the most popular category of apps on ios. Games are inherently a social activity. Sometimes, this social interaction is part of the game itself, such as when the game provides competitive or cooperative multiplayer gameplay. But even for games intended for single-player experiences, players like to see and share their accomplishments. Because social gaming is such an important part of the game-playing experience, Apple supports it directly with the Game Center service. Game Center allows a player s devices to connect to the Game Center service and exchange information. The following figure shows several ways users can interact with Game Center. Each player performs different activities but all of them are interacting with Game Center: Bob uses the Game Center app provided by Apple to view his scores earned in a game that supports Game Center. The Game Center app shows both Bob s scores and scores earned by other players. Even though the scores are displayed by the Game Center app, the score data and formatting are provided to Game Center by the game. Joe is playing an adventure game that supports achievements. He just discovered an item for a quest he wants to complete. The game sends a message to Game Center to update the progress stored there. 8

9 About Game Center At a Glance Mary, Alice, and Charlie are playing a game that supports Game Center s matchmaking. Game Center provides a platform for the player s devices to find and connect to each other. The game exchanges data between the participants through Game Center s servers. Sara plays another multiplayer game also using Game Center s matchmaking. Sara s game supports turn-based play and Sara has received a push notification indicating that it is her turn to act. At a Glance Game Center is best viewed as a collection of interconnected components that provide features both to game developers and to end users: The Game Center service is the online portion of Game Center. The Game Center servers store player and game data and vend the data and other services to Mac and ios devices. The Game Kit framework provides classes that developers use to add support for Game Center to their games. Game Kit is available starting in ios 4.1 and OS X v10.8. The Game Center app provides a centralized app that players use to access Game Center s features. For players to take advantage of Game Center in your game and for your game to be visible in the Game Center app you must explicitly add support for Game Center to your game. You do this by implementing authentication and then at least one other Game Center feature. Some Game Resources Are Provided at Runtime by the Game Center Service All apps include images and localized text inside of its bundle that are used to display the app s user interface. The app loads these resources from the bundle as needed. When you design a Game Center-aware game, some of the resources you create are not stored in the bundle. Instead, those resources are uploaded to the Game Center service during development of your game. At runtime, your game downloads the resources from Game Center. The main reason for storing these resources on Game Center is that those resources are also used by the Game Center app. For example, when the Game Center app displays one of your game s leaderboards, it downloads the resources you provided so that it displays the score data the same way as your game. The requirement that some of your resources be provided to Game Center affects how you design, develop, and test your game. 9

10 About Game Center At a Glance Relevant Chapter: Developing a Game Center-Aware Game (page 14), Testing Your Game Center-Aware Game (page 108) Your Game Displays Game Center s User Interface Elements Game Kit provides many classes that present full-screen user interfaces to the player. Standard classes are provided to display leaderboards, achievements, and matchmaking screens. For example, the GKGameCenterViewController class provides the simplest way to display Game Center content in your game. In ios, these are provided as view controllers. A view controller in your game presents one of these view controllers when necessary. On OS X, the same classes are used, but Game Center provides the infrastructure required to display them in a window. Game Kit also provides support for banners. A banner appears for a short time to display a message to the player. Game Kit automatically presents some banner messages to the player when certain events occur, but your game can use the GKNotificationBanner class to display your own messages. Relevant Chapter: Displaying Game Center User Interface Elements (page 25) Game Center Features Require an Authenticated Player All of Game Center s features require an authenticated player on the device, known as the local player. Before your game uses any Game Center features, it must successfully authenticate the local player. Most Game Center classes function only if there is an authenticated player, and those classes implicitly reference the local player. For example, when your game reports scores to a leaderboard, it always reports scores for the local player. Your game must disable all Game Center features when there is not an authenticated player. Relevant Chapter: Working with Players in Game Center (page 27) Leaderboards Require Your Game to Have a Scoring Mechanism Leaderboards allow your game to post scores to the Game Center service. Players can view these scores by viewing a leaderboard in the Game Center app, but your game can also display the standard leaderboard interface with just a few lines of code. Or, if you'd rather customize the appearance of a leaderboard, your game can download the raw score data. You can create multiple leaderboards for your game and customize each with your game s scoring mechanisms. 10

11 About Game Center At a Glance Relevant Chapter: Leaderboards, Achievements, and Challenges (page 35) Leaderboard Sets Allow You to Manage Your Leaderboards Combine leaderboards into leaderboard sets to logically group leaderboards for your game. Implementing leaderboard sets raises the number of leaderboards that your game is allowed to contain. Combine all of the leaderboards for a single level into a set or combine the high score leaderboard from each level into a set, the decision on how to combine your leaderboards is up to you. Relevant Chapter: Leaderboards, Achievements, and Challenges (page 35) Achievements Require Your Game to Measure Player s Progress An achievement is a specific goal that the player accomplishes within your game, such as Find 10 gold coins or Capture the flag in less than 30 seconds. As with leaderboards, a player views achievements within the Game Center app or in your game. Within the Game Center app, players can compare earned achievements with those earned by friends. Within your game, you can choose to display the standard user interface or you can download the raw data to create your own custom interface. Relevant Chapter: Leaderboards, Achievements, and Challenges (page 35) Challenges Allow Players to Challenge Each Other A challenge is sent from one player to another. Each challenge is a specific goal that the challenged player must complete. When a challenge is completed, both the challenger and the challenged player are notified. Challenges are automatically provided in any game that supports either leaderboards or achievements. However, you can also take the extra step of implementing customized support for challenges directly in your game. Relevant Chapter: Leaderboards, Achievements, and Challenges (page 35) Matchmaking Requires Your Game Design to Incorporate Multiplayer Gaming Matchmaking allows players interested in playing online multiplayer games to discover each other and be connected into a match. Game Center supports three kinds of matchmaking: A real-time match requires all of the players to be connected to Game Center simultaneously. Game Kit provides classes that implement the low-level networking infrastructure to allow the devices to exchange data in real time. 11

12 About Game Center How to Use This Document A hosted match is similar to a real-time match, but involves your own server in the match. In this model, you use Game Center to perform matchmaking but design and implement your own low-level networking code. A turn-based match uses a store-and-forward model. Your game stores a snapshot of the match data on Game Center s servers where it can later be downloaded by any players in the match. At any given time, one of the players is designated as the person who can take a turn in the match. Your game downloads the match data, the player takes a turn, then your game uploads the modified match data to Game Center. When a player s turn ends, your game designates the next player to act and that player receives a push notification. Exchanges allow players who are not the current player to take actions within your game. A player initiates an exchange by sending an exchange request to one or more other players. These players are then able to respond to the exchange or let it time out. During the exchange, updates are also sent to the current player so that match data can be updated. Relevant Chapter: Matchmaking Overview (page 62), Real-Time Matches (page 72), Hosted Matches (page 86), Turn-Based Matches (page 89) How to Use This Document If you are new to developing Game Center-aware games, start by reading Developing a Game Center-Aware Game (page 14). This chapter describes the process for designing and implementing a game that supports Game Center. Then read Displaying Game Center User Interface Elements (page 25) which describes common conventions for displaying Game Center s user interface elements in your game. This topic is particularly important for OS X developers as it explains the infrastructure Game Kit provides for displaying Game Center content over your own user interface. ios developers will find that Game Center conforms to the standard programming model for view controllers. All developers must read Working with Players in Game Center (page 27) to learn how to authenticate players in their game. Then, as necessary, read the other chapters to learn how to implement specific Game Center features. Although this guide describes many aspects of communicating with Game Center and using Game Center s networking features, it is not a reference for low-level networking design patterns. Game Kit provides some networking infrastructure, but to implement a real-time network game, you need to understand and be prepared to handle common networking problems such as slow networks and disconnects. 12

13 About Game Center Prerequisites Prerequisites Before attempting to create a Game Center-aware game, you should already be familiar with developing apps on whichever platform you are targeting: Start Developing ios Apps Today Start Developing Mac Apps Today Game Kit also relies heavily on delegation and block objects. See Also See GameKit Framework Reference for details on the Game Kit framework. The GKAuthentication sample demonstrates how to implement user authentication. The GKLeaderboards sample demonstrates how to implement leaderboards. The GKAchievements sample demonstrates how to implement achievements. The following WWDC session videos also describe Game Center features: WWDC 2012: What's New in Game Center WWDC 2012: Integrating Your Games with Game Center WWDC 2012: Multiplayer Gaming with Game Center WWDC 2012: Building Game Center Games for OS X To learn how to code sign and provision your app to use Game Center, read App Distribution Quick Start. 13

14 Developing a Game Center-Aware Game Adding Game Center support requires more than simple coding changes. Game Center imposes specific requirements on the design of your game. For example, to implement leaderboards, your game must have a way to quantitatively measure a player's performance. But more than that, Game Center changes how you design and test your game. You aren't simply adding code to your app; you are also configuring assets used by Game Center. These assets are configured separately from your app bundle but are intimately tied to the code in your game. You need to test these pieces to ensure that all of the pieces work correctly together. To create a Game Center-aware game, you need to understand these basics before you begin writing code. Supporting Game Center in Your User Interface When you add Game Center support to your game, parts of your game s user interface displays Game Center content. Some of this content, such as player authentication, is required. Other user interface elements, such as leaderboards, are optional, but are often expected by players. 14

15 Developing a Game Center-Aware Game Supporting Game Center in Your User Interface Figure 1-1 shows an example model for a game s user interface, shown as a series of screens and transitions between them. Not all games use this exact organization of user interface screens, but it provides a useful starting point for a discussion of how adding Game Center might alter your game s user interface. Figure 1-1 A game user interface screen flow When this sample game is launched, the first thing the player sees is a loading screen. Games often require large, memory-intensive images, 3D models, sounds and game data. These resources must be accessed quickly while the game is running. Often, to accomplish this, a game loads critical resources when first launched and keeps them in memory until the app terminates. A typical loading screen displays information about the game or your company, along with a progress bar or an animated user interface while the content loads. After the game has loaded enough resources, it transitions to a menu screen. Typically, this is the first interactive screen the player sees. The menu screen has a series of buttons that players use to launch the gameplay or other features of the game. For example, any or all of the following functions are commonly accessed from the menu screen: Single player play mode Multiplayer play mode Game configuration options Social networking services 15

16 Developing a Game Center-Aware Game Supporting Game Center in Your User Interface Using the the screen flow shown in Figure 1-1, tapping the single-player Play button allows the user to choose the difficulty of the game. The purpose of this screen is to provide the player with options on how they want to play the game. Depending on the design of your game, this configuration process could be a simple interface on a single screen or a complex series of user interface screens. For example: A chess game that allows the player the choice of color. A puzzle game that allows the player to select a particular puzzle to play. A role-playing game that has a series of screens that allow the player to configure a character. The gameplay screen is where the bulk of your game logic executes. This part of your project includes rendering code, user interface interactions, and game logic that executes your game s concept. Depending on the type of game you are implementing, your app s gameplay can be a single screen or a series of multiple screens with transitions between them. After the player completes a game, an epilogue screen appears to tell the player how they did. For example, a game that includes a scoring mechanism can show the player how their score was calculated. Once the player dismisses this screen, the game transitions back to the main menu. 16

17 Developing a Game Center-Aware Game Supporting Game Center in Your User Interface Figure 1-2 shows the example game modified to incorporate Game Center. Figure 1-2 Game Center-enabled UI All Game Center apps must authenticate the player. The authentication typically begins as soon as the user starts your game. In the sample game, the authentication process begins while the title screen is displayed. If a player is not currently signed in to Game Center, the title screen is temporarily replaced with Game Center s authentication screen. This screen stays up until the player completes the authentication process or cancels. Either returns the player to the title screen. If a player is already signed in to a Game Center account, then the authentication screen is never displayed. Instead, a banner is briefly displayed to welcome the player back without leaving the main menu. The menu screen now includes buttons to display Game Center content. When the player presses one of these buttons, the game allocates, initializes and presents one of Game Kit s user interface classes. When dismissed, control returns back to the title screen. The game shown in Figure 1-2 has also been modified to provide a multiplayer game mode. As with single-player mode, the game presents a series of screens to configure the desired match. Some of these screens are specific to the game and are used to configure the game s options. Other screens display the built-in matchmaking 17

18 Developing a Game Center-Aware Game Adapting Your Game Design user interface. Note that your own game s configuration screens can appear both before and after the matchmaking screen. The choices made before a matchmaking screen appears are usually choices that affect the matchmaking experience. For example, the player can choose a specific map to play on, so that they can be matched with players interested in the same map. The configuration screens that appear after matchmaking is complete are used to allow the players, now connected into a match, to make other decisions about how the match is played. Both sets of screens include match configuration data that must be synchronized to all players in the match. Finally, a Game Center-aware game can be launched because the player received a push notification related to Game Center for example, when the player has been invited to join a match. If your game was launched as a result of a push notification, it can transition directly into a matchmaking screens immediately after the authentication process completes. In this case the title screen appears only for a brief period of time. While Figure 1-2 focuses on new screens of content to display, the content on existing screens can change too, or the tasks you perform on those screens can change. For example, at the end of the match, you can have your game report the score it displays to a Game Center leaderboard. Similarly, during gameplay, as a player makes progress towards an achievement, your game sends the updated progress to Game Center. It is important that you remember that this is only one possible way to design your game s user interface. You should consider other alternatives when building your user interface, and choose one that makes the most sense for your game. For example, many games use a customized graphics design with a consistent artistic theme. In this case, Game Center s standard user interface classes won t match your game s theme. So, one question you must ask is whether you want to use the standard user interface (which takes little effort to add) or whether you want to incorporate your own custom user interface. If you decide to create a custom user interface, you should further decide whether to create that user interface as distinct screens of content or incorporate the content into existing interfaces, such as your game s menu screen. Adapting Your Game Design Each feature in Game Center imposes requirements on your game design. For example, a leaderboard score is a numerical value representing how well the player did while playing your game. To implement a leaderboard in your game, the game design must include a play mechanism and calculate a score based on how well the player did. The requirements and limitations for each Game Center feature are described in the detailed chapters later in this document. Table 1-1 summarizes the relevant characteristics. 18

19 Developing a Game Center-Aware Game Customizing the Game Center Sounds Table 1-1 Game Center feature summary Feature Requirements Limitations Assets Leaderboard Scoring mechanism Maximum number of leaderboards, formatting options for leaderboard scores Strings, leaderboard sorting, artwork Leaderboard Sets A leaderboard Maximum number of leaderboards and sets allowed. All apps in a group must either have sets or not have sets. Strings, leaderboard grouping, artwork Achievements Tracking code to watch what a player does in the game Maximum number of achievements per game, maximum point allocation. Strings, artwork Challenges You must implement either leaderboards or achievements Saving Games Code to load and save game information The player must have an icloud account Matchmaking Multiplayer game design Number of players, size of data packets, networking Custom invitation sound Customizing the Game Center Sounds You can change the default Game Center sounds using GKInvite. For example, when a player receives an invitation, Game Center plays a sound to announce the invitation. Your game can instead provide a custom sound to be played when invitations for it are received. To do this, include a sound file in your app bundle. All of the default Game Center sounds can be changed using a custom sound file. The file must be in either caf, aif, or wav format and be named GKInvite plus the appropriate file extension. 19

20 Developing a Game Center-Aware Game Creating and Managing Game Center Resources Creating and Managing Game Center Resources Building a game that supports Game Center is different from building a game that does not. All games have resources, such as images, models, and sound files, used to render the game s user interface. However, you also need to create specific resources to support Game Center s user interface. The way you provide these assets is different than in a standard app. Figure 1-3 shows the process for a standard app. Figure 1-3 Publishing an app on the App Store You develop and test your app on your own development machine. App resources are embedded in the app bundle you create using Xcode. The process of building your app includes these resources in the final bundle, where they are loaded by your app s binary at runtime. When your app is complete, you submit the app bundle for review by copying it to itunes Connect. At the same time, you create a record in itunes Connect using the same bundle ID as the one in your app bundle. This record includes metadata that describes the app; most of this data is used to describe your app in the App Store. Once submitted, Apple reviews your app and it is either approved or denied. After your app is approved, you choose when it is published. Once published, the app bundle and metadata are copied from itunes Connect to the App Store. There, users discover and purchase the app. Once purchased, the app bundle is downloaded to the user s device. 20

21 Developing a Game Center-Aware Game Creating and Managing Game Center Resources Figure 1-4 shows the additional steps required and the process when creating Game Center assets. Although this step is not shown, your app bundle and metadata are submitted to itunes Connect as before. Figure 1-4 Developing and distributing Game Center assets Here are some of the changes to the development process: Originally, the itunes Connect record was created at the end of the development process, when you were ready to submit the app for review. When creating a Game Center-aware game, you create the itunes Connect record as soon as you are ready to implement and test your Game Center features. The itunes Connect record is needed to authorize your game to access the Game Center service. Assets you create in itunes Connect are automatically copied to a special test environment provided by Apple. This environment mimics the regular Game Center service but is private to developers. Development builds of your game automatically load the assets from the test environment. 21

22 Developing a Game Center-Aware Game Creating and Managing Game Center Resources When your game is published, the Game Center assets are copied to the Game Center service in the same way that your game is copied to the App Store. These builds of your game load the assets from the live Game Center servers. Once your assets are published to the live servers, some assets become more difficult to change because they are already in use by players and live versions of your game. For example, leaderboard scores are formatted using the leaderboard assets you created. If you changed your scoring mechanism and changed your leaderboard assets to match, older scores would still be posted on Game Center and would be inconsistent with newer scores. For this reason, some assets you create cannot be modified after a version of your game that uses those assets ships. You should set up your development process to ensure that your assets (and the related code) are extensively tested before you submit your game for review so that changes to these assets are not necessary. Game Groups Game Groups are an additional feature in itunes Connect that allow you to tie multiple Game Center-aware games into a single connected group that shares some portion of your Game Center content. Each game in the game group is a distinct game on itunes Connect with its own record. However, some assets are shared. The benefit of a game group is that you can ship multiple distinct versions of your game on the App Store, but still allow these games to act as if they are a single game online. For example: You have separate ios and OS X versions of your game. You have free and paid versions of your game. Two distinct forms of grouping are possible in itunes Connect: Shared game assets. You create a common pool of leaderboards and achievement assets that are shared by all versions of your game. If a player has both versions of your game, items earned in one version are visible in the other. Matchmaking compatibility. This allows you to specify which versions of your game can form matches. You ensure that all games in a compatibility group share the same networking code. A matchmaking group can even be formed between different versions of a game shipping with a single bundle ID. For example, if you shipped four versions of your game (1.0, 1.1, 2.0, 3.0), you could specify that version 1.0 and version 1.1 of the game could play together, because nothing in version 1.1 changed the networking implementation. 22

23 Developing a Game Center-Aware Game Incorporating Game Center into Your Game Game Groups impose additional process overhead on your game design. Now, instead of merely having to deal with synchronization issues between your game code and the assets you create in itunes Connect, you now also need to synchronize any implementation changes between the different game implementations. See Groups in Game Center Configuration Guide for itunes Connect for information on how to create and manage game groups in itunes Connect. Incorporating Game Center into Your Game Here s a reasonable process to follow when designing a game that supports Game Center: 1. Decide which Game Center features you plan to support. 2. Define your game mechanics, keeping in mind the requirements and limitations of Game Center. 3. Implement your game engine, ignoring Game Center for now. Focus on developing the other aspects of your game, such as your game engine and gameplay. You do this to avoid needing to create an itunes Connect record earlier than you need to. 4. When you need to implement Game Center: a. Create an itunes Connect record for your game, using the game s bundle ID. Enable Game Center in the itunes Connect record; setting this flag in the itunes Connect record authorizes the Game Center service to allow your game to connect to it. b. Create an explicit App ID using your game s bundle ID. c. Enable Game Center in this App ID; this authorizes the app on the device to contact Game Center s servers. d. Create a new provisioning profile using this new explicit App ID. e. Test to ensure you can build and sign your game using this profile. f. Add the Game Kit framework to your project. g. Import the GameKit/GameKit.h header. Important: Game Center is available only to apps distributed through the ios App Store or Mac App Store. To learn how to code sign and provision your app to use this app service, read App Distribution Quick Start. Xcode will create a team provisioning profile containing an explicit App ID for you. 5. If your game requires Game Center, add the Game Center key to the list of capabilities your app requires from the device. See Requiring Game Center in Your Game (ios only) (page 24). 6. If your game does not require Game Center, you should establish a weak link from your game to the Game Kit framework. Then, when your game launches, test to make sure that Game Center is supported. See Optionally Supporting Game Center in Your Game (page 24). 23

24 Developing a Game Center-Aware Game Incorporating Game Center into Your Game 7. Implement authentication. 8. Implement other Game Center features. 9. Test your Game Center features using the Game Center development environment. Requiring Game Center in Your Game (ios only) If your game requires Game Center to function (for example, a multiplayer game that requires Game Center to match players), you want to ensure that only devices that support Game Center can download your game. To ensure that your game runs only on supported devices, add the gamekit key to the list of required device capabilities in your game s Info.plist file. See Information Property List Key Reference for information about property lists. Optionally Supporting Game Center in Your Game If you want your game to use Game Center, but your game does not require Game Center to function properly, you can weak link your game to the Game Kit framework and test for its existence at runtime. See SDK Compatibility Guide. 24

25 Displaying Game Center User Interface Elements Game Center provides two distinct types of user interface elements for you to use in your game. The first type is intended to be displayed modally by your game, covering your own game s user interface and temporarily interrupting the normal flow of your game. Typically these user interface screens allow a player to interact with content loaded from Game Center or to perform Game Center tasks. When the player finishes interacting with one of these screens of content, your game shows the next appropriate screen, either by returning to one of your game screens or by advancing to another screenful of content. In ios, a fullscreen user interface is packaged as a view controller, and follows the standard conventions of view controllers on the system. One of your game s view controllers is expected to present these view controllers when needed, and later respond when the view controller is dismissed. On OS X, a special class provided by Game Kit provides a similar infrastructure so that your game can present the user interface. The second type of user interface element is a banner that is displayed for a short time to the player. Afterwards, the banner automatically disappears from the screen. While players can interact with some banners, usually banners are simply used to display a message to the player. Game Center displays many banners on behalf of your game, but you can also present your own banners to the player if your game has information you need to display. Game Center UI Is Displayed by Your View Controller (ios) The convention used by Game Kit is for one of your view controllers to present the Game Kit view controller. Your view controller acts as a delegate to the view controller it presents so that the view controller can be informed when the player is finished looking at the presented screen. The Game Center view controller displays many different pieces of Game Center content, so most games should offer a button that brings the player to this screen, even if the game also shows Game Center content using a custom user interface. To present a Game Kit view controller you create a new instance of a GKGameCenterViewController, set its delegate and display the desired information. In most cases, your game would pause gameplay or other real-time behavior when displaying one of these standard user interface classes. When the view controller is later dismissed, it can resume these activities. 25

26 Displaying Game Center User Interface Elements Game Center UI Is Displayed by Your Window (OS X) Game Center UI Is Displayed by Your Window (OS X) In OS X, view controllers do not play the same role as they do in ios. In many cases, some other object responsible for your user interface displays the Game Center control. It does this through the use of the GKDialogController class. This class presents the user interface in a window provided by your game. You create and populate your Game Center view controller in the same way as in ios. However, after creating the Game Center view controller, you then create a GKDialogController instance. The Game Center view controller is associated with the GKDialogController using the presentviewcontroller: method. Displaying Notification Banners Creating a banner in your game is accomplished using the GKNotificationBanner class. You create a title and message for the banner and send this information to showbannerwithtitle:message:completionhandler:. If you want to change the amount of time that the banner is displayed, use the showbannerwithtitle:message:duration:completionhandler: method. 26

27 Working with Players in Game Center Players are a critical part in any game that supports Game Center, because all Game Center features are related to the players. As a game developer, you need to understand some of the infrastructure that Game Center uses to support player accounts and how you implement it in your app. After reading this chapter, you will understand how to manage player information in your game. In particular, you ll learn: How a game identifies different players on Game Center How a player logs themselves into Game Center and how your game knows whether a player is logged into a device it is running on How to retrieve details about particular players from Game Center How to implement support in your game so that a player can invite other players to become friends on Game Center Game Center Manages Player Accounts To take advantage of Game Center s features, a user creates a Game Center account that identifies to identify themselves as a specific user. That user is known as a player on Game Center. The Game Center service keeps track of critical account information for that player, such as who that player is, what games that player has played, what the player has accomplished in each game, and who that player s friends are. Some of this information is directly available to your game; typically this is information specifically related to the game and general information about the player. When a player wants to access Game Center on a particular device, the player signs in, or authenticates on that device. A player authenticates their account by launching the Game Center app or by launching any game that implements Game Center support. In either case, the player is presented with an interface to provide their account name and password. Once authenticated, the player is associated with that device persistently until they explicitly sign out of Game Center in the Game Center app. Only one player is allowed to be authenticated on a device at a time; for a new player to be authenticated on the device, the existing authenticated player must sign out first. Game Center is intended to be a social experience. Game Center allows a player to invite other players to be friends. When two players are friends, they can see each other s status in the Game Center app, compare scores, and invite each other into matches more easily. Through Game Kit, your game can also access some information 27

28 Working with Players in Game Center Game Center Manages Player Accounts about the authenticated player s friends or allow the player to invite players to become friends. For example, you can use this functionality to allow a player to send a friend invitation to a player they just met in a match played within your game. Player Identifier Strings Uniquely Identify Players Every player account is uniquely identified by a player identifier string contained within a GKPlayer object. The identifier string is created when the player s account is first created and never changes, even if other information in the account changes. Thus, player identifiers are the only reliable way to track a particular player. For this reason, the Game Kit API uses player identifiers wherever a specific player needs to be identified. If Game Center needs to identify a specific player in your game, the Game Kit API returns that player s identifier. Your game uses a player identifier to retrieve information from Game Center about that player. In addition to using player identifiers in your interactions with Game Center, your game should also use the player identifier whenever it wants to store data locally about a specific player. For example, if your game stores data to track a player s progress (such as on the device, on your own server, or on icloud), use player identifiers to distinguish between multiple players playing on the same device. That way, if a different player signs into the device, you can immediately personalize the experience by showing content specific to that player. Important: Never make assumptions about the format or length of player identifier strings. Although any individual player identifier string is immutable, the format and length of player identifier strings are subject to change. You must treat player identifier strings as opaque tokens. The Local Player Is the Player Signed in to the Device When you design your game, you ll find that your game is often aware of multiple players at the same time. For example, if you design a game using multiplayer networking, then you have information and a player identifier for each player in the match. However, on any particular device, one player always takes precedence 28

29 Working with Players in Game Center Game Center Manages Player Accounts over other players. The local player is the player that is currently authenticated to play on that device. In Figure 3-1, two players are connected in a network match. On the left device, Bob is the local player and Mary is a remote player. On the right device, Mary is the local player and Bob is a remote player. Figure 3-1 Local and remote players Almost all classes in Game Kit that send data to or retrieve information from Game Center expect the device to have an authenticated local player. The work those classes do is always on behalf of the local player. For example, if your game reports scores to a leaderboard, it can only report a score earned by the local player. As such, before using any Game Center features, your game must first authenticate that there is a local player on the device. Game Kit returns an error to your game if it attempts to perform Game Center-related tasks that require an authenticated player when one isn t available on the device. Important: Games that support multitasking should take special note of this behavior. When your game moves into the background, the player may launch the Game Center app and sign out. Also, another player might sign in before control is returned to your app. Whenever your game moves to the foreground, it may need to disable its Game Center features when there is no longer an authenticated player or it may need to refresh its internal state based on the identity of the new local player. Player Objects Provide Details About Players When your game needs details for a particular player, it retrieves those details by making a query to Game Center using the player s player identifier. Game Kit returns those details to your game in a GKPlayer object. Table 3-1 lists some of the more interesting properties on a player object. 29

30 Working with Players in Game Center Common Tasks When Working with Players Table 3-1 Property playerid Important Player Object Properties Description A string that holds the player identifier string used to retrieve this player information. displayname A user-readable string you can display for this player in your own user interface. For example, in a network match, you might show the display names for each player in the match so that everyone knows who they are playing against. The GKLocalPlayer class is a special subclass of the GKPlayer class, and includes additional properties specific to the local player: The authenticated property states whether the local player has been authencticated. The underage property states whether this player is underage. Table 3-2 Property Local Player Object Properties Description authenticated underage A Boolean value that states whether the local player has been authenticated and is logged into Game Center. If a player is not authenticated, certain Game Center capabilities are not available. A Boolean value that states whether the local player is underage. Some Game Center features are disabled when the value of this property is YES; Game Center returns a GKErrorUnderage error if you try to use those features. Your game can also use this property to decide whether it should disable some of its own features for an underage player. In addition to the display name for a given player, if the player has provided a photo, you can download that player s photo to your game and use it in your game s user interface. Common Tasks When Working with Players Authenticating a Local Player on the Device Your game should start to authenticate the player as early as possible after launching, even before you present the user interface. Authentication is an asynchronous process and won t slow down the loading of your title screen. Waiting until after the title screen is presented before authenticating the user only increases the delay 30

31 Working with Players in Game Center Common Tasks When Working with Players until the player can play your game. The main reason you need to authenticate the player as early as possible is so that ios can launch your game specifically to handle events that the player is interested in. For example, if your game supports turn-based matches, it might be launched because the player has already tapped a notification banner. Thus, you need to authenticate early so that your game can retrieve and process the Game Center event. When your game authenticates a player, Game Kit first checks to see whether there is already an authenticated player on the device. Because a player stays authenticated until they explicitly sign out of Game Center, it is quite common that an authenticated player is already on the device. In this situation, a banner is briefly shown to let the player know that authentication succeeded, and then your game is immediately notified. If there is not currently an authenticated player on the device, then an authentication dialog needs to be displayed so that the player can sign in with an existing account or create a new Game Center account. This is important, because it means that supporting authentication also means transparently supporting account creation. Important: Game Kit handles opting out of Game Center across all games that support Game Center. If a player has already declined to create an account, when your game authenticates the player, it is told there is no authenticated player. The player never sees an authentication dialog. Because Game Kit handles this process across all games, your game should not include its own mechanism to disable Game Center authentication or ask a player s permission to authenticate. Instead, your game should simply authenticate the player every time it launches and respond appropriately when authentication completes. To authenticate the local player, your game is handed a view controller to display at a time of your choosing. Typically, this means your game can cleanly pause its own animations and other features before displaying the view controller. This mechanism allows you to create a better user experience for the player. Authenticating a Local Player To authenticate the local player, you create your own method that sets the authenticatehandler property. The method retrieves the shared instance of the GKLocalPlayer class and then sets that object s authenticatehandler property to point to a block object that handles authentication events. Once you set an authentication handler, Game Kit automatically authenticates the player asynchronously, calling your authentication handler as necessary to complete the process. Each time your game moves from the background to the foreground, Game Kit automatically authenticates the local player again. See the authenticatehandler property for an example of how to create this method. Always check the authenticated property on the local player object to determine whether Game Kit was able to authenticate a local player. Do not rely on the error received by your game to determine whether an authenticated player is available on the device. Even when an error is returned to your game, Game Kit may have sufficient cached information to provide an authenticated player to your game. Also, it is not necessary 31

32 Working with Players in Game Center Common Tasks When Working with Players for your game to display errors to the player when authentication fails; Game Kit already displays important errors to the player on your behalf. Most authentication errors are returned to your game primarily to assist you with debugging. Enable Other Game Center Code Immediately After a Player Is Successfully Authenticated Once the player has been successfully authenticated, your game can read other properties on the local player object to determine the player s display name and other attributes. You can also use other classes that access Game Center. In most cases, your game should immediately enable other code related to Game Center. For example, here are some common tasks that most games perform after successfully authenticating the local player: Read the displayname property to retrieve the local player s name. Use this display name throughout your game when you want to refer to the player; do not prompt the player separately for their name. Add event handlers to receive events for Game Center features. For example, turn-based matches, real-time matches and challenges all require event handlers to process Game Center events. Because your game may have been launched specifically to receive a pending invitation; adding event handlers immediately after authenticating the player allows those events to be processed promptly. Retrieve the local player s previous progress on achievements. Retrieve a list of player identifiers for the local player s friends. This is a first step before loading more detailed information about those players. If your game stores its own custom information for a particular player (such as state variables indicating the player s progress through your game), your completion handler might also load this data so that it can restore the player s progress. Authenticating the Local Player in a Multitasking App A game that supports both multitasking and Game Center must take additional steps when authenticating the local player. When your game is in the background, the status of the authenticated player may change, because the player may sign out or a new player may sign in. As such, you can never rely on the information staying the same when your game moves into the background,. Here are some guidelines for authenticating the local player in a game that supports multitasking: Like other multitasking apps, your game should archive its state before moving into the background. As soon as your game moves to the background, the value of the local player object s authenticated property becomes and remains invalid until your game moves back to the foreground. You cannot read the value to determine if the player is still authenticated until Game Kit reauthenticates the player and 32

33 Working with Players in Game Center Common Tasks When Working with Players calls your authentication handler. Your game must act as though there is not an authenticated player until your completion handler is called. Once your handler is called, value stored in the authenticated property is valid again. If the value of the authenticated property changed to NO, then there is no longer a local player authorized to access Game Center content. Your game must dispose of any Game Kit objects that were created using the previous local player. If the value of the authenticated property is YES, then there is a local player authenticated on the device. However, a new player may have logged in. Your game should store the player identifier for the local player after it authenticates the player. Then, on future calls to your completion handler, compare the value of the local player object s playerid property to the identifier stored by your game. If the identifier changed, then a new player has signed in. Your game should dispose of any objects associated with the previous player and then create or load the appropriate state for the new local player. Retrieving the Local Player s Friends You may want to your game to reference the local player s friends. For example, you might do this if you are implementing your own custom matchmaking or challenge interface and want to allow the player to pick and choose players from the friends list. Information about the local player s friends is only loaded when you ask for it as this information can potentially be quite large and take awhile to send over the network. Use the loadfriendplayerswithcompletionhandler: method to retrieve information about the local player s friends. Retrieving details about the local player s friends is a two-step process. First, your game loads the list of player identifiers for the local player s friends. Then, as with any other player identifiers, your game calls Game Center to retrieve the details for those players. Retrieving Information About Players Regardless of which Game Kit class returned player identifiers to your game, you retrieve detailed information about those players in the same way by calling the loadplayersforidentifiers:withcompletionhandler: class method on the GKPlayer class. This Game Kit method takes two parameters. The first is an array of player identifiers for the players you are interested in. The second is a completion handler to be called after Game Kit retrieves the data from Game Center. 33

34 Working with Players in Game Center Common Tasks When Working with Players Loading a Photo for a Player In addition to the information found in the player object, you can also attempt to load a photo for the player. Not all player objects have photos associated with them, so your code must be able to work without them. Use the loadphotoforsize:withcompletionhandler: method to import player photos. Note that there is not a property on the player object that stores the returned photo. You must write your own code to associate player photos with player objects. Allowing the Local Player to Invite Other Players to Be Friends The Game Center app allows players to send invitations to other players. Use the GKFriendRequestComposeViewController class to allow a player to send friend requests. The friend request must be presented modally by a view controller that your game creates and can not be pushed onto a navigation controller. When the player dismisses the friend request, the delegate s friendrequestcomposeviewcontrollerdidfinish: method is called. 34

35 Leaderboards, Achievements, and Challenges Creating a game is more than putting a bunch of sprites and graphics on the screen. A game needs to engage your players and creates an environment that encourages to continue playing. Game Center provides the following ways for you to interact with your players: Achievements Provides players with feedback during gameplay along with optional goals for the player to persue. Leaderboards Allows players to see how well they are doing compared to their friends and the rest of the world. Challenges Provides players with the ability to challenge their friends to beat a high score or accomplish a specific achievement. By incorporating these Game Center options into your game, you expand the replayability of your game while making the game more engaging for your players. Achievements Achievements are a great way to track what a player has done in your game and to give the player more incentive to keep playing your game. An achievement represents a quantitative goal that the player can accomplish in your game. As the local player plays your game, they make progress towards completing the achievement. When the player meets or exceeds the goal, the achievement is considered earned, and the player is rewarded. Your game defines the goal and the game mechanics that describe how a player earns the achievement. In practice, Game Center does not need to know anything about your game design; it only knows what progress the player has made towards an achievement. In Game Center, an achievement earns a player achievement points. When you define an achievement, you decide how many points it is worth. A player can see the total number of points that can potentially be earned in your game as well as how many points he or she has currently earned. The Game Center app allows players to compare their achievements with those of friends; this comparison screen includes the total points earned. When you add an achievement to your game, you configure how the achievement is granted and how it is described to the player. You also design the game mechanics that allow the player to make progress towards completing the achievement. 35

36 Leaderboards, Achievements, and Challenges Achievements Checklist for Supporting Achievements To add achievements to your game, you need to take the following steps: 1. Before you add achievements, add code to authenticate the local player. See Working with Players in Game Center (page 27). 2. Design your game s achievements. See Designing an Achievement (page 36). 3. Go to itunes Connect and configure the achievements for your game. You provide all of the data needed to display achievements to the player. See Configuring Achievements in itunes Connect (page 39). 4. Add code to report the local player s progress to Game Center. By storing the progress on Game Center, you also make the player s progress visible in the Game Center app. See Reporting Achievement Progress to Game Center (page 40). 5. Add code to load the local player s previous progress on achievements from Game Center. The local player s progress should be loaded shortly after the player is successfully authenticated. See Loading Achievement Progress (page 41). Designing an Achievement The design of an achievement starts with a simple statement of the achievement s goal. Here are some example goals that can define a game: Capture 10 pirates. Defeat 1 boss. Find 1000 gold coins. Earn first place in 5 races. Earn first place on 5 different race tracks. A goal statement describes a triggering condition ( Earn first place on a different race track ) and a quantity (5). The triggering condition is essential as it defines something your game logic needs to track. In the racing example, your game must check the victory conditions at the end of each race, but it also needs to record which tracks a player has defeated. The quantity usually defines how granular the task is for the player. With some achievements, quantity is irrelevant; the achievement is either earned or not. For example, Defeat the end-game boss is not a goal that the player generally earns partial credit towards completing. In contrast, a goal of Capture 10 pirates is a more granular task. Your game needs to track the number of pirates captured and use this count to report progress to Game Center. 36

37 Leaderboards, Achievements, and Challenges Achievements When you design an achievement, consider a few other characteristics: value, visibility, and repeatability. These characteristics affect more than the design of your game; later, when you define your achievement in itunes Connect, you ll set attributes based on these characteristics: The value of an achievement is a measure of how difficult you believe it will be for a player to earn the achievement. Some achievements are easily earned in a few minutes of play. Difficult achievements might require hours of focused gameplay or require the player to develop advanced playing skills or strategies to earn the achievement. The visibility of an achievement determines whether a player can see the achievement at the start of play or whether the achievement must be discovered during play. By default, achievements are visible to the player. This is helpful, because a player can scan the list of available achievements and see what actions earn rewards. However, some achievements can be more useful if hidden. For example, if your game includes a story or plot, listing all of the achievements at the start of play may reveal too much of the story to the player. Achievements critical to the story can be marked as hidden so that you can choose when the player sees them. An achievement is normally not repeatable. After the achievement is earned, the player sees no further messages about that achievement. If an achievement is marked as repeatable, then each time your game reports that the player has completed the achievement, the player sees the appropriate reward banner. You have a lot of room to be creative with the kinds of achievements you create. Here are some common strategies for designing achievements that can guide you through the process. Create Achievements That Show the Different Things Players Can Do in Your Game When experienced players purchase new games, they examine the list of achievements to see what s possible in those games. Your list of achievements should strongly communicate what you want players to think about or do while playing your game. You want achievements to provide a variety of different goals a player can strive towards. When you provide a variety of goals and achievements, players continue to play your game. Create Achievements That Require Different Levels of Skill or Dedication Provide achievements for both new players and experienced players and the players in between. Achievements are a reward to the player for playing your game. If all of your game s achievements are too easy to beat, the rewards will seem cheap and the player won t feel challenged. On the other hand, if all the achievements are too difficult to earn, then players may not be rewarded often enough to continue playing your game. Strive to include achievements that can be earned when learning how to play the game and also achievements that reward players for learning how to play your game well. Another reason to include more difficult challenges is that they encourage players to use them when challenging other players. See Challenges (page 54). 37

38 Leaderboards, Achievements, and Challenges Achievements Create Achievements for Different Sections Or Modes Present in Your Game For various reasons, you might choose to partition the gameplay into smaller games or game modes. Some reasons include: Distinct sets of game rules or rule variants (capture the flag, survival) Distinct game levels or maps A game with an underlying story separated into distinct acts or story arcs If your game does partition its gameplay into smaller mini-games, define achievements for each as it encourages players to try each of the game modes or to complete your game. Use Hidden Achievements to Delight and Reward the Player Hidden achievements should be used sparingly. Usually, you want players to know what s expected of them in your game, so that they can actively set goals for themselves. And hidden achievements cannot be used to create new challenges. However, a hidden achievement can be a great opportunity to surprise a player with something unexpected. For example, any of the following might be places where a hidden achievement could be helpful: An unexpected element in the plot or a story. The player succeeds at a crazy stunt. You can flip the convention from an achievement being something the player tries hard to earn into something more ignoble, earned when they fail spectacularly. The achievement then represents a way to inject humor into the situation. For example, an achievement called Hot Foot that might appear after the player has fallen into lava 20 times. Save Some of Your Budget for Later Versions of Your Game There are limits to how many achievements you can create in your game and how many points you can reward to the player: Each game can have up to 100 achievements. Each game can award up to 1000 points. No individual achievement can award more than 100 points. Avoid spending all of your budget on the initial version of your game. Save some of your budget to support updates and new content. 38

39 Leaderboards, Achievements, and Challenges Achievements Configuring Achievements in itunes Connect When you are ready to add achievements, you define them first in itunes Connect. For each achievement, you provide values for all of the properties listed in Table 4-1. Further, for each language you plan to localize the achievement into, you provide data for all of the properties listed in Table 4-2. Table 4-1 Property Achievement properties Description Achievement Reference Name Achievement ID Point Value Hidden Achievable More Than Once An internal name that you must provide for each achievement, used only in itunes Connect. This is the name you will use if you search for the achievement in itunes Connect. A chosen alphanumeric identifier for your achievement. This ID is limited to 100 characters. Your achievement ID is a permanent setting and therefore cannot be edited at a later date. The achievement ID is used inside your game to refer to this achievement. The points that your achievement is worth. Achievements marked as Hidden remain hidden to a player on Game Center until after the first time you report progress for that achievement. Indicates whether the user can earn the achievement multiple times. Table 4-2 Property Language Title Achievement language properties Description The language in which you would like this achievement to appear. The localized title of this achievement as you would like it to appear in Game Center. Pre-earned Description Earned Description Image The description of your achievement as it appears to a Game Center player before he or she earns it. The description of your achievement as it appears to a Game Center player after he or she earns it. A localized image that represents the achievement. The image must be a.jpeg,.jpg,.tif,.tiff, or.png file that is 512 x 512 or 1024 x 1024 pixels, at least 72 dpi, and in the RGB color space. This property is required. 39

40 Leaderboards, Achievements, and Challenges Achievements For more information on setting up your leaderboards in itunes Connect, see Achievements. Adding Achievement Support to Your Game When you are ready to implement achievements in your game, you do so using the classes listed in Table 4-3. Table 4-3 Class Name Classes in Game Kit used to implement achievement support Description GKAchievement GKAchievement- Description GKGameCenterView- Controller GKAchievementView- Controller Holds information about the player s progress towards completing an achievement. Your game creates GKAchievement objects to report progress to Game Center. Game Kit can also load the current progress stored on Game Center and return it to your game using GKAchievement objects. Holds the localized text and images for an achievement. The data for achievement descriptions is retrieved from Game Center at runtime and is based on the data you provided to itunes Connect when you created your achievement there. Provides a standard user interface to display Game Center content to the player. This content includes an achievements page. Provides a standard user interface to display an achievements page. If the GKGameCenterViewController class is available, you should use that class instead. Reporting Achievement Progress to Game Center Your game should report progress to Game Center whenever the player makes progress towards completing an achievement. By storing progress information in Game Center, you gain a few benefits: The Game Center app can display the player s progress towards the achievement. If a player has multiple devices, your game on another device can retrieve the player s progress towards achievements. You store the a user s progress towards an achievement using the percentcomplete property. When you report progress to Game Center, two things happen: If the achievement was previously hidden, it is revealed to the player. The achievement is revealed even if your player has made no actual progress on the achievement (a percentage of 0.0). 40

41 Leaderboards, Achievements, and Challenges Achievements If the reported value is higher than the previous value reported for the achievement, the value on Game Center is updated to the new value. Players never lose progress on achievements. When the progress reaches 100 percent, the achievement is marked as completed, and both the image and completed description appear when the player views the achievements screen. Whether reporting progress on a single achievement or on multiple achievements at once, your game rarely needs to do anything specific when an error occurs. If an error occurs, such as when a network is not available, Game Kit automatically resends the data at an appropriate time. Best Practices for Reporting Achievement Progress When designing a game that uses Game Center achievements, you need to balance the need to be responsive to the player against your goal to use as few device resources as possible. With those two concepts in mind, consider the following practices: Report progress on an achievement as soon as the player makes progress. Don t delay reporting until a later time; if a player earns an achievement, the banner should be displayed immediately. Report progress only when the player has actually made further progress. Do not report changes to Game Center if the player has not made progress, because it consumes network resources without actually changing the state of the data on Game Center. If your game displays a custom banner or indicator when a player earns an achievement, set the showscompletionbanner property to NO before reporting the achievement to Game Center. Loading Achievement Progress You load the local player s current progress information from Game Center by calling the loadachievementswithcompletionhandler: method. If the operation completes successfully, it returns an array of GKAchievement objects, one object for each achievement your game previously reported progress for. Resetting Achievement Progress You may want to allow the player to reset their progress on achievements in your game. See resetachievementswithcompletionhandler: for information on how to reset the player s progress. When your game resets a player s progress on achievements, all progress information is lost. Hidden achievements, if previously shown, are hidden again until your game reports progress on them. For example, if the only reason those achievements were originally hidden was that they were associated with an In-App Purchase, then you would reveal those achievements again. 41

42 Leaderboards, Achievements, and Challenges Leaderboards Leaderboards Many games offer scoring systems that measure how well a player does in the game. Scores are not just a way for players to measure their own progress; they also provide a way for players to compare their skills with those of other players. In Game Center, a leaderboard is a database of score data. Your game posts scores to a leaderboard so that the player can later view those scores. When you add leaderboards to your game, you define what a score means in your game and how score data is formatted for display. Checklist for Supporting Leaderboards To add leaderboards to your game, you need to take the following steps: 1. Before you add leaderboards, add code to authenticate the local player. See Working with Players in Game Center (page 27). 2. Decide how you want to use leaderboards in your game. You choose how many leaderboards to use and how each leaderboard interprets its score data. You are free to design a different scoring mechanism for each leaderboard. See Leaderboards Require a Scoring Mechanism (page 42). 3. Go to itunes Connect and configure the leaderboards for your game. For each leaderboard, you configure the kind of score recorded and how the score is formatted for display. Leaderboard formatting can be localized for different languages and regions. See Working with Leaderboards in itunes Connect (page 45). 4. Add code to report scores to Game Center. See Reporting Scores to Game Center (page 46). 5. Add code to display a leaderboard to the local player. See Working with the Default Leaderboard (page 47). Optionally, you can retrieve score data from Game Center and use it to create your own custom leaderboard user interface. See Retrieving Score Data (page 48). Leaderboards Require a Scoring Mechanism To include leaderboards into your game, you must have a gameplay mechanism that allows your game to calculate a score. You are free to design your gameplay and scoring mechanism however you want. The only restriction is that your scoring mechanism must return a 64-bit integer value. When you report a score, you report this integer value to Game Center so it can be stored. 42

43 Leaderboards, Achievements, and Challenges Leaderboards How can you make the integer into something more interesting? As part of the development process, you configure a leaderboard description in itunes Connect so that Game Center understands what scores mean in your leaderboard. You describe to Game Center what type of score is stored in the leaderboard and how to convert your score into a string for display. An advantage of this mechanism is that the same description is used by the Game Center app to show your game s scores. The most critical decision to make is what kind of score is stored in the leaderboard. Game Center provides three basic formatting types: An abstract number, such as an integer or a fixed point number. A time value, such as minutes or seconds. A monetary value, such as dollars or euros. You also decide the order in which scores are ranked. When scores are ranked low-to-high, a lower score is considered a better score for example, a racing game that records the time it took to complete the race. In this circumstance, a faster time that is, a lower score is better, so a sorting order of low-to-high is appropriate. In contrast, a game that adds points to the player s total for each successful action taken in the game expects that a higher score is better, so a high-to-low sorting order would be more appropriate. Once you have the formatting type and sorting order chosen, you also customize the final results with a localized formatting string. For example, if you chose to represent the score as an integer, you might choose point and points as the English localization for singular and plural values of scores stored in that leaderboard. Other games might use the same score type, but use different localized strings ( laps, cars ). When you design a scoring mechanism, make sure that you consider the range of possible (legal) score values. When you create the leaderboard description, you can also provide minimum and maximum values for scores reported to it. Providing a score range adds a layer of security onto your leaderboard, as it reduces the likelihood that a player can cheat if they discover a way to report an absurdly high score. A Game Can Have Multiple Leaderboards You can define up to 100 different leaderboards for a game (or game group) if your game does not support leaderboard sets. The number of different leaderboards allowed increases to 500 leaderboards per game when leaderboard sets have been enabled. See Leaderboard Sets (page 50) for more information. Each leaderboard has its own score type, sorting order, and formatting information. When you implement multiple leaderboards, you choose what sort of score data to record in each leaderboard, which essentially means that each leaderboard may have its own scoring mechanism, if desired. Here are a few possibilities on how you can use different leaderboards in your game: A game with multiple levels of difficulty can have a different leaderboard for each level of difficulty. A game with different maps (levels, tracks) can have a different leaderboard for each map. 43

44 Leaderboards, Achievements, and Challenges Leaderboards A game with different play modes (rule sets) can have a different leaderboard for each play mode. You might create multiple scoring mechanisms that evaluate the player s skill in different ways, and create a different leaderboard for each. For example, a racing game might evaluate the player s best track time, best lap time, as well as a score based how well the player drifts while driving around the track. Evaluating players in different ways allows players to find multiple ways to improve their skills. To allow leaderboards to be differentiated from each other in your game, you assign each leaderboard a leaderboard ID. Your game uses a leaderboard ID to report the score to the appropriate leaderboard. For example, if your game included three leaderboards for different levels of difficulty, you might use mygame.easy, mygame.normal and mygame.hard as the leaderboard IDs. One Leaderboard Is the Default Leaderboard When you define your leaderboards in itunes Connect, one leaderboard is designated as the default leaderboard. When your game performs a leaderboard task without specifying a leaderboard, the default leaderboard is automatically chosen. The initial value for the default leaderboard is the value you assign in itunes Connect. However, as a player plays your game, you can set a different default leaderboard for that player. You can change the default leaderboard automatically when reporting a new score or you can change the default leaderboard independent of score reporting. For example, if your game has multiple sequential levels and a leaderboard for each level, you can change the default leaderboard each time the local player advances to a higher level. That way, future scores (or displayed leaderboards) automatically show the best level the player has played. Combined Leaderboards Gather Scores from Multiple Single Leaderboards A combined leaderboard is a special type of leaderboard that combines scores reported to multiple leaderboards into one leaderboard. The individual leaderboards continue to exist and are where you report scores to. You don t report scores to combined leaderboards. For example, if your game offers multiple race tracks, you can create a single leaderboard for each race track and a combined leaderboard that shows the best time earned on any track. When deciding whether to set up one or more combined leaderboards for your game, keep the following guidelines in mind: Only non combined leaderboards can be included in a combined leaderboard. That is, you cannot combine other combined leaderboards into a combined leaderboard. A non combined leaderboard can only be attached to one combined leaderboard. The non combined leaderboards that are attached to a combined leaderboard must have the same score format type and sort order. And, in practice, they should share the same scoring mechanism in your game. 44

45 Leaderboards, Achievements, and Challenges Leaderboards Working with Leaderboards in itunes Connect After you ve considered the design of your scoring mechanism, you go to itunes Connect to precisely define each leaderboard. Defining a leaderboard is a critical step; once your game ships to customers, many pieces of the leaderboard cannot be changed. It s important to note that the information you enter into itunes Connect must match your game s implementation. As such, you should exercise caution when creating your leaderboards and test your game thoroughly before releasing it. For complete details on managing your game s leaderboards and leaderboard sets see Game Center Configuration Guide for itunes Connect. However, for your convenience, Properties for a single leaderboard describes the properties you use to define a single leaderboard. Leaderboard language properties lists the properties you set for each language you plan to localize your game into. Table 4-4 Property Properties for a single leaderboard Description Leaderboard Reference Name Leaderboard ID Score Format Type Sort Order Score Range An internal name for your leaderboard, used only in itunes Connect. This is the name that you use to search for your leaderboard in itunes Connect. A chosen alphanumeric identifier for your leaderboard. This ID is limited to 100 characters. Your leaderboard ID is a permanent setting and cannot be edited at a later date. Choose the type of format in which you want scores to be expressed in the leaderboard for example, integer, elapsed time, or money. Choose between Low to High or High to Low for the display of your leaderboard scores. Choose Low to High if you want lowest scores displayed first. Choose High to Low if you want highest scores displayed first. Define the score range using 64-bit signed integers. The values must be between the long min (-2^63) and long max (2^63-1). Any scores outside of this range will be deleted. Score range values are optional, but if they are added then both values must be set and they must not be equal. When first adding a score range, or when changing it in the future to a smaller range that will restrict data, all data outside of the range will be lost and can t be recovered. Table 4-5 Property Language Name Leaderboard language properties Description This is the language in which your leaderboard appears. The name of the leaderboard that appears in the standard leaderboard user interface. 45

46 Leaderboards, Achievements, and Challenges Leaderboards Property Score Format Score Format Suffix (Singular) Score Format Suffix (Plural) Image Description This property determines how your scores are displayed when the leaderboard is displayed in the specified language. For example, if your leaderboard stores a score as money, you may want to specify different types of money based on the language you select. The permitted values for this property are based on your Score Format Type. This suffix is added to the end of scores displayed in the singular form. This suffix is optional, but is useful for clarifying the type of score stored in the leaderboard. Examples include point, and hit. This suffix is added to the end of scores displayed in the plural form. This suffix is optional, and is useful for clarifying the type of score stored in the leaderboard. Examples include points, coins, and hits. A localized image that represents the leaderboard. This property is optional; if specified, the image is displayed as part of the standard leaderboard user interface. The image must be a.jpeg,.jpg,.tif,.tiff, or.png file that is 512 x 512 or 1024 x 1024 pixels, at least 72 dpi, and in the RGB color space. For more information on setting up your leaderboards in itunes Connect, see Leaderboards and Leaderboard Sets. Reporting Scores to Game Center Your game transmits scores to Game Center by creating an array of GKScore objects, whether you are reporting a single score or multiple scores. A score object has properties for the player that earned the score, the date and time the score was earned, the identifier for the leaderboard the score should be reported to, and the actual score that was earned. You allocate and initialize a new score object for each score, configure their properties, and then call the reportscores:withcompletionhandler: method to send the data to Game Center. The score object is initialized with the leaderboard ID for the leaderboard it reports its score to and then your score reporting method sets the value property to the score the player earned. The leaderboard ID must be the identifier for a leaderboard you configured in itunes Connect. The player who earned the score and the time the score was earned are set automatically when the score object was created. Scores are always reported for the local player. 46

47 Leaderboards, Achievements, and Challenges Leaderboards Your game should create the score object and report the score to Game Center immediately after the score is earned. This sets the date and time accurately and ensures that the score is reported correctly. If for some reason the score could not be reported because of a network error, Game Kit automatically resends the data when the network becomes available. Security and Score Reporting When you design a game that reports scores to Game Center, you should also consider the security needs of your game. You want scores reported to Game Center to be an accurate accounting of how players are doing. Here are two suggestions: Store your game s preferences and saved games in a secure format, rather than in clear text. If your game s data is stored in clear text, a player can download the saved game data using itunes, modify it, and resync it back to the device. This may allow the player to achieve a higher score than you intended. Always set reasonable minimum and maximum values for a leaderboard. Working with the Default Leaderboard The default leaderboard is set when you create your leaderboards in itunes Connect. However, the default leaderboard is a per-player setting also; as a player plays your game you can update the default leaderboard shown to that player. The most common time to update the default leaderboard is when you report a score, and Game Kit provides a convenient way to set the default leaderboard as you report the score. Create the score object, and then set its shouldsetdefaultleaderboard property to YES. When the score is reported, the value in the score object s leaderboardidentifier property becomes the new default leaderboard ID. However, you can also use the GKLocalPlayer object to update the default leaderboard directly by calling the setdefaultleaderboardidentifier:completionhandler: method. Displaying the Standard Leaderboard In addition to sending scores to Game Center, you should also allow players to view scores within your game. The simplest way to do this is with a GKGameCenterViewController object. You can adjust the behavior of a Game Center view controller so the initial content it displays is the leaderboard page. Configure the other properties to show the leaderboard page, displaying only scores earned in the last day. You then present the view controller. In OS X, you use the GKDialogController class to display the view controller, as described in Displaying Game Center User Interface Elements (page 25). When the player finishes looking at the leaderboard, the delegate is called. Override the gamecenterviewcontrollerdidfinish: method and dismiss the presented view controller. 47

48 Leaderboards, Achievements, and Challenges Leaderboards Retrieving Score Data There are times when you want to retrieve score data from Game Center. The most common reason to download the score data is when you want to create a custom leaderboard user interface. Your game uses a GKLeaderboard object to retrieve score data. In this case, the leaderboard object represents a query on the data stored on Game Center. You set properties on the GKLeaderboard object to filter which scores are returned to your game, then tell the object to load the scores. Retrieving a subset of leaderboard data stored on Game Center has the following steps: 1. Start with the set of all scores stored in the leaderboard. 2. Discard any scores that do not match the playerscope, timescope and identifier properties. 3. Keep only the best remaining score for each player. 4. Sort the list of scores from best to worst. 5. Return the subset of scores requested by the range property. Leaderboard data is filtered, sorted, and returned to your game shows an example of one possible search. In this example, scores more than a day old are ignored. Then, from the remaining set of scores, we see that Mary has two scores, so only her best score is kept. Finally, the scores are sorted and ranked. The selected range is then returned to the game. Figure 4-1 Leaderboard data is filtered, sorted, and returned to your game 48

49 Leaderboards, Achievements, and Challenges Leaderboards If you provide a leaderboard identifier that matches a combined leaderboard, all of the scores in the single leaderboards are pooled together before filtering and sorting occurs. Figure 4-2 shows the same scores as in the earlier example, but now you can see that the scores are actually stored in two different leaderboards that make up a combined leaderboard. Figure 4-2 Combined leaderboards include scores from the single leaderboards It is important to note that combined leaderboards are set up in itunes Connect and are considered a unique leaderboard. You can not determine where the scores from a combine leaderboard come from inside of your app. You need to query each leaderboard individually through their leaderboard ID and manually determine what scores were used to create the combined leaderboard if you want to display that information. Extending Leaderboards Using Score Contexts Although the score and formatting system allows you to create interesting leaderboards, you may want to extend the leaderboard system to include other information specific to your game. You do this using score contexts. A GKScore object has a context property that holds a 64-bit integer. The value stored in this property is stored along with the score. Game Center doesn t use this value at all, nor does it affect score formatting. Your game is free to use this integer to store whatever information you want. Here are a few possibilities: You can use the context property to store flags that provide additional content. For example, in a racing game, use the flags to store what kind of car the person completed the racetrack with. Then, in your own custom leaderboard user interface, you could display the appropriate car image next to each score. 49

50 Leaderboards, Achievements, and Challenges Leaderboard Sets Record the user s actions and other data in to a file. You then design your game engine to be able to replay the contents of that file. You store the file on your own server and use the context field as an index to reference the file. Your custom leaderboard user interface can then offer the ability to see exactly how someone earned the score. You can implement the replay directly into your gameplay. For example, in the hypothetical racing game, you could use a player s replay file to display a phantom car for the current player to race against. Leaderboard Sets Leaderboard sets offer developers the ability to combine several leaderboards into a single group. ios developers are able to create leaderboard sets starting with ios 7. Leaderboard sets are not supported in OS X v10.9. The following example shows why you would want to incorporate leaderboard sets in your game. The created game has several different worlds with each world containing several leaderboards for example, a leaderboard for most coins collected, highest score obtained, and most enemies captured. The developer combines the different leaderboards into a single leaderboard set for each world. Users can see a displayed list of world leaderboard sets. Opening a set shows the leaderboards contained in the set. 50

51 Leaderboards, Achievements, and Challenges Leaderboard Sets Important: After you decide to use leaderboard sets, every leaderboard must be placed into a leaderboard set. You can not have a leaderboard outside of a leaderboard set in games that support leaderboard sets. Leaderboards combined into a leaderboard set shows the leaderboards for each world combined into a leaderboard set. Figure 4-3 Leaderboards combined into a leaderboard set Checklist for Supporting Leaderboard Sets To add leaderboard sets to your game, you need to take the following steps: 1. Before you add achievements, add code to authenticate the local player. See Working with Players in Game Center (page 27). 2. Ensure that your game contains at least one leaderboard. See Leaderboards (page 42) for information on creating leaderboards. 3. Go to itunes Connect and configure leaderboard sets for your game. For each leaderboard set, add the desired leaderboards to the leaderboard set. See Working with Leaderboard Sets in itunes Connect (page 52). 4. Add code to load the leaderboard sets associated with the current game. See Adding Leaderboard Set Support to Your Game (page 53). 51

52 Leaderboards, Achievements, and Challenges Leaderboard Sets A Game Can Have Multiple Leaderboard Sets You can define up to 100 different leaderboard sets for your game. Each leaderboard set can contain up to 100 leaderboards with a maximum of 500 leaderboards for your game. You choose which leaderboards are placed inside of each leaderboard set. Games that don t use leaderboard sets are limited to 100 leaderboards. Here are a few possible ways to use different leaderboard sets in your game: A game with multiple scoring mechanisms for each world (score, enemies captured, coins collected) can combine the leaderboards for each world into a leaderboard set. A game with multiple scoring mechanisms for each world (score, enemies captured, coins collected) can combine all of the leaderboards for a single scoring mechanism into a leaderboard set. A game with multiple playable characters (warrior, archer) can combine all of the leaderboards for a particular character into a single leaderboard set. You can combine the number of leaderboards and leaderboard sets in any format as long as the individual maximums are not exceeded. The following are all allowable combinations: 5 leaderboard sets, each containing 100 leaderboards 100 leaderboard sets, each containing 5 leaderboards 3 leaderboards sets, each containing 50 leaderboards; 2 leaderboard sets, each containing 100 leaderboards; 1 leaderboard set containing 1 leaderboard Game Group Leaderboard and Leaderboard Set Limits The number of leaderboards and leaderboard sets within a group is limited only by the number of apps within the group. Each game within a group can have a number of leaderboard sets and leaderboards, as stated in A Game Can Have Multiple Leaderboard Sets (page 52). For example, if a group has three apps inside of it, then the group can have a total of 300 leaderboard sets and 1500 leaderboards. However, an individual app is still limited to 100 leaderboard sets and 500 leaderboards. Working with Leaderboard Sets in itunes Connect After you have decided to use leaderboard sets in your game, you must configure the leaderboard sets in itunes Connect. In itunes Connect you can create new leaderboard sets and move your leaderboards into them. For complete details on managing your game s leaderboards and leaderboard sets see Leaderboards and Leaderboard Sets. 52

53 Leaderboards, Achievements, and Challenges Leaderboard Sets Adding Leaderboard Set Support to Your Game To implement leaderboard set support in your game, you use the classes listed in Game Kit classes used to implement leaderboard set support. Table 4-6 Class Name GKScore Game Kit classes used to implement leaderboard set support Class Function A GKScore object holds information for a score that was earned by the player. Your game creates GKScore objects to post scores to a leaderboard on Game Center. When a game retrieves score information from a leaderboard those scores are returned as GKScore objects. GKLeaderboard GKLeaderboardSet GKGameCenterView- Controller GKLeaderboardView- Controller A GKLeaderboard object provides information about a leaderboard, including its leaderboard ID and title. You also create GKLeaderboard objects when you want to retrieve score data from a leaderboard. You typically do this if you want to create your own custom leaderboard user interface. A GKLeaderboardSet object provides information about the leaderboard sets contained within your game. Each set contains from 1 to 100 GKLeaderboard objects assigned to the set. The GKGameCenterViewController class provides a standard user interface to display Game Center content to the player. This content includes a leaderboard page. The GKLeaderboardViewController class provides a standard user interface to display a leaderboard. If the GKGameCenterViewController class is available, you should use that class instead. Before you can load the leaderboards contained within a set, you must load the set itself. Retrieve the list of leaderboard sets for your game from Game Center and display their titles. Use the loadleaderboardsetswithcompletionhandler: method to retrieve the leaderboard sets for your app. You can then load the leaderboards for a specific leaderboard set using the loadleaderboardswithcompletionhandler: method. 53

54 Leaderboards, Achievements, and Challenges Challenges Challenges Achievements and leaderboards both allow players to measure their progress playing your game. But it is also common for players to want to test their progress against each other. It s more satisfying to beat a friend s score than to merely achieve a decent score. Game Center embraces this idea in the form of challenges. Players on Game Center can challenge other Game Center members to beat earned scores or achievements. Challenges represent a different style of multiplayer experience where players compete against each other indirectly. When a challenge is issued by one player to another, a push notification is sent to the challenged player. The challenged player can then accept or refuse the challenge. If the player accepts the challenge, the challenge is placed on a list of challenges associated with that player. Later, if the player beats the challenge, Game Center notifies both the challenged player and the challenger that the challenge is complete. Game Center supports two kinds of challenges: A score challenge is issued based on a leaderboard score previously earned by the challenger. The challenge is completed when the challenged player earns a better score. When the challenged player beats a score challenge, Game Center automatically issues a new score challenge to the original challenger. Score challenges continue to pass back and forth between the two players as they work to beat each other s scores. An achievement challenge is issued from an achievement that the challenger has already completed. The challenge is completed when the challenged player completes the achievement. If your game supports achievements or leaderboards, it automatically supports challenges without requiring any additional code. In this case, players go to the Game Center app to challenge their friends. However, you can also customize your game to directly support challenges: You can allow players to challenge other players from within your game. You can retrieve the list of open challenges for the local player. Your game can receive notifications when players tap banners for new challenges. Your game can receive notifications when players receive or complete challenges. You can even prevent challenge banners from being displayed when your game is running, allowing you to completely control the user interface displayed when a challenge event is received by your game. You can determine whether your game shows challenge banners inside of the game by adding GKShowChallengeBanners to your Info.plist. See Cocoa Keys for details. Checklist for Supporting Challenges To add challenges to your game, you need to take the following steps: 54

55 Leaderboards, Achievements, and Challenges Challenges First, add support for leaderboards or achievements to your game. See Leaderboards (page 42) and Achievements (page 35). Optionally, add code to allow a player to send challenges within your game. See Issuing Challenges from Your Game (page 55) Optionally, add code to receive and act on challenge notifications. See Issuing Challenges from Your Game (page 55) and Reacting to Challenge Events (page $@) Each type of challenge is defined by a distinct subclass of GKChallenge. Challenge subclasses lists the subclasses and how to retrieve the remaining information needed to display the challenge to the player. Table 4-7 Challenge subclasses Subclass GKScoreChallenge GKAchievementChallenge Description Read the score property to obtain a score object representing the score used to generate the challenge. Read the achievement property to obtain an achievement object representing the achievement that completes the challenge. Issuing Challenges from Your Game You issue a challenge from within your game using either a GKScore object or a GKAchievement object. Both classes implement an issuechallengetoplayers:message: method with a similar signature. Issuing a challenge does not display a user interface to the player issuing the challenge; this is code you need to implement yourself. The following section shows a series of methods you can use to issue an achievement challenge. The design for score-based challenges is similar. Create a score object, submit the score, then use it to generate a challenge request. Displaying the Challenge User Interface Displaying the challenge user interface begins the challenge process. This method is called when the player completes an achievement. The first thing the code does is create a new achievement object to tell Game Center that the achievement has been completed. If the player completes multiple achievements for a challenge at once, create a new object for each achievement and add the achievement to an array. Note that a challenge can only be performed on a completed achievement. It disables the achievement s default completion banner because it plans to display a custom challenge screen instead. The method reports the progress to Game Center and then triggers a segue to display the game s custom challenge user interface. 55

56 Leaderboards, Achievements, and Challenges Challenges Listing 4-1 Displaying the challenge user interface - (void) bossmonsterdefeated { GKAchievement *achievement = [[GKAchievement alloc] initwithidentifier:@"mygame.bossdefeated"]; achievement.percentcomplete = 100.0; achievement.showscompletionbanner = NO; [achievement reportachievements: [NSArray arraywithobjects:achievement, nil] WithCompletionHandler:NULL]; } [self performseguewithidentifier:@"achievementchallenge" sender:achievement]; Displaying and Dismissing the Challenge View Controller Preparing the challenge view controller shows the issuing view controller s prepareforsegue:sender: method. When the method detects that this is a segue to show the achievement user interface, it sets the issuing view controller as a delegate. The achievement object is also provided to the challenge view controller so that it can customize its user interface to match the earned achievement. Listing 4-2 Preparing the challenge view controller - (void )prepareforsegue:(uistoryboardsegue *)segue sender:(id)sender { if ([segue.identifier isequaltostring:@"achievementchallenge"]) { MyAchievementChallengeViewController* challengevc = (MyAchievementChallengeViewController*) segue.destinationviewcontroller; } } challengevc.delegate = self; challengevc.achievement = (GKAchievement*) sender; Dismissing the challenge view controller shows the issuing controller s implementation of the delegate method. When the user dismisses the challenge view controller, the delegate is called. The delegate method takes a parameter that states whether the player issued a challenge. If the player issued a challenge, then the method retrieves the list of players and the message from the challenge view controller and issues the challenge. Note 56

57 Leaderboards, Achievements, and Challenges Challenges that this design gives control over issuing the challenge to the original view controller. If your design does not need this additional flexibility, you can simply issue the challenge directly from the challenge view controller instead. Listing 4-3 Dismissing the challenge view controller - (void) challengeviewcontroller:(myachievementchallengeviewcontroller*)controller wasdismissedwithchallenge:(bool)issued { [self dismissviewcontrolleranimated:yes completion:null]; if (issued) { [controller.achievement issuechallengetoplayers:controller.players message:controller.message]; } } Best Practices for Issuing Challenges The local player must always have control over when and how a challenge is issued. Your game must never issue a challenge on the player s behalf without the player first approving the challenge. When you implement your custom user interface for challenges, you must ensure that the player has the option to not issue a challenge. Even when a player issues a challenge, the player needs to be in control of who receives the challenge and what message is displayed to those players. Ideally, your game should provide default behavior that matches a player s expectations. The default message and list of players should be reasonable choices that a player might make. For example, when a player wants to issue a score challenge, your first impulse might be to include all of a player s friends in the challenge. In practice, that may not be the best answer. Some of the player s friends may have already earned much higher scores. Instead, consider something like the algorithm in Retrieving the list of players with lower scores than the one just earned. It searches the leaderboard using a friends-only filter. The resulting friends list is then filtered so that only players who have not earned as high of a score are challenged. Listing 4-4 Retrieving the list of players with lower scores than the one just earned - (void) challengelessermortalsforscore: (int64_t) playerscore inleaderboard: (NSString*) leaderboard { GKLeaderboard *query = [[GKLeaderboard alloc] init]; query.leaderboardidentifier = leaderboard; 57

58 Leaderboards, Achievements, and Challenges Challenges query.playerscope = GKLeaderboardPlayerScopeFriendsOnly; query.range = NSMakeRange(1,100); [query loadscoreswithcompletionhandler:^(nsarray *scores, NSError *error) { NSPredicate *filter = [NSPredicate predicatewithformat:@"value < %qi",playerscore]; } }]; NSArray *lesserscores = [scores filteredarrayusingpredicate:filter]; [self presentchallengewithpreselectedscores: lesserscores]; Your challenge view controller can then use the score data to populate its user interface. For example, it can use the player identifiers embedded in the score to load the name and photo of each challenged player. You can perform a similar operation for achievement challenges using the selectchallengeableplayers:withcompletionhandler: class method. Determining the list of players who can complete an achievement challenge shows a possible implementation of this. Listing 4-5 Determining the list of players who can complete an achievement challenge - (void) challengeplayerstocompleteachievement: (GKAchievement*) achievement { [achievement selectchallengeableplayers:[gklocalplayer localplayer].friends withcompletionhandler:^(nsarray *challengeableplayeri, NSError *error) { } }]; if (challengeableplayers) { } [self presentchallengewithpreselectedplayers: challengeableplayers]; 58

59 Saving A Game Saving and sharing game data between ios devices can be difficult. Current icloud strategies do not provide developers with a good solution to saving game data between devices. Whether requiring developers to implement several different APIs or limiting the amount of information they can save, current icloud strategies do not provide developers with a viable solution. To provide saved game data between devices, developers need to create their own solutions, either using their own servers or using a secondary service, such as Facebook. Using the new saved game methods found in GKSavedGame, GKLocalPlayer, and GKSavedGameListener classes, developers can easily save game data to icloud. General information about saved games Currently, the saved game API is best used for single-player games or a pass-and-play game on a single device. Only the local player is required to save the game and any device can be used to retrieve the saved game information. Turn-based games already have a saved state as the turn is passed from one player to another and real-time games require all players to be present any time the game is played and only a single player can save the game. When implementing saved games in your app, you must keep the following information in mind: The player must have an icloud account to save games No specific limit on the amount of data that can be saved Game won t be saved if there is no room in the player s icloud account The app controls how and what data is saved Saved games are tied to the icloud account, not the Game Center account Table 5-1 shows the common properties used by a GKSavedGame object. Table 5-1 Property Common saved game properties Description devicename modificationdate The name of the device that created the saved game file. The date the saved game file was last modified. 59

60 Saving A Game icloud Requirements Property name Description The name of the saved game file. icloud Requirements Saving games using the saved game APIs requires the user to have an icloud account. Using icloud provides users with a way to save a game from any device that has an Internet connection. Along with providing the ability to save games from anywhere, icloud provides users with the ability to save large data files. The size of a saved game file is limited to the amount of space in the users icloud account. However, you should always strive to minimize the amount of data being saved. This prevents the user from running out of space and decreases the amount of time required to fetch or save a game file. Saving a Game Today s games are played on multiple devices depending on where the user happens to be. Whether they are at home playing on their imac, sitting in front of a television with their ipad, or on a bus with their iphone, a player wants to continue playing a game from the last place they left off and not have to worry about which device they were playing on. Including the ability to save and retrieve saved games greatly increases the playability of your game. Saving the game data It is up to you to decide how and when users can save a game. If you want your player s to consider each action before performing that action, then you might want to only allow a single saved game file. However, if you don t mind your players going back and trying different actions, then allow the player to name and create several different saved game files. In either case, it is up to you to create a save game mechanism for your app. After the player creates a new saved game file, use the savegamedata:withname:completionhandler: method to save the game data to icloud. If there is already a saved game object with the same name, the new saved game data overwrites the old saved game data. Otherwise a new GKSavedGame object is created and saved. 60

61 Saving A Game Retrieving a saved game Retrieving a saved game Players want to continue to play games they have saved, whether they saved the game on their current device or another device. To retrieve the list of games the player has saved from a device, your app calls the fetchsavedgameswithcompletionhandler: method to retrieve the list of games for the player. This method returns a list of GKSavedGame objects that contains the identifying information for each saved game. Before presenting the list of saved games to the player, you must ensure that none of the saved games have the same name. If more than one saved game has the same name, you must resolve the name conflict before you present the list of saved games to the player. After you have resolved any conflicts, present the list of saved games to the player, if applicable. The player then selects the saved game file they wish to continue playing. Call the loaddatawithcompletionhandler: method to retrieve the data associated with the GKSavedGame object chosen by the player. Conflicting saved games With users having multiple devices, it is not unusual for a player to be playing the same game on different devices at the same time. Because of this, it is possible to have multiple saved games with the same name and from different devices. It is up to your app to find any conflicting games and fix the conflict. After determining that there is a conflict between saved games, you need to create an array containing only the GKSavedGame objects for the conflicting games. You then send the array to the resolveconflictingsavedgames:withdata:completionhandler: method. This method resolves any saved game conflicts and modifies the array so that it does not contain any saved game conflicts. 61

62 Matchmaking Overview In Game Center, a match is formed when a group of players want to play a game together. Each player plays the game on their own device, and the experience on each device is tailored to the player playing on that device with the match as a whole representing a shared experience. To accomplish this, the instances of the game share data with each other so that there is agreement about the state of the match. Game Center matchmaking provides the infrastructure needed to allow players to find other players interested in playing in a match. It allows players to invite specific players almost always a friend or to simply find other players looking for a match in your game. Once those players have been discovered and formed into a match, Game Center makes it easy for you to implement the networking code needed for your game. When necessary, Game Kit routes network data through Game Center s servers so that all of the match s participants are connected to each other, regardless of where they are or what kind of network they are on. Matchmaking on Game Center is a complex topic, as there are many kinds of matches you can create and many ways to create them. This chapter provides an overview of the process. The chapters that follow provide details on the specific kinds of matches that Game Center offers. Game Center Supports Multiple Kinds of Matches Table 6-1 lists the different kinds of matches supported by Game Center matchmaking. Each kind of match has different restrictions and capabilities. Table 6-1 Match Type Real-time Game Center match types Description All of the players are connected to Game Center simultaneously and for the duration of the match. Game Kit provides all of the low-level networking support for a real-time match in the GKMatch class. Your game implements its own logic to sit on top of this networking infrastructure. Although intended for real-time games, it is usable for any game that requires the players to be connected simultaneously. 62

63 Matchmaking Overview Game Center Provides Multiple Ways to Connect Players into a Match Match Type Turn-based Self-hosted Description The state of the match is stored on Game Center s servers. It is transmitted to the participants when needed. The participants of the match are not connected to each other, and are connected to Game Center only when they want to read or write the match data. When a player takes a turn, his instance of the game updates the match data stored on Game Center. Game Kit provides support for this match type in the GKTurnBasedMatch class. A networking implementation provided by your game and your own servers. When you create a hosted match, Game Center helps you find players for your match (matchmaking), but relies on your game to implement its own low-level networking code. It is primarily intended for games that already have existing network implementations. Game Center Provides Multiple Ways to Connect Players into a Match Game Center makes it as easy as possible for your game to connect players into a match: Your game can present the standard matchmaking user interface. This interface allows players to invite friends to the match or to allow the remaining empty slots to be filled by other players searching for a match. Your game can programmatically invite players or search for other waiting players. In this case, you are responsible for implementing your own matchmaking user interface to give the player control over this process. You typically use this approach when you want to add your own steps to the matchmaking process or when you want the matchmaking user interface to fit with your game s artistic style. A player can use the Game Center app to create a match with another player. A player can be invited to join a match even when a game is not launched on that player s device. When a player is sent an invitation, a push notification is sent to that player s device. When the player accepts the invitation, the game is launched immediately to handle the invitation. This behavior is important because it increases the likelihood of players playing your game. In fact, a player can be invited to play in a match for a game he or she does not own. In this case, the player is immediately offered an opportunity to purchase and download your game. 63

64 Matchmaking Overview Matchmaking and Gameplay Are Separate Tasks Matchmaking and Gameplay Are Separate Tasks Finding players for a match is a distinct behavior that is different from actually playing a match. In most circumstances, matchmaking and gameplay occur at different times. The typical behavior for most games is to first create a match and then to play the match. However, other scenarios are possible: For a real-time match, it is possible for a match to already exist even while you search for more players. In this case, the match exists simultaneously with the matchmaking process, which means that match participants can exchange data while additional players are discovered. For a turn-based match, matchmaking does not need to be complete before a match starts. Instead, whenever a new player is needed to continue the match, matchmaking automatically executes to fill that position. You Can Match Across Different Versions of Your Game In itunes Connect, you can provide compatibility information that describes which versions of your game can see each other during the matchmaking process. Each compatible group of devices and versions of your game are matched as separate groups. The ability to create these matchmaking groups is quite flexible: When you create a new version of a game (such as a bug fix), you can declare whether the new version is compatible with the older versions (and which ones, specifically). You can create distinct games (with different bundle identifiers) and still allow them to play against each other. You can create distinct games on both OS X and ios and match them against each other. Important: In each of these cases, all that itunes Connect and Game Center provides is the ability to create these larger matching groups across versions and products. Game Center itself does not provide any special code to make your games compatible. When implementing your code, you are responsible for ensuring that the network data exchanged between the participants can be interpreted properly by all of the devices and versions of your game. For example, if you introduce a new version of your game with a different network data format or a significant change in behavior, you need to ensure this version is not matched with incompatible game versions. For more information on configuring multiplayer compatibility, see Distributing Game Center Apps. 64

65 Matchmaking Overview Creating Any Kind of Match Starts with a Match Request Creating Any Kind of Match Starts with a Match Request All new matches start with a match request that describes the desired parameters for the match. Essentially, the match request tells Game Center how many players to find and which players to find for the match. Game Kit also uses the match request to customize its matchmaking behavior. For example, when your game displays the standard matchmaking interface, the request is used to customize the screen s appearance. The way that Game Kit and Game Center use match requests is described in later chapters for each type of match. However, because all of the matches share a common infrastructure, you need to understand how to create and configure a match request before reading other chapters. When designing your game s match infrastructure, start by implementing the basic support for matchmaking and get your network game working. Then, consider adding some of the more advanced features. The match request is defined in Game Kit by the GKMatchRequest class. Table 6-2 lists the properties of a match request. Table 6-2 Property Important match request properties Description minplayers maxplayers defaultnumber- OfPlayers recipients invitemessage playergroup The minimum number of players to find for the match. This property must be set on every match request. See A Match Request Must Specify the Number of Players in the Match (page 66). The maximum number of players to find for the match. This property must be set on every match request. See A Match Request Must Specify the Number of Players in the Match (page 66). The default number of players to find for the match. This is used to configure the default user interface to show the appropriate number of player slots. However, the player can add or subtract slots so long as the number of players stays between the minimum and maximum number of players, inclusive. An optional property that declares a list of player IDs for a set of players to invite to the match. See Inviting a List of Players (page 66). If you are inviting a set of players to the match, you can provide a custom string message that is displayed to those players. Typically, you provide the player an opportunity to create this string in your custom user interface, then use the string provided to populate your match request. An optional property that allows you to create distinct subsets of players in your game. Each subset is matched separately against each other. Use these subsets to allow players to provide more information about exactly what kind of match they are looking for. See Player Groups (page 67). 65

66 Matchmaking Overview Creating Any Kind of Match Starts with a Match Request Property playerattributes Description An optional property that allows you to specify a distinct role the player wants to play in the match. Use player attributes to allow players to define what or how they want to play your game. See Player Attributes (page 67). 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 (page 65) lists the current maximum; this maximum is subject to change. Table 6-3 Match Type Maximum number of players for each kind of match Maximum Number of Players Peer-to-Peer Hosted Turn-based 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: 66

67 Matchmaking Overview Creating Any Kind of Match Starts with a Match Request 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. 67

68 Matchmaking Overview Creating Any Kind of Match Starts with a Match Request 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; 68

69 Matchmaking Overview Creating Any Kind of Match Starts with a Match Request 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 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 a player is added 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, 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 0xFF #define MyRole_Cleric 0x00FF0000 #define MyRole_Wizard 0x0000FF00 69

70 Matchmaking Overview Creating Any Kind of Match Starts with a Match Request #define MyRole_Thief 0x000000FF None of the role masks overlap; if any two masks are joined by AND, the resulting value is always h. 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 they want to play the black pieces, the white pieces, or they don t care what color they start with. Listing 6-3 (page 70) provides an example set of masks for this design. Listing 6-3 Creating the masks for chess #define MyRole_Black #define MyRole_White 0xFFFF0000 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 70

71 Matchmaking Overview Creating Any Kind of Match Starts with a Match Request Two players that do not care which color their pieces are Figure 6-1 Possible mask combinations 71

72 Real-Time Matches In a real-time match, the players are connected to Game Center (and thus to each other) simultaneously. This form of match is suitable for implementing any type of game that requires live participation. A key advantage of real-time matches is that Game Kit and Game Center provide extensive support for real-time matches, which simplifies the code you need to write. In particular, it solves many of the problems when trying to find players to join into a match, it provides a high-level networking interface that lets you ignore many of the problems of the underlying networking layer, and it provides extensive built-in support for voice chat. Game Kit allows you to focus on implementing your game without worrying about the precise mechanics of how game and voice data are delivered. However, even though Game Kit solves many of these problems, your game design still needs to be prepared to deal with complex issues that arise from real-time networking, including: The need for multiple instances of your game (running on different devices) to perform tasks simultaneously or near simultaneously, while synchronizing states between the devices Network reliability Network latency Implementing a real-time match requires extensive work designing, implementing, and testing your game. Checklist for Adding Real-Time Matchmaking to Your Game The checklist for creating a game that supports real-time matches is more extensive than that for other Game Center technologies and comprises three main areas: matchmaking, data exchange, and voice chat. As part of this process, you also have many design decisions to make about how matches are played in your game, including: How many players can play at once What does a network version of your game looks like What data needs to be shared to build your design These and other questions impact the design of your gameplay and networking code. 72

73 Real-Time Matches Checklist for Adding Real-Time Matchmaking to Your Game Getting Started The following tasks must be performed before starting your matchmaking implementation: If your app is an OS X app, you must add the following entitlements or all real-time functionality fails: com.apple.security.network.client com.apple.security.network.server Add code to your game to authenticate the local player. See Working with Players in Game Center (page 27). Familiarize yourself with the matchmaking concepts described in Matchmaking Overview (page 62) as well as the contents of this chapter. Finding Players for a Match Determine whether your game will use the standard matchmaking interface, display a custom matchmaking interface, or use a combination of both. Regardless of which implementation you choose, you must support the chosen implementation behavior inside your game as well as add support for handling invitations received from outside of your game. If you are implementing the standard user interface, see Using the Standard Matchmaking User Interface (page 76). If you are implementing a custom user interface, see Implementing a Custom Match User Interface (page 77). Exchanging Data Between Match Participants This is the most complex step of the process as it requires you to perform extensive design work for both the game mechanics for a real-time match and the low-level details of synchronizing communication between the participants of the match. Design the network messages your game uses to communicate with other participants in the match. Most games exchange information at the start of the match to provide each participant the same initial game state, and then send updates as events occur within the game. See Designing Your Network Game (page 80). Write code to use the match object to send data to other match participants. Your game encodes the game state into binary data and uses the match object to transmit it to other players. See Sending Data to Other Players (page 83). Implement a match delegate to handle events that can occur during the match: The delegate is notified when other players are connected at the start of the game. Your delegate usually waits until everyone is connected before starting the game. See Starting the Match (page 82). 73

74 Real-Time Matches Checklist for Adding Real-Time Matchmaking to Your Game The delegate receives the data that other players send. Your delegate reverses the procedure used to send the data by decoding and acting on the data from the other players. See Receiving Data from Other Players (page 83). If players get disconnected while your game is running, the delegate receives a notification and must decide whether to discontinue the match or reconfigure your game to handle the reduced number of players. See Disconnecting from a Match (page 83). Adding Voice Chat to a Match Voice chat support is optional, but can take a good game and turn it into a great game. It allows the players a closer and more natural level of interaction. Here are the steps for implementing voice chat in your game: Decide how many voice channels your game needs. For example, a free-for-all match can use a single channel for all participants while a match with multiple teams might use a separate channel for each team and an additional channel that includes all players in the game. If your game is running in ios, configure an audio session to enable the microphone. All games that record or play audio must have an audio session. See Creating an Audio Session (ios only) (page 84). Create the voice channel by calling the match object s voicechatwithname: method. The match returns a GKVoiceChat object. See Creating Voice Channels (page 84). Call the voice chat object s start method to activate the channel. See Starting and Stopping Voice Chat (page 84). Enable the microphone for a chat channel when a player needs to speak into it. Each participant can speak into only one channel at a time. See Enabling and Disabling the Microphone (page 85). Provide controls in your game that allow the user to enable and disable voice chat, set volume levels or mute players within a channel. See Controlling the Volume of a Voice Chat (page 85). Decide whether your game should support a push-to-talk model or whether it should continuously sample the microphone. In a push-to-talk game, provide a control that the player presses to transmit voice data to other players. In a game that continuously samples the microphone, provide a control to mute the microphone. Implement an update handler that is called when a player connects or disconnects, or when a player starts or stops speaking. Typically, you use this handler to update your game s user interface to display up to date information for each player in the voice chat for example, highlighting a user interface item when a player is speaking. See Seeing When a Player s State Changes (page 85). 74

75 Real-Time Matches Overview of Real-Time Matches in Game Center Overview of Real-Time Matches in Game Center Table 7-1 lists the classes you use when designing a game that uses real-time matches in Game Center. Table 7-1 Class Classes used to implement real-time matches Description GKMatchRequest GKMatchmaker GKInvite GKMatchmakerView- Controller GKMatch GKVoiceChat A match request object specifies the properties of the match to be created. See Creating Any Kind of Match Starts with a Match Request (page 65). This singleton is used by all games that support real-time matchmaking. A game must provide an invitation handler to the matchmaker object so that push notifications that launch the game are handled promptly. Optionally, a game that wants to create a custom matchmaking user interface uses the matchmaker to programmatically search for matches. Delivered when a player accepts an invitation to play in a match. A view controller class that displays the standard matchmaking user interface. The default user interface allows players to add friends to the match, search for other players connected to Game Center, or even find players that are physically in close proximity to each other, even if they do not currently have a connection to Game Center. This object, which is returned to your game, holds information about the players in the match. Each instance of your game uses its own GKMatch object to communicate with other players in the match. Returned by the match object and represents a specific voice channel players can communicate over. Finding Players for a Match When a player wants to create a match, your game must display a user interface to allow the player to see and configure the state of the match. The simplest way to implement this is to use the standard user interface provided by the GKMatchmakerViewController class. It implements many common matchmaking scenarios with a small investment in code. However, if you want to implement your own custom behavior, you can design your own custom user interface and then call the GKMatchmaker class to perform this task programmatically. The matchmaker class returns data to your game so that it can update its own user interface. 75

76 Real-Time Matches Finding Players for a Match Using the Standard Matchmaking User Interface The standard matchmaking user interface is often displayed in response to the user tapping a button on your game s title screen. It can appear immediately after the button is tapped or after several interim screens between the title screen and the matchmaking screen. For example, if your match request includes player groups or player attributes, you usually have your own custom user interface screen to configure the match request before displaying the default matchmaking user interface. Presenting the Matchmaking User Interface Create and configure a new match request and initialize a new GKMatchmakerViewController object using the match request. The presenting view controller makes itself the matchmaking view controller s delegate and then presents the matchmaking interface over itself. The player interacts with the matchmaking screen until the match is ready to start or an error occurs. As the delegate, your view controller (or some other class) must implement a few methods to respond to events. Each of these methods dismisses the view controller, and then performs any specific actions required for your game. The matchmakerviewcontrollerwascancelled: delegate method is called when the player cancels the matchmaking process before a match has been created. Typically, your game dismisses the view controller and then backs out to the title screen (or some other reasonable user interface screen). The matchmakerviewcontroller:didfailwitherror: delegate method is called when matchmaking encounters an error while trying to set up the match for example, when a device loses its network connection. Similar to when the player cancels the matchmaking process, your game dismisses the view controller and moves to a previous screen. Finally, if a match has been created and everyone is ready to start, your delegate s matchmakerviewcontroller:didfindmatch: method is called. This method returns a GKMatch object to your game. Typically, when the match starts, the match is returned to all of the participants, so this delegate method is called on multiple devices at the same time. Processing Invitations from Other Players When a player accepts an invitation from another player, your game is launched (if necessary) and an invitation is delivered to your game. Your game receives this invitation by registering a listener to the local player. Create a class that implements the GKLocalPlayerListener protocol. Inside of your class, implement the player:didacceptinvite: method to handle the invitation. 76

77 Real-Time Matches Finding Players for a Match Adding Players to an Existing Match Occasionally, a match may drop below the number of players your game requires. For example, this situation can occur if a player loses their network connection. In this case, instead of disbanding the match entirely, you might want to add additional players. To implement this in your game, create and present a matchmaker view controller just as you did in the default case. You only do this from one device already participating in the match. After presenting the view controller, call the view controller s addplayerstomatch: method, passing in the match to add the players to. The match interface uses the information in the match request to add players to the existing match, rather than creating a new match. The match object is still returned to your delegate s matchmakerviewcontroller:didfindmatch: method. The match is still active while the matchmaking screen is displayed; the devices in the match can still exchange data with each other. However, you might need to pause the actual gameplay until a new player is found. Because the match is active, voice chat channels continue to work. Implementing a Custom Match User Interface Implementing a complete custom match interface can be as simple as displaying a network progress indicator until auto-matching completes, or as sophisticated as implementing a complete custom view controller that replicates the standard behavior. The latter is potentially a significant investment in programming time, as it needs to include support for all of the following: Inviting specific players into a match Listening for responses from invited players Looking for nearby players (available via Wi-Fi or Bluetooth) This section starts with the simplest scenario finding a match with no user-interface implementation and then builds to more detailed concepts needed to build your own user interface. Auto-matching to Fill a Match The simplest interface your game can provide is an instant match button. When this button is pressed, the player is added to a match without needing to enter any additional information. Create your own method that contains a GKMatchRequest. Retrieve the matchmaker singleton object and ask it to find a match for the player using the findmatchforrequest:withcompletionhandler: method. The match s completion handler is called when a match is found or if an error occurs. If a match is returned to the completion handler, the match is assigned to a property. As before, your game executes code to determine whether the match is ready to begin. 77

78 Real-Time Matches Finding Players for a Match You can also add players to an existing match. Instead of calling the findmatchforrequest:withcompletionhandler: method, your game calls the addplayerstomatch:matchrequest:completionhandler: method, passing in the match to add the players to. Canceling a Search The matchmaking process takes time and may not complete quickly enough for some players. If your game includes support for programmatic matching, it needs to provide a user interface that allows the player to cancel an active search. Call the cancel method on the matchmaker singleton object to cancel an active search. Inviting Specific Players to a Match If you are implementing a complete custom user interface, you need to allow players to invite their friends to a match. Typically, this means that your game presents an interface that shows all the players currently in the match, with empty slots for positions to be filled. A player can then pick one or more of those empty slots and issue an invitation to a specific player. To accomplish this, your game needs to be able to send the invitations and receive notifications when the invitations are processed. You handle both of these problems by assigning more information to the match request. Assign the list of players to the recipients property and implement the block statement for the recipientresponsehandler property. When a response is received, if the response is equal to GKInviteeResponseAccepted, the player is added to the match. Update the user interface to show that this player is now part of the match. If any other response is received, the player is removed from the user interface so that the slot appears empty again. When a match request includes a list of player objects, then the matchmaking behavior changes (regardless of whether you are creating a new match or adding players to a specific match). The normal process of finding players for the match is suspended. Instead, the only thing the matchmaking code does is extend the invitations to the players in the match request and wait for responses. Assuming your game does not cancel the matchmaking process, it completes and returns a match to your game when all the invitations are processed. Because some of the invitations may not be accepted, it is possible you may receive a match that still needs more players. With this in mind, your custom user interface should implement the following behavior: The first time the player invites players to join the match, create the match request with those players and call the findmatchforrequest:withcompletionhandler: method. Wait for the match to be returned (or cancel the request if the player cancels the invitations). 78

79 Real-Time Matches Finding Players for a Match If the player wants to add more players to the match after the invitations are processed, perform the same procedure again, but call the addplayerstomatch:matchrequest:completionhandler: method instead. If the player wants to automatch the remaining slots, create a match request but do not include a list of players to invite. Call the addplayerstomatch:matchrequest:completionhandler: method to fill the remaining slots. You must wait until all invited players have connected as all pending match requests are cancelled when automatching the remaining player slots. If the player wants to start the match with the players already in the match, call the finishmatchmakingformatch: method to end matchmaking entirely. If you want to create a match that contains both invited players and automatched players, you must first create the match with the invited players. After all invited players have connected, you can then add players through automatching. Searching for Nearby Players The standard user interface allows players to discover other nearby players, even when neither player is currently connected to Game Center directly. The discovery uses local Wi-Fi or Bluetooth to find other players. This capability is very useful when players are away from their normal network but still want to play against each other. You can implement similar behavior in your custom user interface. Here s how you typically implement this behavior: 1. Provide a button in your user interface to allow the player to search for nearby players. When pressed, this button presents a new user interface screen that displays any nearby players it finds. Alternatively, your user interface can simply display nearby players automatically. If you choose this approach, it usually makes sense to keep this player list separated from the rest of the user interface. 2. Call the shared matchmaker s startbrowsingfornearbyplayerswithreachablehandler: method, passing in a block to receive notifications of players as they enter and leave the area. When a player is found, add the player to your visible list of players. When a player disappears, remove the player. 3. If the player selects one or more players to send an invitation to, create a match request and add the player identifiers for those players to the match request. Then, follow the behavior described in Inviting Specific Players to a Match (page 78). 4. When your browsing screen is removed from the screen (either because the player canceled browsing or because he or she invited players already) call the stopbrowsingfornearbyplayers method. 79

80 Real-Time Matches Exchanging Data Between Match Participants Finding Player Activity in Your Game Players who are looking for a multiplayer match often want to be matched immediately, or at least be aware of when matchmaking may take longer. For example, if a player is online during a period of time when players are not regularly online, the number of players who are interested in joining a match may be substantially smaller than during prime time. The determination of how many players are online is referred to as player activity. The GKMatchmaker class provides the queryactivitywithcompletionhandler: and queryplayergroupactivity:withcompletionhandler: methods to test for activity on Game Center related to your game. The value returned by either method is the number of players who have recently requested a match. Exchanging Data Between Match Participants After you have created your match, the participants in the match need to exchange data to synchronize the state of the match between each other. This section describes how to implement and design this part of your matchmaking code. Designing Your Network Game Each participant in the match relies on a GKMatch object to exchange data with the other participants connected to the match. The GKMatch class does not define the format or content of your network messages. Instead, it simply sees your messages as bytes to transmit. This gives you great flexibility in designing your network game. The rest of this section describes key concepts you need to understand before implementing your network game. Whenever you send data to other participants, you decide how much effort the match should use to send the data. Matches can send your data reliably, which means the match retransmits the data until it is received by the target(s), or unreliably, which means it sends the data only once. A reliable transmission is simpler, but potentially slower; a slow or error-prone network may require the device to send the message multiple times before it is successfully delivered to its intended recipients. A match also guarantees that multiple reliable messages sent from one device to the same recipient are delivered in the order they were sent. Messages transmitted unreliably may never reach their destination or may be delivered out of order. Unreliable transmissions are most useful for real-time transactions where any delay in transmission caused by using reliable messaging invalidates the contents of the message. For example, if your game transmits position and velocity information for a dead-reckoning algorithm, reliable messages might provide positioning data that is badly out of date by the time it is delivered to the recipient. By using unreliable messages, messages are delivered faster. Your game takes responsibility for network errors by sending new messages with updated position and reckoning information. 80

81 Real-Time Matches Exchanging Data Between Match Participants The size of your messages also plays an important role in how quickly the data can be delivered to its targets. Large messages must be split into smaller packets (such splitting is called fragmentation) and reassembled by each target. Each of these smaller packets might be lost during transmission or delivered out of order. Large messages should be sent reliably, so that Game Kit can handle the fragmentation and assembly. However, the process of resending and assembly takes time. You should not use reliable transmissions to send large amounts of real-time data. Be mindful that your network data is being transmitted across servers and routers that are out of your control. Your messages are subject to inspection and modification by other devices on the network. When your game on one device receives network data from participants on other devices, it should treat that message as untrusted data, and validate its contents before using it. See Secure Coding Guide for information on how to avoid security vulnerabilities. Here are some general guidelines to follow when designing your game s networking: Your message format needs to include a way to differentiate between message types. The GKMatch class does not know anything about the contents of your messages, so you must implement that functionality in your game. For example, you might create an enumerated type that identifies different kinds of messages, and start each message with that enumerated type. Send messages at the lowest frequency that allows your game to function well. Your game s graphics engine may be running at 30 to 60 frames per second, but your networking code can send updates much less frequently. Use the smallest message format that gets the job done. Messages that are sent frequently or messages that must be received quickly by other participants should be carefully scrutinized to ensure that no unnecessary data is being sent. Pack your data into the smallest representation you can without losing valuable information. For example, an integer in your program may use 32 or 64 bits to store its data. If the value stored in the integer is always in the range 1 through 10, you can store it in your network message in only 4 bits. Limit the size of unreliable messages to 1000 bytes or smaller. Limit the size of reliable messages to 87 kilobytes or smaller. Send messages only to the participants that need the information contained in the message. For example, if your game has two different teams, team-related messages should be sent only to the members of the same team. Sending data to all participants in the match uses up networking bandwidth for little gain. Although the GKMatch object creates a full peer-to-peer connection between all the participants, you can reduce the network traffic by layering a ring or client-server networking architecture on top of it. Figure 7-1 shows three possible network topologies for a four-player game. On the left, a peer-to-peer game has 12 connections between the various devices. However, you could layer a client-server architecture on top of this by nominating one of the devices to act as the host. If your game transmits to or from the host only, you can halve the number of connections. A ring architecture allows devices to forward network 81

82 Real-Time Matches Exchanging Data Between Match Participants packets to the next device only, but further reduces the number of connections. Each topology provides different performance characteristics, so you will want to test different models to find one that provides the performance your game requires. Figure 7-1 graphic name Game Network Center topologies Programming Guide Apple, Inc. Specify how to handle network disruptions. Networks are an inherently unreliable medium of communication. A participant can be disconnected at any time while the match is in progress. Your game must handle disconnection messages. For example, if you implemented your game to use a client-server topology, then when the server disconnects from the match, your game might want to nominate a new device to become the new server. Starting the Match When Game Kit delivers a GKMatch object to your game, the connections to other participants in the match may not be established yet. The players array on that user s device can be empty if no other players are connected, or it might hold a subset of players that have already been connected. Your game must wait until all players are connected before starting the match. To determine how many players are waiting to join the match, your game reads the match s expectedplayercount property. When the value of this property reaches 0, all players are connected and the match is ready to start. The appropriate place to perform this check is in the match delegate s match:player:didchangeconnectionstate: method. This method is called whenever a member of the match connects or disconnects. Even before the match starts, all players already connected to the match can already exchange data with each other. This allows your game to create voice channels (or your own user interface) that allows the players already there to communicate with each other. 82

83 Real-Time Matches Adding Voice Chat to a Match Determining the Best Server If you are implementing a client-server architecture on top of the peer-to-peer model provided by the match object, choosing the right server is critical to achieving good network performance and latency in the resulting match. For this reason, Game Kit provides built-in support that allows all the peers in the game to test each other to determine the best server. You implement this by calling the choosebesthostplayerwithcompletionhandler: method. When the operation completes, the player identifier that is returned is the person whose device would make the best server for your game. If you intend to search for the best server using this method, all devices in the match must be running on versions of Game Kit that support this method, and every device in the match must call this method at the same time. This allows all the devices to test and communicate with each other simultaneously. Typically, you find the best server after everyone is connected and gameplay is ready to start. Sending Data to Other Players To send data from one device to other devices connected to the match, your game creates a message and encapsulates it in an NSData object. You send this message to all connected players using the senddatatoallplayers:withdatamode:error: method, or to a subset of the players using the senddata:toplayers:datamode:error: method. Receiving Data from Other Players When the match receives data sent by another participant, the message is delivered by calling your match delegate s match:didreceivedata:fromremoteplayer: method. Your implementation of this method needs to decode the message and act on its contents. Disconnecting from a Match When a player is ready to leave a match, your game calls the match object s disconnect method. A player may also be automatically disconnected if their device does not respond for a certain period of time. When a player disconnects from the match, the other participants in the match are notified by calling the match delegate s match:player:didchangestate: method. Adding Voice Chat to a Match Game Kit provides all of the low-level voice encoding and transmission so that you do not have to handle this yourself. However, any game that supports voice chat should provide its own custom user interface that allows players to configure the voice chat. This means that a player should be able to: Opt-in or out of any voice chat options you provide. 83

84 Real-Time Matches Adding Voice Chat to a Match Mute other players as well as control the overall volume of voice chat. Mute the microphone. Choose which channel he or she speaks into, if your game supports multiple channels. See which player is speaking. Creating an Audio Session (ios only) Before your ios game can use the voice chat services provided by the match object, you must create an audio session that has the capability to both play and record sounds. If your game provides other sound effects, you probably already have an audio session. Note: Your app needs to stop any voice chats currently active after receiving an AVAudioSessionDidBeginInterruptionNotification. You can restart any voice chats after receiving an AVAudioSessionDidEndInterruptionNotification. For more details on creating and using audio sessions, see Audio Session Programming Guide. Creating Voice Channels Your game never directly creates GKVoiceChat objects. Instead, voice chat objects are created on your behalf by the GKMatch object. Create new channels using the voicechatwithname: method. A single match can create multiple channels, and a single player can be assigned to more than one channel at a time. Audio received on any of the channels is mixed together and outputted through the speakers. For multiple participants on different devices to join the same channel, they need a way to identify a particular channel. This identification is accomplished through a channel name. A channel name is a string, defined by your game, that uniquely names the channel. When two or more participants join a channel with the same name, they are automatically connected to a voice chat with each other. Starting and Stopping Voice Chat Voice data is not sent or received through a voice channel until the channel is started. You start a voice chat by calling the voice chat object s start method. After the start method is called, the voice chat object on that device connects to other participants in the channel if the following are true: The device is on a Wi-Fi network. There is a microphone connected to the device. 84

85 Real-Time Matches Adding Voice Chat to a Match If either of these conditions is not met, the voice chat object waits until both are true before connecting to the channel. Similarly, when a player is ready to leave a channel or whenever you want a channel to be temporarily turned off, you call the voice chat object s stop method. An advantage to stopping the channel (rather than simply muting the other players) is that the other players are not required to send data to the player who has left the channel. This decrease in data transmission leaves more bandwidth available for your game s messaging. Enabling and Disabling the Microphone When you want the player to be able to speak, you enable the microphone. Depending on the nature of your game, you may want to enable the microphone continuously while your game is running, or you may want to include a push-to-talk button in your interface. A channel enables the microphone by setting the voice chat object s active property to YES: Only one channel can enable the microphone at a time. When you enable the microphone for one channel, the active property on the previous owner is automatically set to NO. Controlling the Volume of a Voice Chat Your game can control the volume of a voice chat in two ways. First, your game can set the overall volume level for the chat by changing the voice chat object s volume property: The volume property accepts values between 0.0 and 1.0, inclusive. A value of 0.0 mutes the entire channel; a volume of 1.0 outputs voice data at full volume. Second, your game can selectively mute players in a channel. Typically, if your game intends to mute players, it should offer a user interface that allows the player to choose which players they want to mute. To mute a player, you call the voice chat object s setplayer:muted: method and YES. To unmute a player, you make the same call, passing NO instead. Seeing When a Player s State Changes You can implement an update handler when your game wants to be notified about changes in a player s status. The playervoicechatstatedidchangehandler property handler is a block object that the voice chat object calls when a player connects to or disconnects from the channel and when a player starts and stops speaking. For example, you use the update handler to highlight a player s name in your user interface when that player is speaking. 85

86 Hosted Matches Hosted matches allow your game to use Game Center s matchmaking service to find players, but use your own server to connect the players to each other. Hosted matches require you to implement your own custom low-level networking code, because Game Center s servers are not involved in the match play at all. However, hosted games offer larger match sizes and the ability to add your own server into every match. Matching Players for a Hosted Match The code you write for hosted matchmaking is similar to the code you write for real-time matches. Before you attempt to create a game that uses hosted matches, you should already be familiar with real-time matchmaking. The critical difference between the two models is that hosted matchmaking returns player identifiers instead of a completed match object. Your game then connects that player to your own server. Your server must match that player s network address to the player identifier and, similar to a match, perform routing when one device in the match needs to communicate with others. Table 8-1 lists the most common methods for real-time matchmaking and the corresponding methods or implementation details for hosted matchmaking. Table 8-1 Methods to implement hosted matchmaking Real-time matchmaking Your view controller delegate implements the matchmakerviewcontroller: didfindmatch: method to receive the match. Your programmatic matchmaking code calls findmatchforrequest: withcompletionhandler: to create a new match. Hosted matchmaking Your delegate implements the matchmakerviewcontroller: hostedplayerdidaccept: method to receive a notification that a player has accepted an invitation to join the match. Your programmatic code calls findplayersforhostedrequest: withcompletionhandler: to find a set of new players for a match. 86

87 Hosted Matches Hosted Matches Overview Real-time matchmaking Your programmatic code calls addplayerstomatch: matchrequest: completionhandler: to add players to a match. Your game receives an invitation. Hosted matchmaking Your programmatic code calls findplayersforhostedrequest: withcompletionhandler: to find a set of new players for a match. Because you implement your own match architecture, you need to decide when you make this call whether or not you are adding the players to an existing hosted match. The GKInvite object s hosted property tells you whether the match is a hosted match. Typically, this matters only if your game implements both hosted and nonhosted matches. Hosted Matches Overview By default, when you perform the matchmaking process, Game Kit returns an instance of the GKMatch object on each device connected to the match. Each device then uses its match object to communicate with other participants. For most games, this default behavior is exactly what you want. The GKMatch class abstracts the underlying network topology so that your game can simply focus on sending data to other participants without you having to worry about how the data is transmitted. However, some games may want to support more players than the maximum number of supported players on Game Center, or may want their own server to arbitrate the match. In these cases, you can still use matchmaking to find players for a hosted match. A hosted match does not use GKMatch objects. Instead, each copy of your game receives the player identifiers for all of the players in the match. Your game then takes additional steps to connect the players to your server. Creating a hosted match requires your game to implement all of the low-level networking required for your game. In particular, you must do all of the following in your game: Design and implement your own networking code to connect each device to your server. Design and implement your own networking protocol to inform other devices of the state of any participant in the match. Design and implement your own server implementation to map player identifiers to the specific device connected to your server. Thus, your server becomes responsible for routing network data between players. If your game uses Game Kit s standard matchmaking user interface, you must make sure each device informs Game Kit after it connects to your server. This information allows Game Kit to update its user interface. 87

88 Hosted Matches Creating a Hosted Match Using the Matchmaker View Controller Creating a Hosted Match Using the Matchmaker View Controller Create and configure a new match request and then initializes a new GKMatchmakerViewController object using the match request. The presenting view controller makes itself the matchmaking view controller s delegate and then presents the matchmaking interface over itself. The player interacts with the matchmaking screen until the match is ready to start or an error occurs. When the view controller is hosted, your delegate implements the matchmakerviewcontroller:hostedplayerdidaccept: method to process the new player. Your delegate needs to behave differently depending on which device your game is running on: When called on the player s device, the device needs to connect to your own server. When successfully connected, call the sethostedplayer:connected: method to tell the view controller that the player has connected to the match. When called on another player s device, your game needs to determine that it can talk to the new player s device through your server. Once it knows it can send messages to the other client, call the sethostedplayer:connected: method to update the user interface. Dismissing the MatchMaking View Controller After all invitees have accepted your app s match request, you send the information about the players to the server, and then send a start-game message to all of the invitees. When invitees receive the start-game message, they must manually close the view controller for their app. 88

89 Turn-Based Matches In a turn-based match, the players of the match do not need to be simultaneously connected to Game Center to play a match together. Instead, the game uses a store-and-forward approach; one player takes a turn before passing the next play to another player. The players continue to take turns until the match ends with only one player able to make changes to the game at a time. Turn-based matches have many useful characteristics that make them great for implementing board games and other similar styles of games; for example: A player can participate in multiple matches simultaneously. A game loads whichever match the player is interested in viewing or advancing. Players must connect to Game Center only to take a turn. A match can be created with less than a full complement of players, even a single player. Other players are added as needed. In ios 7, exchanges were introduced to turn-based matches. Exchanges allow two or more players to take an action, even when it is not their turn. This allows developers to create more complex and diverse turn-based games than are currently possible by allowing more than just the local player to make changes to the game. Some possible uses for exchanges are: Two players want to trade cards in your game. This can be accomplished during another player s turn. One player wants to auction a card and all players have a chance to bid on the card at the same time. Two players attack each other. They both take turns through exchanges until finished. You can build a game by adding exchanges to the existing turn-based gaming model or create a game solely through the use of exchanges. This chapter first describes how to implement a traditional turn-based match and then adds information about exchanges later. When you implement turn-based matches in your game, the list of players, the data for matches, and other details are all stored on Game Center. Your game downloads this information as needed. Game Center is primarily responsible for storing data. You are responsible for providing the game logic that uses this infrastructure. In particular, you define: What data must be stored on Game Center When the match data needs to be updated 89

90 Turn-Based Matches Checklist for Implementing a Turn-Based Match When play passes to another player Checklist for Implementing a Turn-Based Match To add turn-based support to your game, you write code to handle the following activities: Allow the local player to join a match. See Joining a New Match (page 96). Allow the local player to see the list of existing matches. See Working with Existing Matches (page 98). Allow the local player to view the state of a match in progress. See Working with Match Data (page 100). Allow the player to take a turn in the match. See Advancing the State of the Match (page 101). When a player leaves a match, set the player s match outcome. See Setting the Match Outcome When a Participant Leaves a Match (page 102). When all the players have a match outcome set, end the match. See Ending a Match (page 103). Handle invitations and other match events. See Responding to Match Notifications (page 103). Expand your game to include exchanges. See Adding Exchanges to a Turn-Based Match (page 105). Every Match Has a List of Participants Think of a turn-based match on Game Center as a board game in the middle of a table. Around the table are empty seats, waiting to be filled by potential players. The number of players is set when the match is first created and never changes. When a match begins, only some of the seats may be filled by players. The other seats may be reserved for specific players or to be filled by Game Center s matching service. For example, consider Figure 9-1. Mary has created a new match with four seats. Because Mary created the match, she performs the first turn and then play passes to another player. Figure 9-1 Mary starts a new match 90

91 Turn-Based Matches The Match Data Represents the State of the Match At this point, Game Center sees that this match needs a new player to continue play. When Bob searches for a match, Game Center sees that Bob wants to play the same game as Marry and assigns Bob as a new player of Mary s match. Because this game was waiting on a new player to continue the match, it is now Bob s turn. Game Center always tracks the players of a match in a specific order. That order never changes for the duration of the match, regardless of which device your game is running on. In this example, if Mary is in the first seat (slot), she stays in the first seat for the entire game. Every match has the concept of the current player. The current player changes throughout the match and represents the player whose turn it is to act. When that player finishes taking a turn, your game chooses another player to act. That player is notified that it is now his or her turn and becomes the current player. The Match Data Represents the State of the Match Your game sends to Game Center match data that describes the state of a match. Game Center sets a limit on the size of this match data but otherwise does not care about its contents. Your game should store whatever data is necessary to preserve the match state. 91

92 Turn-Based Matches The Match Data Represents the State of the Match At any time, a player in the match can launch your game to view the match. When a player launches the game, your game loads the match data, interprets it, and displays it to the player. Figure 9-2 graphic name The currentgame player Center wants Programming to view theguide match Apple, Inc. Only the current player is allowed to change the match data. Provide the current player with a user interface that allows them to take actions in the game. As the player takes actions, your game updates the match data graphic name and transmits it back to Game Center. Game Center Programming Guide Apple, Inc. 92

93 Turn-Based Matches Your Game Decides the Rules of Play Your Game Decides the Rules of Play When you design a turn-based game, you create the rules that dictate play. You decide exactly what actions a player is allowed to take and when play passes to another player. When play passes to another player, you decide which player plays next. As an example, consider chess. The player with the white pieces moves first. After white moves, play passes to the player controlling the black pieces. After black makes a move, play passes back to white. The players alternate turns until the match ends in either a checkmate or a stalemate. The rules dictate that play alternates and each player makes a single move each time. The rules that chess uses for players are very consistent, but Game Center allows you to design more flexible games. For example, each time a player takes a turn, you can show them a different user interface screen and present the player with different options for play. A player s turn can be as simple as making a single decision or as complex as choosing what to build, deciding where to send resources, and engaging in combat with another player. Your game tracks the moves a player makes and the moves they are allowed to make as part of your match data. Consider another popular style of strategy game: the 4X game that encourages players to explore, expand, exploit, and exterminate. In this style of game, multiple types of turns are used at different points in the match. Here is one possible way to organize this: At the start of the match, each player takes a starting turn. Play passes sequentially through the entire player list. On a starting turn, a player action consists of naming the player s empire and choosing options for how they intend to play in the match. For example, a common 4X trope is for a player to choose a faction that provides specific advantages and disadvantages during play. After all the players have completed their starting turns, the match begins by allowing players to administrate their empires. On an administrative game turn, each active player takes a turn, and play passes sequentially through the player list. Each participant performs all the actions necessary to control their empire. After all players complete their orders, the administrative turn ends. Your game then executes all the orders simultaneously, usually on the client of the last player to take an administrative turn. If any player units come into conflict, then a conflict game turn is executed; otherwise, a new administrative game turn starts. On a conflict game turn, the game creates a list of all of the players involved in conflicts. Then, each player on the list is given a turn to allow them to give combat orders. After all players give orders, the orders are executed simultaneously and the conflicts are resolved at once. If any players are eliminated as a result of combat, the game takes them out of the match on future turns. If only one player remains active in the match, the match ends and that player is declared the winner. Otherwise, play continues with another administrative game turn. 93

94 Turn-Based Matches Your Game Decides the Rules of Play Figure 9-3 shows how this hypothetical game s logic is processed. It has three distinct kinds of player turns, each with a different user interface, possible user actions, and data to be stored in the match data. Figure 9-3 A turn flowchart for a hypothetical 4X game Whenever a player takes a turn, the match data indicates what type of turn the player takes. After a player takes a turn, their actions are stored in the match data. The design also avoids passing turns to other players for nontrivial reasons. Every player makes multiple decisions at once before passing control to another player. 94

95 Turn-Based Matches Save the Match Data Whenever Important Events Occur When the final player completes a turn, that player s game client processes everyone s turns simultaneously, writing any necessary changes to the match data. Although this kind of design is not required, it keeps the game moving by avoiding small, trivial player turns. Save the Match Data Whenever Important Events Occur The current player s device can save the data to Game Center immediately whenever any action is taken, without transferring control to another player. You should save match data whenever anything interesting happens. Consider the following list as critical places where data should be sent to Game Center: The action should be immediately visible to other players if those players choose to look at the match. The action should be irrevocable, such as when the action reveals information previously hidden from the player or generates a randomized result that needs to be persistent. The action changes the current player. Implementing a Turn-Based Match Using Game Kit To implement turn-based support in your game, you use the classes listed in Table 9-1. Table 9-1 Class Name Classes in Game Kit used to implement turn-based match support Class Function GKTurnBasedMatch GKMatchRequest GKTurnBased- Participant GKTurnBased- MatchmakerView- Controller Describes a turn-based match stored on Game Center. You use this object to inspect the current state of the match and to update the state of the match when the current player takes a turn. Describes the characteristics of a match and may include an initial list of players to invite. Describes a player in a match. Most of its properties are read-only, but the matchoutcome property is not; you assign an outcome to this property when a player leaves a match. Provides a standard user interface that allows the local player to create new matches or view existing matches. 95

96 Turn-Based Matches Implementing a Turn-Based Match Using Game Kit Class Name GKTurnBasedEvent- Handler GKTurnBasedEvent- Listener Class Function Handles events when the player receives an invitation to join a match or a notification that an existing match has been updated. There is a single event handler object provided to you by Game Kit. After the player is authenticated, you assign an event handler to this singleton object. The exact events delivered to your game vary depending upon whether your game is currently the foreground app on the device. When your game is in the foreground, it receives all events related to turn-based matches. If not running in the foreground, your game is launched or brought to the foreground only when important events are received. Handles events for turn-based games. Do not implement this class directly, instead use GKLocalPlayerListener. Game Center Imposes Limits on the Match Table 9-2 describes two of the important limits you need to consider when designing your game. These limits are subject to change and can both be queried at runtime. Table 9-2 Item Important match limits Limit Runtime Access Number of Players Size of Match Data 16 64k Call the maxplayersallowedformatchoftype: class method of the GKMatchRequest class. Read the matchdatamaximumsize property of the GKTurnBasedMatch object. Joining a New Match For players, a new match begins when the player joins a match. As with other forms of matchmaking, your game starts the process by creating a GKMatchRequest object, as described in Creating Any Kind of Match Starts with a Match Request (page 65). A match request does not guarantee that a new match is going to be created; it may also match the player into an existing match that has an empty position as the current player. You can choose to display a standard user interface provided by Game Center or implement your own custom user interface. Regardless of which technique you use, the match returned to your game always has the local player as the current player expected to take a turn. 96

97 Turn-Based Matches Implementing a Turn-Based Match Using Game Kit Showing the Standard Matchmaking User Interface You use a GKTurnBasedMatchmakerViewController object to display the standard user interface. The presenting view controller in this example implements the GKTurnBasedMatchmakerViewControllerDelegate pattern. For matchmaking, you need to handle three of the protocol s methods: The turnbasedmatchmakerviewcontrollerwascancelled: delegate method is called when the player dismisses the matchmaking screen by tapping the Cancel button. In most cases, you should simply return to the previous screen in your game. The turnbasedmatchmakerviewcontroller:didfailwitherror: delegate method is called when matchmaking encounters an error while trying to find the match. For example, the device may have lost its network connection. Your implementation should also return to your game s previous screen. The turnbasedmatchmakerviewcontroller:didfindmatch: method is called when a match has been found or created. The match object is returned to your delegate. Typically, your game dismisses the matchmaker view controller and immediately starts its own user interface to allow the player to play a turn. Implementing a Custom Match Interface To create your own custom match interface, you typically use methods on the GKTurnBasedMatch class. Create a new match request and then find a new match using the findmatchforrequest:withcompletionhandler: method. (Typically, if your game was implementing a custom match interface, it might set other properties of the request object, such as the playerstoinvite property.) If a match is found, transition to the gameplay screen. One common scenario is supported automatically by Game Center. When a match ends, you can call its rematchwithcompletionhandler: instance method to create a new match with the same participants. Handling Invitations Programmatically If a match request includes a list of players to invite, then those players are added to the list of players in the newly created match. However, invitations are not actually delivered until one of those players becomes the current player. When that happens, a push notification is sent to the player. The process for handling notifications is described later in Responding to Match Notifications (page 103). For now, all you need to know is that you can display your own interface that allows the player to accept or decline the match invitation. You call the match object s acceptinvitewithcompletionhandler: method to accept the invitation or its declineinvitewithcompletionhandler: method to decline the invitation. 97

98 Turn-Based Matches Implementing a Turn-Based Match Using Game Kit Working with Existing Matches If you display the standard matchmaking user interface, then the player sees existing matches as well. The player can choose an existing match already in progress and perform other common tasks. If the player picks an existing match, the turnbasedmatchmakerviewcontroller:didfindmatch: method is called, exactly as it was called when a new match was created. Note that in this case, the player may not be the current player. A player can choose to resign from a match from within the standard user interface. Your delegate must implement a turnbasedmatchmakerviewcontroller:playerquitformatch: method to handle a player resignation. Your game must set a match outcome for the resigning player, and if necessary, choose another player to act in the match. For more information, see Setting the Match Outcome When a Participant Leaves a Match (page 102). Table 9-3 lists the most common actions a player might want to perform on a match. Table 9-3 Action Common actions to perform on a match Implementation View a match Delete a completed match Resign from a match End a match for all participants Create a rematch Present your gameplay user interface, using the match object as an input. Call the match object s removewithcompletionhandler: method. Set the player s outcome and then call a method to resign from the match. See Setting the Match Outcome When a Participant Leaves a Match (page 102). Set outcomes for all of the players and then call the match s endmatchinturnwithmatchdata: completionhandler: method. See Ending a Match (page 103). Call the rematchwithcompletionhandler: method on an ended match. Retrieving Information About a Match When a player decides to view a match, your game reads the properties of the match to determine the current state of the match. Table 9-4 lists the most common properties you need to access. 98

99 Turn-Based Matches Implementing a Turn-Based Match Using Game Kit Table 9-4 Property matchid status message Important properties of a match object Description A string that uniquely identifies the match. If you want to store match-specific data elsewhere, use this string as a key. Your game could also save this ID and use it later to load this specific match. To load a specific match, call the loadmatchwithid: withcompletionhandler: class method. States whether the match is still in progress. A text string your game sets to provide a human-readable status for the match. Typically, you update this property before changing the current player. The message is displayed by the standard user interface. If you display a custom interface, you should also display the message. participants currentparticipant An array of GKTurnBasedParticipant objects. The objects in the array are always stored in the same order. You read the properties of participant objects to build your user interface. These objects are also used as inputs to certain methods on the match object. Table 9-5 lists the most common properties used to implement your game. The participant object for the next player expected to act in the match. This object is always one of the objects stored in the participants array. Table 9-5 lists the most common participant properties used to implement your game. Table 9-5 Property playerid status Important properties of a participant object Description The player identifier for the player, assuming this seat is filled. Use it to load display names and photos for the player. Declares whether or not this seat is filled and, if it is, declares whether the player is still active in the match. timeoutdate matchoutcome The time at which the player must act before forfeiting a turn. Your game decides what happens when a turn is forfeited. For some games, a forfeited turn might end the match. For other games, you might choose a reasonable set of default actions for the player, or simply do nothing. When a player leaves a match, this property describes what happened to the player. The player may have won or lost the match. 99

100 Turn-Based Matches Implementing a Turn-Based Match Using Game Kit Working with Match Data When a match is first created, the match data is empty. But once the match begins and players start taking turns, your game is expected to provide match data that makes sense for your game. The match data is an NSData object and its size is limited, so you need to be creative and encode your game s data so that it fills as little space as possible. In general, the match data needs to store enough information so that your game can display the current state of the match. If the player is the current player, then the match data should also store enough data so that your game knows what kind of turn the player may take. Here are a few possible strategies you can follow when designing your match data format: Encode only player actions: In this design, your match data simply consists of the moves made by the players. For example, in chess, you know that white goes first, moves always alternate, and a piece moves from one board position to another. This makes it easy for you to encode each move as the starting and ending position of the piece moved. The rest of the data (who made the moves) can be completely inferred. When your game loads the match data, it quickly replays the moves to generate the current board position. This strategy works best for games with a small number of possible kinds of actions and a small number of moves per match. Also, with this model, it is very possible for your game to replay the moves in its user interface, allowing players to see exactly what moves other opponents made to get the board into the new state. Showing a player these moves makes it very easy for a player to understand how the game got to the current state. Encode only the current state of the match: For very complex games, the actual state required to encode the game could be very large. In this case, you may need to encode the current state of the match without worrying about the actions that generated that match data. This is particularly true for very complex games where the list of moves might grow too large to fit in the available storage space. This strategy is recommended as a last resort. Players lose all context of what happened on previous turns of the match. For games with long timeouts between turns, players may grow bored or frustrated if they cannot remember the state of a match they were playing. This is particularly true when players participate in multiple matches simultaneously. Encode the current state of the match and a set of recent player actions: This is a hybrid strategy that borrows elements from the other two strategies. Essentially, the match data stored on Game Center consists of a recent snapshot of the match plus other data that encodes recent actions since that last snapshot was taken. When the data that records the actions grows too large, your game replays some of those moves to update the match snapshot and then deletes those moves from its list of actions. With this strategy, you typically need to determine which actions the current player has seen (based on when they last took a turn). When your game flattens the match data, it never removes any data that hasn t been seen by all the participants. This allows all participants to see the moves their opponents made. 100

101 Turn-Based Matches Implementing a Turn-Based Match Using Game Kit And here are some other general guidelines: Avoid using the NSCoder class except for the most trivial of games. Although useful for general-purpose apps, the NSCoder class may not archive data in a compact enough format for your game. You cannot precisely predict the size of the archive it produces. Instead, you allocate your own block of memory and perform your own data serialization. Encode individual items as compactly as needed. For example, in a 16-player game, you can encode the participant number of the player in 4 bits. Balance the need for compactness with the need for readability in your code. For example, a chess position could be encoded in as little as 6 bits, but in practice a chess match does not approach the match data limit. If your game runs in both OS X and ios, use network data encoding techniques to avoid byte ordering problems. Loading Match Data When you need to load the match data, you call the match object s loadmatchdatawithcompletionhandler: method to retrieve the match data. When the completion handler is called, you receive the match data. After the operation completes, the match object s matchdata property is also updated to point at the same data object. Saving Match Data If the player takes an action that is irrevocable (but control is not yet passed to another player), encode the updated match data and send it to Game Center by calling the savecurrentturnwithmatchdata:completionhandler: method. Advancing the State of the Match Eventually, the current player takes an action that either ends the match or requires another participant to act. Typically, your game updates the message property of the match object, encodes the match data, and determines who acts next in the match. Usually, this means encoding the list of all participants in the match in the order they will act next. The reason you do this is that sometimes players drop from a match without forfeiting; they just stop playing. You don t want the match to end because it is stuck waiting forever for an absent player. Instead, you encode the list of participants so that if one participant forfeits a turn, the match advances to another participant. Use the endturnwithnextparticipants:turntimeout:matchdata:completionhandler: method to actually pass control to that list of players. 101

102 Turn-Based Matches Implementing a Turn-Based Match Using Game Kit Setting the Match Outcome When a Participant Leaves a Match As the match progresses, participants may leave the match. For example, your game logic might determine that a participant has been eliminated from the match. If the local player resigns from the match and is also the match s current player, your game must call the match object s participantquitinturnwithoutcome:nextparticipants:turntimeout:matchdata:completionhandler: method. This method is similar to the endturnwithnextparticipants:turntimeout:matchdata:completionhandler: method in that it gives control to another participant. Because of this, you are required to update the match data and provide a participant list. However, your game also provides a match outcome for the player that just exited the match essentially, a numerical value that indicates why that player left the match. The participant object for that player is updated to include this new match state. Once a participant has exited the match, your game may not make that player the current player. Game Kit provides some standard values you can use to set the match outcome. See Setting the Match Outcome. For example, in Figure 9-4, Bob has just been eliminated from the match. The game chooses to set an outcome of GKTurnBasedMatchOutcomeFourth and make Mary the new current player. Bob may still view the match, but may not take actions. Figure 9-4 graphic name Bob Game has Center been eliminated Programming from Guide the match Apple, Inc. 102

103 Turn-Based Matches Implementing a Turn-Based Match Using Game Kit Occasionally a player may resign the game when they are not the current player. To handle this, your game calls the match object s participantquitoutofturnwithoutcome:withcompletionhandler: method. You provide a match outcome but do not provide new match data or a participant list. Ending a Match Eventually, your game logic is going to decide that the match is over. All participants in the match must have a valid match outcome before ending the match. Your game calls the match object s endmatchinturnwithmatchdata:completionhandler: method to formally end the match. This method is similar to the other methods that update the match state, but in this case you do not provide a list of participants because no further actions are allowed in this match. You do update the saved match data to describe how the match ended. Players can still select this match from the matchmaking user interface; your game should display the match ending but not allow the player to take actions. Responding to Match Notifications A player can receive notifications about turn-based matches. For example, the most common notification a player receives is when that player becomes the current player for a match (and is expected to take action). In all cases, after a player accepts a notification, your game is called to handle the event. It should process the event and display an appropriate user interface specific to your game. Your game receives turn-based match events by installing an event handler. As with other similar handlers, you almost always install this handler as soon as the local player is authenticated. If your game was launched specifically to handle an event, the event handler is called immediately. 103

104 Turn-Based Matches Implementing a Turn-Based Match Using Game Kit To respond to events, your event handler implements the methods defined by the GKTurnBasedEventHandlerDelegate protocol. Table 9-6 lists the events. Events received via a push notification launch your game or bring your game to the foreground (if necessary) and are then delivered to the game. Foreground events are delivered only if your game was running in the foreground when the event was received. When an event is received, your game should pause what it is doing and display a user interface that allows the player to decide whether to load the notification s match for display. Even if this match is already loaded, you should reload the match s data, because it may have been updated by the event. Table 9-6 Event Turn-based event handler methods Event Type Event Handler Method Player receives an invitation It becomes the player s turn A match ended It becomes someone else s turn A player updated the match data A player receives an exchange request A player cancels an exchange request All players have responded or timed out while responding to an exchange Push Push Push Foreground Foreground Push Push Push handleinvitefromgamecenter: handleturneventformatch: didbecomeactive: handlematchended: handleturneventformatch: didbecomeactive: handleturneventformatch: didbecomeactive: player: receivedexchangerequest: formatch: player: receivedexchangecancellation: formatch: player: receivedexchangereplies: forcompletedexchange: formatch: By default, when your game receives a notification, a badge is added to the game icon. Add GKGameCenterBadgingDisabled to your Info.plist to change this behavior. See Cocoa Keys for details. 104

105 Turn-Based Matches Adding Exchanges to a Turn-Based Match Adding Exchanges to a Turn-Based Match Add exchanges to your game to expand what your game can do. Exchanges allow players other than the current player to affect the current turn. Whether through trading items with another player or directly affecting the current player s turn, exchanges provide for greater flexibility in how you design your game. Anatomy of an Exchange In the basic turn-based match, control of the game moves from player to player, following rules defined by the app. Only the current player can affect the match, with all other players relegated to observing the match. This works very well for certain types of games, but as a game turn becomes more complicated, it is not uncommon for multiple players needing to interact at the same time. Turn-based matches can quickly become bogged down when each player must perform a small action in order for a turn to be completed. Exchanges provide you with a way to create complex turns without slowing down the pace of the match. Using exchanges, you can design your game so that players other than the current player can take actions during a turn. An exchange is an interaction between the exchange initiator and one or more exchange recipients. The following workflow is used for an exchange: The initiator sends an exchange request to a recipient. The recipients is notified that they have received an exchange request. The recipient acts on the exchange request and sends their action back to the initiator. The initiator is notified of the completed exchange. The current player is notified of the completed exchange and updates the match data. 105

106 Turn-Based Matches Adding Exchanges to a Turn-Based Match Sending an Exchange Request Depending on how you design your game, any player can initiate an exchange request, whether they are the current player or not. For example, during Mary s turn, Fred decides that he wants to trade cards with Kelly. Fred chooses the cards he wants to trade to Kelly and what he wants in return. He then sends the exchange request to Kelly. After the request is sent, an update is sent to Mary so that the match can be updated. See Figure 9-5. Figure 9-5 Initializing a trade through an exchange When a player sends an exchange request, several pieces of information are required to successfully send the request. There is no particular order in which this information needs to be collected. For example, your game may ask who the sender wants to trade with before asking which cards to trade, or the sender could choose cards to give and then designate who will receive the cards. The sender chooses whom to send the exchange request to. The nature of the request has to be determined. Is the player asking to trade cards, asking for help in attacking another player, or something else? The amount of time the recipients have to respond to the exchange request must be set. You can allow the sender to choose this or set a hard time limit. The amount of data that you can send is limited to a maximum of 1k. The data must be comprehensive enough that the receiving player s game can act and present the data to the player in a way that makes sense in the context of your game. When the exchange request is sent, using the sendexchangetoparticipants:data:localizablemessagekey:arguments:timeout:completionhandler: method, ensure that the current player also receives the request data so that the current match can be updated. Before any recipients respond to an exchange request, the sender can cancel the request. When the sender cancels an exchange using the cancelwithlocalizablemessagekey:arguments:completionhandler: method, a push notification is sent to all of the recipients telling them that the exchange has been canceled. 106

107 Turn-Based Matches Adding Exchanges to a Turn-Based Match Responding to an Exchange Request After an exchange request is created, the players in the recipients array receive a push notification. Opening the game will present the exchange message. The recipient can choose to respond to the exchange request or let it time out. Figure 9-6 shows Kelly accepting Fred s trade and responding to his exchange request. After the exchange is completed, the exchange result is sent to the current player. The exchange is reconciled at the end of the current player s turn. Figure 9-6 Accepting a trade through an exchange The recipient responds to the exchange request using the replywithlocalizablemessagekey:arguments:data:completionhandler: method and sends any relevant data back to the original sender. Your game also needs to send the results of the exchange to the current player so that they can update the match. 107

108 Testing Your Game Center-Aware Game To help you test your game, Apple provides a nonproduction development environment for Game Center. This development environment duplicates the live functionality of Game Center, but is separate from the live servers. The development environment allows you to test your Game Center features without making your game visible to regular users. You should thoroughly test your game in a development environment before submitting it for approval. 108

109 Testing Your Game Center-Aware Game Testing a Game Center-Aware Game Testing a Game Center-Aware Game Before submitting your game to the App Store, your game can only run in the Game Center sandbox test environment. Use the sandbox test environment to test the Game Center integration of your game. To do this, go to Settings > Game Center and enable the Sandbox option as shown in Figure Then launch your game and sign into Game Center when prompted. If this is the first time you have used your AppleID with the Game Center sandbox, you may need to complete your sandbox Game Center profile. 109

110 Testing Your Game Center-Aware Game Testing a Game Center-Aware Game Figure 10-1 Enabling the sandbox option 110

111 Testing Your Game Center-Aware Game Testing a Game Center-Aware Game Note: When testing in Sandbox mode, Friend Recommendations for Contacts and Facebook are turned off. Trying to turn on Friend Recommendations will cause an error message to appear. Otherwise, enter your live account information (signing you in to the live environment. Table 10-1 shows which builds run in which environments. Important: Always create new test accounts to test your game in Game Center. Never use an existing Apple ID. Table 10-1 Build Different kinds of app builds Audience Game Center Environment Simulator build Developer build Ad hoc distribution build Signed Distribution build Developer Developer Beta testers End users Development environment Development environment Development environment Live environment A development environment does not allow sharing of information about what games are being played. This prevents your testers from revealing the existence of your game to other players. Testing Your Game in ios Simulator Leaderboards and achievements work the same way in ios Simulator as they do on a device. However, matchmaking invitations may not be sent or received while your game is running in ios Simulator. 111

112 Document Revision History This table describes the changes to Game Center Programming Guide. Date Notes Added information on saving games and moved code examples to the appropriate API reference guides Added information on resolving turn-based exchanges Added information about leaderboard sets and exchanges Renamed to Game Center Programming Guide. Removed chapters not related to Game Center apps. Updated to include features added in ios 5 and ios 6. Also updated to include OS X support Added to the OS X Developer Library Revised the process for authenticating the local player. Clarified many aspects of Game Center usage Clarified the requirements for performing server-based matchmaking. Improved the guidelines implementing voice chat in a Game Center application Updated to add Game Center classes Revised to include more conceptual material. 112

113 Document Revision History Date Notes New document that describes how to use GameKit to implement local networking over Bluetooth as well as voice chat services over any network. 113

114 Apple Inc. Copyright 2015 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer or device for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-branded products. Apple Inc. 1 Infinite Loop Cupertino, CA Apple, the Apple logo, Cocoa, imac, ipad, iphone, itunes, Mac, OS X, Sand, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. icloud is a service mark of Apple Inc., registered in the U.S. and other countries. App Store and Mac App Store are service marks of Apple Inc. IOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED AS IS, AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT, ERROR OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. Some jurisdictions do not allow the exclusion of implied warranties or liability, so the above exclusion may not apply to you.