Tutorial 30 - Codea v1.5.2: Objective C Add On, Game Center

Figure 0. iOS Dev Center

30.1 Overview

CodeaAddon is an experimental protocol for adding native extensions to exported Codea projects. You must deal with Lua directly to register your functions and globals. This protocol should be considered alpha and is subject to change in future Codea releases.As with the previous tutorial on iAds, we have provided a lot of background on Game Center in these tutorials:

1. Tutorial 19 - Integrating Game Centre (Part 1); 
2. Tutorial 20 - Integrating Game Centre (Part 2); 
3. Tutorial 21 - Integrating Game Center (Part 3).

Have a look at the above to refresh your knowledge on what is required from an iTunes Connect perspective as we will only cover that area briefly in this tutorial.

Figure 1. Find out the Bundle Identifier for your App.

30.2 Registering your Application in iTunes Connect

In order to test your app's Game Center functionality you need to register an app ID associated with this app which enables Game Center. The association is done via the bundle identifier of your app (Figure 1). Click on the app title in the top left of the project navigator screen in Xcode to bring up this screen. Make sure that you have selected the "Summary" tab. Write down the bundle identifier shown, we will need this shortly.

Figure 2. Set up a new App ID for your app.

Log into your apple developer account, go to the iOS Dev Center (Figure 0) and select the Certificates, Identifiers & Profiles link on the right hand side of the page. Select a name for your app ID (pick something you can remember e.g. we used AudioDemoAppID) and fill in the App ID Suffix bundle identifier. This is the critical step which will link your app to the configuration in iTunes Connect. Use the bundle identifier that you wrote down earlier. Click "confirm" and then "submit".

Figure 3. Associate your bundle identifier with the App ID.

Head back to the iOS Dev Center (Figure 0) and this time click on iTunes Connect link in the top right of the page. You will be asked to sign in again, do so and then click on the Manage your Apps link (Figure 4).

Figure 4. iTunes Connect

On the Manage your Apps page (Figure 5), click on the "Add New App" button at the top left of the screen. Click on iOS App on the next screen.

Figure 5. Manage your Apps

Fill in the app name, SKU number (this can be any unique identifier, we normally use the date), and then select the App ID that you just created for the bundle identifier (Figure 6). Click "Continue" when you are done.

Figure 6. iTunes Connect App Information.

Fill in all the meta data (have a look at the earlier tutorials if you get stuck) and save the configuration. When you are done (Figure 7), we can enable Game Center for your app. Click on the "Manage Game Center" button on the right hand side of the page (Figure 7).

Figure 7. Metadata addition complete.

Click on the button that says "Enable for Single Game" and then either configure some achievements and leader boards or just click "Done". We can now test our exported app once we have included the Game Center add on.

Figure 8. Adding the GameKit Framework.

30.3 Add the GameKit Framework to Your App

Fire up Xcode and load the exported version of your Codea application (See Tutorial 27). Click on the imported project file at the top of the project navigator then in the Build Phases tab, scroll down to the link binary with libraries area and select the drop down arrow. Click on the "+" button below your existing frameworks to add a new framework. Find GameKit and click on "Add"

30.4 Changes to your Exported AppDelegate Files

All of the source code files are provided at the end of this tutorial. You need to update AppDelegate.h as follows:

//
// AppDelegate.h
// AudioDemo
//
// Used to demonstrate the audio, game center and iAds add on libraries
//
// Created by Reefwing Software on Sunday, 14 April 2013
// Copyright (c) Reefwing Software. All rights reserved.
//

    #import <UIKit/UIKit.h>
    #import "AudioAddOn.h"
    #import "IAdsAddOn.h"
    #import "GameCenterAddOn.h"

    @class CodeaViewController;

    @interface AppDelegate : UIResponder <UIApplicationDelegate>

    @property (strong, nonatomic) IAdsAddOn *iAdsAddOn;
    @property (strong, nonatomic) AudioAddOn *audioAddOn;
    @property (strong, nonatomic) GameCenterAddOn *gameCenterAddOn;
    @property (strong, nonatomic) UIWindow *window;
    @property (strong, nonatomic) CodeaViewController *viewController;

