Kobold2D Is Ready to Use

Kobold2D installs like a regular application. There’s no need to run a script in the Terminal app or perform any other such error-prone tasks. Download and run the package installer, follow the onscreen instructions, and you’re done. It’s quick and painless.

After installing Kobold2D, you can build one of the 15 template projects right away; most of them are based on projects you’ve worked on throughout the book. With the exception of the app start-up process, which is now simply a configuration file, everything you’ve learned about cocos2d in this book and elsewhere still applies.

The Kobold2D installer also adds the various API references to the Documentation tab of the Xcode Organizer window.

Kobold2D Is Free

Kobold2D is free and distributed under the MIT License. All the included libraries use either the MIT License or a compatible license.

The only exception is iSimulate, which requires the paid iSimulate app from the App Store to unlock all features. The free iSimulate Lite, for example, doesn’t support the forwarding of multitouch events to the iOS Simulator.

Kobold2D Is Easy to Upgrade

A big incentive for Kobold2D was to simplify and streamline upgrading cocos2d in existing projects. The downside of using the cocos2d Xcode project templates is that a copy of the entire cocos2d source code resides in each and every project, making the upgrade process unnecessarily tedious and error-prone.

Kobold2D fixes that by keeping your code separate from any library’s code. If a new version of Kobold2D is released, and you want your project to use the updated code, simply run the Kobold2D Project Upgrader tool of the newly installed Kobold2D version. It will scan previous Kobold2D versions and offer to upgrade each individual project with a click of the mouse. The only task that remains for you to upgrade your code is the unavoidable code maintenance because of API changes—for example, classes that may have been renamed in cocos2d or other libraries, or library methods whose parameters have changed.

Kobold2D Includes Popular Libraries

A central aspect of Kobold2D is to spare developers the pain of adding third-party libraries to cocos2d projects. Correctly setting up third-party libraries often requires intricate knowledge of the build system, an intuition about how to read compiler and linker errors, and possibly even small but crucial source code changes in the right places. It can take hours, if not days, for someone else’s code to compile and link successfully on all platforms: iOS (ARMv6 and ARMv7), iOS Simulator, and Mac OS X both in 32-bit and 64-bit variants, and all of those either with or without ARC.

That’s what Kobold2D provides: lib service. Kobold2D 2.0 includes the following libraries.

Libraries for both iOS and Mac OS X projects:

• Kobold2D (game engine code, Objective-C)
• cocos2d-iphone (2D graphics, Objective-C)
• cocos2d-iphone-extensions (utility code, Objective-C)
• Box2D (physics, C++)
• GBox2D (Box2D physics, Objective-C)
• Chipmunk (physics, C)
• Chipmunk SpaceManager (Chipmunk physics, Objective-C)
• CocosDenshion (audio, Objective-C)
• Lua (scripting)

Libraries available only for iOS projects:

• ObjectAL (audio, Objective-C)
• SneakyInput (joystick, Objective-C)
• iSimulate (library for iSimulate app)

Whenever an essential library such as cocos2d is updated, a new release of Kobold2D will follow within days, if not hours. There’s no need for you to get active on the library front.

Some readers may wonder whether this means that Kobold2D apps are bloated, with all those libraries being included. You may be surprised to hear that early tests showed that Kobold2D apps are actually slightly smaller compared to cocos2d-iphone apps, even though Lua is built into Kobold2D. The reason is that the Kobold2D projects are set up to allow the linker to throw away any code that isn’t used in your app. That means if, for example, you don’t include any of the Box2D headers, none of the Box2D library code will be linked with your app. But if you do want to start using Box2D, it’s as simple as adding the Box2D.h header file to your project, and you’re ready to start writing Box2D-enabled physics apps.

Kobold2D Takes Dual-Platform to Heart

By having one target for each platform (iOS and Mac OS X) by default in its project templates, Kobold2D allows you to build and run your code on both platforms from within the same Xcode project.

Developing for both iOS and Mac OS platforms is also encouraged by the Kobold2D API, which goes a long way toward ensuring that game engine code compiles for both platforms. For example, if you try to read the mouse button states on iOS, the code still compiles, and the result is a safe default, which in this case would simply report that no mouse button is pressed.

