This is the first in a series of blog articles explaining some of the interesting technical hurdles we encountered while building our new iPad puzzle game Flockwork.

Shortly before our app launched, Apple announced the iPad 3 with retina display. We knew it would be important to support retina graphics in our app. Luckily, it didn't take too much additional effort to get our game ready for the "resolutionary" display!

We're using the cocos2d framework to build Flockwork, and it does have some built-in support for retina graphics. So first we had to:

1. Enable retina display mode

if( ! [director enableRetinaDisplay:YES] ) {
	CCLOG(@"Retina Display Not supported");
}

First, set enableRetinaDisplay to YES in your AppDelegate. If you build immediately after enabling this, your app will look a complete mess! You now need to provide alternative HD assets for all the static assets in your games: images, spritessheets, fonts, particle effects, and so on.

2. Upgrade your image assets

Every PNG file used in your app will now need an HD version, double the width and height of the original. If your original source files are in vector format, for example Adobe Illustrator files, this shouldn't be too hard. If you made bitmaps in Photoshop, there may be some extra work.

Cocos2d uses the convention of a -hd suffix, for example the hi-res version of a file called button.png (20x24 pixels) would be button-hd.png (40x48 pixels).

After adding the new file to your project, cocos will automatically load the HD version on a retina display. This is handled by the CCFileUtils class.

If your project has a large number of image assets, it can be easy to lose track of which files have been upgraded to HD. It's also very important to ensure that the -hd version is exactly double the size of the standard version.  A cautionary tale: in Flockwork, we were using the pixel size of some assets to determine the size of Box2d physics bodies. Because some of our -hd assets were off by a few pixels, the physics of the objects changed in Retina mode, causing some very obscure bugs!

To avoid this, we wrote a little Python script to scan through our assets folders.

import subprocess,re,glob
def dimensions(path):
    #get dimensions of an image from sips
    dimensionArgs = ['/usr/bin/sips', '-g', 'pixelHeight', '-g', 'pixelWidth', path]
    sips = subprocess.Popen(dimensionArgs, stdout=subprocess.PIPE)
    dimensions = sips.stdout.read()
    dimensions = re.findall(r'pixel(Height|Width): ([0-9]+)', dimensions)
    if len(dimensions) == 2:
        label, height = dimensions[0]
        label, width = dimensions[1]
        height = int(height)
        width = int(width)
        return width, height
 
def parse(path):
    #parse all files and check that theres an HD version with the right dimensions
    files = glob.glob(path)
    for f in files:
        if "-hd" in f:
            w2,h2 = dimensions(f)
            w1,h1 = dimensions(f.replace("-hd",""))
            if w1*2==w2 and h1*2==h2:
                pass
            else:
                print f+" is not double the size of "+f.replace("-hd","")
                ratiow=float(w2)/float(w1)
                ratioh=float(h2)/float(h1)
                print (ratiow,ratioh)
 
#parse everything in the specified folder
parse('Resources/images/*.png')

Note that Flockwork is iPad-only. If you're trying to make a Universal app (iPhone and iPad) you may have to provide up to four sets of images for each asset!)

3. Upgrade your spritesheets

Spritesheets work similarly to images. First, you need to make HD versions of each of the frames within the spritesheet. Then, create a spritesheet double in size to the original (for example, a 2048x2048 sheet instead of 1024x1024). We used the excellent Zwoptex. In your HD spritesheet, you then need to add all the HD assets instead of the SD ones, save and publish. All being well you'll now have files named something like:

sprites_campaign_4.png (1024x1024)
sprites_campaign_4.plist
sprites_campaign_4-hd.png (2048x2048)
sprites_campaign_4-hd.plist

Add the new .png and .plist to your project, and you're good to go.

4. Upgrade your fonts

If you're using any bitmap-based fonts, you'll also need HD versions there. We use GlyphDesigner to create our fonts files, which are then used by CCLabelBMFont. Make a copy of your GlyphDesigner project, and double the font size, for example a 35-point font would now be 70 points.

5. Test, test, test

Once all your images and fonts are in place, it's time to test. You can do testing in the iOS Simulator in Retina mode, but its likely you'll get a very slow frame rate. There's no substitute for getting a real iPad 3 to test on (even if that's a major challenge in China!).

Test all the screens and functionality of your app. It's likely you'll find some glitches or areas you've missed. For example, Flockwork uses particle effects: we needed to create HD assets of those too. We also found we'd got a few filenames for HD assets switched - this is something only a human is likely to spot!

Let us know your cocos2d retina war stories in the comments - and of course, if you haven't already, download Flockwork!