@end

And AppDelegate.mm, should now look like:

//
// AppDelegate.mm
// AudioDemo
//
// Created by Reefwing Software on Sunday, 14 April 2013
// Copyright (c) Reefwing Software. All rights reserved.
//

#import "AppDelegate.h"
#import "CodeaViewController.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

    self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
    self.viewController = [[CodeaViewController alloc] init];

    // Create and add our AudioAddOn to Codea

    self.audioAddOn = [[AudioAddOn alloc] init];
    [self.viewController registerAddon: self.audioAddOn];

    // Create and add our iAdsAddOn to Codea

    self.iAdsAddOn = [[IAdsAddOn alloc] init];
    [self.viewController registerAddon: self.iAdsAddOn];

    // Create and add our GameCenterAddOn to Codea

    self.gameCenterAddOn = [[GameCenterAddOn alloc] init];
    [self.viewController registerAddon: self.gameCenterAddOn];

    NSString* projectPath = [[[NSBundle mainBundle] bundlePath]    stringByAppendingPathComponent:@"AudioDemo.codea"];

    [self.viewController loadProjectAtPath:projectPath];

    self.window.rootViewController = self.viewController;
    [self.window makeKeyAndVisible];

    return YES;

}

- (void)applicationWillResignActive:(UIApplication *)application
{

}

- (void)applicationDidEnterBackground:(UIApplication *)application
{

}

- (void)applicationWillEnterForeground:(UIApplication *)application
{

}

- (void)applicationDidBecomeActive:(UIApplication *)application
{ 

}

- (void)applicationWillTerminate:(UIApplication *)application
{

}

@end

Obviously there is no need to register the iAds and Audio add ons if you are just using Game Center. We have just left these in to demonstrate how you can stack add ons.

Figure 9. If you try to show Achievements or Leaderboards with none set up in iTunes Connect, you will see this screen.

30.5 The Game Center Add On

You need to add the GameCenterAddOn.h and GameCenterAddOn.m files to your project (plus the other iAds and Audio add on classes if you are using them). These are available below.

To do this, right click on the Addons folder in the project navigator and select Add files to "YourProjectName"... Navigate to where ever you saved these files and select them.

This Game Center Add On will make four new functions available in your Lua code:

• gameCenterStart(); 
• showLeaderBoardWithIdentifier(int ident); 
• showAchievementsView(); and
• playerIsAuthenticated;

You need to call gameCenterStart() first as your game must authenticate a local player before you can use any Game Center classes. 

Figure 10. You may need to sign in the first time you try to authenticate a player.

If you want to add more Game Center functionality the just follow the pattern in the add on. For example, if you want to add a save score function then, in GameCenterAddOn.h add:

static int saveScore(struct lua_State *state);

Then in GameCenterAddOn.m add/modify:

// Add to method

- (void)codea:(CodeaViewController*)controller didCreateLuaState:(struct lua_State*)L
{
    ...
    lua_register(L, "saveScore", saveScore);
    ...
}

// New Objective C method

- (void) saveNewScore: (int) score
{
    // INSERT YOUR LEADERBOARD IDENTIFIER IN THE LINE BELOW
    // Replace "Easy Difficulty" with your identifier from iTunes Connect

    GKScore *scoreReporter = [[GKScore alloc] initWithCategory: @"Easy Difficulty"];

    if (scoreReporter)
    {
        scoreReporter.value = score;

        [scoreReporter reportScoreWithCompletionHandler: ^(NSError *error)
        {
            if (error != nil)
            {
                // handle the reporting error

                NSLog(@"Game Center: Error Saving Score - %@", [error localizedDescription]);
            }
        }];   
    }
}

// New C function

static int saveScore(struct lua_State *state)
{
    [gameCenterAddOnInstance saveNewScore: lua_tonumber(state, 1)];

    return 0;
}

