Tutorial 21 - Integrating Game Center (Part 3)

21.1 On the Shoulders of Giants...

Juan Belón (@juaxix over on the Codea Forums) has already done a lot of the hard work required to get Game Center up and running on your Codea App. If all you need is to submit scores to a single leaderboard then just follow Juan's instructions at this post. Juan has also provided the ability to play and stop mp3's from a Codea App.

We want to be able to submit scores to multiple leaderboards (Easy, Medium and Hard) and incorporate achievements so we need to add to the code that Juan has generously contributed. To this end we will fork his Game Center class on GitHub.

We will start by updating the Codea Runtime Objective C code.

21.2 Modifications to LuaState

In Xcode, make sure that you are showing the Project Navigator (top left button on the tool bar). Open up the Frameworks group, then Codea -> Backend. In Backend, click on the LuaState.m file. Within this file you will see a method called - (void)create{ }. To this method add the following:

//  Game Center Functions:

    LuaRegFunc(aGameCenter_start);

    LuaRegFunc(aGameCenter_isGameCenterAvailable);

    LuaRegFunc(aGameCenter_showEasyLeaderboard);

    LuaRegFunc(aGameCenter_showMediumLeaderboard);

    LuaRegFunc(aGameCenter_showHardLeaderboard);

    LuaRegFunc(aGameCenter_reportEasyScore);

    LuaRegFunc(aGameCenter_reportMediumScore);

    LuaRegFunc(aGameCenter_reportHardScore);

    LuaRegFunc(aGameCenter_reportAchievementIdentifier);

    LuaRegFunc(aGameCenter_showAchievements);

    LuaRegFunc(aGameCenter_resetAchievements);

//  Play Music

    LuaRegFunc(playMusic);

    LuaRegFunc(stopMusic);

21.3 Modifications to OSCommands

In the same directory as LuaState you will see OSCommands.h and OSCommands.m, click on the header file OSCommands.h and after int alert(struct lua_State *L) add the following:

//  Game Center:

    int aGameCenter_start(struct lua_State *state);

    int aGameCenter_isGameCenterAvailable(struct lua_State *state);

    int aGameCenter_showEasyLeaderboard(struct lua_State *state);

    int aGameCenter_showMediumLeaderboard(struct lua_State *state);

    int aGameCenter_showHardLeaderboard(struct lua_State *state);

    int aGameCenter_reportEasyScore(struct lua_State *state);

    int aGameCenter_reportMediumScore(struct lua_State *state);

    int aGameCenter_reportHardScore(struct lua_State *state);

    int aGameCenter_reportAchievementIdentifier(struct lua_State *state);

    int aGameCenter_showAchievements(struct lua_State *state);

    int aGameCenter_resetAchievements(struct lua_State *state);

  //  Play Music

    int playMusic(struct lua_State *L);

    int stopMusic(struct lua_State *L);

Then in the implementation file, OSCommands.m add the following:

static aGameCenter_Codea *CodeaGameCenter;

int aGameCenter_start(struct lua_State *state){

    NSLog(@"Starting Game Center");

    if (CodeaGameCenter==nil){

        CodeaGameCenter = [[[aGameCenter_Codea alloc] init] autorelease];

    }

    [CodeaGameCenter start];

    return 0;

}

int aGameCenter_isGameCenterAvailable(struct lua_State *state){

    return [CodeaGameCenter isGameCenterAvailable];

}

int aGameCenter_showLeaderboard(struct lua_State *state) {

    [CodeaGameCenter showLeaderboard];

    return 0;

}

int aGameCenter_reportEasyScore(struct lua_State *state) {

    [CodeaGameCenter reportEasyScore:lua_tonumber(state,1)];

    return 0;

}

int aGameCenter_reportMediumScore(struct lua_State *state) {

    [CodeaGameCenter reportMediumScore:lua_tonumber(state,1)];

    return 0;

}

int aGameCenter_reportHardScore(struct lua_State *state) {

    [CodeaGameCenter reportHardScore:lua_tonumber(state,1)];

    return 0;

}

