Texture Packer Tutorial: How to Create and Optimize Sprite Sheets

Installing the Texture Packer Command Line Tool

When using Texture Packer, you can use the GUI tool as you did here, or you can integrate it into your Xcode build so it automatically updates your sprite sheets for you (if necessary) each time you compile. To use the command line tool you will need to install it. Texture Packer makes this a snap! Launch Texture Packer and select the Install Command Line Tool option in the TexturePacker menu.

Upon selecting this menu option you will be greeted with a dialog box asking where to install the utility. The default location of /usr/local/bin is the best place, so go ahead and click Install. You may be prompted to enter admin privileges in order have the file written. When done the install, you will be greeted with an Installation seems to be fine dialog. Click OK, then click Done in the remaining dialog. You now have the command line tool installed :]

Open a terminal window and just type TexturePacker and hit return. You should see a help screen scroll by. Next, you will integrate this into your Xcode project's build cycle.

Everything you can do with Texture Packer, you can do with the command line tool (named TexturePacker, oddly enough!).

Texture Packer and XCode Integration

If you've worked on a Cocos2D 2.x game in the past, you know how annoying it can be to have to constantly regenerate your sprite sheets. Even if it only takes a couple seconds each time, it adds up and gets old quickly.

So, let's automate this for our project - it only takes a few seconds and saves a lot of time later. Right click on Resources, choose New File..., choose OS X\Other\Shell Script, and click Next. Name the file PackTextures.sh, select the Resources directory of your TextureFun project, and click Create.

Then replace the contents of PackTextures.sh with the following:

#!/bin/sh

TP="/usr/local/bin/TexturePacker"
cd ${PROJECT_DIR}/${PROJECT}

if [ "${ACTION}" = "clean" ]; then
    echo "cleaning..."
    
    rm -f Resources/sprites*.pvr.ccz
    rm -f Resources/sprites*.plist

    rm -f Resources/background*.pvr.ccz
    rm -f Resources/background*.plist

    # ....
    # add all files to be removed in clean phase
    # ....
else
    #ensure the file exists
    if [ -f "${TP}" ]; then
        echo "building..."
        # create assets
        ${TP} --smart-update \
        --format cocos2d \
        --texture-format pvr2ccz \
        --main-extension "-ipadhd" \
        --autosd-variant 0.5:-hd \
        --autosd-variant 0.25: \
        --data Resources/sprites-ipadhd.plist \
        --sheet Resources/sprites-ipadhd.pvr.ccz \
        --dither-fs-alpha \
        --opt RGBA4444 \
        TextureFun_Art/sprites/*.png

        ${TP} --smart-update \
        --format cocos2d \
        --texture-format pvr2ccz \
        --main-extension "-ipadhd" \
        --autosd-variant 0.5:-hd \
        --autosd-variant 0.25: \
        --data background-ipadhd.plist \
        --sheet background-ipadhd.pvr.ccz \
        --dither-fs \
        --opt RGB565 \
        --border-padding 0 \
        --width 2048 \
        --height 2048 \
        TextureFun_Art/background/*.png
        # ....
        # add other sheets to create here
        # ....

        exit 0
    else
        #if here the TexturePacker command line file could not be found
        echo "TexturePacker tool not installed in ${TP}"
        echo "skipping requested operation."
        exit 1
    fi

fi
exit 0

This script simply runs the TexturePacker command line tool to create sprite sheets from the files in your Art directory - just like you did a little bit ago with the GUI tool. Check the TexturePacker command line help for more information about what each of these commands does.

Next, you need to set up your project to run this shell script when you compile. Select your project in Xcode, select the TextureFun target under TARGETS, and click the Add Target button on the bottom. Select OSX, Other, External Build System and click Next.

For the Product Name enter TexturePacker, and click Finish. Now select the new Tartget and enter /bin/sh in the Build Tool field. Finally, enter ${PROJECT_DIR}/${PROJECT}/Resources/PackTextures.sh for the Arguments field. This allows Xcode to find your PackTextures.sh script by searching off where your project is located.

Adding The Target As Part Of The Build

The final step is to set this target as a dependency of your app. Single click on your TextureFun target, go to the Build Phases tab, select the Target Dependencies row and expand it. Click the + button and select the TexturePacker Target in the dialog.

Compile and run your app, and you should see the output from Texture Packer from your build results if everything is working OK.

If you see those printouts, that means that if you want to add a new file to your sprite sheet, literally all you need to do is drop it into your sprites directory and recompile! Pretty convenient, eh?

Once you take the time to integrate Texture Packer into your XCode project, you will love life. It makes things so convenient, especially when working back and forth with your artist in the development cycle.

Why get the Pro version?

The pro license gets you is an ability to greatly simplify the script you used above within Xcode by referencing the .tps files you created within TexturePacker, removing the need to code out all those settings in the script.

The other advantage is you can change your settings graphically and update/save the new tps file and Xcode will pick it up the next time it does a build! The new (pro) version of the PackTextures.sh script becomes:

#!/bin/sh

TP="/usr/local/bin/TexturePacker"
cd ${PROJECT_DIR}/${PROJECT}

if [ "${ACTION}" = "clean" ]; then
    echo "cleaning..."
    
    rm -f Resources/sprites*.pvr.ccz
    rm -f Resources/sprites*.plist

    rm -f Resources/background*.pvr.ccz
    rm -f Resources/background*.plist

    # ....
    # add all files to be removed in clean phase
    # ....
else
    #ensure the file exists
    if [ -f "${TP}" ]; then
        echo "building..."
        # create assets
        ${TP} --smart-update Resources/sprites.tps

        ${TP} --smart-update Resources/background.tps

        # ....
        # add other sheets to create here
        # ....

        exit 0
    else
        #if here the TexturePacker command line file could not be found
        echo "TexturePacker tool not installed in ${TP}"
        echo "skipping requested operation."
        exit 1
    fi

fi
exit 0

In the above script you are referencing the sprite.tps and the background.tps files rather than writing out all those options as you did earlier! What a time-saver :]

Where To Go From Here?

Here is a sample project with all of the code from the above tutorial.

If you have any good strategies for efficiently using Texture Packer, or any extra cool information, please let me know! :]