You want to learn how to use block objects and Grand Central Dispatch so that you can write Game Center apps in iOS.

Learn the basics of block objects and Grand Central Dispatch here.

All of us, at some point, have used threads. We use threads to separate the paths of execution in our code and to give priority to certain paths of execution over others. A classic example of this is the main UI thread in every iOS application. All iOS developers are encouraged to avoid keeping the UI thread busy for work that is non-UI-related, in order to sustain a responsive user interface. Therefore, all work that is not UI-related can, and indeed should, be executed in separate threads.

With the introduction of multicore mobile devices such as the iPad 2, threads and their management have become more complicated than ever before. Not only should developers know what path of execution is running at any instance, they should also know which core of the processor that path is running on in order to utilize the power of the multicore processor. To simplify matters, Apple made available, to iOS and OS X developers, an excellent set of APIs wrapped in a library named Grand Central Dispatch (GCD). GCD allows developers to simply focus on the code that has to be executed and forget about the dirty work that needs to be carried out in order to balance the work among multiple threads on a device that can have multiple cores.

GCD works with block objects. Block objects are first-class functions, which means, among many other traits, that they can be passed to other methods as parameters and can be returned from methods as return values. Block objects have a syntax that differs from a simple C function or procedure. For instance, a C function that takes two int parameters (call them value1 and value2), adds them up, and returns the sum as an int can be implemented in this way:

int sum (int value1, int value2){
  return value1 + value2;
}

The equivalent of this code written using a block object would be:

int (^sum)(int, int) = ^(int value1, int value2){
  return value1 + value2;
};

Or, for instance, if we were to implement a procedure in C that simply prints out a string to the console, we would write it like this, using the printf procedure:

void printSomestring(void){
  printf("Some string goes here...");
}

The same code can be written using block objects as demonstrated here:

void (^printSomeString)(void) = ^(void){
  printf("Some string goes here...");
};

As mentioned earlier, block objects are first-class functions, and can therefore be passed to methods, procedures, and functions as parameters. For example, the sortUsingComparator: method of instances of NSMutableArray, as we will soon see, accepts block objects that return a value of type NSComparisonResult and take in two parameters each of type id. Here is how you would call that method to sort your array:

NSMutableArray *array = [[NSMutableArray alloc] initWithObjects:
                         @"Item 1", 
                         @"Item 2",
                         @"Item 3",
                         nil];

[array sortUsingComparator:^NSComparisonResult(id obj1, id obj2) {
  /* Sort the array here and return an appropriate value */
  return NSOrderedSame;
}];

[array release];

In addition to passing inline block objects to other methods, it is important that you also learn how to write methods that accept and work with inline block objects passed as parameters. Let’s say we have an Objective-C method, sumOf:plus:, which will take in two parameters of type NSInteger, calculate the sum, and return a 64-bit value of type long long. This Objective-C method itself will then call a block object that will calculate the sum and return the result. Here is how we can implement this:

long long (^sum)(NSInteger, NSInteger) = 
^(NSInteger value1, NSInteger value2){
  
  return (long long)(value1 + value2);
  
};

- (long long) sumOf:(NSInteger)paramValue1
              plust:(NSInteger)paramValue2{
  
  return sum(paramValue1, paramValue2);
  
}

Block objects are executed just like C procedures and functions. In the case of the sum block object that we had before, we can execute it easily as shown here, inside an Objective-C method:

int (^sum)(int, int) = ^(int value1, int value2){
  return value1 + value2;
};

- (int) calculateSumOfTwoNumbersUsingBlockObjects:(int)number1
                                     secondNumber:(int)number2{
  return sum(number1, number2);
}

The calculateSumOfTwoNumbersUsingBlockObjects:secondNumber: Objective-C method calls the sum block object and passes the return value of the block object to the calling code. Are you starting to see how simple block objects are? I suggest that you start writing a few block objects in your Xcode projects to just get used to the syntax. I am quite aware that the syntax of a block object is not exactly desirable as far as Objective-C developers are concerned, but once you learn the power that block objects have to offer, you will most likely forget this difficulty in constructing them and instead focus on the advantages.

One of the most important advantages to block objects is that they can be used inline and, as a result, passed to other methods as parameters. For example, if we want to sort an instance of NSMutableArray in an ascending fashion, we could use the sortUsingComparator: method of the NSMutableArray class as shown here. This method accepts a block object with two parameters and returns a value of type NSComparisonResult. Because sortUsingComparator: accepts a block object as a parameter, we can use it for any kind of data and adjust the sorting method as appropriate.

NSMutableArray *array = [[NSMutableArray alloc] initWithObjects:
                         [NSNumber numberWithInteger:10],
                         [NSNumber numberWithInteger:1],
                         [NSNumber numberWithInteger:20],
                         [NSNumber numberWithInteger:15],
                         nil];

/* Start an ascending sort on the array */
[array sortUsingComparator:^NSComparisonResult(id obj1, id obj2) {
  
  /* By default, let's assume the values are the same */
  NSComparisonResult result = NSOrderedSame;
  
  /* Get the two values as numbers */
  NSNumber *firstNumber = (NSNumber *)obj1;
  NSNumber *secondNumber = (NSNumber *)obj2;
  
  /* If the second number is bigger than the first, we are on
   an ascending trend */
  if ([secondNumber integerValue] > [firstNumber integerValue]){
    result = NSOrderedAscending;
  }
  /* Otherwise, if the second number is smaller than the first number,
   we are on a descending trend */
  else if ([firstNumber integerValue] > [secondNumber integerValue]){
    result = NSOrderedDescending;
  }
  
  return result;
  
}];

NSLog(@"%@", array);

[array release];

The output printed by the NSLog procedure in this example code is:

(
 1,
 10,
 15,
 20
)

Although there’s an even simpler way to sort an array, this example demonstrates the use of block objects and how other classes such as NSMutableArray allow you to pass block objects as parameters to different methods inside that class. The example goes one step further in using block objects as first-class functions that can be used as parameters to other methods.

With GCD, Apple decided block objects were the perfect match for what they wanted to achieve: simplicity in developing multithreaded applications on single or multicore devices. Think of GCD as a controller object. A controller of what, you might ask? A controller of a big pool of threads placed in dispatch queues. Dispatch queues are simply a queue of tasks submitted by the system or by the developer. The tasks will get executed in the threads, as managed by GCD. So when we talk about dispatch queues, just think of a queue of tasks.

At the heart of GCD are some global concurrent queues, which can be accessed using the dispatch_get_global_queue function like so:

dispatch_queue_t dispatchQueue =
  dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_LOW, 0);

The first parameter to the method is the priority of the dispatch queue. The second parameter to the method is reserved and currently should always be set to 0. The higher the priority of the queue, the faster the tasks inside it get executed (ideally). For the first parameter, you can pass any of the following values:

In addition to the global concurrent queues, you can also use the main queue. Each application has at most one main queue. The difference between the main queue and the global concurrent queues is that the main queue always executes your code on the main thread, whereas the global concurrent queues will execute your code, depending on a decision made by the system, on various other threads created and managed by GCD.

In order to retrieve your application’s main queue, you must use the dispatch_get_main_queue function like so:

dispatch_queue_t mainQueue = dispatch_get_main_queue();
/* Dispatch tasks to the queue */

We now know how to get the handle to global concurrent queues and the main queue. The big question is: how do we execute a piece of code on these queues? The answer is simple: use one of the dispatch_ procedures. Here are a few flavors for you:

Fair enough! Let’s give it a go. I want to have three loops, each printing the number sequence 1 to 10, and I want to have all of them run at the same time, asynchronously. When we talk about asynchronous execution of block objects, we know we should be using the dispatch_async procedure:

