iOS Components and Frameworks: Understanding the Advanced Features of the iOS SDK (2014)

Chapter 3. Leaderboards

Leaderboards have become an important component of nearly every mobile game, as well as having numerous applications outside of gaming. Leveraging Game Center to add leaderboards makes it easier than it has ever been in the past to include them in an iOS app. Although leaderboards have been around almost as long as video games themselves—the first high-score list appeared in 1976—they have more recently become critical parts of a social gaming experience. In this chapter you will learn how to add a full-featured leaderboard to a real-world game, from setting up the required information in iTunes Connect to displaying the leaderboard using GKLeaderboardViewController.

Whack-a-Cac

In this chapter and in Chapter 4, “Achievements,” the same sample game will be used. It is important that you are familiar with the game itself so that you can remove the complexity of it from the process of integrating Game Center. Whack-a-Cac was designed to use minimal code and be simple to learn, so the game can act as a generic placeholder for whatever app you are integrating Game Center into. If you already have an app that you are ready to work with, skip this section and follow along with your existing project.

Whack-a-Cac, as shown in Figure 3.1, is a simple whack-a-mole type of game. Cacti will pop up and you must tap them before the timer fires and they go back into the sand dunes. As the game progresses it continues to get more difficult, and after you have missed five cacti the game ends and you are left with a score. The game itself is controlled through ICFGameViewController. Cacti can appear anywhere along the x-axis and on one of three possible rows on the y-axis. The player will have two seconds from the time a cactus appears to tap it before it goes back down and the player is deducted a life. Up until a score of 50, every 10 cacti that are hit will increase the maximum number shown at once by one. The game can also be paused and resumed.

Figure 3.1 A first look at Whack-a-Cac, the game that is used for the Game Center chapters of this book.

Before you can dig into the game-specific code, attention must first be paid to the home screen of the game. IFCViewController.m will not only handle launching the gameplay but also enable the user to access the leaderboards as well as the achievements. The Game Center-specific functionality of this class is discussed in detail later in this chapter, but for the time being the focus should be on the play: method. When a new game is created, IFCViewController simply allocs and inits a new copy of IFCGameViewController and pushes it onto the navigation stack. The rest of the game will be handled by that class.

Whack-a-Cac is a very simplified example of an iOS game. It is based on a state engine containing three states: playing, paused, and game over. While the game is playing, the engine will continue to spawn cacti until the user runs out of life and enters the game-over state. The user can pause the game at any time by tapping the pause button in the upper-left corner of the screen. To begin, direct your attention to the viewDidLoad: method.

- (void)viewDidLoad
{
[[ICFGameCenterManager sharedManager] setDelegate: self];

score = 0;
life = 5;
gameOver = NO;
paused = NO;

[super viewDidLoad];

[self updateLife];

[self spawnCactus];
[self performSelector:@selector(spawnCactus) withObject:nil afterDelay:1.0];
}

On the first line ICFGameCenterManager has its delegate set to self, which is covered in depth later in this section. During the viewDidLoad execution, a few state variables are set. First the score is reset to zero along with the life being set to five. The next requirement is setting two Booleans that represent the current state of the game; since the game starts with gameplay on launch, both gameOver and paused are set to NO. A method named updateLife is called. Although this is discussed later in this section, for now just note that it handles rendering the player’s lives to the upper right of the screen, as shown in Figure 3.1. The final initialization step is to spawn two cacti at the start of the game. One is spawned instantly and the other is delayed by one second.

Spawning a Cactus

One of the most important functions in IFCGameViewController is spawning the actual cacti to the screen. In the viewDidLoad method spawnCactus was called twice; turn your attention to that method now. In a state-based game the first thing that should be done is to check to make sure you are in the correct state. The first test that is run is a gameOver check; if the game has ended, the cactus should stop spawning. The next check is a pause test; if the game is paused, you don’t want to spawn a new cactus either, but when the game is resumed you want to start spawning again. The test performed on the paused state will retry spawning every second until the game is resumed or quit.

if(gameOver)
{
return;
}

if(paused)
{
[self performSelector:@selector(spawnCactus) withObject:nil afterDelay:1];

return;
}

If the method has passed both the state checks, it is time to spawn a new cactus. First the game must determine where to randomly place the object. To randomly place the cactus in the game, two random numbers are generated, the first for the row to be spawned in, followed by the x-axis location.

int rowToSpawnIn = arc4random()%3;
int horizontalLocation = (arc4random()%1024);

To create a more interesting gaming experience, there are three different images for the cactus. With each new cactus spawned, one image is randomly selected through the following code snippet:

int cactusSize = arc4random()%3;
UIImage *cactusImage = nil;

