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.