/* Define our block object */
void (^countFrom1To10)(void) = ^{
  
  NSUInteger counter = 0;
  for (counter = 1;
       counter <= 10;
       counter++){
    NSLog(@"Thread = %@. Counter = %lu",
          [NSThread currentThread],
          (unsigned long)counter);
  }
  
};

The second and final piece of the puzzle is the decision as to which dispatch queue we want our code to be executed on. For this example, we can execute the code on either the main queue (run on the main thread) or better yet, on any one of the global concurrent queues. So let’s go ahead and use a global concurrent queue:

/* Calling this method will execute the block object
 three times */
- (void) countFrom1To10ThreeTimes{
  
  /* Get the handle to a global concurrent queue */
  dispatch_queue_t concurrentQueue =
  dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0);
  
  /* Now run the block object three times */
  dispatch_async(concurrentQueue, countFrom1To10);
  dispatch_async(concurrentQueue, countFrom1To10);
  dispatch_async(concurrentQueue, countFrom1To10);
  
}

If you invoke the countFrom1To10ThreeTimes method in your application, the results printed in the console might be similar to these:

...
Thread = <NSThread: 0x94312b0>{name = (null), num = 3}. Counter = 7
Thread = <NSThread: 0x9432160>{name = (null), num = 5}. Counter = 6
Thread = <NSThread: 0x9431d70>{name = (null), num = 4}. Counter = 7
Thread = <NSThread: 0x94312b0>{name = (null), num = 3}. Counter = 8
Thread = <NSThread: 0x9432160>{name = (null), num = 5}. Counter = 7
Thread = <NSThread: 0x94312b0>{name = (null), num = 3}. Counter = 9
Thread = <NSThread: 0x9431d70>{name = (null), num = 4}. Counter = 8
Thread = <NSThread: 0x9432160>{name = (null), num = 5}. Counter = 8
Thread = <NSThread: 0x94312b0>{name = (null), num = 3}. Counter = 10
Thread = <NSThread: 0x9431d70>{name = (null), num = 4}. Counter = 9
Thread = <NSThread: 0x9432160>{name = (null), num = 5}. Counter = 9
Thread = <NSThread: 0x9431d70>{name = (null), num = 4}. Counter = 10
Thread = <NSThread: 0x9432160>{name = (null), num = 5}. Counter = 10

Now let’s take a look at another example. Suppose we want to asynchronously download the contents of three URLs and mark the end of all the downloads by displaying an alert to our users on the user interface. The choice here between the main queue and one of the global concurrent queues is rather simple. Since the contents of the URLs could be very large, it is best not to keep the main thread busy downloading them. In other words, we should avoid using the main queue. Also, we want to download the URLs one by one. Put simply, we want to wait for the first URL to be downloaded before moving to the second one, and so on. We have the luxury of synchronous URL requests because we know that we are going to execute our block object on a global concurrent queue, which will not block the main thread. To achieve this, we shall use the dispatch_sync procedure, which will block a given queue before moving to the next block of code.

Let’s break this down into two pieces of code. One piece is the block object, which will be able to download any URL that we pass to it and return YES if the download succeeds or NO if it fails:

BOOL (^downloadURL)(NSURL *) = ^(NSURL *paramURL){
  
  NSURLRequest *request = [NSURLRequest requestWithURL:paramURL];
  NSData *data = [NSURLConnection sendSynchronousRequest:request
                                       returningResponse:nil
                                                   error:nil];
  
  if ([data length] > 0){
    NSLog(@"Successfully downloaded %lu bytes of data",
          (unsigned long)[data length]);
    return YES;
  } else {
    NSLog(@"Failed to download the data.");
    return NO;
  }
  
};

Now what? We have the block that can download URLs for us synchronously. Now let’s get the handle to a global concurrent queue and execute this block synchronously on it. After we are done, we want to display a message to the user on the user interface. To do anything UI-related, we have to execute our blocks on the main queue, which executes its tasks on the main thread as shown here:

- (void) downloadThreeURLsAndDisplayAlert{
  
  __block BOOL wasSuccessful = YES;
  
  dispatch_queue_t concurrentQueue =
  dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0);
  
  dispatch_sync(concurrentQueue, ^(void){
    NSLog(@"Downloading iOS 4 Cookbook's main page data...");
    wasSuccessful &= downloadURL([NSURL URLWithString:
                                  @"http://www.ios4cookbook.com"]);
  });
  
  dispatch_sync(concurrentQueue, ^(void){
    NSLog(@"Downloading a blog's main page data...");
    wasSuccessful &= downloadURL([NSURL URLWithString:
                                  @"http://vandadnp.wordpress.com"]);
  });
  
  dispatch_sync(concurrentQueue, ^(void){
    NSLog(@"Downloading O'Reilly's main page data...");
    wasSuccessful &= downloadURL([NSURL URLWithString:
                                  @"http://www.oreilly.com"]);
  });
  
  /* Make sure the UI-related code is executed in the
   main queue */
  dispatch_queue_t mainQueue = dispatch_get_main_queue();
  
  dispatch_async(mainQueue, ^(void) {
    if (wasSuccessful == YES){
      NSLog(@"Successfully downloaded all URLs.");
      /* Display an alert here */
    } else {
      NSLog(@"At least one URL failed to download.");
      /* Display an alert here too */
    }
  });
  
}

If you have an Internet connection, running this code will give you results similar to those shown here:

Downloading iOS 4 Cookbook's main page data...
Successfully downloaded 518 bytes of data
Downloading a blog's main page data...
Successfully downloaded 74849 bytes of data
Downloading O'Reilly's main page data...
Successfully downloaded 80530 bytes of data
Successfully downloaded all URLs.

If you do not have an Internet connection, you will receive results similar to these:

Downloading iOS 4 Cookbook's main page data...
Failed to download the data.
Downloading a blog's main page data...
Failed to download the data.
Downloading O'Reilly's main page data...
Failed to download the data.
At least one URL failed to download.

The dispatch_sync procedure executes our block object on a global concurrent queue, meaning that the block object will get executed on a thread other than the main thread. At the same time, because of the nature of dispatch_sync procedure, the executing code will block the concurrent queue until it has finished. Then the second synchronous dispatch happens, and so on, until we get to where we want to display a message to the user. In this case, we execute our block object on the main queue, because all UI-related code (to display something, hide something, add a view to a window, etc.) needs to be executed on the main thread.

Before we can move to subjects related to Game Center, we should also take a look at the dispatch_once procedure discussed earlier. This procedure will execute a block object on a given dispatch queue once and only once during the lifetime of the application. There are a few things that you have to bear in mind when working with the dispatch_once procedure:

Let’s take a look at an example. Let’s say I have a block object that counts from 0 to 5 and I just want it to be executed once, on a global concurrent queue to avoid blocking the main thread, during the lifetime of my application. This is how I should implement my code:

void (^countFrom1To5)(void) = ^(void){
  NSUInteger counter = 0;
  for (counter = 1;
       counter <= 5;
       counter++){
    NSLog(@"Thread = %@, Counter = %lu",
          [NSThread currentThread],
          (unsigned long)counter);
  }
};

- (void) countFrom1To5OnlyOnce{
  
  dispatch_queue_t globalQueue =
  dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0);
  
  static dispatch_once_t onceToken;
  
  dispatch_async(globalQueue, ^(void) {
    dispatch_once(&onceToken, countFrom1To5);
    dispatch_once(&onceToken, countFrom1To5);
  });
  
}

If I call the countFrom1To5OnlyOnce method and run my program, I will get results similar to those shown here:

