Our BlogTips, Tricks, and Thoughts from Cerebral Gardens

Last Wednesday we released our newest game, Party Doodles. A unique picture guessing game that uses AirPlay mirroring to create a party game experience unseen before now on the App Store. It has been in the works since AirPlay mirroring was announced (yes, almost a year from concept to release).

I believe, and app reviewers (here, here, and here) seem to agree, that Party Doodles is the first of it's kind on the App Store. The tag line for the game is 'Made for iPad, designed for Apple TV' because while you can play without Apple TV, the game is really meant to be played on the Apple TV.

The easiest way to describe the game, is to compare it to Pictionary. A group of friends break into two teams, each person takes a turn drawing clues (on the iPad) while their teammates try and guess what it is (watching on the big screen TV) before time is up. If time runs out, the other team can steal the points. I added some strategy to the game by having 3 difficulty levels baked into each turn, the person doodling can pick an easy topic to win 1 point, a medium topic for 2 points, or a hard topic for 3 points. If you're behind the other team it gives you a chance to catch up, or if you're winning, a chance to get even further ahead!

The game really is a lot of fun, and I'm not just saying that cause I made it. I had people actually come over to my house and ask to play it. And it's not uncommon for players to break out into uncontrollable laughter.

Anyway, enough plugging the game, please download it and give it a try. Did I mention it's free?

On to what lessons the game has for us, as developers....

First, it's important to know that progress on the game was sometimes slow as I was working full time at a normal job when I first started working on the game. Even when I went full time indie, client projects usually take precedence and consume the majority of my time. I recently looked back at my source commits and noticed several months where I hadn't committed a single line.

A lot of things happened over the course of the development of the game. One of which was that Draw Something came out and became a massive hit. There was a definite 'Oh shit' moment at that point. But it didn't take long to come to terms with the fact that the games are significantly different. I never intended Party Doodles to have mass market appeal anyway. It's definitely for a niche market since the requirements to play properly are high; you need:

  1. an iPad
  2. an Apple TV
  3. actual friends in the same room1

The goals for Party Doodles were to create a unique experience doing something that no other app on the store was doing yet (I expect more will come along shortly), to try the freemium model out, to create a fun game that people can really enjoy playing together, and to get a little attention for the game itself since it is the first of it's kind on the App Store, not an easy feat nowadays.

I've definitely learned a lot while developing this game and plan to share a bunch of tips/tools and code over the next few blog posts. Today's tip is a short one though (since I used up so much space detailing the game in the first place).

When releasing an app with In-App purchases, make sure you test the purchase functionality with the live app from the App Store as soon as it's available. (Use a promo code to download the app after it's approved and before it's released if need be). There are some slight differences between the Production IAP system and the sandbox we can get to test with before submission. In my case, I added receipt verification as suggested by Apple (using PHP on the server, with code I'll likely share in a later post) and the verification process would fail on production requests only due to a minor difference in data sent back from Apple. That caused the first few purchases to be rejected. Not a good user experience at all! Even Apple's reviewers test the app in the sandbox and thus missed my production only bug.

Fortunately I was able to fix it fast since it was just server side code and not in-app code that needed to be changed.

Ok, lots more to come in future articles so stay tuned. In the meantime, please download the game, and like us on Facebook.

1As a french review (Google Translation) of the game pointed out, you also need a TV which they said makes my free game very expensive. I hadn't considered that someone would add the TV to the cost of my game.

No doubt you're excited about the new iPad being released next Friday. Me too! I've been hoping for an iPad with a Retina display since the days of the original iPad. In celebration, here are a few tips to make creating your images a little easier. These of course work for iPhone too.

