How to make HD games with Sparrow

Daniel Sperl on August 7, 2010

Before the release of the iPhone 4, developers were in the comforting situation that all iPhones had the same screen resolution (unlike Android developers, which have to support many kinds of displays). Now, with the arrival of the iPhone 4, there are two screen resolutions that can be targeted: 480x320 and 960x640.

Fortunately, Apple did the best to make that transition as painless as possible. It’s no coincidence that the new resolution is exactly twice the old resolution - that way, old applications simply use 4 pixels on the iPhone 4 for what was one pixel on previous devices, and look just like before.

New applications, however, can profit from the higher resolution. If you create all graphics in the high resolution from the start, the additional effort is minimal - if you follow the steps I show below.

BTW, the tools I am using throughout this tutorial are part of Sparrow - but that does not mean that you cannot use them with other game engines (like Cocos2D) or pure UIKit applications. The texture atlas generator, for example, can easily be modified so that it produces a different output format.

What we want to achieve

Sparrow’s demo application was created in the way I am describing in this tutorial. Start up the demo application in the iPhone simulator to see the result. When the simulator appears, select “Hardware - Device - iPhone 4” in the menu bar, and “Window - Scale - 100%”. (The next time you start the simulator, it will have remembered these settings.)

Depending on the selected hardware (iPhone vs. iPhone 4), different textures will be used. Don’t worry if the HD version runs slowly on your Mac; on a real iPhone 4, it will run smoothly.

Preparations

First, you have to make sure that the tools “texture scaler” and “atlas generator” work. They can be found in the “sparrow/sparrow/util” directory of the download package. Have a look at the README files of those tools to find out how to prepare them.

Creating the graphics

When the tools work, we can start creating the graphics. Create the textures only for the high resolution (960x640). If you use a texture atlas, place your graphics in one directory per atlas. All other graphics are in a separate directory.

This leads to a directory structure like the following:

textures/
  atlas/
    tree.png
    house.png
    guy.png
  others/
    button.png
    background.png  

As I said, those graphics are all targeting the high resolution. A tip: try to make the width and height of those textures even numbers. That way, the down-scaled versions we create below will have widths and heights that are whole numbers, and you avoid some aliasing issues later.

Now, do not add those graphics to the Xcode project! They are just the “raw material” for the graphics you use in your application. Save them in a directory outside of your project.

What we will do instead is the following: we will create two shell scripts that will use Sparrow’s tools to scale the graphics to the appropriate sizes and copy them to the project directory.

Script 1 - Normal Textures

First, we handle the textures that are loaded directly (they are not part of a texture atlas). Create the following script and save it into the “textures” directory from above. Let’s call it “scale_and_copy_textures.sh”:

#!/bin/bash

SCALE_TEXTURES=/sparrow_path/util/texture_scaler/scale_textures.rb  
OUTPUT_PATH=/application_path/media/graphics

