Posted: 10 May 2012
Tags: libgdx, texture atlas, texturepacker

Tutorial for TexturePacker and libGDX

TexturePacker is a slick GUI for building an optimized texture atlas for texture-heavy applications. This tutorial walks through the most basic aspects of using it with libGDX.

This tutorial is based on the Pro version of TexturePacker 2.4.2. And I'm using the 0.9.3 version of libGDX. I'm running on Windows, but that shouldn't matter.

I assume you've got your libGDX application set up already (especially the part about configuring the asset folder). Ideally, you should have an application that already works with individual texture files, and you just want to switch to a texture atlas.

Generate the Atlas

1. Start TexturePacker. By default a new, empty project is started. Note that you can have multiple atlases open for editing (each time you click 'New' a new TexturePacker window is opened.)
2. Click 'Add Sprites' on the toolbar or in the Edit menu. Add a couple sprites to this Atlas, you can add more later.
3. Click 'Save As...' in the File menu to save your state and give the output files some default names. I use "packed.tps" as the save-file name in this example.
4. In the Texture Settings along the left side, make sure the Output section is open. Under Output change the "Data Format" to "LibGDX". TexturePacker will generate two files for a libGDX atlas: a .txt file that describes the atlas (in a format that libGDX expects), and an image file (.png by default) that is the atlas.
5. The libGDX TextureAtlas expects these two files to be in the same directory (and the name of the image file is embedded in the .txt file, too).
6. Change the "Data file" and "Texture file" entries in Texture Settings to save directly to your libGDX project's Android "asset" folder. The basename of the files should be fine at this point, but feel free to change them as you see fit. (Or, manually copy the files after publishing them.)
7. If you are targeting OpenGL ES 1.x make sure "Allow free sizes" is unchecked in the Geometry section of the settings. This will ensure the atlas image dimensions are a power of two.
8. The other settings in TexturePacker should be fine at their defaults.
9. Click "Publish" on the toolbar to create the .txt and image file in your asset directory. (Note that "Save" does not generate the atlas, it just saves the configuration.)
10. Now is a good time to Save your state. You can exit TexturePacker now, and concentrate on the libGDX side.

Use the Atlas

1. Let Eclipse know you made changes behind its back by refreshing the assets directory (right-click on the "assets" directory and select Refresh). You should see your .txt and .png (or whatever) images files here.
2. Inside your libGDX application, the atlas published to your Android application's assets directory should now be accessible as a libGDX "internal" file.
3. You can open the atlas by referencing the .txt file that TexturePacker generated, as in: TextureAtlas myTextures = new TextureAtlas("packed.txt");
4. Texture regions can be pulled out of the atlas by looking them up with findRegion (names are based on the original file names, without an extension). So, for an original image named "foo.png", something like myTextures.findRegion("foo") will fetch the TextureAtlas.AtlasRegion representing that original image. See TextureAtlas for additional APIs for looking up elements.
5. When rendering, either use the TextureRegion directly with Sprites and/or SpriteBatch, or bind the atlas texture, and set your mesh's (u, v) texture attributes to those provided by the TextureRegion.

That should cover the basics for hooking up your libGDX application with a texture atlas generated from TexturePacker.