{emailcloak=off}First, it goes without saying (but I'll say it anyway), you need to create the high res version of the image to start with. I use Adobe's Illustrator and Photoshop for most of my graphics. (Actually, my Wife uses Illustrator mostly, while I import her stuff into Photoshop for any pixel level tweaks and to ensure sizes are consistent etc). For the most part, that means I have images in Photoshop with one image per layer. I use one .psd file for all images of the same size in the app.

When I have a part of the app that needs multiple images, say for a menu, each menu item will be on it's own layer, if there are separate overstate images, they also get their own layer.

Even Steven

Make sure your canvas width and heights are even numbers. If you have an odd number you'll get slight cosmetic errors and off by 1 pixel effects.

Mass Export

Name the layer with the desired filename for that image. Eg: btnMenuItem1@2x etc. Make sure you include the @2x part.

Now you can use Photoshop's Export Layers as Files script to quickly create PNG's of all the images in your .psd file. Leave the File Prefix blank, and make sure you uncheck the 'Trim Layers' option which is always defaulted to on or some of your image sizes will be altered and could end up odd.

Honey, I Shrunk The Files

Next you're going to need to do some setup.

Setup Step 1: We're going to use the awesome ImageMagick tools, so you'll need to install them. The quickest way is to use MacPorts, follow the instructions here.

Setup Step 2: Copy the following script to somewhere in your path. I use ~/bin, but other options will work.

~/bin/1x (Download):

#!/bin/bash

## Copyright (C) 2012 Cerebral Gardens http://www.cerebralgardens.com/
##
## Permission is hereby granted, free of charge, to any person obtaining a copy of this
## software and associated documentation files (the "Software"), to deal in the Software
## without restriction, including without limitation the rights to use, copy, modify,
## merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
## permit persons to whom the Software is furnished to do so, subject to the following
## conditions:
##
## The above copyright notice and this permission notice shall be included in all copies
## or substantial portions of the Software.
##
## THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
## INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
## PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
## HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
## CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
## OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

CONVERT=/opt/local/bin/convert
IDENTIFY=/opt/local/bin/identify

if [ $# -lt 1 ] ; then
	echo "Usage: ${0} filename@2x.ext"
	exit
fi

for ARG in "$@"; do
	FILEPATH=`dirname "${ARG}"`
	FILENAME=`basename "${ARG}"`
	FULLNAME=${FILEPATH}/${FILENAME}

	PHOTOSHOPTEST=${FILENAME#_[0-9][0-9][0-9][0-9]_}

	if [ "${PHOTOSHOPTEST}" != "${FILENAME}" ] ; then
		mv "${FULLNAME}" "${FILEPATH}/${PHOTOSHOPTEST}"
		SOURCEFILE=${PHOTOSHOPTEST}
	else
		SOURCEFILE=${FILENAME}
	fi

	IMAGENAME=`expr "${SOURCEFILE}" : '\(.*\)@2x.png'`
	EXTENSION=`expr "${SOURCEFILE}" : '.*@2x.\(png\)'`
	DESTFILE=${IMAGENAME}.${EXTENSION}
	FAILNAME=.
	BLANKS="                                                  "

	if [ "${DESTFILE}" != ${FAILNAME} ] ; then
		${CONVERT} "${FILEPATH}/${SOURCEFILE}" -resize 50% "${FILEPATH}/${DESTFILE}"

		FILENAME_LENGTH=${#IMAGENAME}
		SOURCE_WIDTH=`${IDENTIFY} -format "%W" "${FILEPATH}/${SOURCEFILE}"`
		SOURCE_HEIGHT=`${IDENTIFY} -format "%H" "${FILEPATH}/${SOURCEFILE}"`
		DEST_WIDTH=`${IDENTIFY} -format "%W" "${FILEPATH}/${DESTFILE}"`
		DEST_HEIGHT=`${IDENTIFY} -format "%H" "${FILEPATH}/${DESTFILE}"`

		echo "${IMAGENAME} - @2x : ${SOURCE_WIDTH}x${SOURCE_HEIGHT}"
		echo "${BLANKS:1:${FILENAME_LENGTH}}   @1x : ${DEST_WIDTH}x${DEST_HEIGHT}"

	else
		echo "Skipping: " "${FULLNAME}"
	fi
done

Once you're setup, and after running the export script, you'll have a series of files in the export folder with names like _0000_btnMenuItem1@2x.png, _0001_btnMenuItem2@2x.png etc. Drop to a terminal in that folder (Go2Shell works great for this). And run the script you created above for each file you've exported. You can do this one file at a time:

1x _0001_btnMenuItem2\@2x.png

or for a collection of files at once,

1x *

What this script does, is chop off the _xxxx_ part of the filename (if it's there), then create a @1x version of the image with the appropriate filename. It will skip any file that doesn’t match the filename@2x.ext format.

The script will also print out the original image dimensions along with the new image dimensions as a quick way to ensure you don't have an odd sized image. (It's ok for the @1x image to have odd dimensions).

Size Apparently Does Matter

Take a look at the sizes of your final images. Apple recommends using PNG files, but they're not always the best solution. Some images just do not compress well as PNG files and are better suited as JPG files (assuming you don't need alpha transparency). For example, an @2x image in my upcoming iPad game was over 5 mb in size as a PNG and just 305 kb as a JPG. There is no discernible difference in the way the file looks or behaves as a JPG, but 10 million users (fingers crossed) will each save 6 mb of space on their iPads (the @1x version went from 1.3 mb to 85 kb).

Get Your App To The Gym

Check out Slender in the Mac App Store. Run your project through it and it'll catch any odd size images, or extra images you're no longer referencing in your app. It can even automatically remove the extra images from your project for you (saving a backup first of course).

On a completely unrelated note, we've launched a Cerebral Gardens Facebook page. If you use Facebook, it would be swell if you'd head over there and do the like thing. Thanks!

Today I'm going to follow up on some interesting comments to my previous tip regarding enumerating NSMutableArray's.

I had suggested to make a copy of the mutable array before enumerating, in order to prevent another thread from modifying the array you're working on and causing a crash.

It was mentioned that making that copy is itself an enumeration and so we were just moving the crash point. So, I did some digging.

// array is an NSMutableArray
- (IBAction)button1TouchUp:(id)sender
{
    DebugLog(@"Populating Array");
    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0),
    ^{
        for (int i = 0; i < 10000000; ++i)
        {
            [array addObject:[NSNumber numberWithInt:i]];
        }
        DebugLog(@"Done Populating Array: %d", [array count]);
    });
}

- (IBAction)button2TouchUp:(id)sender
{
    DebugLog(@"Enumerating Array");
    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0),
    ^{
        DebugLog(@"Copying Array");
        NSArray *copyOfArray = [array copy];
        DebugLog(@"Done Copying Array");

        long long x = 0;
        for (NSNumber *number in copyOfArray)
        {
            x += [number intValue];
        }
        DebugLog(@"Done Enumerating Array: %d", [copyOfArray count]);
    });
}

