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: 3realTextureFileName
the file name of the texturetextureFileName
in cocos2d: contained the sprite name without -hd extensionsize
size of the texturesmartupdate
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.