Atlas export format

This page describes Spine's texture atlas format, which is based on the libgdx atlas format. The Spine Runtimes load this data to display animations.

The Spine Runtimes handle loading the texture atlas data. You do not need to write your own loading code unless you are writing your own runtime from scratch (which is an enormous amount of work).

The format is a simple, line-based text format made up of one or more page entries, each with any number of region entries. Page entries are separated by a blank line. Whitespace other than newlines is optional. Here is an example atlas with 2 pages:

Page sections

The page section provides the page image name and information about loading and rendering the image. Here is an example of the page section header:

Page properties:

• name: The first line is the image name for this page. Where the image is located is up to the atlas loader, but typically it is relative to directory containing the atlas file.
• size: The width and height of the page image. This is useful for the atlas loader to know before it loads the image, eg to allocate a buffer. 0,0 if omitted.
• format: The format the atlas loader should use to store the image in memory. Atlas loaders may ignore this property. Possible values: Alpha, Intensity, LuminanceAlpha, RGB565, RGBA4444, RGB888, or RGBA8888. RGBA8888 if omitted.
• filter: Texture filter minification and magnification settings. Atlas loaders may ignore this property. Possible values: Nearest, Linear, MipMap, MipMapNearestNearest, MipMapLinearNearest, MipMapNearestLinear, or MipMapLinearLinear. Nearest if omitted.
• repeat: Texture wrap settings. Atlas loaders may ignore this property. Possible values: x, y, xy, or none. none if omitted.
• pma: If true, the image for this page has had premultiplied alpha applied. false if omitted.

Region sections

The region section provides the region location within the page image and other information about the region. Here is an example of a region section:

Region properties:

• name: The first line is the region name. This is used to find a region in the atlas. Multiple regions may have the same name if they have a different index.
• index: An index allows many images to be packed using the same name, as long as each has a different index. Typically the index is the frame number for regions that will be shown sequentially for frame-by-frame animation. -1 if omitted.
• bounds: The x and y pixel location of this image within the page image and the packed image size, which is the pixel size of this image within the page image. 0,0,0,0 if omitted.
• offsets: The amount of whitespace pixels that were stripped from the left and bottom edges of the image before it was packed and the original image size, which is the pixel size of this image before it was packed. If whitespace stripping was performed, the original image size may be larger than the packed image size. If omitted, 0,0 is used for the left and bottom edges and the original image size is equal to the packed image size.
• rotate: If true, the region was stored in the page image rotated by 90 degrees counter clockwise. Otherwise it may be false for 0 rotation or a number representing degrees from 0 to 360. 0 if omitted.
• split: The left, right, top, and bottom splits for a ninepatch. These are the number of pixels from the original image edges. Splits define a 3x3 grid for a scaling an image without stretching all parts of the image. null if omitted.
• pad: The left, right, top, and bottom padding for a ninepatch. These are the number of pixels from the original image edges. Padding allows content placed on top of a ninepatch to be inset differently from the splits. null if omitted.

A blank line after a region section denotes the end of regions for a page. The next line after that will be either another page section or the end of the file.

Name/value pairs

Region values with names other than the above are stored as name/value pairs. This allows extra data to be associated with each region. Spine uses this for image export of frame-by-frame animation to store the origin (the offset for the position of world 0,0) and bone locations for each region.

Rendering

Special care must be taken when rendering a region from an atlas, depending on the texture packing settings that created the atlas. These settings can result in more efficient texture packing, but to simplify rendering they can be disabled when the atlas is created.

Rotation

If the region was stored in the atlas rotated, rendering needs to adjust the UVs to compensate for the rotation.

Whitespace stripping

If the region was stripped of whitespace around its edges before being packed, rendering needs to adjust the drawing position so it appears as though the whitespace was not removed.

If a region can be drawn flipped, the whitespace stripping must be taken into account when rendering the flipped region.

The amount of whitespace removed from the right and top edges can be calculated this way: