Sprite packing tool for Cocos2d-x

Editors and Tools
#1

Hi,

I have written a pair of tools to build sprite sheets from the command line and I would like your opinion about them.

The first tool is auto-pack-my-sprites; it receives a collection of image files and build the sprite sheet from them:

# create a file named sprite-sheet.png with all the sprites from the assets directory
auto-pack-my-sprites assets/*.png

For example, here is a packing from a collection of sprites (thanks C-TOY for the assets):

b9026d8de38fd79f.png1024Ă—1024

This tool has options to control the size of the sprite sheet, to make the sprites “bleeding” and to adjust the margin between them, among others. It can also produce an atlas in the format used by Cocos2d-x:

# create a file named sprites.png of a maximum width and height of 2048
# pixels, with all the sprites from the assets/dry directory, as is, and
# all the sprites from the assets/bleed directory by
# making them bleeding; with no blank space between the sprites, and
# generate an atlas for Cocos2d-x.
auto-pack-my-sprites --output "sprites" \
    --size 2048x2048 \
    assets/dry/*.png \
    --bleeding assets/bleed/*.png \
    --margin 0 \
    --plist

It also supports generating multiple sprite sheets if all sprites cannot fit in a single one and generating CSS sprite sheets. In a sense, this tool is similar to glue and to the command line version of TexturePacker.

The second tool is pack-my-sprites; it creates the sprites by combining some layers selected from an XCF image (the format used by the GIMP) then pack them in a sprite sheet. Thus effectively preventing the tedious task of building the sprites as individual images in the GIMP.

For example, I draw all the parts of the animation in the GIMP:

00b2fb4f0b55998e.png1224Ă—928

Then I describe how to compose the sprites:

sprite_sheet "projectiles" 256 x 512 margin 1

lava "water-fire-stone.xcf.bz2"

"lava 1" image_size * 1 with lava
  "base"
;

"lava 2" image_size * 1 with lava
  "base 2"
;

"lava 3" image_size * 1 with lava
  "base 3"
;

"lava 4" image_size * 1 with lava
  "base 2"
  "bubble right 1"
;

"lava 5" image_size * 1 with lava
  "base"
  "bubble right 2"
;
/* …more frames… */

And I run the tool to build the sprite sheet

pack-my-sprites projectile.spritedesc

Ta-da:

From then I can rework the source image, rebuild the sprite sheet. As long as I don’t add more layers in the sprites (think layer groups!), the output will be immediately usable.

The C++ source of the tools is available on GitHub and licensed under the version 3 of the GNU AGPL.

For the future releases I plan to support the format used by libgdx, to add a tool to unpack an atlas (i.e. to extract the individual images of a sprite sheet) and to add an option to crop and trim the sprites. I also plan to replace the spritedesc format with something more classical, certainly a Json object.

What do you think of these tools? Is there a feature you would like to have?

2 Likes
#2

if I make a spritesheet with your tool, can I just drop it into my project and use SpriteFrameCache like:

_spritecache = cocos2d::SpriteFrameCache::getInstance();
_spritecache->addSpriteFramesWithFile("sprites.plist");
#3

Yes it should work with your code. When invoked with the --plist argument then the tools produce a .plist file respecting the syntax used by Zwoptex, which is supported by the sprite frame cache.

#4

Does your tool support polygon packing?

#5

It does not support polygon packing, though it would be a nice feature. Do you know any game engine that would support such format (except Cocos2d-x)?

#6

I don’t think there is a standard 2d format, although you could export using various 3d model formats (.fbx etc).

Most engines will be able to render custom meshes, and will even likely have support for 2d meshes. It might be necessary to write an importer for the engine or adhere to their bespoke format however. Unity is a good example, while it does have sprite polygon generation, importing your spritesheets would require a custom unity importer to generate sprite resources.

@AndreasLoew (Author of TexturePacker) will likely have more insight into this.