Thread = <NSThread: 0x5f07f10>{name = (null), num = 3}, Counter = 1
Thread = <NSThread: 0x5f07f10>{name = (null), num = 3}, Counter = 2
Thread = <NSThread: 0x5f07f10>{name = (null), num = 3}, Counter = 3
Thread = <NSThread: 0x5f07f10>{name = (null), num = 3}, Counter = 4
Thread = <NSThread: 0x5f07f10>{name = (null), num = 3}, Counter = 5

What if I pass a different token to the dispatch_once procedure in the countFrom1To5OnlyOnce method?

Thread = <NSThread: 0x6a117f0>{name = (null), num = 3}, Counter = 1
Thread = <NSThread: 0x6a117f0>{name = (null), num = 3}, Counter = 2
Thread = <NSThread: 0x6a117f0>{name = (null), num = 3}, Counter = 3
Thread = <NSThread: 0x6a117f0>{name = (null), num = 3}, Counter = 4
Thread = <NSThread: 0x6a117f0>{name = (null), num = 3}, Counter = 5
Thread = <NSThread: 0x6a117f0>{name = (null), num = 3}, Counter = 1
Thread = <NSThread: 0x6a117f0>{name = (null), num = 3}, Counter = 2
Thread = <NSThread: 0x6a117f0>{name = (null), num = 3}, Counter = 3
Thread = <NSThread: 0x6a117f0>{name = (null), num = 3}, Counter = 4
Thread = <NSThread: 0x6a117f0>{name = (null), num = 3}, Counter = 5

The code in this example was executed twice. Not what we wanted. So make sure that, for whatever block of code that has to be executed once, you pass the same pointer to the first parameter of the dispatch_once procedure.

You should now have a good understanding of block objects and GCD, so we can dive right into more interesting subjects concerning Game Center. Here are a few links if you require further information about block objects and GCD:

Creating Game Center Accounts; Setting Up Game Center for an iOS App

You know you need to set something up before being able to use Game Center but you are not quite sure what you need to do.

Use the iOS Simulator’s built-in Game Center app to set up your Game Center accounts as demonstrated here.

Each player is identified by an account on Game Center. Each account is linked to an email address. Game Center accounts run on either the production server or the sandbox server. The production server is the server that hosts Game Center apps when they go live on the App Store. The sandbox server is the server that hosts Game Center apps before they go to production, such as apps that are run on the iOS Simulator so that developers can test whether the app is working fine before they submit it to the App Store. All code that you write for your Game Center apps will work on the production server if they work fine on the sandbox server.

To test your Game Center apps, you must create Game Center accounts. Each account is associated with just one of the two servers just discussed. Since we want to test our apps before submitting them to the store, we must create a few Game Center sandbox players. Please take the following steps to create Game Center sandbox players:

Figure 1-2. The main Game Center interface, once logged in

Now go ahead and create at least one more Game Center player on the sandbox environment. To test the example code in this book, you will ideally need three sandbox players. If you are reluctant to spend time registering three players, you must at least create two. Otherwise, you will not be able to test about 90 percent of the example code.

Authenticating the Local Player in Game Center

You want to be able to connect to the Game Center servers in your iOS apps.

You need to create your app in iTunes Connect and also set your app’s bundle identifier both in iTunes Connect and your app’s info.plist file as demonstrated in the Discussion section.

In Creating Game Center Accounts, we created sandbox Game Center accounts using the Game Center iOS App, which is installed on all instances of iOS Simulator. That was the first piece of the puzzle. The next is setting up our iOS App with Game Center using iTunes Connect. This might confuse you a bit at first. The linchpin is to create an app in Xcode and give it a bundle identifier. For instance, here is the bundle identifier that I am using:

com.pixolity.testgame

Setting the identifier in your app bundle won’t do the trick by itself. You have to set up your application on iTunes Connect. Set the app’s bundle identifier on iTunes Connect to the same identifier you set in your application bundle in Xcode.

We’ll handle these tasks in this section, but we will not upload the app to iTunes Connect. By following the procedure in this section, you’ll set up your app on iTunes in the state of Prepare for Upload. You will be able to access Game Center for the app. But because it is not actually uploaded to iTunes Connect, your Game Center connections will run on the sandbox environment. The same code will run on the production server in a later stage, after your app has been uploaded to iTunes Connect.

Follow these steps to set up an iOS app with Game Center on iTunes Connect:

Now you’re done. Go ahead and import the Game Kit framework into your project, as described in Adding the Game Kit Framework.

Adding the Game Kit Framework

You have set up your project and want to start incorporating Game Center APIs into your app.

Add the Game Kit framework to your app as demonstrated in the Discussion section.

Figure 1-5. Setting the Bundle Identifier of an app in Xcode 4

To use Game Center’s capabilities, you must link your application against the Game Kit framework. Assuming you have created an Xcode project already for this app, import this framework into your Xcode project as follows:

Figure 1-6. Build Phases for an iOS app

Figure 1-7. Adding the Game Kit framework to an iOS target

Game Kit is now added to your project. Now you have to decide whether or not using Game Kit is a requirement in your application. iOS versions older than 4.1 do not support Game Center (although iOS 4.0 demoed Game Center), so you must decide whether or not your application really requires Game Center to function or whether Game Center is an optional functionality that you are offering with your game.

If your application cannot function without Game Center, you must follow these steps to make it clear in your application’s Info.plist file:

<key>UIRequiredDeviceCapabilities</key>
<array>
  <string>gamekit</string>
</array>

If your app makes use of Game Center but Game Center isn’t the main part of the app, you can optionally load Game Center. To do so, follow these steps:

Combine these two methods and you can be 100 percent sure whether or not Game Center is available on the given device. Here is sample code that lets you detect the availability of Game Center in your application:

- (BOOL) gameCenterSupported{
  
  NSUInteger availabilityPercentage = 0;
  
  if (NSStringFromClass([GKLocalPlayer class]) != nil){
    availabilityPercentage += 50;
  }
  
  NSString *systemVersionAsString =
  [[UIDevice currentDevice] systemVersion];
  
  NSNumber *systemVersion = [NSNumber numberWithDouble:
                             [systemVersionAsString doubleValue]];
  
  NSNumber *minimumSystemVersion = [NSNumber numberWithDouble:4.1];
  
  if ([minimumSystemVersion compare:systemVersion] != NSOrderedDescending){
    availabilityPercentage += 50;
  }
  
  if ((NSUInteger)availabilityPercentage == 100){
    NSLog(@"Game Center is supported.");
    return YES;
  } else {
    NSLog(@"Game Center is not supported");
    return NO;
  }
  
}

#import <GameKit/GameKit.h>

The code compares the current system version to the minimum required system version and makes sure the current version is higher or the same (ascending order). For instance, 4.1 (minimum required) followed by 4.2 (current version) is an ascending order, hence we can conclude that Game Center is supported. Compare that to 4.1 (minimum required) followed by 4.0 (current version) which is a descending order, indicating a lack of support for Game Center on the current machine.

Now that you have determined whether Game Center is present on the host device, we can move on to the next step.

Authenticating the Local Player in Game Center

You know that the first step to using Game Center functionalities is to authenticate the local player, but you have no idea how you should do that.

Use the authenticateWithCompletionHandler: instance method of the GKLocalPlayer class, as shown in the Discussion section.

In Game Center, everything depends on the simple ability to access the local player. The local player is the player that is authenticated into Game Center either through the Game Center app on an iOS device or through an iOS app that utilizes Game Center. If the player has not authenticated herself yet, attempting to retrieve the local player will prompt the player to authenticate first. If the player cancels, we will get an error back in our code. If the player has already authenticated, she won’t be prompted to log into Game Center again. So long as she is authenticated, we will be able to retrieve her player object.