int aGameCenter_reportAchievementIdentifier(struct lua_State *state) {

    [CodeaGameCenter reportAchievementIdentifier:lua_tonumber(state,1)];

    return 0;

}

int aGameCenter_showAchievements(struct lua_State *state) {

    [CodeaGameCenter showAchievements];

    return 0;

}

int aGameCenter_resetAchievements(struct lua_State *state) {

    [CodeaGameCenter resetAchievements];

    return 0;

}

int playMusic(struct lua_State *L){

    [CodeaGameCenter playMusic:lua_tonumber(L,1)];

    return 0;

}

int stopMusic(struct lua_State *L){

    [CodeaGameCenter stopMusic];

    return 0;

}

21.4 Modifications to the aGameCenter_Codea Class

The final change in Xcode is to add the updated version of the aGameCenter_Codea class. You can download the forked version of Juan's code here. Add these two files to the Supporting Files group in the runtime.

	//
	// aGameCenter_Codea.h
	//
	// Created by Juan Belón on 28/05/12
	// Games -> http://www.xixgames.com
	// LGPL - @juaxix - Codea connection!
	//
	// Modified by Reefwing Software on 14/10/12
	// http://www.reefwing.com.au
	// @reefwing on the Codea Forums
	//
	// Version: 1.5
	// - Multiple Leaderboard (Easy, Medium & Hard) access added
	// - Achievements added.
	// 1.6
	// - Modified for universal apps (http://codeatuts.blogspot.com.au/2012/10/tutorial-22-building-universal-app-in.html)
	// - New showLeaderBoard: (int)ident method
	//
	// Licensed under the Apache License, Version 2.0 (the "License");
	// you may not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.
	//
	#import <Foundation/Foundation.h>
	#import <GameKit/GameKit.h>
	#import <AVFoundation/AVAudioPlayer.h>
	@interface aGameCenter_Codea : NSObject <GKLeaderboardViewControllerDelegate, AVAudioPlayerDelegate, GKAchievementViewControllerDelegate>
	{
	bool hasGameCenter;
	bool playing;
	AVAudioPlayer *player;
	}
	- (void) start;
	- (void) authenticateLocalPlayer;
	- (void) registerForAuthenticationNotification;
	- (void) authenticationChanged;
	- (BOOL) isGameCenterAvailable;
	- (void) leaderboardViewControllerDidFinish: (GKLeaderboardViewController *)viewController;
	- (void) showAchievements;
	- (void) achievementViewControllerDidFinish:(GKAchievementViewController *)viewController;
	- (void) resetAchievements;
	- (void) reportAchievementIdentifier: (int) ident;
	- (void) showLeaderboard: (int)ident;
	- (void) showEasyLeaderboard;
	- (void) showMediumLeaderboard;
	- (void) showHardLeaderboard;
	- (void) reportEasyScore:(int) score;
	- (void) reportMediumScore:(int) score;
	- (void) reportHardScore:(int) score;
	- (void) playMusic:(int) songNumber;
	- (void) stopMusic;
	@end