The Hello World Project Files

In Figure 16-3 you’ll see the groups and files in the My First Kobold2D Project, which was created from the Hello-Kobold2D template project.

The immediately noticeable difference compared to a regular cocos2d project is that three groups begin with Projectfiles, and there is the additional BuildSettings group. The idea behind that is to have a Projectfiles group and folder that contain the source code and resource files common to all platforms. The majority of your source code and resources will be in this folder. The additional Projectfiles-iOS and Projectfiles-Mac groups should contain only files used by that particular platform. These groups are meant as suggestions; you’re of course free to structure your project’s group as you see fit.

The BuildSettings group contains several .xcconfig files, which are the textual format for Xcode build settings. Normally you don’t need to modify these files, but in some cases you may want to,—or example, to enable iSimulate. One huge benefit of the .xcconfig files is that you can document them, and accordingly you’ll find several notes for each build setting, what it does, what it affects, and when you might want to enable or disable it. The other big benefit of .xcconfig files is that Kobold2D controls each project’s default settings. Should an Xcode or cocos2d update require different build settings, then that change will be shipped with Kobold2D instead of leaving it up to you. In the past, this has caused a lot of grief whenever certain build settings became incompatible with cocos2d.

Almost all Kobold2D project templates provide targets for both iOS and Mac OS X, which are suffixed with -iOS and -Mac, respectively. I hope that the readily available Mac target will encourage you and other developers to consider cross-platform development from the start and to publish more apps to both the iOS and Mac App Store. It’s certainly a lot easier to take cross-platform development into account from the start rather than porting the app once it’s finished.

How Kobold2D Launches an App

Kobold2D simplifies the start-up process, in particular how much custom code is needed in your project (by default: none). Kobold2D does all the initialization performed by the main function, the app delegate, and the root view controller behind the scenes.

Furthermore, Kobold2D lets you easily modify the start-up settings, such as the first scene or layer to display, the device orientation, the render settings, the Mac window size, Retina support, and many more. All these settings are centralized in the config.lua script file.

#import "kobold2d.h"
 
int main(int argc, char *argv[])
{
  return KKMain(argc, argv, NULL);
}

#import "KKAppDelegate.h"
 
@interface AppDelegate : KKAppDelegate
{
}
@end

#import "AppDelegate.h"
 
@implementation AppDelegate
// Called when Cocos2D is fully setup and you are able to run the first scene
-(void) initializationComplete
{
}
@end

local config =
{
 KKStartupConfig =
 {
  -- load first scene from a CCScene or CCLayer derived class with this name
  FirstSceneClassName = "HelloWorldLayer",
 
  MaxFrameRate = 60,
  DisplayFPS = YES,
 
  EnableUserInteraction = YES,
  EnableMultiTouch = NO,
 
  -- Render settings
  DefaultTexturePixelFormat = TexturePixelFormat.RGBA8888,
  GLViewColorFormat = GLViewColorFormat.RGB565,
  GLViewDepthFormat = GLViewDepthFormat.DepthNone,
  GLViewMultiSampling = NO,
  GLViewNumberOfSamples = 0,
 
  Enable2DProjection = NO,
  EnableRetinaDisplaySupport = YES,
  EnableGLViewNodeHitTesting = NO,
  EnableStatusBar = NO,
 
  -- Orientation & Autorotation
  -- Kobold2D uses the supported orientations from the Target's Summary pane
  -- (same as Info.plist "Supported interface orientations")
 
  -- iAd setup
  EnableAdBanner = YES,
  LoadOnlyPortraitBanners = YES,
  LoadOnlyLandscapeBanners = NO,
  PlaceBannerOnBottom = NO,
  AdProviders = "iAd, AdMob", -- comma seperated list
  AdMobRefreshRate = 15,
  AdMobFirstAdDelay = 5,
  AdMobPublisherID = "YOUR_ADMOB_PUBLISHER_ID",
  AdMobTestMode = YES,
 
  -- Mac OS specific settings
  AutoScale = NO,
  AcceptsMouseMovedEvents = NO,
  WindowFrame = RectMake(1024–640, 768–480, 640, 480),
  },
}
 
return config

The Hello Kobold2D Scene and Layer

