Sprite sheet data formats

cocos2d-x plist file

Description of the plist file format used for sprites sheets in cocos2d and cocos2d-x

The top level layout of the file consists of 2 <dict> entries:

frames - containing the sprite frames
metadata - texture size, format, texture file name

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>frames</key>
        <dict>
            <key>sprite-name-1.png</key>
            <dict>
                ... sprite data ...
            </dict>
            <key>sprite-name-2.png</key>
            <dict>
                ... sprite data ...
            </dict>
        </dict>
        <key>metadata</key>
        <dict>
            ... meta data ...
        </dict>
    </dict>
</plist>

Frames

frames is a dictionary containing the sprite names as key, the sprite values as <dict>.

Sprite Data

Polygon mesh data

Cocos2d-x assumes sprites to be built from rectangular texture parts by default.

If triangles, vertices and verticesUV is found inside the plist file polygon sprite are used instead of rectangles.

Polygon sprites can be used to increase rendering performance — especially when the sprite have many transparent pixels.

See Performance optimization for cocos2d-x using polygon sprite meshes for more details.

Anchor point data

Anchor point can be added to a sprite to overwrite the default pivot point location in cocos2d-x. The default location is the sprite center (0.5/0.5).

XML example

<key>sprite-name-1.png</key>
<dict>
    <key>aliases</key>
    <array/>
    <key>spriteOffset</key>
    <string>{0.5,-37.5}</string>
    <key>spriteSize</key>
    <string>{251,181}</string>
    <key>spriteSourceSize</key>
    <string>{256,256}</string>
    <key>textureRect</key>
    <string>{{252, 1},{251, 181}}</string>
    <key>textureRotated</key>
    <false/>
    <key>triangles</key>
    <string>1 4 5 2 3 4 1 2 4 0 1 5</string>
    <key>vertices</key>
    <string>254 133 131 256 121 256 3 130 57 76 199 75</string>
    <key>verticesUV</key>
    <string>503 59 380 182 370 182 252 56 306 2 448 1</string>
    <key>anchor</key>
    <string>{1,0.5}</string>
</dict>

aliases: a reference to sprites containing the same image data (not used by TexturePacker)
spriteOffset: translation vector: the offset of the sprite's untrimmed center to the sprite's trimmed center
spriteSize: size of the trimmed sprite
spriteSourceSize: size of the untrimmed sprite
textureRect: sprite's position and size in the texture
textureRotated: true if the sprite is rotated
triangles - cocos2d-x 3.9: Optional: Triangle indices (3) for a polygon sprites
vertices - cocos2d-x 3.9: Optional: Vertex coordinates (pairs of x and y) of a polygon sprites — describing vertices in the sprite image
verticesUV - cocos2d-x 3.9: Optional: Vertex coordinates (pairs of x and y) of a polygon sprites — describing the vertex position in the texture
anchor - cocos2d-x 3.11: Optional: Anchor point for the sprite in coordinates relative to the original sprite size. Sprite center (0.5/0.5) is used by cocos2d-x if omitted. The anchor point is assigned to new sprites.

MetaData

The meta data block stores additional information.

<key>metadata</key>
<dict>
    <key>format</key>
    <integer>3</integer>
    <key>realTextureFileName</key>
    <string>x.png</string>
    <key>size</key>
    <string>{504,183}</string>
    <key>smartupdate</key>
    <string>$TexturePacker:SmartUpdate:.....$</string>
    <key>textureFileName</key>
    <string>x.png</string>
</dict>

format: the file format version: 3
realTextureFileName: the file name of the texture
textureFileName: in cocos2d: contained the sprite name without -hd extension
size: size of the texture
smartupdate: Hash used by TexturePacker to detect changes in existing sprite sheets to speed up sprite sheet processing when used as part of the build process.