Adding Events and Quests in Your iOS Game

This guide shows you how to save and load a player’s game progress data using the Events and Quests services in an iOS application.

Before you begin

If you haven’t already done so, you might find it helpful to review the quests and events game concepts.

To set up your iOS development environment to use the Events and Quests services, follow the instructions in the Getting Started for iOS guide. You can download the Play Game services iOS SDK from the SDK downloads page page.

Before your game can access events and quests, you must define them first in the Google Play Developer Console.

Submitting an event

You can add code in your game to notify the Events service whenever an event of interest to your game occurs. Examples of events you could capture in your game might include killing enemies, exploring or returning to various game regions, or acquiring a number of in-game items. Typically, you would call the increment method to increment an event’s count by 1 every time the player performs an action or achieves a milestone associated with the event (for example, “Killed one monster”).

The following example shows how you might submit the updated event count to the Events service.

/** Increment the event count when player performs the 'Attack blue monster' action.
 *  @param sender A reference for the object sending the message.
 */
- (IBAction)attackBlue:(id)sender {
    [GPGEvent eventForId:BLUE_MONSTER_EVENT_ID
            completionHandler:^(GPGEvent *event, NSError *error) {
        NSLog(@"Event: %@ Error: %@", event, error);
        if (event) {
            [event increment];
            NSLog(@"BLUE count incremented, now: %llxl", event.count);
        } else {
            NSLog(@"Error while incrementing count: %@", error);
        }
    }];
    NSLog(@"Attacked a blue monster.");
}

Retrieving events

To retrieve the current count value stored in Google's servers for a specific event, call the eventForId method and pass in the event ID. You might do this, for example, if you want to show a player’s in-game statistics or progress from a custom UI in your game.

The following example shows how you might retrieve and display event data in your game.

/** Show a toast with Event details. */
- (IBAction)ShowEvents:(id)sender {
    NSLog(@"---- Showing Event Counts -----");
    NSArray* events = [NSArray arrayWithObjects:  BLUE_MONSTER_EVENT_ID,
            GREEN_MONSTER_EVENT_ID, RED_MONSTER_EVENT_ID, YELLOW_MONSTER_EVENT_ID, nil];
    NSArray* labels = [NSArray arrayWithObjects: @"Blue", @"Green", @"Red", @"Yellow", nil];

    for (int i=0; i < 4; i++) {
        [GPGEvent eventForId:events[i] completionHandler:^(GPGEvent *event, NSError *error) {
            if (event) {
                int count = (int)event.count;
                NSLog(@"%@ Monster: %d", labels[i], count);
            }
        }];
    }
}

Displaying quests

To integrate quests into your game, you should provide players with a user interface (UI) to view the list of available quests. To simplify your development, the Play Games SDK provides a default Quest list UI through the GPGLauncherController that you can use out-of-the-box. The Quest list UI allows players to view details about quests, accept an open quest, and claim rewards for quests they completed.

To bring up the default Quest list UI:

Set up your delegate to implement the GPGQuestListLauncherDelegate interface.
```
@interface AppDelegate ()<GPGQuestListLauncherDelegate>
```

Tell the GPGLauncherController that this class will be its delegate.

[GPGLauncherController sharedInstance].questListLauncherDelegate = self;

You can now open the Quest list UI from within your game.

/** Show the Quest list UI */
- (IBAction)ShowQuests:(id)sender {
    [[GPGLauncherController sharedInstance] presentQuestList];
}

Handling quest acceptance

Your game can begin tracking players' progress on a quest once they accept it. If your game uses the built-in Quest list UI, this is handled by the GPGLauncherController object. The Quest service sends a message via the questListLauncherDidAcceptQuest: delegate method to notify your game when the player accepts a quest from the UI.

If your game is not using the built-in UI, you can accept the quest on the player's behalf via the GPGQuest object's acceptWithCompletionHandler method.

Handling quest completion

To claim a quest reward, your game should first inform the Quest service that the reward has been claimed. Your game can then reward the player with the appropriate in-game items or benefits designated by the rewardData property associated with the quest.

After players accept a quest, make sure to capture their progress in your game by submitting event updates as they perform game actions or achieve milestones towards completing the quest.

When players achieve all the criteria required to complete a quest, they can claim the quest reward from the Quest list UI. If a player makes this selection, your delegate that implements the Quests protocol receives a message that your game can then use to claim the reward and retrieve the reward data.

To handle the message informing your game that a player claimed a quest reward, implement the questListLauncherDidClaimRewardsForQuestMilestone: method for your GPGQuestListLauncherDelegate.

/** Message handler for when the player accepts a reward for a quest.
 *  @param questMilestone An object representing an important progression
 *                        point within the quest.
 */
- (void)questListLauncherDidClaimRewardsForQuestMilestone:(GPGQuestMilestone *)
        questMilestone {
    if (questMilestone.state == GPGQuestMilestoneStateCompletedNotClaimed) {
        [questMilestone claimWithCompletionHandler:^(NSError *error) {
            if (!error) {
                [self.myGame givePlayerRewardItem:questMilestone.rewardData];
                NSLog(@"Quest reward with id %@ has been claimed.",
                        questMilestone.questMilestoneId);
            }
        }];
    }
}