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 framesmetadata
- 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.