Git Clone

If you have git installed, you can clone a copy of this project with the following command:

git clone git://github.com/mitchallen/TestGame.git

Going forward, I will attempt to post all sample code using git. Usually this means that it will come wrapped in a full Xcode project.

I have several reasons for using git:

• I don’t have to wrestle with creating a zip file and uploading it to some obscure server somewhere
• You don’t have to wrestle with downloading a zip file and expanding it somewhere
• You don’t need an account to copy my public repositories
• All you have to do is enter one line in a terminal window
• You instantly end up with a local copy of the repository that you can copy and branch any which way you like
• It forces you to think about source control
• If something is missing, I can just checkin new stuff and do a refresh
• If I hack an existing project, I can just add a branch instead of forcing you and I to deal with multiple projects

So if you still haven’t installed git on your Mac yet, I suggest you go back and read my post on the subject again.  Also if you have, you may want to read it again.  I’ve added a few more links and info on filtering out certain files to keep your repository from getting cluttered.

What follows are notes that I gathered from looking at various tutorials on getting started with the Cocos2D Game Engine. You can find the tutorials that I used as a source for my notes here:

• http://monoclestudios.com/cocos2d_whitepaper.html
• http://morethanmachine.com/macdev/?p=83

Additional links may be found in my entry here:

• http://mitchallen.com/iphone/archives/254

This tutorial was tested with cocos2d-iphone-0.8 – I had trouble compiling with 0.8.1.

UPDATE: I’ve added some notes for compiling using 0.8.2 – with the help of some reader comments below.

Build Options

There are a number of options for creating a Cocos2D Game Project:

1. Use the engine as a shared library
2. Start from a template
3. Copy the engine components and put them in your project

For simplicity this article covers Option #3 – copying the engine components to your project.

If you would like to know more about the other options, see these links:

• http://www.clintharris.net/2009/iphone-app-shared-libraries/
• http://iphonedev.net/2009/07/29/how-to-create-your-own-cocos2d-project-template/

Setting Up the Project

• Download and unpack the latest stable release of the Cocos2D Game Engine from here: http://code.google.com/p/cocos2d-iphone/
• Launch Xcode
• Select: File / New Project … / [iPhone OS : Application] / Window-based Application / Choose …
• Save As: TestGame, Save
• Delete: Resources / MainWindow.xib
• Edit: TestGame-Info.plist:
• Delete the line: Main nib file base name : MainWindow
• Add the line: Status bar is initially hidden – and check it
• Save the file
• Click on the TestGame folder icon at the top of the Groups & Files pane
• Select: Project / Add to Project … / cocos2d-phone-x.y.z / cocos2d
• Hold down the Apple-key and also select: external
• Click: Add
• Check: Copy items in destination group’s folder (if needed)
• Click: Recursively create groups for any added folders
• Click: Add
• Note that if you mess up and need to delete the folders, you also may have to go to the project folder itself and delete them.  Otherwise you may get an error if trying to add them again.
• In the external folder, delete everything that is NOT the Chipmunk folder (if you are using 0.8.2 keep the FontLabel folder too!).  Why?  Because some of those items are experimental and may not compile.
• From within the external / Chipmunk folder, delete everything that is NOT the src folder.
• Right-click on the Resources folder and select: Add / Existing Files …
• If using 0.8: cocos2d / Resources / Images / fps_images.png
• If using 0.8.2: cocos2d / Resources / Fonts / fps_images.png
• Add / Check Copy …, Recursive …, Add
• Right-click on the Frameworks folder and select: Add / Existing Frameworks …
• Select the Frameworks folder
• Select: OpenGLES.framework
• Click Shift and also select: QuartzCore.framework and click: Add, click Add again

Additional Steps for 0.8.2

If you are using 0.8.2 (or possibly a later version) you will need to also do the following steps to get the project to compile:

• Double-click on Targets \ TestGame
• Make sure that the General tab is selected in the dialog box
• There are two sets of + / - buttons in the dialog, click the + button on the bottom under the list of Linked Libraries
• Select libz.1.2.3.dylib and Add it

Add New Files

