cocos2d-x plist file format

Andreas Löw
Last updated:

cocos2d-x plist file format

Description of the plist file format used for sprites sheets in cocos2d and cocos2d-x and Axmol Engine.

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"
<plist version="1.0">
                ... sprite data ...
                ... sprite data ...
            ... meta data ...

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

    <string>{{252, 1},{251, 181}}</string>
    <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>
  • 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.


The meta data block stores additional information.

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