view raw aGameCenter_Codea.h hosted with ❤ by GitHub

	//
	// aGameCenter_Codea.m
	//
	// Created by Juan Belón on 28/05/12
	// Games -> http://www.xixgames.com
	// LGPL - @juaxix - Codea connection!
	//
	// Modified by Reefwing Software on 14/10/12
	// http://www.reefwing.com.au
	// @reefwing on the Codea Forums
	//
	// Version: 1.5
	// - Multiple Leaderboard (Easy, Medium & Hard) access added
	// - Achievements added.
	//
	// Licensed under the Apache License, Version 2.0 (the "License");
	// you may not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.
	//
	#import "aGameCenter_Codea.h"
	#import "SharedRenderer.h"
	@implementation aGameCenter_Codea
	- (id)init
	{
	self = [super init];
	player = [[AVAudioPlayer alloc] init];
	playing = false;
	return self;
	}
	- (void)dealloc
	{
	[player release];
	[super dealloc];
	}
	- (void) start
	{
	//Game Center
	hasGameCenter = false;
	[self authenticateLocalPlayer];
	}
	- (BOOL) isGameCenterAvailable
	{
	// Check for presence of GKLocalPlayer API.
	Class gcClass = (NSClassFromString(@"GKLocalPlayer"));
	// The device must be running running iOS 4.1 or later.
	NSString *reqSysVer = @"4.1";
	NSString *currSysVer = [[UIDevice currentDevice] systemVersion];
	BOOL osVersionSupported = ([currSysVer compare:reqSysVer options:NSNumericSearch] != NSOrderedAscending);
	if (gcClass && osVersionSupported)
	NSLog(@"Game Center is Available");
	else
	NSLog(@"Game Center is not Available");
	return (gcClass && osVersionSupported);
	}
	- (void)authenticateLocalPlayer
	{
	if(![self isGameCenterAvailable])
	{
	hasGameCenter = false;
	return;
	}
	[[GKLocalPlayer localPlayer] authenticateWithCompletionHandler:^(NSError *error)
	{
	if (error == nil)
	{
	[self registerForAuthenticationNotification];
	hasGameCenter = true;
	NSLog(@"Game Center - local player authenticated.");
	}else
	{
	hasGameCenter = false;
	}
	}];
	}
	- (void)registerForAuthenticationNotification
	{
	NSNotificationCenter *nc = [NSNotificationCenter defaultCenter];
	[nc addObserver: self selector:@selector(authenticationChanged) name:GKPlayerAuthenticationDidChangeNotificationName object:nil];
	}
	- (void)authenticationChanged
	{
	if([self isGameCenterAvailable ])
	{
	return;
	}
	if ([GKLocalPlayer localPlayer].isAuthenticated)
	{
	hasGameCenter = true;
	}else
	{
	hasGameCenter = false;
	}
	}
	// Achievement Methods
	- (void) reportAchievementIdentifier: (int) ident
	{
	NSString *identifier;
	// INSERT YOUR ACHIEVEMENT IDENTIFIERS BELOW
	switch (ident)
	{
	case 1:
	identifier = @"Easy Winner";
	break;
	case 2:
	identifier = @"Medium Winner";
	break;
	case 3:
	identifier = @"Hard Winner";
	break;
	case 4:
	identifier = @"Boom";
	break;
	case 5:
	identifier = @"Bad Luck";
	break;
	case 6:
	identifier = @"Decathlon";
	break;
	case 7:
	identifier = @"Centurion";
	break;
	default:
	NSLog(@"Warning Unknown Achievement");
	break;
	}
	NSLog(@"Achievement complete: %@", identifier);
	GKAchievement *achievement = [[GKAchievement alloc] initWithIdentifier: identifier];
	if (achievement)
	{
	achievement.showsCompletionBanner = YES;
	achievement.percentComplete = 100.0;
	[achievement reportAchievementWithCompletionHandler:^(NSError *error)
	{
	if (error != nil)
	{
	NSLog(@"Error in reporting achievements: %@", error);
	}
	}];
	}
	}
	- (void)showAchievements
	{
	GKAchievementViewController *achievements = [[GKAchievementViewController alloc] init];
	if (achievements != nil)
	{
	achievements.achievementDelegate = self;
	[[SharedRenderer renderer] presentViewController: achievements animated: YES completion:nil];
	}
	[achievements release];
	}
	- (void)achievementViewControllerDidFinish:(GKAchievementViewController *)viewController
	{
	[[SharedRenderer renderer] dismissViewControllerAnimated:YES completion:nil];
	[[SharedRenderer renderer] startAnimation];
	}
	- (void) resetAchievements
	{
	// You may want to allow the player to reset their progress on achievements in your game.
	// First, this method clears any locally cached achievement objects created by you.
	// Then, it calls Game Kit to reset the player’s progress stored on Game Center.
	//
	// Clear all locally saved achievement objects - Enter your code to clear locally saved achievements below.
	// YOUR CODE GOES HERE
	// Clear all progress saved on Game Center.
	[GKAchievement resetAchievementsWithCompletionHandler:^(NSError *error)
	{
	if (error != nil)
	// handle the error.
	NSLog(@"Game Center: Error Resetting Achievements - %@", [error localizedDescription]);
	else
	NSLog(@"Game Center - Achievements Reset.");
	}];
	}
	// Leaderboard Methods
	- (void)showLeaderboard: (int)ident
	{
	NSString *identifier;
	// INSERT YOUR ACHIEVEMENT IDENTIFIERS BELOW
	switch (ident)
	{
	case 1:
	identifier = @"Easy Difficulty";
	break;
	case 2:
	identifier = @"Medium Difficulty";
	break;
	case 3:
	identifier = @"Hard Difficulty";
	break;
	default:
	NSLog(@"Warning Unknown Leader Board");
	break;
	}
	GKLeaderboardViewController *leaderBoardCont = [[GKLeaderboardViewController alloc] init];
	if (leaderBoardCont)
	{
	// INSERT YOUR LEADERBOARD IDENTIFIER IN THE LINE BELOW
	leaderBoardCont.category=identifier;
	leaderBoardCont.timeScope=GKLeaderboardTimeScopeToday;
	leaderBoardCont.leaderboardDelegate=self;
	[[SharedRenderer renderer] presentModalViewController:leaderBoardCont animated:YES];
	}
	}
	- (void)showEasyLeaderboard
	{
	GKLeaderboardViewController *leaderBoardCont = [[GKLeaderboardViewController alloc] init];
	if (leaderBoardCont)
	{
	// INSERT YOUR LEADERBOARD IDENTIFIER IN THE LINE BELOW
	leaderBoardCont.category=@"Easy Difficulty";
	leaderBoardCont.timeScope=GKLeaderboardTimeScopeToday;
	leaderBoardCont.leaderboardDelegate=self;
	[[SharedRenderer renderer] presentModalViewController:leaderBoardCont animated:YES];
	}
	}
	- (void)showMediumLeaderboard
	{
	GKLeaderboardViewController *leaderBoardCont = [[GKLeaderboardViewController alloc] init];
	if (leaderBoardCont)
	{
	// INSERT YOUR LEADERBOARD IDENTIFIER IN THE LINE BELOW
	leaderBoardCont.category=@"Medium Difficulty";
	leaderBoardCont.timeScope=GKLeaderboardTimeScopeToday;
	leaderBoardCont.leaderboardDelegate=self;
	[[SharedRenderer renderer] presentModalViewController:leaderBoardCont animated:YES];
	}
	}
	- (void)showHardLeaderboard
	{
	GKLeaderboardViewController *leaderBoardCont = [[GKLeaderboardViewController alloc] init];
	if (leaderBoardCont)
	{
	// INSERT YOUR LEADERBOARD IDENTIFIER IN THE LINE BELOW
	leaderBoardCont.category=@"Hard Difficulty";
	leaderBoardCont.timeScope=GKLeaderboardTimeScopeToday;
	leaderBoardCont.leaderboardDelegate=self;
	[[SharedRenderer renderer] presentModalViewController:leaderBoardCont animated:YES];
	}
	}
	- (void)leaderboardViewControllerDidFinish:(GKLeaderboardViewController *)viewController
	{
	[[SharedRenderer renderer] dismissModalViewControllerAnimated:YES];
	[[SharedRenderer renderer] startAnimation];
	}
	- (void) reportEasyScore:(int) score
	{
	// INSERT YOUR LEADERBOARD IDENTIFIER IN THE LINE BELOW
	GKScore *scoreReporter = [[[GKScore alloc] initWithCategory: @"Easy Difficulty"] autorelease];
	if(scoreReporter)
	{
	scoreReporter.value = score;
	[scoreReporter reportScoreWithCompletionHandler:^(NSError *error)
	{
	if (error != nil)
	{
	// handle the reporting error
	NSLog(@"Game Center: Error Reporting Easy Score - %@", [error localizedDescription]);
	}
	}];
	}
	}
	- (void)reportMediumScore:(int) score
	{
	// INSERT YOUR LEADERBOARD IDENTIFIER IN THE LINE BELOW
	GKScore *scoreReporter = [[[GKScore alloc] initWithCategory: @"Medium Difficulty"] autorelease];
	if(scoreReporter)
	{
	scoreReporter.value = score;
	[scoreReporter reportScoreWithCompletionHandler:^(NSError *error)
	{
	if (error != nil)
	{
	// handle the reporting error
	NSLog(@"Game Center: Error Reporting Medium Score - %@", [error localizedDescription]);
	}
	}];
	}
	}
	- (void)reportHardScore:(int) score
	{
	// INSERT YOUR LEADERBOARD IDENTIFIER IN THE LINE BELOW
	GKScore *scoreReporter = [[[GKScore alloc] initWithCategory: @"Hard Difficulty"] autorelease];
	if(scoreReporter)
	{
	scoreReporter.value = score;
	[scoreReporter reportScoreWithCompletionHandler:^(NSError *error)
	{
	if (error != nil)
	{
	// handle the reporting error
	NSLog(@"Game Center: Error Reporting Hard Score - %@", [error localizedDescription]);
	}
	}];
	}
	}
	// Music Play and Stop Methods
	- (void)playMusic:(int) songNumber
	{
	NSString* resourcePath = [[NSBundle mainBundle] resourcePath];
	NSString* song = [[NSString alloc] initWithString:@""];
	NSError* err;
	switch (songNumber)
	{
	case 1: //menu song
	song = @"/menu.MP3";
	break;
	case 2:
	song = @"/game.MP3";
	break;
	case 3:
	song = @"/winner.MP3";
	default:
	break;
	}
	if ([song isEqualToString:@""])
	{
	return ;
	}
	//NSLog(@"Playing song %d: %@",songNumber,song);
	resourcePath = [resourcePath stringByAppendingString:song];
	//NSLog(@"Path to play: %@", resourcePath);
	//Initialize our player pointing to the path to our resource
	if (playing && player)
	{
	[player stop];
	playing = false;
	}
	player = [[AVAudioPlayer alloc] initWithContentsOfURL:
	[NSURL fileURLWithPath:resourcePath] error:&err];
	if( err )
	{
	//bail!
	NSLog(@"Failed with reason: %@", [err localizedDescription]);
	}
	else
	{
	//set our delegate and begin playback
	player.delegate = self;
	[player prepareToPlay];
	player.numberOfLoops = -1; //One Infinite Loop (music!) ;)
	[player play];
	playing = true;
	}
	}
	- (void)stopMusic
	{
	if (playing)
	{
	[player stop];
	playing = false;
	}
	}
	@end