Let’s move on to the actual scene class HelloWorldLayer, which is set as the first scene via the config.lua setting FirstSceneClassName = "HelloWorldLayer". You’ll notice that this first scene is actually derived from CCLayer. Kobold2D realizes that and automatically wraps the HelloWorldLayer class into a CCScene instance behind the scenes.

[[CCDirector sharedDirector] replaceScene:[MyGameLayer nodeWithScene]];

The HelloWorldLayer interface declaration is pretty unspectacular and provides only three instance variables that will later be loaded from the config.lua file:

#import "cocos2d.h"
 
@interface HelloWorldLayer : CCLayer
{
  NSString* helloWorldString;
  NSString* helloWorldFontName;
  int helloWorldFontSize;
}
 
@property (nonatomic, copy) NSString* helloWorldString;
@property (nonatomic, copy) NSString* helloWorldFontName;
@property (nonatomic) int helloWorldFontSize;
 
@end

At this point, you should take note of a particular addition to the config.lua file. There’s an additional Lua table labeled HelloWorldSettings in Listing 16-2, which provides three familiar-looking settings: HelloWorldString, HelloWorldFontName, and HelloWorldFontSize.

Listing 16-2.  Custom config.lua Settings

local config =
{
  KKStartupConfig =
  {
  -- start-up settings removed for brevity
  },
 
  HelloWorldSettings =
  {
  HelloWorldString = "Hello Kobold2D!",
  HelloWorldFontName = "Marker Felt",
  HelloWorldFontSize = 50,
  },
}

With the exception of the uppercase first letter, these settings match the properties of the HelloWorldLayer class in name and data type. I’m sure you can see the connection here. Indeed, the KKConfig class method injectPropertiesFromKeyPath, shown in Listing 16-3, loads the values from the HelloWorldSettings subtable and injects them into the correspondingly named properties of the target class, in this case self.

Listing 16-3.  Injecting (Assigning) the Custom Settings to Class Properties

[KKConfig injectPropertiesFromKeyPath:@"HelloWorldSettings" target:self];

By inject I mean if there is a Lua table named HelloWorldSettings, then each setting it contains will be assigned to a correspondingly named property of the target class, in this case self. For example, the setting HelloWorldString will be assigned to the class property helloWorldString if it has the correct data type (NSString*) and isn’t set to be a readonly property.

After injection, the three properties will contain the same values as the HelloWorldSettings Lua table. They’re ready to be used by the label:

CCLabelTTF* label = [CCLabelTTF labelWithString:helloWorldString
                                       fontName:helloWorldFontName
                                       fontSize:helloWorldFontSize];

Listing 16-4 shows the HelloWorldLayer implementation in its entirety. Apart from the previous call to KKConfig and the use of the CCDirector extensions and platform macros discussed earlier, it’s still 100-percent cocos2d code.

Listing 16-4.  Hello Kobold2D Implementation File

#import "HelloWorldLayer.h"
 
@implementation HelloWorldLayer
@synthesize helloWorldString, helloWorldFontName;
@synthesize helloWorldFontSize;
 
-(id) init
{
  if ((self = [super init]))
  {
  CCDirector* director = [CCDirector sharedDirector];
 
  CCSprite* sprite = [CCSprite spriteWithFile:@"ship.png"];
  sprite.position = director.screenCenter;
  [self addChild:sprite];
 
  // get the hello world string from the config.lua file
  [KKConfig injectPropertiesFromKeyPath:@"HelloWorldSettings" target:self];
 
  CCLabelTTF* label = [CCLabelTTF labelWithString:helloWorldString
  fontName:helloWorldFontName
  fontSize:helloWorldFontSize];
  label.position = director.screenCenter;
  label.color = ccGREEN;
  [self addChild:label];
 
  // print out which platform we're on
  NSString* platform = @"(unknown platform)";
 
  if (director.currentPlatformIsIOS)
  {
  // add code
  platform = @"iPhone/iPod Touch";
 
  if (director.currentDeviceIsIPad)
  platform = @"iPad";
 
  if (director.currentDeviceIsSimulator)
  platform = [NSString stringWithFormat:@"%@ Simulator", platform];
  }
  else if (director.currentPlatformIsMac)
  {
  platform = @"Mac OS X";
  }
 
  CCLabelTTF* platformLabel = [CCLabelTTF labelWithString:platform
  fontName:@"Arial"
  fontSize:24];
  platformLabel.position = director.screenCenter;
  platformLabel.color = ccYELLOW;
  [self addChild:platformLabel];

  glClearColor(0.2f, 0.2f, 0.4f, 1.0f);
  }
 
  return self;
}
 