echo ""
echo "-> Renaming and copying high-res textures ..."
# no scale, add suffix
${SCALE_TEXTURES} -s 1 -a @2x others/*.png ${OUTPUT_PATH}/2x

echo ""
echo "-> Resizing and copying low-res textures ..."
# scale by 50%, sharpen
${SCALE_TEXTURES} -s 0.5 -r others/*.png ${OUTPUT_PATH}/1x

echo ""
echo "Done!"

Modify the two variables at the beginning so that they point to Sparrow’s texture scaler and to your game’s media directory. Before we can execute the script, we have to make it executable. Open the terminal and type:

cd path_to_textures/
chmod u+x scale_and_copy_textures.sh

Now you can execute it by calling

./scale_and_copy_textures.sh

If everything worked, this will create the following files in the output directory:

/graphics
  /1x
    button.png
    background.png
  /2x
    button@2x.png
    background@2x.png

The “2x”-folder contains the original graphics. The suffix “@2x” was added to the filenames. We’ll see later what that’s for. The folder “1x” contains the downsized and sharpened textures. (If you don’t want them to be sharpened, remove the “-r” flag in the script).

Script 2 - Atlas Textures

Thanks to Sparrow’s atlas generator, the process of creating the two atlases is just as simple. Create the script “create_and_copy_atlas.sh” in the same directory as the other script:

#!/bin/bash

GENERATE_ATLAS=/sparrow_path/util/atlas_generator/generate_atlas.rb  
OUTPUT_PATH=/application_path/media/graphics

echo ""
echo "-> Creating High Resolution Atlas ..."
# no scale
${GENERATE_ATLAS} atlas/*.png -m 2048x2048 ${OUTPUT_PATH}/2x/atlas@2x.xml

echo ""
echo "-> Creating Standard Resolution Atlas ..."
# shrink by 50%, sharpen, and copy
${GENERATE_ATLAS} -r -s 0.5 atlas/*.png ${OUTPUT_PATH}/1x/atlas.xml

echo ""
echo "Done!"

The maximum size of the HD atlas is 2048x2048 pixels; that’s the maximum size of a single texture on iPhone 4. The smaller atlas has a maximum size of 1024x1024; that size is supported by all iPhone/iPod variants. Again, the smaller textures were scaled down to half of the size and sharpened.

Just like before, you have to make that file executable before you can start it:

cd path_to_textures/
chmod u+x create_and_copy_atlas.sh
./create_and_copy_atlas.sh

Now, the graphics directory should contain all of our textures:

/graphics
  /1x
    button.png
    background.png
    atlas.xml
    atlas.png    
  /2x
    button@2x.png
    background@2x.png
    atlas@2x.xml
    atlas@2x.png

Preparations complete!

Phew! OK, that was quite a bit of work - but now, everything is prepared. From this moment on, when you add a new texture or change an existing one, all you have to do is to start up the corresponding scripts.

Using those Textures

Sparrow 0.9 makes it very easy to use those HD textures. You develop your game just like before, with a stage size of 480x320. All you have to do is to add the following line at the beginning of your application delegate:

- (void)applicationDidFinishLaunching:(UIApplication *)application 
{    
  [SPStage setSupportHighResolutions:YES];
  // ...
}

Add all textures to your Xcode project (low and high resolution). Now, create SPImages and SPTextureAtlases just like before - no need to add the “@2x” suffix!

SPImage *background = [SPImage 
    imageWithContentsOfFile:@"background.png"];
SPTextureAtlas *atlas = [SPTextureAtlas 
    atlasWithContentsOfFile:@"atlas.xml"];

Behind the scenes, Sparrow will load the correct texture for you. The “width” and “height” properties of the loaded images and textures will always be the size of the low resolution (!) textures. That way, you can pretend that you are developing the game only in the low resolution. The HD-version will be a side-product you don’t have to think about while you are writing your game in Xcode.

Last words

This tutorial should have shown you nearly everything you need to know to create your next game in HD.

One thing I left out is Bitmap Fonts. Sparrow has no tool for that on its own. I recommend you use the bitmap font generator by AngelCode. To use bitmap fonts in HD, create the font files two times: once with the high resolution and the suffix “@2x”, and once with half the size (and no suffix). The demo project contains a bitmap font that shows you what the files should look like.

I think that should be it! If anything is unclear, just post your question below or in the forum - as always. Good luck!

UPDATE: What about the iPad?

You will have noticed that this post was only about the iPhone and iPod variants, not the iPad. Here’s the reason for this:

When you create an iPad-only application, there’s nothing special you have to think about. The SPView and SPStage objects will have a size of 1024x768, and you create textures for that size. That should be straight forward.

However, so-called “Universal Apps”, which contain iPad and iPhone/iPod versions within one application bundle are bit special. Currently, the “@2x”-textures are not loaded automatically on the iPad (and you’d need to modify the Sparrow source to do so).

Why is that so? Well, first of all, I expect that as soon as iOS 4 is released on the iPad, I bet that Apple will start up applications that were built for the retina display in full screen mode (well, at least in 960x640). That means that the application will run in high definition automatically.

Second, for a real iPad-app (universal or not), you normally don’t want to simply scale up everything, anyway. An iPad application should make use of the additional screen space, not just display everything twice the size. So I’m afraid you will have to use a different set of textures for the iPad, anyway (in scale, somewhere between the HD and LD textures), and move the controls and graphics to different positions. If that is not feasible: as I said above, I am confident that iOS 4 on the iPad will take care of the simple “double size” solution.

If I am mistaken about Apple’s plans - don’t worry, in that case, a Sparrow update will take care of that! :-)