Every player in Game Center is represented with an object of GKPlayer. The local player is also a player, but is represented with an object of type GKLocalPlayer, a subclass of the GKPlayer class. In order to retrieve a reference to the local player object, you can use the localPlayer class method of the GKLocalPlayer class like so:

GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

After you have the local player’s object, you must, as soon as you have the ability to do so (right after your application loads), authenticate the player using the authenticateWithCompletionHandler: instance method of the GKLocalPlayer class. This method accepts a block object that should have no return value and should accept a single parameter of type NSError that will store any error that occurs during the authentication process:

- (void) authenticateLocalPlayer{

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  [localPlayer authenticateWithCompletionHandler:^(NSError *error) {

    if (error == nil){
      NSLog(@"Successfully authenticated the local player.");
    } else {
      NSLog(@"Failed to authenticate the player with error = %@", error);
    }

  }];

}

If the player has not logged into Game Center, after the execution of this code, she will be prompted with a dialog asking her to do so. This is depicted in Figure 1-8.

Figure 1-8. Game Center, asking the local player to log in

The isAuthenticated instance method of the GKLocalPlayer class returns YES if the local player has already authenticated and NO if she has not. So, in order to improve our authentication method, we can add this factor in:

- (void) authenticateLocalPlayer{

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  if ([localPlayer isAuthenticated] == YES){
    NSLog(@"The local player has already authenticated.");
    return;
  }

  [localPlayer authenticateWithCompletionHandler:^(NSError *error) {

    if (error == nil){
      NSLog(@"Successfully authenticated the local player.");
    } else {
      NSLog(@"Failed to authenticate the player with error = %@", error);
    }

  }];

}

Now that you know how to authenticate the local player, it is time to move to more sophisticated subjects in Game Center, such as Retrieving the Local Player’s Information.

Retrieving the Local Player’s Information

You have authenticated the local player, but you need to get her alias and other information.

Use different properties available to the GKLocalPlayer class, such as the alias property, as demonstrated in the Discussion section.

The GKPlayer object represents a player in Game Center. Each player possesses a few very important properties:

Now let’s go ahead and demonstrate this with example code. In this code, what I want to demonstrate can be separated into two pieces of code expressed in block objects. One block object simply attempts to print out the local player’s alias and player ID:

void (^printLocalPlayerInfo)(void) = ^{

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];
  if ([localPlayer isAuthenticated] == YES){

    NSLog(@"Player ID = %@", [localPlayer playerID]);
    NSLog(@"Player Alias = %@", [localPlayer alias]);

  }

};

The second block object does the authentication and passes the control to the first block object after the authentication is done:

- (void) authenticateLocalPlayerAndGetHerInfo{

  dispatch_queue_t concurrentQueue =
    dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0);

  dispatch_async(concurrentQueue, ^(void) {
    GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];
    if ([localPlayer isAuthenticated] == NO){
      [localPlayer authenticateWithCompletionHandler:^(NSError *error) {
        if (error == nil){
          NSLog(@"Successfully authenticated.");
          dispatch_async(concurrentQueue, printLocalPlayerInfo);
        } else {
          NSLog(@"Failed to authenticate. Error = %@", error);
        }
      }];
    } else {
      dispatch_async(concurrentQueue, printLocalPlayerInfo);
    }
  });

}

Plain and simple! If I invoke the authenticateLocalPlayerAndGetHerInfo method in my application, the following information is printed to the console:

Successfully authenticated.
Player ID = G:1428628142
Player Alias = Test Game User 1

The local player (GKLocalPlayer), unlike any other player (GKPlayer), has a property named friends that defines which players have been associated as friends with the local player. To read more about this, please refer to Retrieving the Local Player’s Friends Information.

Retrieving the Local Player’s Friends Information

You have learned to authenticate the local player, but to test Game Center APIs on other players, you want to add some friends to the local player’s account.

Use the iOS Simulator built-in Game Center app to add friends to the local player, as demonstrated in the Discussion section.

To add a friend in Game Center on the sandbox server, follow these steps:

It just couldn’t be simpler than this!

Retrieving the Local Player’s Friends Information

You’ve added friends to the local player’s Game Center account, but now you want to enumerate them and retrieve their information, such as their alias.

Use the friends property of the local player’s object, an instance of GKLocalPlayer.

The GKLocalPlayer class has a property called friends of type NSArray. This property will contain the players that the local player is friends with. The array represents the players using their player IDs (explained in Retrieving the Local Player’s Information).

I said will in the previous paragraph because, after authentication of the local player, this array is empty (nil). You need to call the loadFriendsWithCompletionHandler: instance method of the GKLocalPlayer class to load the player ID for each of the local player’s friends. After retrieving the IDs, call another method to retrieve other information for each friend based on his or her player ID.

The loadFriendsWithCompletionHandler: instance method of the GKLocalPlayer class accepts one parameter, which should be a block that returns void (or in other words, doesn’t return anything). This block object will have two parameters. The first is of type NSArray and will, upon return, contain the friend IDs of the local player. The second is of type NSError and will indicate whether an error occurred during the process.

Let’s take a look at an example where we just load the local player’s friends’ IDs:

void (^getLocalPlayerFriends)(void) = ^{

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  if ([localPlayer isAuthenticated] == NO){
    NSLog(@"The local player is not authenticated.");
    return;
  }

  NSLog(@"Loading local player's friend IDs...");
  [localPlayer loadFriendsWithCompletionHandler:
   ^(NSArray *friends, NSError *error) {

     if (friends != nil){
       NSLog(@"Successfully retrieved friends of the local player.");
       NSUInteger counter = 1;
       for (NSString *friendID in friends){
         NSLog(@"Friend %lu = %@", (unsigned long)counter, friendID);
         counter++;
       }
     }

     if (error != nil){
       NSLog(@"Error occurred. Error = %@", error);
     }

  }];

};

Running this code in the iOS Simulator, I get the following results:

Loading local player's friend IDs...
Successfully retrieved friends of the local player.
Friend 1 = G:1428629254
Friend 1 = G:1428629742

As you can see, I’ve added two friends to the local player’s list (Adding Friends in Game Center). If you look at the code once again, you’ll notice that I am checking whether the friends array is nil and then checking whether an error occurred during the loading process. The reason behind this is quite simple: Game Center attempts to load the local player’s friends. If an error occurs, some of the information might have been loaded nonetheless. Therefore, you might get an array that contains the partial list of the local player’s friends. If you do get this, you might decide to go ahead with the partial array. But if you want to be sure that no error occurs, I suggest that you check the error parameter first and then print out the contents of the friends array.

To detect if Game Center could successfully load the list of friends, we should make sure that the error parameter is nil, and to detect if the list of friends was partially retrieved, we should check if the array of friends and the error parameter are both not nil. This means that although we did get some of our friends enumerated in the array, there was also an error retrieving the rest of them.

All is good. I have the identifiers of the local player’s friends. How can I get instances of the GKPlayer class using the player identifiers? For that you will have to use the loadPlayersForIdentifiers:withCompletionHandler: class method of the GKPlayer class. The complete sequence of tasks is:

void (^getLocalPlayerFriendsDetails)(void) = ^{

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  if ([localPlayer isAuthenticated] == NO){
    NSLog(@"The local player is not authenticated.");
    return;
  }

  if ([[localPlayer friends] count] == 0){
    NSLog(@"The local player has no friends. How sad!");
    return;
  }

  NSLog(@"Loading players...");
  [GKPlayer
   loadPlayersForIdentifiers:[localPlayer friends]
   withCompletionHandler:^(NSArray *players, NSError *error) {

     if (players != nil){
       NSLog(@"Successfully loaded the players.");
       for (GKPlayer *player in players){
         NSLog(@"%@", player);
       }
     }

     if (error != nil){
       NSLog(@"Error happened. Error = %@", error);
     }

   }];

};