• Right-click on the Classes folder and select:
• Add / New File … / [iPhone OS : Cocoa Touch Class ] / Object-C class / [NSObject] / Next
• File Name: TestScene.m, leave Also create “TestScene.h“ checked and click Finish

Make the following changes to Classes / TestScene.h:

• Remove the line:  #import <Foundation/Foundation.h>
• Add the following import lines:
• #import <UIKit/UIKit.h>
• #import “cocos2d.h”
• #import “chipmunk.h”
• Change the class definition so that it is based on Scene instead of NSObject
• At the bottom of the file add another @interface called TestLayer based on Layer

//
//  TestScene.h
//  TestGame
//
//  Created by Mitchell Allen on 9/16/09.
//  Copyright 2009 __MyCompanyName__. All rights reserved.
//
 
#import
#import "cocos2d.h"
#import "chipmunk.h"
 
@interface TestScene : Scene { }
@end
 
@interface TestLayer : Layer { }
@end

Make the following changes to Classes / TestScene.m:

• Add init method that adds a TestLayer to the scene
• Add an @implementation for TestLayer
• Add init method to TestLayer that puts something on the screen

//
//  TestScene.m
//  TestGame
//
//  Created by Mitchell Allen on 9/16/09.
//  Copyright 2009 __MyCompanyName__. All rights reserved.
//
 
#import "TestScene.h"
 
#pragma mark -
 
@implementation TestScene
 
-(id) init {
	self = [super init];
	if( self != nil ) {
		[self addChild: [TestLayer node] z:1];
	}
	return self;
}
 
@end
 
#pragma mark -
 
@implementation TestLayer
 
-(id) init {
	self = [super init];
	if(self != nil) {
		// Note that if you spell the fontName wrong, the label won't appear.
		Label *test = [Label labelWithString:@"Hello World" fontName: @"Helvetica" fontSize: 24];
		test.position = cpv(160, 240);	// cpv = Chipmunk vector
		[self addChild: test];	// Add the label to the layer.
	}
	return self;
}
 
@end

Edit the Existing Files

Make the following changes to Classes / TestGameAppDelegate.h:

• Add two #import statements:
• #import “cocos2d.h”
• #import “TestScene.h”
• Remove the two lines referencing the window property

//
//  TestGameAppDelegate.h
//  TestGame
//
//  Created by Mitchell Allen on 9/16/09.
//  Copyright __MyCompanyName__ 2009. All rights reserved.
//
 
#import 
 
#import "cocos2d.h"
#import "TestScene.h"
 
@interface TestGameAppDelegate : NSObject  {
}
 
@end

Make the following changes to Classes / TestGameAppDelegate.m:

• Remove the line: @synthesize window;
• Remove the dealloc method
• Clear the contents of the method: applicationDidFinishLaunching and replace it with the code below
• If you don’t want your game to start in landscape mode, comment out the line containing setDeviceOrientation

//
//  TestGameAppDelegate.m
//  TestGame
//
//  Created by Mitchell Allen on 9/16/09.
//  Copyright __MyCompanyName__ 2009. All rights reserved.
//
 
#import "TestGameAppDelegate.h"
 
@implementation TestGameAppDelegate
 
- (void)applicationDidFinishLaunching:(UIApplication *)application { 
 
	UIWindow *window = [[UIWindow alloc] initWithFrame: [[UIScreen mainScreen] bounds]];
 
	[window setUserInteractionEnabled:YES];
	[window setMultipleTouchEnabled:YES];
 
	// DEPRECATED: [[Director sharedDirector] setLandscape: YES];
	[[Director sharedDirector] setDeviceOrientation: CCDeviceOrientationLandscapeLeft ];
	[[Director sharedDirector] attachInWindow: window];
	[window makeKeyAndVisible];
 
	TestScene *game = [TestScene node];
	[[Director sharedDirector] runWithScene: game];
}
 
@end

Make the following changes to Other Sources / main.m:

• Change the last argument in the call to UIApplicationMain to a string containing the name of the delegate: @”TestGameAppDelegate”

//
//  main.m
//  TestGame
//
//  Created by Mitchell Allen on 9/16/09.
//  Copyright __MyCompanyName__ 2009. All rights reserved.
//
 
