Bare Bones Project

From Pixelwave

1 Prerequisites

Before you start going through this tutorial you should have successfully set up Pixelwave (to test it, just run one of the included sample projects).

You do not need to install the templates for this tutorial to work.

2 Setup

2.1 Boot up Xcode

This tutorial was written using Xcode 3.2.5, iOS SDK 4.2, on Mac OS X 10.6.

2.2 Create a new project

Navigate to (File -> New Project). Under the iOS template section choose the Window-Based Application category. Now you can choose whatever option you'd like for product, but we chose to go with Universal in order to support both the iPhone and iPad with a single app.

2.3 Save it

Click 'Choose...' on the bottom right corner and pick a location to save your project. Choose anywhere on your machine except the directory where Pixelwave is located (the path of PIXELWAVE_SRC). Let's call our app 'HelloPixelwave'.

2.4 View it

If everything went well you should now have a new blank project ready for Pixelwave. It would look something like this:

2.5 Add it

Now that you have a blank project, it is time to add Pixelwave! You should already have the files on your computer, so lets add them.

Now just locate where you put pixelwave:

Thinking that was too simple? Unfortunately, you are correct.

2.6 Link it

Lets set it up so your project can properly link to Pixelwave. First things first, tell Xcode how to find the project.

You want to set it relative to Pixelwave, that way if anyone else uses the project, and they have already set up Pixelwave, then the project can automatically link properly.

2.7 Add To Target

Now we need to add Pixelwave to your target.

Add the new setting...

and select Pixelwave.

2.8 Build Settings

Next click on the Build tab, and go to user header path. While you are here, also check Always Search User Path. Then add the PIXELWAVE_SRC to the path.

Make sure to click recursive as our files are nested.

2.9 Link Those Binaries!

Lets link the Pixelwave binary. Just drag the libPixelwave.a file from the Pixelwave.xcodeproj to the target Link Binary With Libraries under Targets->HelloPixelwave.

2.10 Adding Frameworks

Pixelwave uses a lot of frameworks that are available to you. All you need to do is add them.

Locate the following frameworks and click add:

Prior to iOS 3.2, CoreText was not available. If you don't plan to support anything less then iOS 3.2, than you need to make sure it is weak referenced. This is easily done by going to target and clicking on info. Then go down to CoreText and select weak.

2.11 A Little Code

At some point, you will want to add a PXView to the window by adding a small segment of code:

// Create a new Pixelwave View
pixelView = [[PXView alloc] initWithFrame:window.frame];

PXSprite *root = (PXSprite *)(pixelView.root);

[root.graphics beginFill:0x40E0D0 alpha:1.0f];
[root.graphics drawRectWithX:40.0f andY:30.0f andWidth:80.0f andHeight:60.0f];
[root.graphics endFill];

// Add the Pixelwave view to the main window.
[window addSubview:pixelView];

Make sure at some point you release the view. This means that you may also want to store it somewhere. The window in this case would be an instance of your UIWindow.

You may also wish to consider adding these methods to your app delegate pause / resume the engine when it is appropriate:

- (void) applicationWillResignActive:(UIApplication *)application
{
	pixelView.stage.playing = NO;
}

- (void) applicationDidBecomeActive:(UIApplication *)application
{
	pixelView.stage.playing = YES;
}

You may want to consider making yourself some sort of sprite now to set as the root. In the example I draw a small box directly on the default root.

3 The Power Is Yours!

Now you should have Pixelwave officially set up. From here on out the code is up to you. See our samples for examples.

4 Adding PixelKit

Adding a static library to Xcode is the same every time, thus adding PixelKit is the same as adding Pixelwave. Some steps are needed only once. Like the steps 2.5 - 2.9? You can simply iterate through those again, replacing every instance of Pixelwave with PixelKit, and you will have PixelKit!