void (^getLocalPlayerFriends)(void) = ^{

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  if ([localPlayer isAuthenticated] == NO){
    NSLog(@"The local player is not authenticated.");
    return;
  }

  NSLog(@"Loading local player's friend IDs...");
  [localPlayer loadFriendsWithCompletionHandler:
   ^(NSArray *friends, NSError *error) {

     if (friends != nil){
       NSLog(@"Successfully retrieved friends of the local player.");

       dispatch_queue_t concurrentQueue =
        dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0);
       dispatch_async(concurrentQueue, getLocalPlayerFriendsDetails);

     }

     if (error != nil){
       NSLog(@"Error occurred. Error = %@", error);
     }

  }];

};

- (void) authenticateLocalPlayerAndGetHerInfo{

  dispatch_queue_t concurrentQueue =
    dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0);

  dispatch_async(concurrentQueue, ^(void) {
    GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];
    if ([localPlayer isAuthenticated] == NO){
      [localPlayer authenticateWithCompletionHandler:^(NSError *error) {
        if (error == nil){
          NSLog(@"Successfully authenticated.");
          dispatch_async(concurrentQueue, getLocalPlayerFriends);
        } else {
          NSLog(@"Failed to authenticate. Error = %@", error);
        }
      }];
    } else {
      dispatch_async(concurrentQueue, getLocalPlayerFriends);
    }
  });

}

After calling the authenticateLocalPlayerAndGetHerInfo method in this example code, I get the following results (because I authenticate the local player, who has two friends in her list):

Successfully authenticated.
Loading local player's friend IDs...
Successfully retrieved friends of the local player.
Loading players...
Successfully loaded the players.
<GKPlayer 0x5f32d90>(playerID: G:1428629254, alias: Test Game User 2,
      status: (null), rid:(null))
<GKPlayer 0x5f32cf0>(playerID: G:1428629742, alias: Test Game User 3,
      status: (null), rid:(null))

Once you have this information, you can either display it to the player or keep it for future reference. With regard to player IDs, please do not store these in your game. Whenever the player runs your app, you must attempt to retrieve the fresh list of friends instead of assuming the friends that your app retrieved a few days ago are still the local player’s friends. Also, the format of the player ID might change, as Apple has mentioned in its documentation:

Authenticating the Local Player in Game Center

You don’t know how to start incorporating leaderboards into your iOS games.

Set up leaderboards in iTunes Connect.

One of the functionalities in Game Center is the ability to manage leaderboards in your iOS apps. For instance, you can write a racing game for iOS and have players compete to achieve the best score. You can then report these scores to a leaderboard and allow the players to see the leaderboard. This gives your players a reason to come back to your app (in order to compete with their friends).

To use leaderboards in your app, you must first create them for your app in iTunes Connect. Here is how you can do that:

There are two types of leaderboards in Game Center:

Follow these steps to create a single leaderboard that can contain scores from 1 to 1,000, with 1,000 being the highest score:

Once you have created a leaderboard for your app, you will be able to access it in your app using Game Kit. This is explained in Reporting Scores to Leaderboards.

Reporting Scores to Leaderboards; Retrieving Leaderboards Information Programmatically; Displaying Leaderboards to Players

You have created at least one leaderboard in iTunes Connect and now you want to store players’ scores to that leaderboard.

Use the reportScoreWithCompletionHandler: instance method of the GKScore class as demonstrated in the Discussion section.

Assuming that you have already created a leaderboard (see Creating Leaderboards in iTunes Connect), you must follow these steps to report scores to it:

- (BOOL) reportScore:(NSUInteger)paramScore
       toLeaderboard:(NSString *)paramLeaderboard{

  __block BOOL result = NO;

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  if ([localPlayer isAuthenticated] == NO){
    NSLog(@"You must authenticate the local player first.");
    return NO;
  }

  if ([paramLeaderboard length] == 0){
    NSLog(@"Leaderboard identifier is empty.");
    return NO;
  }

  GKScore *score = [[[GKScore alloc]
                     initWithCategory:paramLeaderboard] autorelease];

  score.value = (int64_t)paramScore;

  NSLog(@"Attempting to report the score...");

  [score reportScoreWithCompletionHandler:^(NSError *error) {
    if (error == nil){
      NSLog(@"Succeeded in reporting the error.");
      result = YES;
    } else {
      NSLog(@"Failed to report the error. Error = %@", error);
    }
  }];

  return result;

}

- (void) authenticateLocalPlayerAndReportScore{

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  if ([localPlayer isAuthenticated] == YES){
    NSLog(@"The local player has already authenticated.");
    return;
  }

  [localPlayer authenticateWithCompletionHandler:^(NSError *error) {

    if (error == nil){
      NSLog(@"Successfully authenticated the local player.");

      [self reportScore:10
          toLeaderboard:@"MGL1LB"];

    } else {
      NSLog(@"Failed to authenticate the player with error = %@", error);
    }

  }];

}

Calling the authenticateLocalPlayerAndReportScore method will attempt to authenticate the local player and then report the score of 10 to a leaderboard with Reference ID of MGL1LB (see Creating Leaderboards in iTunes Connect). Here are the results that I see printed to my console window:

Successfully authenticated the local player.
Attempting to report the score...
Succeeded in reporting the error.

If you try reporting a score to a nonexistent leaderboard, the error that you will receive from the reportScoreWithCompletionHandler: method will be similar to this:

Error Domain=GKErrorDomain Code=17 "The requested operations could
not be completed because one or more parameters are invalid."
UserInfo=0x5f43a90 {NSUnderlyingError=0x5f09390 "The operation
couldn’t be completed. status = 5053", NSLocalizedDescription=The
requested operations could not be completed because
one or more parameters are invalid.}

There are three ways you can see the scores that you have reported to Game Center (sandbox server):

The latter two methods of displaying leaderboard scores to the player are explained in their own sections. Here I’ll just explain how to display scores using the iOS Simulator. Follow these steps to see the local player’s leaderboards using the Simulator:

Read on to the next two sections to learn the other ways to display scores.

Retrieving Leaderboards Information Programmatically; Displaying Leaderboards to Players

Figure 1-11. Leaderboard screen in iOS Simulator

After reporting scores to a leaderboard, you are curious as to how you can retrieve this information from the leaderboard programmatically.

Use the loadScoresWithCompletionHandler: instance method of the GKLeaderBoard class, as shown in the Discussion section.

To retrieve a leaderboard’s scores in your app, follow these steps:

Each leaderboard score in Game Center is encapsulated into an instance of GKScore, as we saw in Reporting Scores to Leaderboards. Let’s take a look at example code retrieving scores from a leaderboard with Reference ID (category) of MGL1LB:

GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  NSLog(@"Authenticating the local player...");
  [localPlayer authenticateWithCompletionHandler:^(NSError *error) {

    if (error == nil){

      NSLog(@"Successfully authenticated the local player.");
      GKLeaderboard *leaderboard =
        [[[GKLeaderboard alloc] init] autorelease];

      [leaderboard setCategory:@"MGL1LB"];
      NSLog(@"Loading the scores in leaderboard...");
      [leaderboard loadScoresWithCompletionHandler:
       ^(NSArray *scores, NSError *error) {

         if (scores != nil){
           for (GKScore *score in scores){
             NSLog(@"%@", score);
           }
         }

         if (error != nil){
           NSLog(@"Error occurred = %@", error);
         }

      }];

    } else {
      NSLog(@"Failed to authenticate with error = %@", error);
    }

  }];

