Sprite sheet data formats

Line endings

TexturePacker stores files with local file endings. That means LineFeed (LF) on macOS and Linux, CarriageReturn-LineFeed (CRLF) on Windows.

If you are using in a mixed environment with Windows and macOS or Linux clients, you should configure your license management system to convert between the different ending styles. See our tutorial How to handle line endings in git for more details about how you can do that.

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.