view raw aGameCenter_Codea.m hosted with ❤ by GitHub

21.5 Modifications to your Codea App

  

Once you start adding the Game Center functionality you wont be able to compile and run your App in Codea anymore (since these functions are only defined in the runtime). Consequently, debug all of your code apart from the Game Center specific parts before you make the following modifications. 

After you are in Xcode and using the runtime, you can still update your Lua code but you need to force the runtime to reload the Lua files into the documents directory. You can do this by changing the version number in the Lua info.plist which can be found in Project.codea. 

This number just needs to be different (not necessarily larger) to what it was the last time you compiled, to force an upload. Alternatively, if you get sick of doing this each run-test cycle (like we did), you can go into the CodifyAppDelegate.m file, find the - (BOOL) migrateProjectAtPath:(NSString*)path toPath:(NSString*)destPath method and comment out the following code as shown below.
  

// NSString* oldVersion = [self versionForProjectAtPath:destPath];

// NSString* newVersion = [self versionForProjectAtPath:path];

// if ([oldVersion isEqualToString:newVersion]) 

//    {

//        return YES;

//    }

Should you need to add sprites, you can save these directly into the dropbox folders in the runtime but you may need to do a clean build (select Product from the menu bar and then Clean) before Xcode will see them.

As part of the Game Center update of MineSweeper (v1.5) we took the opportunity to tweak the code based on feedback from the Codea Forum. In particular:

