Using a texture atlas

If you’re working on a big, complex game, you’ll want a fast and efficient way to create sprites from tilesets. This is where a texture atlas becomes really useful. A texture atlas is a JSON data file that contains the positions and sizes of sub-images on a matching tileset PNG image. If you use a texture atlas, all you need to know about the sub-image you want to display is its name. You can arrange your tileset images in any order and the JSON file will keep track of their sizes and positions for you. This is really convenient because it means the sizes and positions of tileset images aren’t hard-coded into your game program. If you make changes to the tileset, like adding images, resizing them, or removing them, just re-publish the JSON file and your game will use that data to display the correct images. You won’t have to make any changes to your game code.

Pixi is compatible with a standard JSON texture atlas format that is output by a popular software tool called Texture Packer. Texture Packer’s “Essential” license is free. Let’s find out how to use it to make a texture atlas, and load the atlas into Pixi. (You don’t have to use Texture Packer. Similar tools, like Shoebox or spritesheet.js, output PNG and JSON files in a standard format that is compatible with Pixi.)

First, start with a collection of individual image files that you’d like to use in your game.

(All the images in this section were created by Lanea Zimmerman. You can find more of her artwork here. Thanks, Lanea!)

Next, open Texture Packer and choose JSON Hash as the framework type. Drag your images into Texture Packer’s workspace. (You can also point Texture Packer to any folder that contains your images.) It will automatically arrange the images on a single tileset image, and give them names that match their original image names.

(If you’re using the free version of Texture Packer, set Algorithm to Basic, set Trim mode to None, set Extrude to 0, set Size constraints to Any size and slide the PNG Opt Level all the way to the left to 0. These are the basic settings that will allow the free version of Texture Packer to create your files without any warnings or errors.)

When you’re done, click the Publish button. Choose the file name and location, and save the published files. You’ll end up with 2 files: a PNG file and a JSON file. In this example my file names are treasureHunter.json and treasureHunter.png. To make your life easier, just keep both files in your project’s images folder. (You can think of the JSON file as extra metadata for the image file, so it makes sense to keep both files in the same folder.) The JSON file describes the name, size and position of each of the sub-images in the tileset. Here’s an excerpt that describes the blob monster sub-image.

"blob.png":
{
    "frame": {"x":55,"y":2,"w":32,"h":24},
    "rotated": false,
    "trimmed": false,
    "spriteSourceSize": {"x":0,"y":0,"w":32,"h":24},
    "sourceSize": {"w":32,"h":24},
    "pivot": {"x":0.5,"y":0.5}
},

The treasureHunter.json file also contains “dungeon.png”, “door.png”, “exit.png”, and “explorer.png” properties each with similar data. Each of these sub-images are called frames. Having this data is really helpful because now you don’t need to know the size and position of each sub-image in the tileset. All you need to know is the sprite’s frame id. The frame id is just the name of the original image file, like “blob.png” or “explorer.png”.

Among the many advantages to using a texture atlas is that you can easily add 2 pixels of padding around each image (Texture Packer does this by default.) This is important to prevent the possibility of texture bleed. Texture bleed is an effect that happens when the edge of an adjacent image on the tileset appears next to a sprite. This happens because of the way your computer’s GPU (Graphics Processing Unit) decides how to round fractional pixels values. Should it round them up or down? This will be different for each GPU. Leaving 1 or 2 pixels spacing around images on a tilseset makes all images display consistently.

(Note: If you have two pixels of padding around a graphic, and you still notice a strange “off by one pixel” glitch in the way Pixi is displaying it, try changing the texture’s scale mode algorithm. Here’s how: texture.baseTexture.scaleMode = PIXI.SCALE_MODES.NEAREST;. These glitches can sometimes happen because of GPU floating point rounding errors.)

Now that you know how to create a texture atlas, let’s find out how to load it into your game code.