Then in your Lua code you can use saveScore(yourNewScore).

Figure 11. Player Authenticated.

30.6 Download the Code

Tutorial 29 - Codea v1.5.2: Objective C Add On, iAds

Figure 0. Codea implementing iAds - showAdFromTop()

29.1 Overview

CodeaAddon is an experimental protocol for adding native extensions to exported Codea projects. You must deal with Lua directly to register your functions and globals. This protocol should be considered alpha and is subject to change in future Codea releases.

With that disclaimer out of the way, let's have a look at what we can do with this new functionality. We have previously done tutorials to add Game Center and iAd functionality using the old runtime but with the great new export to Xcode functionality, this is no longer the best way to skin that particular cat.

You may want to re-read our previous tutorial on implementing iAds in Codea as we won't cover the same background in this tutorial.

We will build on the previous tutorial which uses the audio add on. This has the added benefit of showing how you can stack a number of add ons to the same project.

Note that before you start adding advertising support to your applications available on iTunes, you must first agree to the iAd Network agreement. Further, you must explicitly enable iAd for each application in iTunes Connect. As a part of the iAd Network, you control the kinds of ads that are delivered to your application. We don't need to do this to test it in the simulator though.

Figure 1. Add the iAd Framework to your App

29.2 Add the iAd Framework to your App

Fire up Xcode and load the exported version of your Codea application (See Tutorial 27). Click on the imported project file at the top of the project navigator then in the Build Phases tab, scroll down to the link binary with libraries area and select the drop down arrow. Click on the "+" button below your existing frameworks to add a new framework. Find iAds and click on "Add" (Figure 1).

29.3 Update the AppDelegate Files

In the AppDelegate we need to register our new add on classes. The new AppDelegate.h file now looks like:


//
//  AppDelegate.h
//  AudioDemo
//
//  Used to demonstrate the audio add on and iAds add on libraries
//
//  Created by Reefwing Software on Sunday, 14 April 2013
//  Copyright (c) Reefwing Software. All rights reserved.
//

#import <UIKit/UIKit.h>
#import "AudioAddOn.h"
#import "IAdsAddOn.h"

@class CodeaViewController;

@interface AppDelegate : UIResponder <UIApplicationDelegate>

@property (strong, nonatomic) IAdsAddOn *iAdsAddOn;
@property (strong, nonatomic) AudioAddOn *audioAddOn;
@property (strong, nonatomic) UIWindow *window;
@property (strong, nonatomic) CodeaViewController *viewController;

@end


And similarly to what we had in the previous tutorial AppDelegate.mm now looks like:


//
//  AppDelegate.mm
//  AudioDemo
//
//  Created by Reefwing Software on Sunday, 14 April 2013
//  Copyright (c) Reefwing Software. All rights reserved.
//

#import "AppDelegate.h"
#import "CodeaViewController.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
    self.viewController = [[CodeaViewController alloc] init];
    
    //  Create and add our AudioAddOn to Codea
    
    self.audioAddOn = [[AudioAddOn alloc] init];
    [self.viewController registerAddon: self.audioAddOn];
    
    //  Create and add our iAdsAddOn to Codea
    
    self.iAdsAddOn = [[IAdsAddOn alloc] init];
    [self.viewController registerAddon: self.iAdsAddOn];
    
    NSString* projectPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingPathComponent:@"AudioDemo.codea"];
    
    [self.viewController loadProjectAtPath:projectPath];
    
    self.window.rootViewController = self.viewController;
    [self.window makeKeyAndVisible];
    
    return YES;
}

- (void)applicationWillResignActive:(UIApplication *)application
{
}

- (void)applicationDidEnterBackground:(UIApplication *)application
{
}

- (void)applicationWillEnterForeground:(UIApplication *)application
{
}

- (void)applicationDidBecomeActive:(UIApplication *)application
{
}

- (void)applicationWillTerminate:(UIApplication *)application
{
}

@end

29.4 The iAds Add On

