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

---

Earned or Unearned Achievements

The easiest achievement from Table 4.1 to implement is the com.dragonforged.whackacac.killone achievement. Whenever you’re working with adding a hook for an achievement, the first step is to retrieve a copy of the GKAchievement that will be incremented. Use the method discussed in the section “Adding Achievement Hooks” to grab an up-to-date copy of the achievement.

GKAchievement *killOneAchievement = [[ICFGameCenterManager sharedManager] achievementForIdentifier: @"com.dragonforged.whackacac.killone"];

Next a query is performed to see whether this achievement has already been completed. If it has, there is no need to update it again.

if(![killOneAchievement isCompleted])

Since the Kill One achievement cannot be partially achieved because it is impossible to kill fewer than one cactus, it is incremented to 100% at once. This is done using the reportAchievement:withPercentageComplete: method that was added to theICFGameCenterManager class earlier in the chapter.

[[ICFGameCenterManager sharedManager] reportAchievement:@"com.dragonforged.whackacac.killone" withPercentageComplete:100.00];

Since this achievement is tested and submitted when a cactus is whacked, an appropriate place for it is within the cactusHit: method. The updated cactusHit: method is presented for clarity.

- (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];

GKAchievement *killOneAchievement = [[ICFGameCenterManager sharedManager] achievementForIdentifier: @"com.dragonforged.whackacac.killone"];

if(![killOneAchievement isCompleted])
{
[[ICFGameCenterManager sharedManager]reportAchievement: @"com.dragonforged.whackacac.killone" withPercentageComplete:100.00];
}

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

Partially Earned Achievements

In the previous example, the achievement was either fully earned or not earned at all. The next achievement that will be implemented into Whack-a-Cac is com.dragonforged.whackacac.score100. Unlike the Kill One achievement, this one can be partially progressed, although it is nonstackable between games. The user is required to score 100 points in a single game. The process begins the same way as the preceding example, in that a reference to the GKAchievement object is created.

GKAchievement *score100Achievement = [[ICFGameCenterManager
sharedManager] achievementForIdentifier:
@"com.dragonforged.whackacac.score100"];

A quick test is performed to ensure that the achievement is not already completed.

if(![score100Achievement isCompleted])

After the achievement has been verified as not yet completed, it can be incremented by the appropriate amount. Since this achievement is completed at 100% and is for 100 points tied to the score, there is a 1%-to-one point ratio. The score can be used to substitute for a percentage complete when populating this achievement.

[[ICFGameCenterManager sharedManager]
reportAchievement:@"com.dragonforged.whackacac.score100"
withPercentageComplete:score];

Although this hook could be placed into the cactusHit: method again it makes more sense to place it into the displayNewScore: method since it is dealing with the score. The entire updated displayNewScore: method with the new achievement hook follows for clarity.

- (void)displayNewScore:(float)updatedScore;
{
int scoreInt = score;

if(scoreInt % 10 == 0 && score <= 50)
{
[self spawnCactus];
}

scoreLabel.text = [NSString stringWithFormat: @"%06.0f", updatedScore];

GKAchievement *score100Achievement = [[ICFGameCenterManager sharedManager] achievementForIdentifier: @"com.dragonforged.whackacac.score100"];

if(![score100Achievement isCompleted])
{
[[ICFGameCenterManager sharedManager] reportAchievement: @"com.dragonforged.whackacac.score100" withPercentageComplete:score];
}
}

Since the Score 100 achievement is hidden, it will not appear to the user until the user has completed progress toward it (at least one point). At any time after beginning working on this achievement, the user can see the progress in the Game Center View Controllers, as shown in Figure 4.6.

Figure 4.6 Viewing the partially progressed Score 100 achievement after scoring 43 points in a game; note the completion of the Kill One achievement.

Multiple Session Achievements

In the previous example, the Score 100 achievement required the player to earn the entire 100 points while in a single match. However, there often will be times when it will be required to track a user across multiple matches and even app launches as they progress toward an achievement. The first of the multiple session achievements that will be implemented is the com.dragonforged.whackacac.play5 achievement.

Each time the player completes a round of game play, the com.dragonforged.whackacac.play5 achievement will be progressed. Since the achievement is completed at five games played, each game increments the progress by 20%. This hook will be added to theviewWillDisappear method of ICFGameViewController. As with the previous examples, first a reference to the GKAchievement object is created. After making sure that the achievement isn’t already completed, it can be incremented. A new variable is created to determine the number of matches played, which is the percentage complete divided by 20. The matchesPlayed is then incremented by one, and submitted using reportAchievement:withPercentageComplete: by multiplying matchesPlayed by 20.

-(void)viewWillDisappear:(BOOL)animated
{
GKAchievement *play5MatchesAchievement = [[ICFGameCenterManager sharedManager] achievementForIdentifier: @"com.dragonforged.whackacac.play5"];

if(![play5MatchesAchievement isCompleted])
{
double matchesPlayed = [play5MatchesAchievement percentComplete]/20.0f;

matchesPlayed++;

[[ICFGameCenterManager sharedManager] reportAchievement: @"com.dragonforged.whackacac.play5" withPercentageComplete: matchesPlayed*20.0f];
}

[super viewWillDisappear: animated];
}

