INDIE DEVELOPERS DISCOUNT Independent developers get 50% discount on single user licenses for TP, PE and SI Visit store

Cocos2d/Cocos2d-x plist file format

2016-01-29 Andreas Löw

This post describes cocos2d plist file format version 3 and extensions made for TexturePacker.

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

<?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
    <plist version="1.0">
                    ... sprite data ...
                    ... sprite data ...
                ... meta data ...


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

    <string>1 4 5 2 3 4 1 2 4 0 1 5</string>
    <string>254 133 131 256 121 256 3 130 57 76 199 75</string>
    <string>503 59 380 182 370 182 252 56 306 2 448 1</string>
a reference to sprites containing the same image data (not used by TexturePacker)
translation vector: the offset of the sprite's untrimmed center to the sprite's trimmed center
size of the trimmed sprite
size of the untrimmed sprite
sprite's position and size in the texture
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.


The meta data block stores additional information.

the file format version: 3
the file name of the texture
in cocos2d: contained the sprite name without -hd extension
size of the texture
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.

Did you like the tutorial? Please share!