Pack textures and fonts at build time for your LibGDX project

When working with LibGDX and openGL ES we usually need to provide our application with various assets such as :

• PNG for textures
• Fonts (whether BitmapFont or FreeTypeFont) for texts
• Sounds
• 3D objects
• etc...

When designing the application, we need to take care of :

• Reducing the loading time of the assets by reducing the number of required assets
• Reducing the rendering time of the required assets by packing assets together 
• Reducing the integration time of the required assets by handling assets generation as part of the automated build process

A way of doing this is to pack all the required PNG for textures into a single TextureAtlas asset. LibGDX provides a TexturePacker utility for that. Some other third party utilities are usefull to generate BitmapFont that can be loaded by the LibGDX runtime.

As an experimented developper, we should expect regular changes among our application design during the development phase which means we should whether re-generate fonts and re-pack textures everytime or work with an application that is not efficient to load and to render (without packed assets and BitmapFont)... As a lazy developper, we might want all the assle of font and texture generation and packing to be handled automagically by the gradle build process.

Here is how we can achieve this...

The big picture

Okay, so let say we want to build an UI that renders a deck of cards using LibGDX :

Card Deck rendered with resources generated at build time

The UI is made of 52 sprites (one for each card) and a BitmapFont to render the label "LibGDX Card Deck"... Everything is laid out with a simple Table. What we want is to be able to change the finest detail with a little effort. For instance :

• change the red tone used for hearts and diamonds
• change the shape, the aspect ratio of the card
• increase the size of the rank
• decrease the size of the suite
• change the position of the rank / suit inside the card
• change the font used for the label

Project layout

When setting up a new LibGDX project you get something like this :

+ rootProject.projectDir
|--+ android

     |--+ assets
     |--+ build
     |--+ res
     |--+ src
     |--+ build.gradle
|--+ core
     |--+ src
     |--+ build.gradle
|--+ desktop
     |--+ src
     |--+ build.gradle
|--+ html

|--+ ios

|--+ resources

|--+ build.gradle

Where the ${rootProject.projectDir}/android/assets directory holds the assets required by the application (whatever the targeted platform : android, desktop, html or ios). So what we are going to do is to create a ${rootProject.projectDir}/resources directory containing the source files used to generate the required assets at build time. Intermediate temporary files will be generated into the ${rootProject.projectDir}/android/build directory.

Design of the cards

To design our card, we are going to use a SVG card pattern wich will define the overall aspect of the card : its shape and the position of the rank and the suit inside the shape. The SVG file will look something like this :

This SVG card pattern pattern use the custom SVGMASK file format defined by the AndroidSvgDrawable library. This allow us to generate all of the 52 combination of card rank x card suit without the need of 52 SVG files...

Then, we need 4 SVG files for suits (one for each card suit) and 13 SVG files for ranks (one for each card rank from 2 to A). Here are the sample files for Heart and King :

  

That's it, let see how we can now generate all of our 52 card textures at build time...

Generating the card textures

To generate the 52 textures, we will use the AndroidSvgDrawable plugin that now integrates better with LibGDX. First, we need to add the plugin dependency to our buildscript classpath in ${rootProject.projectDir}/build.gradle :

Then, we define a custom task in our ${rootProject.projectDir}/desktop/build.gradle file :

This will take the SVG card pattern file we put inside ${rootProject.projectDir}/resources/svg/mask and generate a PNG file for each SVG suit file x SVG rank file we put into ${rootProject.projectDir}/resources/svg/masked :

${rootProject.projectDir}/resources/svg/masked 

${rootProject.projectDir}/android/build/generated/assets

Generating the BitmapFont and the TextureAtlas

In order to generate the BitmapFont and the TextureAtlas at build time, we will rely on the API provided by LibGDX (we must use at least version 1.7.3-SNAPSHOT in order to be able to generate the BitmapFont as mentionned bellow). We should then add the necessary dependencies to our buildscript classpath in ${rootProject.projectDir}/build.gradle :