Note: if you test this, do so in the simulator, a device will generate a memory warning and shutdown the test app.

The idea here is that by touching button1, we create a large array in a thread, and touching button 2, we enumerate that array. The array is large enough that it gives you time to ensure you touch button 2 while button 1's thread is still populating the array. If you didn't create the copy of the array before enumerating it button 2, the app will crash. Using the copy of pattern I mentioned in the last post, prevents that crash as expected.

Taking this a little further, the test code shows that when you take a copy of the mutable array, you get a copy of it at in its current state. If something is altering the array when you make the copy, you could get a copy of the array in an unusable or unexpected state. If you were adding or removing elements for example, you might have half of the elements in your copy while expecting all of them, or none of them.

If you need to ensure changes to an array are completed in full before another thread accesses it, you can use the @synchronized directive. The modified code looks like:

- (IBAction)button1TouchUp:(id)sender
{
    DebugLog(@"Populating Array");
    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0),
    ^{
        @synchronized(array)
        {
            for (int i = 0; i < 10000000; ++i)
            {
                [array addObject:[NSNumber numberWithInt:i]];
            }
            DebugLog(@"Done Populating Array: %d", [array count]);
        }
    });
}

- (IBAction)button2TouchUp:(id)sender
{
    DebugLog(@"Enumerating Array");
    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0),
    ^{
        @synchronized(array)
        {
            DebugLog(@"Copying Array");
            NSArray *copyOfArray = [array copy];
            DebugLog(@"Done Copying Array");

            long long x = 0;
            for (NSNumber *number in copyOfArray)
            {
                x += [number intValue];
            }
            DebugLog(@"Done Enumerating Array: %d", [copyOfArray count]);
        }
    });
}

The @synchronized directive creates a lock on the object for you.

A few points to be aware of:

  1. you need to use @synchronized around all places where you need to lock the object.
  2. the code will block until the object can be accessed, so if thread A is using the object thread B will pause until thread A is done with it, so be sure not to create a block on the main thread.
  3. if you define a property on a class as atomic, by omitting the non-atomic keyword, the synthesized accessors will include synchronization code and simply the code for you, but you still need to be aware of the blocking issues.

As always, I love reader feedback. Especially when you point out my mistakes, since that's the fastest way to learn more.

As you may be aware, I went full time indie a couple of months ago. I've been working almost as many hours as I can stay awake for clients, and spending whatever extra time I can find on a new game that I hope will be finished and submitted to the App Store before my next blog! I can't wait to tell you guys all about it.

With all this work though, I've been slacking in the blog department. Today I start to correct that. Here's a quick tip for today that may save you from a few crashes tomorrow.

It's a common sight to see something like this in Objective-C, where you're enumerating through an array (that's mutable), and doing something to each of the objects:

// self.objects is an NSMutableArray
for (NSObject *object in self.objects)
{
    [object doSomething];
}

If your app is multithreaded, you'll get a crash if another thread adds to or removes from the array at the same time this loop is being processed. Depending on timing, you might not see this bug hit until the app is being used by users.

Instead, anytime you're going to run through an array like this, make a copy first and enumerate the copy. Now you're multithreaded safe.

NSMutableArray *copyOfObjects = [self.objects copy];
for (NSObject *object in copyOfObjects)
{
    [object doSomething];
}
[copyOfObjects release]; copyOfObjects = nil;

Here's another common pattern you'll see, when you're enumerating the array in order to remove certain elements from it. Because you know you can't remove objects from the array as you're running through it, you create another array to store the the objects you want to remove and then remove them in a second step:

NSMutableArray *objectsToRemove = [[NSMutableArray alloc] init];

// self.objects is an NSMutableArray
for (NSObject *object in self.objects)
{
    if ([object shouldBeRemoved])
    {
        [objectsToRemove addObject:object];
    }
}
[self.objects removeObjectsInArray:objectsToRemove];
[objectsToRemove release]; objectsToRemove = nil;

Using the copyOf pattern above, you can remove the objects in a single step, since you're not actually enumerating the same array anymore:

NSMutableArray *copyOfObjects = [self.objects copy];
for (NSObject *object in copyOfObjects)
{
    if ([object shouldBeRemoved])
    {
        [self.objects removeObject:object];
    }
}
[copyOfObjects release]; copyOfObjects = nil;

Now you have nice, clean, efficient, crash free code.

RIP Steve Jobs

Steve,

Thanks for everything you've done to improve this world.  Thanks for giving us a platform with which to build a business, a career, and a life that's truly fulfilling.

You'll be missed.