Our iAds add on implements two internal booleans, isBannerVisible and showBannerFromTop. Hopefully the use of these should be fairly obvious. We also register three new functions for use within Codea:

1. showAdFromTop();
2. showAdFromBottom(); and
3. hideAd()

Our example project demonstrates the use of all 3 of these functions. We start by displaying Ads from the top of the page (once the ad has been loaded from the ad server). We hide ads when the play button is tapped and then show them from the bottom when the stop button is tapped.

In the simulator apple will send you ad errors regularly (e.g. Ad inventory unavailable) to make sure that your code can handle this. Your app will get rejected if it displays an empty ad banner so the add on takes care of this situation. When displaying the ad banner, it will slide down from the top or up from the bottom depending on which function that you have used. Similarly hideAd() will animate the ad sliding above or below the screen depending on the state of the boolean showBannerFromTop.

Figure 2. Codea implementing iAds - showAdFromBottom()

This example add on only handles ads for an iPad in portrait orientation. We have included device detection macros in IAdsAddOn.h, just remove the comment slashes if you want to use these to position your Ads. To handle different orientations and devices update the banner view frame variables in the two methods:

1. - (void)showBannerViewAnimated:(BOOL)animated; and
2. - (void)hideBannerViewAnimated:(BOOL)animated.

If you don't want the banner views to slide to the new position then set animated = NO for the above two methods.

29.5 Download the Code

The complete code listing is available below.

Tutorial 28 - Codea v1.5.2: Objective C Add On, Audio

Figure 0. Codea Audio Player

28.1 Overview

CodeaAddon is an experimental protocol for adding native extensions to exported Codea projects. You must deal with Lua directly to register your functions and globals. This protocol should be considered alpha in version 1.5.2 and is subject to change in future Codea releases. If the protocol changes we will update the tutorial to reflect this.

As our first example we will demonstrate how to play an mp3 file from within Codea. iOS provides a number of mechanisms for implementing audio playback. The easiest technique from the perspective of the application developer is to use the AVAudioPlayer class which is part of the AV Foundation Framework. Apple recommends that you use this class for audio playback unless you are playing audio captured from a network stream or require very low I/O latency.

Upon instantiating an AVAudioPlayer class, the playback of audio may be controlled and monitored via the methods and properties available. Play, pause and stop methods may be used to control playback and the volume property may be used to adjust the volume level. The playing property may be used to determine whether or not the AVAudioPlayer object is currently playing audio. Using an audio player you can:

• Play sounds of any duration
• Play sounds from files or memory buffers
• Loop sounds
• Play multiple sounds simultaneously, one sound per audio player, with precise synchronisation
• Control relative playback level, stereo positioning, and playback rate for each sound you are playing
• Seek to a particular point in a sound file, which supports such application features as fast forward and rewind
• Obtain data you can use for playback-level metering

The AV Foundation framework supports the playback of a variety of different audio formats and codecs including both software and hardware based decoding. Codecs and formats currently supported are as follows:

• AAC (MPEG-4 Advanced Audio Coding)
• ALAC (Apple Lossless)
• AMR (Adaptive Multi-rate)
• HE-AAC (MPEG-4 High Efficiency AAC)
• iLBC (internet Low Bit Rate Codec)
• Linear PCM (uncompressed, linear pulse code modulation)
• MP3 (MPEG-1 audio layer 3)
• µ-law and a-law

Figure 1. Adding the AVFoundation Framework

You can optionally implement a delegate to handle interruptions (such as an incoming phone call), or if required update the user interface when a sound has finished playing.

28.2 Add the AVFoundation Framework to your App

Since the AVAudioPlayer class is part of the AV Foundation framework, it will be necessary to add this framework to the project. Fire up Xcode and load the exported version of your Codea application (See Tutorial 27). Click on the imported project file at the top left of the project navigator then in the Build Phases tab, scroll down to the link binary with libraries area and select the drop down arrow. Click on the "+" button below your existing frameworks to add a new framework. Find AVFoundation framework and click on "Add" (Figure 1).