After reporting the score 10, 20, and 35 for three Game Center players (who are all friends of each other) in Reporting Scores to Leaderboards and executing this code, the console window will print following similar to this:

Authenticating the local player...
Successfully authenticated the local player.
Loading the scores in leaderboard...
GKScore player=G:1428629742 rank=1 date=2011-03-27
      10:39:58 +0000 value=35 formattedValue=35points
GKScore player=G:1428629254 rank=2 date=2011-03-27
      10:39:24 +0000 value=20 formattedValue=20points
GKScore player=G:1428628142 rank=3 date=2011-03-27
      09:21:19 +0000 value=10 formattedValue=10points

Displaying Leaderboards to Players

You want to display leaderboards to your app users using a graphical user interface.

Use the GKLeaderboardViewController class as shown in the Discussion section.

Game Center can construct built-in leaderboard screens for your games. Doing this is a piece of cake for Game Center. All you have to do is build an iOS application that makes use of view controllers. This is outside the scope of this book, but is thoroughly explained in iOS 4 Programming Cookbook. For the remainder of this section, I assume you have created an application with one view controller inside a navigation controller.

To have Game Center construct a leaderboard screen for your iOS app, follow these steps:

Instances of the GKLeaderboardViewController class have three important properties:

Let’s take a look at an example where I want to display scores submitted to a leaderboard with Reference ID of MGL1LB (see Creating Leaderboards in iTunes Connect) during this week:

- (void)leaderboardViewControllerDidFinish:
  (GKLeaderboardViewController *)viewController{

  /* We are finished here */
  [self dismissModalViewControllerAnimated:YES];

}

- (void) viewDidLoad{

  [super viewDidLoad];

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  [localPlayer authenticateWithCompletionHandler:^(NSError *error) {

    if (error == nil){

      GKLeaderboardViewController *controller =
        [[GKLeaderboardViewController alloc] init];

      /* The category for our leaderboard. We created this before */
      [controller setCategory:@"MGL1LB"];
      /* Only show the scores that were submitted this week */
      [controller setTimeScope:GKLeaderboardTimeScopeWeek];
      [controller setLeaderboardDelegate:self];
      [self presentModalViewController:controller
                              animated:YES];
      [controller release];

    } else {
      NSLog(@"Could not authenticate the local player. Error = %@", error);
    }

  }];

}

Once you run the app and it loads the view controller that contains this code, you will see results similar to that shown in Figure 1-12.

Figure 1-12. Leaderboard view controller displaying this week’s scores

Retrieving Leaderboards Information Programmatically

You want your game’s users to keep coming back to your app by allowing them to unlock achievements inside your game.

Use iTunes Connect to create achievements for your game, as demonstrated in the Discussion section.

Game Center allows iOS developers to include achievements in their apps and record the player’s progress toward completing an achievement. For instance, you might be writing a first person shooter game. In your game, you have a normal map that the player can walk through and engage in battles with the opponent. You might have decided to include some hidden paths in your game that not everybody can find. Only those who have been playing the game long enough know about these hidden paths. When a player finds a hidden path for the first time, you can report an achievement to the Game Center and give the player some reward in order to keep her interested in the game. The player can then work toward completing that achievement, as each achievement can have a completion percentage.

Let’s consider a simple scenario. Let’s say I find the hidden path in the game. Suppose the game requires me not only to find the path, but also to go to the end of the path for the achievement to be unlocked. When the player finds the path, you can report 0 percent for that achievement. Once the player is halfway through the path, you can report 50 percent for that achievement, and once she goes through the road and comes out of the other side, you can mark that achievement 100 percent completed.

You can have two different types of achievements:

To add achievements to your app, you must first create them for your app in iTunes Connect. Here is how you can do that:

The Game Center app displays achievements (with at least one progress reported) to the player. A player will be able to see a normal achievement in her list even before completing it. Let’s say you are working on a racing game with AI-controlled cars, and one of the achievements goes to players who can win against them 10 times in a row. As soon as the player wins against the computer once, you can report a completion progress of 10 percent (one-tenth of the final achievement). At this point, the player can log into the Game Center app and see this achievement in his list. Game Center will not say that this achievement has been completed, because the completion progress is not 100 percent. What it will say, however, is how the player can work to complete this achievement, a description you should provide. Once the player wins against the AI-driven car 10 times in a row, Game Center will show that he has received this achievement successfully. Because you should provide descriptions of the achievement when the first progress is displayed and after the player completes the achievement, you need to use the localization feature in iTunes Connect as follows:

Once you have created an achievement for your app, you will be able to access it in your app using Game Kit. This is explained in Reporting Achievements to Game Center.

Reporting Achievements to Game Center; Retrieving Achievements Information Programmatically; Displaying Achievements to Players

You created achievements for your game in iTunes Connect and you are ready to use them in your game.

Use the GKAchievement class in your iOS app.

Reporting achievement progress to Game Center is similar to reporting scores to leaderboards in Game Center (see Reporting Scores to Leaderboards). Follow these steps to report an achievement to Game Center:

The following sample code reports 50 percent completion on an achievement with ID of MGL1HP1C (see Creating Achievements in iTunes Connect):

- (BOOL) reportAchievementWithID:(NSString *)paramAchievementID
             percentageCompleted:(double)paramPercentageCompleted{

  BOOL result = NO;

  if ([paramAchievementID length] == 0){
    NSLog(@"Achievement ID cannot be empty.");
    return NO;
  }

  GKAchievement *achievement =
    [[[GKAchievement alloc] initWithIdentifier:paramAchievementID]
     autorelease];

  NSLog(@"Setting percentage to %.02f", paramPercentageCompleted);
  [achievement setPercentComplete:paramPercentageCompleted];

  NSLog(@"Reporting the achievement...");
  [achievement reportAchievementWithCompletionHandler:^(NSError *error) {

    if (error == nil){
      NSLog(@"Successfully reported the achievement.");
    } else {
      NSLog(@"Failed to report the achievement. %@", error);
    }

  }];

  return result;

}

- (void) authenticateLocalPlayerAndReportAchievement{

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  NSLog(@"Authenticating the local player...");
  [localPlayer authenticateWithCompletionHandler:^(NSError *error) {

    if (error == nil){
      NSLog(@"Successfully authenticated the local player.");
      NSLog(@"Reporting achievement...");
      [self reportAchievementWithID:@"MGL1HP1C"
                percentageCompleted:50.0f];
    } else {
      NSLog(@"Failed to authenticate the local player. %@", error);
    }

  }];

}

After calling the authenticateLocalPlayerAndReportAchievement method, you will get results printed to the console window similar to these shown here (unless there is an error, in which case the errors will get printed to the console window):

Authenticating the local player...
Successfully authenticated the local player.
Reporting achievement...
Setting percentage to 50.00
Reporting the achievement...
Successfully reported the achievement.

After an achievement is reported to Game Center, if the achievement wasn’t set up as a hidden achievement, the local player can open the Game Center app and take a look at it, along with all the achievements she has collected while using your app, as shown in Figure 1-14.

Once the player selects the Achievements option, she will see all the achievements that an app has reported to Game Center and the progress along each achievement, as shown in Figure 1-15.

Figure 1-14. Achievements on iOS Simulator

Figure 1-15. Achievement progress on iOS Simulator

Creating Achievements in iTunes Connect; Retrieving Achievements Information Programmatically; Displaying Achievements to Players

You want to retrieve the progress of achievements that have been reported to Game Center for the local authenticated player.

You need to invoke the loadAchievementsWithCompletionHandler: class method of the GKAchievement class.