@end

Notice the way I determine the platform (iOS, Mac OS) and device type (iPad, iOS Simulator) using director properties such as currentPlatformIsIOS and currentDeviceIsSimulator. These are some of the extensions to CCDirector I mentioned earlier.

You may be wondering why I haven’t used preprocessor macros like __IPHONE_OS_VERSION_MAX_ALLOWED to determine platform and device type. First, in Kobold2D I wouldn’t have used the hard-to-remember and verbose SDK macros. Instead, Kobold2D provides the simpler macros KK_PLATFORM_IOS and KK_PLATFORM_MAC to differentiate between the two supported platforms. If needed, you can also differentiate between iOS device and iOS Simulator by using the macros KK_PLATFORM_IOS_DEVICE and KK_PLATFORM_IOS_SIMULATOR.

The real reason for not using preprocessor macros and why conditional compilation with #ifdef should be used only as a last-resort measure is this: the compiler is your friend! Every time your code is compiled, the compiler lets you know that everything is in order or tells you whatever is technically or syntactically wrong with your code. It may be annoying at times, but the compiler is only letting you know that you made a mistake or forgot something. Allowing as much code as possible to be compiled by the compiler every time you build the code is so important for cross-platform development that the added overhead of platform and device runtime tests are entirely negligible.

Once you do cross-platform development, you’ll likely spend a lot of time working on and compiling code for only one platform. Any code that’s within an #ifdef for the other platform is invisible to the compiler, and it won’t complain about errors. Now as soon as you switch targets and compile for the other platform, you’ll likely run into errors that were thus far ignored due to the use of #ifdef. These errors may be related to code changes that you made an hour ago, a day ago, or maybe even a week ago.

Not only does it cause a lot of mental load to figure out which code change caused the error and what the correct fix will be, it’s also frustrating because you’ll frequently find that switching target platforms results in build failures. Either you’ll spend more time than necessary building code regularly for both target platforms or you’ll simply give up, maybe with the good intention of porting the project when it’s finished. However, porting a completed project is much more work than developing it for both platforms from the beginning.

Code that compiles works. At least it’s technically correct. Immediate build errors are more likely to be corrected right away and easier to fix because you still have the most recent code changes in your short-term memory.

Running Hello World with iSimulate

To enable iSimulate you have to open the BuildSettings-iOS.xcconfig file, which is located in the BuildSettings group of your Kobold2D project. The only thing you have to do is to remove the comment from this line:

OTHER_LDFLAGS[sdk = iphonesimulator*][arch = *] = $(OTHER_LDFLAGS) $(FORCE_LOAD_ISIMULATE)

Now if you run the Hello World project on the iPhone or iPad Simulator, you’ll notice a network connection dialog as in Figure 16-4, which is the reason iSimulate is disabled by default. Several users have complained about it; some were confused why Kobold2D projects would want to accept incoming network connections. You’ll also notice the iAd banner that shows up because it was enabled in config.lua.

As I said, the incoming network connections warning dialog is caused by iSimulate. The iSimulate library needs to accept incoming connections from the iSimulate app, which you can run on your WiFi-enabled iOS device in order to remote control the simulator. In other words, iSimulate enables you to test your game using your device but running in the Simulator. All the features the Simulator doesn’t have—such as GPS, accelerometer, or multitouch—can be simulated with the iSimulate app. It can be a real time-saver.

For example, if you have iSimulate running on your device and connected to your Mac, you will receive messages like accelerometer:didAccelerate: in your app, even though the Simulator doesn’t have an accelerometer. This makes iSimulate an invaluable tool if you consider that running your app is usually a lot faster than deploying it to a device. I recommend giving it a try with Kobold2D’s User-Input template project.

iSimulate is available on the App Store and normally costs $15.99: http://itunes.apple.com/app/isimulate/id306908756.