Figure 2. MP3 File added to the Resource Group

28.3 Add the MP3 file to your Project

Any mp3 files that you want to play in your app need to be included in your project bundle. Adding these is simple. For our tutorial we generated a simple loop using Garage Band and then exported it to an mp3 file. Locate your mp3 and drag it from Finder to the Resources Group (folder) in the the Project Navigator of Xcode (Figure 2). We added a sub folder called Music (right click on the Resources Group and add a new Group) to contain the mp3 file but that is optional.

Figure 3. Adding a new Objective-C class.

28.4 Create our Custom Audio Add On Class

To create our new AudioAddOn class, right click on the Addons Group and select New File... from the pop up menu. Click on Cocoa Touch under iOS and make sure that Objective-C class has been selected (Figure 3), then click on Next.

Select Subclass of type NSObject and call the Class AudioAddOn. The two check boxes (Targeted for iPad and With XIB for user interface) should be greyed out. Click on Next, and then click on Create. Two new files will be added to the Addons Group, AudioAddOn.h and AudioAddOn.m.

The header file for our AudioAddOn class is mostly straight forward. We import the AVFoundation framework which we added above and the CodeaAddon class. AudioAddOn conforms to both the CodeaAddon and AVAudioPlayerDelegate protocols. We define a variable called audioAdOnInstance, which allows us to access Objective C methods from within our C functions playMusic() and stopMusic().

In the initialisation of this class we create our audio player object and assign our mp3 file to it. We also pre-buffer the mp3 file and set the number of loops to be infinite (by assigning a negative integer). At the end we assign audioAdOnInstance to self.

Some of the most used AVAudioPlayer delegate methods have been included, but we don't use them in this tutorial. The code is shown at the end of the tutorial.

28.5 Modifications to the Application Delegate

There are only minor changes to the Application Delegate files. We import our add on in the header file and create an instance variable which points to it (called audioAddOn).

In AppDelegate.mm we instantiate our add on class and then register the add on so we can use it in the Lua code.

To play your mp3 file from within your Lua code just call playMusic() and to stop it, call stopMusic(). Too easy!

Tutorial 27 - Codea v1.5.2: Export to Xcode

Figure 1. Tap & Hold the Project Icon.

27.1 Exporting to Xcode is Simple

The team at Two Lives Left continue to innovate. The latest version of Codea includes an export to Xcode function which is so simple to use that you can now submit to the App store without knowing any Objective C at all. Previously, incorporating your Lua code into the Codea runtime was something of an arcane art (see our earlier tutorial on submitting an app to the Apple App Store). Now, it is a matter of a few taps. This latest addition really rounds out Codea as the only development environment that you need.

Figure 2. Check the Export Settings

Loading your Codea apps into Xcode is useful for a couple of reasons:

1. To submit apps to the App Store, this is a necessary interim step;
2. To add additional functionality which isn't currently available in Codea (e.g. iAds, Game Center, creating a universal app - albeit most of this can be done in Codea, audio support, or hooking into some other Objective C methods). We will discuss this in the next tutorial.

Figure 3. Add a Custom Icon

Figure 4. Select an icon from your Photo Library

Figure 5. Tap on the selected icon

Once you are ready to export an app to Xcode, follow the following steps:

1. If you want to use a custom icon for your app, you can either attach this as part of the export process or do it later in Xcode. Assuming you want to include it in the export package, you will need to have it completed and stored in your iPad photo library before you start exporting. Codea will create four icons from the one that you include. Their dimensions are 57 x 57 pixels, 114 x 114 pixels, 72 x 72 pixels and 144 x 144 pixels. This is for the standard and retina versions of the iPhone and iPad icons. I suggest attaching an icon with a resolution of at least 144 x 144 pixels to ensure the best quality. If you are submitting to the app store you will need a version with 1024 x 1024 pixel resolution.
2. In Codea, tap and hold the icon of the project that you wish to export (Figure 1). This will bring up the pop up menu shown. Tap on Export.
3. Check that the Project settings are correct (Figure 2). Taking these one by one: 