Just as we can retrieve leaderboard information programmatically (see Retrieving Leaderboards Information Programmatically), we can ask Game Center to provide us with the latest information about the progress the authenticated local player has made on each one of the achievements that we have enabled on our app. To do this, simply follow these steps:

Here is an example of how we can retrieve achievements programmatically:

- (void) authenticateAndGetAchievements{

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  NSLog(@"Authenticating the local player...");
  [localPlayer authenticateWithCompletionHandler:^(NSError *error) {

    if (error == nil){
      NSLog(@"Successfully authenticated the local player.");

      [GKAchievement loadAchievementsWithCompletionHandler:
       ^(NSArray *achievements, NSError *error) {

         NSUInteger counter = 1;
         for (GKAchievement *achievement in achievements){
           NSLog(@"Achievement %lu = %@",
                 (unsigned long)achievement,
                 achievement);
           counter++;
         }

      }];

    } else {
      NSLog(@"Failed to authenticate the local player. %@", error);
    }

  }];

}

Before invoking the authenticateAndGetAchievements method, I added another achievement in iTunes Connect (see Creating Achievements in iTunes Connect) for my app and then went ahead and reported a progress of 10 percent for that achievement. Here are the results that I got from invoking this method:

Authenticating the local player...
Successfully authenticated the local player.
Achievement 111340288 = id: MGL1HP1C	50.000000
Achievement 111379664 = id: MGL1HP2C	10.000000

As you saw in Creating Achievements in iTunes Connect, each achievement was configured with two descriptions: one that gets displayed to the player before she has completed the achievement and the other that gets displayed after she earns that achievement. The GKAchievement class can’t retrieve these descriptions. You must use the GKAchievementDescription class for that instead. The loadAchievementDescriptionsWithCompletionHandler: class method of the GKAchievementDescription class allows you to retrieve descriptions for all achievements available to the local player, each encapsulated into an object of type GKAchievementDescription. The loadAchievementDescriptionsWithCompletionHandler: method accepts a block object that returns void as a parameter. This block object should have, as parameters, an instance of NSArray that will contain the achievements and an instance of NSError that will contain any errors that occur. Here is example code:

- (void) authenticateAndGetAchievementsInfo{

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  NSLog(@"Authenticating the local player...");
  [localPlayer authenticateWithCompletionHandler:^(NSError *error) {

    if (error == nil){
      NSLog(@"Successfully authenticated the local player.");

      [GKAchievementDescription
       loadAchievementDescriptionsWithCompletionHandler:
       ^(NSArray *descriptions, NSError *error) {

         NSUInteger counter = 1;
         for (GKAchievementDescription *description in descriptions){
           NSLog(@"Achievement %lu. Description = %@",
                 (unsigned long)counter,
                 descriptions);
           counter++;
         }

       }];

    } else {
      NSLog(@"Failed to authenticate the local player. %@", error);
    }

  }];

}

Here is an example of what the authenticateAndGetAchievementsInfo method could print out to the console window:

Authenticating the local player...
Successfully authenticated the local player.
Achievement 1. Description = (
    "id: MGL1HP1C	visible	You came out of
      Hidden Path 1 alive. Great job.",

    "id: MGL1HP2C	visible	You found Hidden
      Path 2. Congratulations."
)
Achievement 2. Description = (
    "id: MGL1HP1C	visible	You came out of
      Hidden Path 1 alive. Great job.",

    "id: MGL1HP2C	visible	You found Hidden
      Path 2. Congratulations."
)

Reporting Achievements to Game Center; Displaying Achievements to Players

You need to display the achievements that the local player has received or is in the progress of receiving, using a graphical user interface.

Use the GKAchievementViewController class.

Game Center can construct built-in achievements screens for your games. All you have to do is to build an iOS application that makes use of view controllers, covered in iOS 4 Programming Cookbook. For the remainder of this section, I assume you have created an application with one view controller inside a navigation controller.

In order to have Game Center construct an achievement screen for your iOS app, follow these steps:

Instances of the GKAchievementViewController class have an important property named achievementDelegate, which is the object that will receive delegate messages from the achievement view controller. You use these delegate methods to dismiss the achievement view controller, among other things.

Let’s take a look at an example where I want to display all achievements for the currently authenticated local player:

- (void)achievementViewControllerDidFinish:
  (GKAchievementViewController *)viewController{
  
  /* We are finished here */
  [self dismissModalViewControllerAnimated:YES];
  
}

- (void) viewDidLoad{
  
  [super viewDidLoad];
  
  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];
  
  [localPlayer authenticateWithCompletionHandler:^(NSError *error) {
    
    if (error == nil){
      
      GKAchievementViewController *controller = 
        [[GKAchievementViewController alloc] init];
      
      [controller setAchievementDelegate:self];
      [self presentModalViewController:controller
                              animated:YES];
      [controller release];
      
    } else {
      NSLog(@"Could not authenticate the local player. %@", error);
    }
    
  }];
  
}

Once you run the app and it loads the view controller that contains this code, you will see results similar to that shown in Figure 1-16.

Figure 1-16. Achievements view controller in iOS Simulator

Creating Achievements in iTunes Connect; Reporting Achievements to Game Center; Retrieving Achievements Information Programmatically

You want to allow multiple players to join the same game and play your game together.

Incorporate matchmaking in your app, as explained in the Discussion section.

One of the most important functionalities provided to iOS developers in Game Center is matchmaking. Matchmaking allows two or more players to play the same game in multiplayer mode at the same time. You can either use Apple’s servers for multiplayer games or host your own server. In this book, we will only cover matchmaking using Apple’s server, for the sake of simplicity.

There are two essential programming activities in a multiplayer game using Game Center:

The first part is perhaps the more difficult one to understand. To make it easier for you, let me paint a rather general picture of how things work in multiplayer mode in Game Center. When your app runs on an iOS device, it must:

Before we jump into coding, please make sure the following conditions have been met:

Let’s get to the most important parts now. Our devices are set up and the provision profiles are set. Now it’s time to develop the core matchmaking and multiplayer functionality into our app. Follow these steps thoroughly and don’t cut corners:

#import <GameKit/GameKit.h>

#import <UIKit/UIKit.h>
#import <GameKit/GameKit.h>

@interface RootViewController_iPhone : UIViewController
  <GKMatchmakerViewControllerDelegate, GKMatchDelegate> {

}

#import <UIKit/UIKit.h>
#import <GameKit/GameKit.h>

@interface RootViewController_iPhone : UIViewController
  <GKMatchmakerViewControllerDelegate, GKMatchDelegate> {
@protected
  GKMatch *acceptedMatch;

  UIButton *buttonSendData;
  UITextView *textViewIncomingData;
}

@property (nonatomic, retain)
  IBOutlet UIButton *buttonSendData;

@property (nonatomic, retain)
  IBOutlet UITextView *textViewIncomingData;

@property (nonatomic, retain)
  GKMatch *acceptedMatch;

- (IBAction)buttonSendDataTapped:(id)sender;

@end

#import "RootViewController_iPhone.h"

@implementation RootViewController_iPhone
@synthesize buttonSendData;
@synthesize textViewIncomingData;
@synthesize acceptedMatch;

- (void)dealloc{
  [acceptedMatch release];
  [buttonSendData release];
  [textViewIncomingData release];
  [textViewIncomingData release];
  [super dealloc];
}

- (void) viewDidLoad{
  [super viewDidLoad];

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  [localPlayer authenticateWithCompletionHandler:^(NSError *error) {

    if (error == nil){

      /* We will write the rest of this code soon */

    } else {
      NSLog(@"Failed to authenticate the player. Error = %@", error);
    }

  }];

}

