Texture atlases (also called texture sheets, sprite sheets, flipbooks, or sub-UVs), are a way to pack multiple textures into a larger texture.
You can use them to represent animated textures, or to pack different unrelated textures together. Packing different unrelated textures allows to draw different particle renderers in the same draw-call, which helps rendering performance.
PopcornFX loads texture atlas definitions from .pkat files, which is a simple text file containing a list of UV coordinates.
The following components can currently use texture atlases:
The renderers allow you to specify a procedural atlas: If your texture is laid out in a regular grid of tiles, as is usually the case of animated flipbooks, you can specify the dimensions of that grid in the renderer’s properties:
When your texture sub-UVs are not laid out along a regular grid, you will need to use an external atlas definition file:
Creating atlas files
Non-procedural atlases will require you to provide an atlas definition file (with the “.pkat” extension).
This is required only for more complex packing layouts, which cannot be represented by a regular grid.
Originally, in PopcornFX v1.x, pkat files were created using the atlas builder tool that shipped with the v1 editor.
In v2, we chose not to keep maintaining this aging tool.
To create .pkat files, you can use the following tools that support exporting them out of the box:
- TexturePacker, since version 5.1.0
- Legacy atlas builder in the PopcornFX v1 editor (not recommended).
Alternatively, you can also create them by hand in a text editor (see the definition file format section below)
Exporting with TexturePacker
To export your texture sheet from TexturePacker into the PopcornFX format, simply click on the “DataFormat” button in the TexturePacker settings panel, and pick the “PopcornFX” exporter from the list:
Important note: Trimming the sprites is currently not supported, so make sure you keep the “Trim mode” setting under the “Sprites” category set to “None”
Atlas definition file format
The .pkat files are simple text files. They are formatted as follows:
- One line per sub-texture
- 4 values per line, separated by commas
- The decimal point is a dot, not a comma
- The values are normalized texture coordinates, between 0.0 and 1.0
- The coordinates are in the following order: left, top, right, bottom
For example, the .pkat file for a 2×2 texture atlas would look like this:
 | 0, 0, 0.5, 0.5 0.5, 0, 1, 0.5 0, 0.5, 0.5, 1 0.5, 0.5, 1, 1 |
Of course, the sub-rectangles can be anything, the whole texture doesn’t have to be covered entirely either.
The .pkat file for a 3×1 texture atlas only spanning half of the vertical height would look like this:
 | 0, 0, 0.333, 0.5 0.333, 0, 0.667, 0.5 0.667, 0, 1, 0.5 |
