Game Center Programming Guide

Game Center

Contents

About Game Center

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

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

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

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

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

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

General information about saved games 59 iCloud Requirements 60

Saving a Game 60

Saving the game data 60 Retrieving a saved game 61

Matchmaking Overview

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

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

Creating a Hosted Match Using the Matchmaker View Controller 88 Dismissing the MatchMaking View Controller 88

Turn-Based Matches

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

Testing a Game Center-Aware Game 109 Testing Your Game in iOS Simulator 111

Figures, Tables, and Listings

Developing a Game Center-Aware Game

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

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

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

Table 5-1 Common saved game properties 59

Matchmaking Overview

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

Figure 7-1 Network topologies 82

Table 7-1 Classes used to implement real-time matches 75

Hosted Matches

Table 8-1 Methods to implement hosted matchmaking 86

Turn-Based Matches

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

Figure 10-1 Enabling the sandbox option 110 Table 10-1 Different kinds of app builds 111

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.

● _{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.

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

GKGameCenterViewControllerclass 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 theGKNotificationBannerclass 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.

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.

● _{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 readingDeveloping a Game Center-Aware Game (page 14). This chapter describes the process for designing and implementing a game that supports Game Center. Then readDisplaying 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 readWorking 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.

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 . Prerequisites

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.

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}

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.

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 Supporting Game Center in Your User Interface

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.

Table 1-1 Game Center feature summary Assets Limitations Requirements Feature Strings, leaderboard sorting, artwork Maximum number of

leaderboards, formatting options for leaderboard scores

Scoring mechanism Leaderboard Strings, leaderboard grouping, artwork Maximum number of

leaderboards and sets allowed. All apps in a group must either have sets or not have sets. A leaderboard

Leaderboard Sets

Strings, artwork Maximum number of

achievements per game, maximum point allocation. Tracking code to watch

what a player does in the game

Achievements

— —

You must implement either leaderboards or achievements

Challenges

— The player must have an iCloud

account Code to load and save

game information Saving Games

Custom

invitation sound Number of players, size of data

packets, networking Multiplayer game design

Matchmaking

Customizing the Game Center Sounds

You can change the default Game Center sounds usingGKInvite. 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 eithercaf,

aif, orwavformat and be namedGKInviteplus the appropriate file extension. Customizing the Game Center Sounds

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.

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.

● _{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.

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 theGameKit/GameKit.hheader.

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. SeeRequiring 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).

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 thegamekitkey to the list of required device capabilities in your game’sInfo.plistfile. 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 .

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 aGKGameCenterViewController, 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.

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

GKDialogControllerclass. 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 thepresentViewController:method.

Displaying Notification Banners

Creating a banner in your game is accomplished using theGKNotificationBannerclass. 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 theshowBannerWithTitle:message:duration:completionHandler:

method.

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

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 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 aGKPlayerobject. Table 3-1 lists some of the more interesting properties on a player object.

Table 3-1 Important Player Object Properties

Description Property

A string that holds the player identifier string used to retrieve this player information.

playerID

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.

displayName

TheGKLocalPlayerclass is a special subclass of theGKPlayerclass, and includes additional properties specific to the local player:

● _{Theauthenticatedproperty states whether the local player has been authencticated.} ● _{Theunderageproperty states whether this player is underage.}

Table 3-2 Local Player Object Properties

Description Property

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.

authenticated

A Boolean value that states whether the local player is underage. Some Game Center features are disabled when the value of this property isYES; Game Center returns aGKErrorUnderageerror 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.

underage

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 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 theGKLocalPlayerclass and then sets that object’s

authenticateHandlerproperty 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 theauthenticateHandler

property for an example of how to create this method.

Always check theauthenticatedproperty 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 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 thedisplayNameproperty 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’sauthenticated}

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 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 theauthenticatedproperty is valid again.

● _{If the value of theauthenticatedproperty changed toNO, 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 theauthenticatedproperty isYES, 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’splayerIDproperty 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 theGKPlayerclass. 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. 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 theloadPhotoForSize: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

GKFriendRequestComposeViewControllerclass 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. Common Tasks When Working with Players

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.

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. SeeWorking with Players in Game Center (page 27).

2. Design your game’s achievements. SeeDesigning 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. SeeConfiguring 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. SeeReporting 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. SeeLoading 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.

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. SeeChallenges (page 54).

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.

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 Achievement properties

Description Property

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.

Achievement Reference Name

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.

Achievement ID

The points that your achievement is worth. Point Value

Achievements marked as Hidden remain hidden to a player on Game Center until after the first time you report progress for that achievement.

Hidden

Indicates whether the user can earn the achievement multiple times. Achievable More Than

Once

Table 4-2 Achievement language properties

Description Property

The language in which you would like this achievement to appear. Language

The localized title of this achievement as you would like it to appear in Game Center.

Title

The description of your achievement as it appears to a Game Center player before he or she earns it.

Pre-earned Description

The description of your achievement as it appears to a Game Center player after he or she earns it.

Earned Description

A localized image that represents the achievement. The image must be a

.jpeg,.jpg,.tif,.tiff, or.pngfile that is 512 x 512 or 1024 x 1024 pixels, at least 72 dpi, and in the RGB color space. This property is required. Image