1. There is a new MineSweeper logo on the Menu screen courtesy of @derhannes (you can see their web site at: http://www.boba-soft.com).
2. The falling mines on the Menu Screen now start dropping from above the screen which makes the animation look smoother. Thanks to @Fred for this suggestion.
3. The textBox used to enter the players name, if a new high score is achieved, now handles a changing orientation (e.g. Portrait to Landscape). Thanks to @West for finding this bug.

Once you have added all the code above, the actual Game Center implementation in Lua is very simple. In the Setup() function in Main add the following code:

-- Initialise Game Center if it is available (requires a device running iOS 4.1
-- or later and the App needs to be running within the Codea run time).
    
    aGameCenter_start()
    if aGameCenter_isGameCenterAvailable() then
        print("Game Center Started.")
    else
        print("Game Center not available")
    end

Then you just need to report your scores and achievements as they happen. For example in MineSweeper when the game is won we do the following achievement checks:

-- Check if any Achievements were completed once game
-- has been won.
        
        if gameDifficulty == stateEasy then
            if readLocalData("easyWinner") == nil then
                saveLocalData("easyWinner", "YES")
                aGameCenter_reportAchievementIdentifier(1)
                print("Easy Winner Achievement.")
            end
        end
        
        if gameDifficulty == stateMedium then
            if readLocalData("mediumWinner") == nil then
                saveLocalData("mediumWinner", "YES")
                aGameCenter_reportAchievementIdentifier(2)
                print("Medium Winner Achievement.")
            end
        end
        
        if gameDifficulty == stateHard then
            if readLocalData("hardWinner") == nil then
                saveLocalData("hardWinner", "YES")
                aGameCenter_reportAchievementIdentifier(3)
                print("Hard Winner Achievement.")
            end
        end
        
        if readLocalData("gamesPlayed") == nil then
            gamesPlayed = 0
        else
            gamesPlayed = readLocalData("gamesPlayed")
        end
        
        gamesPlayed = gamesPlayed + 1
        saveLocalData("gamesPlayed", gamesPlayed)
        if gamesPlayed == 10 then
            if readLocalData("decathlon") == nil then
                saveLocalData("decathlon", "YES")
                aGameCenter_reportAchievementIdentifier(6)
                print("Decathlon Achievement.")
            end
        end
        
        if gamesPlayed == 100 then
            if readLocalData("centurion") == nil then
                saveLocalData("centurion", "YES")
                aGameCenter_reportAchievementIdentifier(7)
                print("Centurion Achievement.")
            end
        end

To save high scores onto the relevant leader board we updated the saveHighScore function as shown below.

function saveHighScore(d)
    
    -- Build the high score data into a string which is saved
    -- using saveLocalData(key, value). Also save gameTime as
    -- the score on Game Center for the appropriate leader board
    -- (easy, medium or hard).
    --
    -- n = playerName
    -- t = gameTime
    -- d = os.date() [current date] not used in this version
    
    playerName = textBox.text
    print("New High Score by: "..playerName)
    
    local hsDataString = string.format("return {\"%s\", %d}", playerName, gameTime)
    
    if gameDifficulty == stateEasy then
        saveLocalData("easyHighScore", hsDataString)
        aGameCenter_reportEasyScore(gameTime)
    elseif gameDifficulty == stateMedium then
        saveLocalData("mediumHighScore", hsDataString)
        aGameCenter_reportMediumScore(gameTime)
    elseif gameDifficulty == stateHard then
        saveLocalData("hardHighScore", hsDataString)
        aGameCenter_reportHardScore(gameTime)
    end
    
    hideKeyboard()
    highScoreSaved = true
    
end