#import 
 
int main(int argc, char *argv[]) {
 
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
 
	// MCA - changed last argument to name of delegate.
    int retVal = UIApplicationMain(argc, argv, nil, @"TestGameAppDelegate");
 
    [pool release];
    return retVal;
}

Compile and Run

• Click: Build and Go

Git Clone

If you have git installed, you can clone a copy of this project with the following command:

git clone git://github.com/mitchallen/TestGame.git

For my next tutorial I will be adding code to the repository. So to get back to the original state of this tutorial, you will need to execute the following at the command line:

git checkout v100

By popular demand, here is a git repository with an updated sample:

git clone git@github.com:mitchallen/TableSize2.git

Note that I have NOT updated the code in this post. Look at the repository for the new code. This new sample fixes two issues: missing IBOutlet and the deprecated setText method on the cell.

To see how it looks in “boxed” mode on the iPad, set the compiler to: Simulator – 3.2 | Debug.

Here is an example of how to create a view that contains a UITableView that doesn’t take over the whole screen.  An example of an application that uses a small table is the Stocks application that comes with the iPhone / iPod Touch.  You may think you need a UITableViewController – but that only gets in the way and takes over the view.

• Create a View-based iPhone application and call it TableSize1
• Modify TableSize1ViewController.h so that it looks like this:

TableSize1ViewController.h

//
//  TableSize1ViewController.h
//  TableSize1
//
//  Created by Mitchell Allen on 5/26/09.
//  Copyright __MyCompanyName__ 2009. All rights reserved.
//
 
#import 
 
@interface TableSize1ViewController : UIViewController {
 
	UITableView *tableView;
}
 
@property (retain, nonatomic) UITableView *tableView;
 
@end

• Modify TableSize1ViewController.m so that it looks like this:

TableSize1ViewController.m

//
//  TableSize1ViewController.m
//  TableSize1
//
//  Created by Mitchell Allen on 5/26/09.
//  Copyright __MyCompanyName__ 2009. All rights reserved.
//
 
#import "TableSize1ViewController.h"
 
@implementation TableSize1ViewController
 
@synthesize tableView;
 
- (void)viewDidLoad {
 
}
 
- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView {
 
    return 1;
}
 
- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section {
    return 20;  // Test hack to display multiple rows.
}
 
- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
 
    static NSString *CellIdentifier = @"Cell";
 
    UITableViewCell *cell = [self.tableView dequeueReusableCellWithIdentifier:CellIdentifier];
    if (cell == nil) {
        cell = [[[UITableViewCell alloc] initWithFrame:CGRectZero reuseIdentifier:CellIdentifier] autorelease];
    }
 
	NSString *szCell = [[NSString alloc] initWithFormat: @"Row %i", indexPath.row ];
 
	[cell setText:szCell];
 
	[szCell release];
 
    // Set up the cell
    return cell;
}
 
- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath {
    // Navigation logic -- create and push a new view controller
}
 
- (void)didReceiveMemoryWarning {
    [super didReceiveMemoryWarning]; // Releases the view if it doesn't have a superview
    // Release anything that's not essential, such as cached data
}
 
- (void)dealloc {
    [super dealloc];
}
 
@end

• In the Resources folder, double-click TableSize1ViewController.xib to launch Interface Builder
• From Library / Cocoa Touch Plugin / Data Views drag a Table View on to the View and make it about half the height of the view (Select Tools / Library from the main menu if it isn’t visible)
• Click on the new Table View
• Click on the second tab in the Inspector window (Select Tools / Inspector from the main menu if it isn’t visible)
• After clicking the second tab, the title of the Inspector window should be Table View Connections
• Under Outlets: for both dataSource and delegate, drag the mouse from the circles next to them to the File’s Owner icon in the TableSize1ViewController.xib window.
• Under Referencing Outlets: drag from New Referencing Outlet to the File’s Owner icon and select tableView.
• With Interface Builder in focus, select File / Save
• Go back to your project window and click Build and Go
• Your application should now display a table that only takes up half the screen.