Most of the time, LibGDX APIs requires the LibGDX runtime to be loaded first, so we must add a specific task in our ${rootProject.projectDir}/desktop/build.gradle file that will load an headless LibGDX runtime for the build purpose :

Generating the BitmapFont

The BitmapFont will be generated from a TrueType font located in the ${rootProject.projectDir}/resources/font directory. A custom task in our ${rootProject.projectDir}/desktop/build.gradle file will generate the BitmapFont for us with the desired parameter :

A BitmapFont is made of 2 files :

• a .fnt file that will be output in the ${rootProject.projectDir}/android/assets directory directly
• a .png file that will be output in the ${rootProject.projectDir}/android/build/generated/assets directory because we want to merge it later with the others texture inside our final TextureAtlas...

You can refer to the LibGDX freetype documentation to customize the task to generate the desired font appearence. You can also use a more complexe task to generate BitmapFont of different size, colors, ...

Generating the Atlas

As all the required PNG are now generated inside the ${rootProject.projectDir}/android/build/generated/assets directory, we are now ready to pack them all inside a single TextureAtlas. Once again, we use a custom task in our ${rootProject.projectDir}/desktop/build.gradle file that will do the job for us :

And here is the final skin.png TextureAtlas generated with a default size of 1024 x 1024 that is available in the ${rootProject.projectDir}/android/assets directory along with its skin.atlas descriptor :

skin.png

Once again you can refer to the LibGDX Texture packer documentation for more packing options and a finest control over the generated atlas. Note that LibGDX Texture packer support packing of NinePatch drawable that could be generated at build time with the AndroidSvgDrawable plugin.

Let's build it

In order to chain all of those tasks together, we bind the compileJava task from the java gradle plugin to our custom generateATLAS task :

Here we are, everything is ready, we can just sit and watch gradle work for us :

gradlew desktop:run

:core:compileJava
:core:processResources UP-TO-DATE
:core:classes
:core:jar
:desktop:initHeadlessLibGDX UP-TO-DATE
:desktop:generateFONT
:desktop:generatePNG
:desktop:generateATLAS
assets
Packing.........
Writing 1024x1024: android\assets\skin.png
:desktop:compileJava
:desktop:processResources UP-TO-DATE
:desktop:classes
:desktop:run

BUILD SUCCESSFUL

Total time: 11.758 secs

And if we build it once again, the Gradle magic happens, nothing is re-generated or re-packed because everything is UP-TO-DATE :

gradlew desktop:run

:core:compileJava UP-TO-DATE
:core:processResources UP-TO-DATE
:core:classes UP-TO-DATE
:core:jar UP-TO-DATE
:desktop:initHeadlessLibGDX UP-TO-DATE
:desktop:generateFONT UP-TO-DATE
:desktop:generatePNG UP-TO-DATE
:desktop:generateATLAS UP-TO-DATE
:desktop:compileJava UP-TO-DATE
:desktop:processResources UP-TO-DATE
:desktop:classes UP-TO-DATE
:desktop:run

BUILD SUCCESSFUL

Loading and rendering the assets

Loading the assets requires only a single atlas to be loaded by the application while rendering all the cards and the label will bind a single OpenGL ES texture :

Want to be more optimal ? We can't !

Changing a detail

One more thing ! It's now possible to change the card layout for all our cards by changing only one file. If I modify the SVG card pattern to have the suit in the center of the card and the rank in the upper left corner and the lower right corner as well :

When building the project once again :

gradlew desktop:run

:core:compileJava
:core:processResources UP-TO-DATE
:core:classes
:core:jar
:desktop:initHeadlessLibGDX UP-TO-DATE
:desktop:generateFONT UP-TO-DATE
:desktop:generatePNG
:desktop:generateATLAS
assets
Packing.........
Writing 1024x1024: android\assets\skin.png
:desktop:compileJava
:desktop:processResources UP-TO-DATE
:desktop:classes
:desktop:run

BUILD SUCCESSFUL

Total time: 11.758 secs

Then, the layout has been changed for all of the 52 cards :

Simple isn't it ?

You can find the whole LibGDX project in the sample directory of the AndroisSvgDrawable plugin GitHub project.