Piggybacked Achievements and Storing Achievement Precision

Sometimes, it is possible to piggyback two achievements off of each other, such as the next case when dealing with the Whack 100 and Whack 1000 achievements. Since both of these achievements are tracking the same type of objective (whacks) a more streamlined approach can be taken.

As with the other achievement hooks that have been implemented in this chapter, the first thing that is done is to create a reference to a GKAchievement. In the following example a reference to the larger of the two achievements is used. Since the largest achievement has more objectives to complete than it does percentage, it will be rounded down to the nearest multiple of 10. To help combat this problem, a localKills variable is populated from NSUserDefaults. This system falls apart when the achievement exists on two different devices, but can be further polished using iCloud to store the data (see Chapter 8).

A calculation is also made to determine how many kills Game Center reports (with loss of accuracy). If remoteKills is greater than the localKills, we know that the player either has reinstalled the game or has progressed it on another device. In this event the system will default to the Game Center’s values as to not progress the user backward; otherwise, the local information is used.

This code example can be placed inside the cactusHit: method following the Kill One achievement from earlier in this section. After each hit, the localKill value is increased by one. Two checks are performed to make sure that each achievement is not already completed. Since references to both GKAchievements are not available here, a check of the kills number can be used to substitute the standard isComplete check. After the achievements are submitted, the new local value is stored into the NSUserDefaults for future reference.

GKAchievement *killOneThousandAchievement = [[ICFGameCenterManager sharedManager] achievementForIdentifier: @"com.dragonforged.whackacac.1000whacks"];

double localKills = [[[NSUserDefaults standardUserDefaults] objectForKey:@"kills"] doubleValue];

double remoteKills = [killOneThousandAchievement percentComplete] * 10.0;

if(remoteKills > localKills)
{
localKills = remoteKills;
}

localKills++;

if(localKills <= 1000)
{
if(localKills <= 100)
{
[[ICFGameCenterManager sharedManager] reportAchievement: @"com.dragonforged.whackacac.100whacks" withPercentageComplete:localKills];
}

[[ICFGameCenterManager sharedManager] reportAchievement:@"com.dragonforged.whackacac.1000whacks" withPercentageComplete:(localKills/10.0)];
}

[[NSUserDefaults standardUserDefaults] setObject:[NSNumber numberWithDouble: localKills] forKey:@"kills"];

Timer-Based Achievements

One of the most popular achievements in iOS gaming is to play for a certain amount of time. In Whack-a-Cac com.dragonforged.whackacac.play5Mins is used to track the user’s progress towards five minutes of total gameplay. This particular example exists for the loss-of-accuracy problem that was faced in the Whack 1000 example from earlier in this section, and it can be overcome in the same manner.

To track time, a NSTimer will be created. To determine how often the timer should fire, you will need to determine what 1% of five minutes is.

play5MinTimer = [NSTimer scheduledTimerWithTimeInterval:3.0 target:self selector:@selector(play5MinTick) userInfo:nil repeats:YES];

When the timer fires a new call to a new play5MinTick method is called. If the game is paused or in a gameOver state, the achievement progress is ignored and the method returns. As with the other examples, a reference to the GKAchievement object is created, and a check is performed to see whether it has completed. If this achievement is completed, the timer is invalidated to prevent wasted CPU time. Otherwise, since the timer is firing every three seconds (1% of five minutes), the achievement is progressed by 1%.

- (void)play5MinTick;
{
if(paused || gameOver)
{
return;
}

GKAchievement *play5MinAchievement = [[ICFGameCenterManager sharedManager] achievementForIdentifier: @"com.dragonforged.whackacac.play5Mins"];

if([play5MinAchievement isCompleted])
{
[play5MinTimer invalidate];
play5MinTimer = nil;
return;
}

double percentageComplete = play5MinAchievement.percentComplete + 1.0;

[[ICFGameCenterManager sharedManager] reportAchievement: @"com.dragonforged.whackacac.play5Mins" withPercentageComplete: percentageComplete];
}

Resetting Achievements

There is often a need to reset all achievement progress for a user, more so in development than in production. Sometimes it is helpful to provide users with a chance to take a fresh run at a game or even some sort of prestige mode that starts everything over, but at a harder difficulty. Resetting achievement progress is simple; the following code snippet can be added into the IFCGameCenterManager class to completely reset all achievements to the unearned state. If you are providing this functionality to users, it is a good idea to have several steps of confirmation to prevent accidental resetting.

- (void)resetAchievements
{
[achievementDictionary removeAllObjects];

[GKAchievement resetAchievementsWithCompletionHandler:
^(NSError *error)
{
if(error == nil)
{
NSLog(@"All achievements have been successfully reset");
}

else
{
NSLog(@"Unable to reset achievements: %@", [error localizedDescription]);
}
}];
}