switch (cactusSize)
{
case 0:
cactusImage = [UIImage imageNamed:
@"CactusLarge.png"];
break;
case 1:
cactusImage = [UIImage imageNamed: @"CactusMed.png"];
break;
case 2:
cactusImage = [UIImage imageNamed:
@"CactusSmall.png"];
break;
default:
break;
}

A simple check is performed next to make sure that the cactus is not being drawn off the right side of the view. Since the x-axis is calculated randomly and the widths of the cacti are variable, a simple if statement tests to see whether the image is being drawn too far right and if so moves it back to the edge.

if(horizontalLocation > 1024 - cactusImage.size.width)
horizontalLocation = 1024 - cactusImage.size.width;

Whack-a-Cac is a depth- and layer-based game. There are three dunes, and a cactus should appear behind the dune for the row it is spawned in but in front of dunes that fall behind it. The first step in making this work is to determine which view the new cactus needs to fall behind. This is done using the following code snippet:

UIImageView *duneToSpawnBehind = nil;

switch (rowToSpawnIn)
{
case 0:
duneToSpawnBehind = duneOne;
break;
case 1:
duneToSpawnBehind = duneTwo;
break;
case 2:
duneToSpawnBehind = duneThree;
break;
default:
break;
}

Now that the game knows where it needs to layer the new cactus, a couple of convenience variables are created to increase the readability of the code.

float cactusHeight = cactusImage.size.height;
float cactusWidth = cactusImage.size.width;

All the important groundwork has now been laid, and a new cactus can finally be placed into the game view. Since the cactus will act as a touchable item, it makes sense to create it as a UIButton. The frame variables are inserted, which cause the cactus to be inserted behind the dune and thus be invisible. An action is added to the cactus that calls the method cactusHit:, which is discussed later in this section.

UIButton *cactus = [[UIButton alloc] initWithFrame:CGRectMake(horizontalLocation, (duneToSpawnBehind.frame.origin.y), cactusWidth, cactusHeight)];

[cactus setImage:cactusImage forState: UIControlStateNormal];

[cactus addTarget:self action:@selector(cactusHit:) forControlEvents:UIControlEventTouchDown];

[self.view insertSubview:cactus belowSubview:duneToSpawnBehind];

Now that a cactus has been spawned, it is ready to be animated up from behind the dunes and have its timer started to inform the game when the user has failed to hit it within two seconds. The cactus will slide up from behind the dune in a 1/4th-second animation using information about the height of the cactus to make sure that it ends up in the proper spot. A two second timer is also begun that will fire cactusMissed:, which is discussed in the “Cactus Interaction” section.

[UIView beginAnimations: @"slideInCactus" context:nil];
[UIView setAnimationCurve: UIViewAnimationCurveEaseInOut];
[UIView setAnimationDuration: 0.25];

cactus.frame = CGRectMake(horizontalLocation, (duneToSpawnBehind.frame.origin.y)-cactusHeight/2, cactusWidth, cactusHeight);

[UIView commitAnimations];

[self performSelector:@selector(cactusMissed:) withObject:cactus afterDelay:2.0];

Cactus Interaction

There are two possible outcomes of a cactus spawning: Either the user has hit the cactus within the two-second limit or the user has failed to hit it. In the first scenario cactusHit: is called in response to a UIControlEventTouchDown on the cactus button. When this happens, the cactus is quickly faded off the screen and then removed from the superView. Using the option UIViewAnimationOptionsBeginFromCurrentState will ensure that any existing animations on this cactus are cancelled. The score is incremented by one anddisplayNewScore: is called to update the score on the screen; more on that later in this section. After a cactus has been hit, a key step is spawning the next cactus. This is done in the same fashion as in viewDidLoad but with a randomized time to create a more engaging experience.

- (IBAction)cactusHit:(id)sender;
{
[UIView animateWithDuration:0.1
delay:0.0
options: UIViewAnimationCurveLinear |
UIViewAnimationOptionBeginFromCurrentState
animations:^
{
[sender setAlpha: 0];
}
completion:^(BOOL finished)
{
[sender removeFromSuperview];
}];

score++;

[self displayNewScore: score];

[self performSelector:@selector(spawnCactus) withObject:nil afterDelay:(arc4random()%3) + .5];
}

Two seconds after any cactus are spawned, the cactusMissed: method will be called, even on cacti that have been hit. Since this method is called regardless of whether it has been hit already, it is important to provide a state check. The cactus was removed from the superView when it was hit, and therefore it will no longer have a superView. A simple nil check and a quick return prevent the user from losing points for cactus that were successfully hit.

You also don’t want to penalize the player for pausing the game, so while the game is in the pause state, the user should not lose any life. If the method has gotten this far without returning, you know that the user has missed a cactus and needs to be penalized. As with the cactusHit:method, the game still needs to remove this missed cactus from the superView and start a timer to spawn a replacement. In addition, instead of incrementing the score, you need to decrement the user’s life, and a call to updateLife is performed to update the display.