- (void) setInviteHandler{

  [GKMatchmaker sharedMatchmaker].inviteHandler =
  ^(GKInvite *acceptedInvite, NSArray *playersToInvite) {


  };

}

- (void) setInviteHandler{

  [GKMatchmaker sharedMatchmaker].inviteHandler =
  ^(GKInvite *acceptedInvite, NSArray *playersToInvite) {

    if (acceptedInvite != nil){

      NSLog(@"An invite came through. process it...");

      GKMatchmakerViewController *controller =
        [[[GKMatchmakerViewController alloc]
          initWithInvite:acceptedInvite] autorelease];

      [controller setMatchmakerDelegate:self];
      [self presentModalViewController:controller
                              animated:YES];

    }

    else if (playersToInvite != nil){

      NSLog(@"Game Center invoked our game. process the match...");

      GKMatchRequest *matchRequest =
        [[[GKMatchRequest alloc] init] autorelease];

      [matchRequest setPlayersToInvite:playersToInvite];
      [matchRequest setMinPlayers:2];
      [matchRequest setMaxPlayers:2];


      GKMatchmakerViewController *controller =
        [[[GKMatchmakerViewController alloc]
          initWithMatchRequest:matchRequest] autorelease];

      [controller setMatchmakerDelegate:self];
      [self presentModalViewController:controller
                              animated:YES];
    }
  };

}

- (void) viewDidLoad{
  [super viewDidLoad];

  GKLocalPlayer *localPlayer = [GKLocalPlayer localPlayer];

  [localPlayer authenticateWithCompletionHandler:^(NSError *error) {

    if (error == nil){

      [self setInviteHandler];

      GKMatchRequest *matchRequest = [[GKMatchRequest alloc] init];
      [matchRequest setMinPlayers:2];
      [matchRequest setMaxPlayers:2];

      GKMatchmakerViewController *controller =
        [[GKMatchmakerViewController alloc]
         initWithMatchRequest:matchRequest];

      [controller setMatchmakerDelegate:self];

      [matchRequest release];

      [self presentModalViewController:controller
                              animated:YES];
      [controller release];

    } else {
      NSLog(@"Failed to authenticate the local player %@", error);
    }

  }];

}

- (void)matchmakerViewControllerWasCancelled:
  (GKMatchmakerViewController *)viewController{

  [self dismissModalViewControllerAnimated:YES];

}

/* Matchmaking has failed with an error */
- (void)matchmakerViewController:
  (GKMatchmakerViewController *)viewController
                didFailWithError:(NSError *)error{

  [self dismissModalViewControllerAnimated:YES];

}

/* A peer-to-peer match has been found, the
 game should start */
- (void)matchmakerViewController:
  (GKMatchmakerViewController *)viewController
                    didFindMatch:(GKMatch *)paramMatch{

  [self dismissModalViewControllerAnimated:YES];

  self.acceptedMatch = paramMatch;
  [self.acceptedMatch setDelegate:self];

}

/* Players have been found for a server-hosted game,
 the game should start */
- (void)matchmakerViewController:
  (GKMatchmakerViewController *)viewController
                  didFindPlayers:(NSArray *)playerIDs{

  [self dismissModalViewControllerAnimated:YES];

}

/* The match received data sent from the player. */
- (void)  match:(GKMatch *)match
 didReceiveData:(NSData *)data
     fromPlayer:(NSString *)playerID{

}


/* The player state changed
 (eg. connected or disconnected) */
- (void)  match:(GKMatch *)match
         player:(NSString *)playerID
 didChangeState:(GKPlayerConnectionState)state{

}

/* The match was unable to connect with the
 player due to an error. */
- (void)              match:(GKMatch *)match
 connectionWithPlayerFailed:(NSString *)playerID
                  withError:(NSError *)error{

}

/* The match was unable to be established
 with any players due to an error. */
- (void)    match:(GKMatch *)match
 didFailWithError:(NSError *)error{

}

/* The match received data sent from the player. */
- (void)  match:(GKMatch *)match
 didReceiveData:(NSData *)data
     fromPlayer:(NSString *)playerID{

  NSLog(@"Incoming data from player ID = %@", playerID);

  NSString *incomingDataAsString =
    [[NSString alloc] initWithData:data
                          encoding:NSUTF8StringEncoding];

  NSString *existingText = self.textViewIncomingData.text;

  NSString *finalText =
    [existingText stringByAppendingFormat:@"
%@",
     incomingDataAsString];

  [self.textViewIncomingData setText:finalText];

  [incomingDataAsString release];

}

- (IBAction)buttonSendDataTapped:(id)sender {

  NSString *dataToSend =
    [NSString stringWithFormat:@"Date = %@",
     [NSDate date]];

  NSData *data =
    [dataToSend dataUsingEncoding:NSUTF8StringEncoding];

  [self.acceptedMatch
   sendDataToAllPlayers:data
   withDataMode:GKMatchSendDataReliable
   error:nil];

}

- (void)viewDidUnload{
  self.buttonSendData = nil;
  self.textViewIncomingData = nil;
  [super viewDidUnload];
}

We are all done. Let’s run the app on two iOS devices and see what happens. What I’m going to demonstrate here is running the app on an iPad 2 and an iPhone 4. The iPad 2 version of the app will send an invite to the local player on the iPhone 4 while the app is not even open on the iPhone. Figure 1-18 shows what the iPhone player will see on her device.

Figure 1-18. An invitation from Game Center to initiate multiplayer game

Once the player unlocks her device by sliding the switch to the right, she will see an alert view on her home screen containing the invitation message the iPad player sent when inviting the iPhone player to play the game, as shown in Figure 1-19.

Figure 1-19. Game Center asking the player to start or decline starting the match

Once the match is initialized, both players can press the Send Data button we implemented in our user interface in order to send some data to the player. The data that we are sending at the moment is a string representation of the current date and time for the sake of simplicity, but you can send anything as long as you can get an NSData out of it.

Handling Players’ State Changes in Multiplayer Games; Authenticating the Local Player in Game Center

You want to detect when players in multiplayer mode get disconnected while playing the game.

Implement and handle the match:player:didChangeState: delegate message of the GKMatchDelegate class.

In a multiplayer game, it is important for each player to know the state of the other players in the game. The state in this case could be either connected or disconnected. Let’s take a look at an example.

Suppose you’ve written a racing game and you’ve incorporated matchmaking (see Supporting Multiplayer Games and Matchmaking). Two players connect to each other and start playing the first lap in a tournament. The game is going well until player #2 gets disconnected. At this point, player #1 must be notified by the game that player #2 has been disconnected. The game could then end the match for player #1 and start listening for other invites.

In order to get notified of changes in state of players in a match, implement and handle the match:player:didChangeState: delegate message of the GKMatchDelegate class. The player parameter will contain the player ID whose state has changed, while the didChangeState parameter, which is of type GKPlayerConnectionState, will contain one of the following values:

You can use the expectedPlayerCount instance method of your match object of type GKMatch to find out how many other players your match object requires before it can get started. For instance, if we start a match that needs a minimum and maximum number of two players and then one of the players gets disconnected, the expectedPlayerCount method will return the value of 1, telling us that the match object expects one more player before it can start again. In the following code, assuming we are in a two-player match during which one player gets disconnected, we will stop the match all together:

/* The player state changed
 (eg. connected or disconnected) */
- (void)  match:(GKMatch *)match
         player:(NSString *)playerID
 didChangeState:(GKPlayerConnectionState)state{

  switch (state){

    case GKPlayerStateDisconnected:{

      if ([match expectedPlayerCount] > 0){
        [match disconnect];
      }
      break;

    }
  }

}

Supporting Multiplayer Games and Matchmaking