• The first item is the app name which is taken from the name of your project (not the "Description" meta tag for your project created using saveProjectInfo). 
• The second item is the developer/author name which is derived from the "Author" meta tag and assigned using saveProjectInfo(). For example, saveProjectInfo("Author", "Reefwing Software"). 
• The third item, "Company Name" is optional. Note that the bundle ID will use a "short form" of the author or company name you include (it will prefer the company name if specified). A short version of a name simply removes any spaces or special characters in the name. So "Two Lives Left" becomes "twolivesleft", and the bundle ID then becomes com.twolivesleft.projectShortName. The bundle ID is important, as it connects your app in Xcode with your app submission in iTunes Connect. I always use a bundle ID of the form au.com.reefwing.LunarLander, so I will need to tweak this in Xcode regardless.
• The next item determines whether your app will display the status bar or not (the black bar right at the top of your iPad which shows your wireless connection strength, network provider, time, battery level, etc). This is an option in your applications pList, so if you change your mind later you can change it in Xcode.
• The final item in Project Settings is Icon. If you are happy with the default Codea icon for your app then you need do nothing. Most people will want to assign a custom icon however, and tapping the arrow to the right of "Icon" will allow you to do this (Figure 3). Tap on the "+" in the "Choose Icon" dialog to bring up your photo library and select the icon (Figure 4). If you created the icon on your Mac then importing it into iPhoto will add the image to your Photo Stream (if enabled) which is then available on your iPad to select.
• The "Included Assets" section allows you to include specific sprite images and shaders in the export bundle. Codea normally does a good job of finding these for you but it will have problems if you are procedurally generating the sprite/shader names in your code. If you find assets are being left out then they can be added here.
• Once you have confirmed all of the Project Settings, tap the Export Button in the top right hand corner of the navigation bar. Codea will chug away (Figure 6) and create your Xcode bundle. When complete (Figure 7), you are given the option to save your exported project bundle somewhere. You need to get this file onto your Mac, so the simplest method is to use Dropbox. If you haven't already signed up for this then I recommend that you do - it is free - and then install the Dropbox app on your iPad. This makes the file movement very simple.

Figure 6. Exporting your Project...

Figure 7. Exported and ready to save.

• Assuming you are using Dropbox, tap the "Open With" button shown in Figure 7, and you will be given the option to select Dropbox (Figure 8). Select this and then save the zipped bundle when prompted (Figure 9). You will then have the bundle saved in your Dropbox repository (Figure 10) which you can unzip and access from your Mac.

Figure 8. Select Export Bundle to Dropbox.

Figure 9. Save the zipped Project Bundle.

Figure 10. Bundle Saved in Dropbox.

27.2 Importing your Bundle into Xcode

1. Open up Finder on your Mac and navigate to the Dropbox folder containing your exported project bundle. Double click on this to unzip the folder (Figure 11).
2. Open up Xcode and select your unzipped project to open (Figure 12). Optionally you may want to save this folder locally first.
3. And that's it! You should now be able to run your imported project on the iPad or iPhone simulator.

Figure 11. Unzip your project bundle on the Mac.

Figure 12. Open the Project with Xcode.

Figure 13. Configure your Project in Xcode.

27.3 Pre-App Submission Tweaks

If you are going to submit your app to the Apple App Store for approval and listing on iTunes, then there are a few things you still need to do. Have a read of our previous tutorial on this for the full story but in short:

1. Click on the project (top left of the project navigator) to bring up the project configuration (Figure 13).
2. Check that the bundle identifier is the same as that entered in iTunes Connect.
3. Determine whether you want to distribute a universal app (works on iPad and iPhone) or target a specific device. The default is universal.
4. Check the supported orientations.
5. You may want to add your own default load images. The default ones say "made with Codea".
6. When adding your App to iTunes Connect you will need a version of your icon which is 1024 x 1024 pixels in size.

As shown above, the process is now much simpler than it used to be. Good luck with your submissions!