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 find links to download the necessary libraries on the Downloads 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 Game services 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 the default Quest list UI:
-
Set up your delegate to implement the
GPGQuestListLauncherDelegateinterface.@interface AppDelegate ()<GPGQuestListLauncherDelegate> -
Tell the
GPGLauncherControllerthat 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);
}
}];
}
}