Creating Texture Atlas JSON files

Json files are used in javascript to describe simple data structures or objects. We use them in Kiwi.js to define TileMaps and texture atlases. This tutorial we cover how to write your own JSON files for use with your texture atlases.

Creating Texture Atlas JSON Files

Texture atlas JSON files consist of three parts, a name, an array of cells and an array of sequences. Let’s dissect a basic JSON file (named ‘atlasJSON’) and look at each part in more detail.

The name is used as a unique variable by the Kiwi.js library. You do not need to worry about it, but all your JSON
files must have unique names.

Next are the definitions of the cells of the atlas. Each cell is defined by having a x, y coordinate as well as a width and height. This is because cells of a texture atlas can be at different coordinates and have different sizes. Cells could also occupy the same space within a image!

Take note that the order in which you define the cells is also important, as that will be the order they are stored in the array. For example, the first cell you define will be in position 0, the second in position 1 and so on.

Cells may also have defined hit boxes, which  used for collision detection in Kiwi.js. Hit boxes are determined with x and y positions and width and height variables. 

Lastly we can define set animation sequences which we can add to our game objects. Sequences are defined with a name, which will transfer to the name of the animation, which cells are being used and in which order, whether or not the sequence is looping and the speed at which the animation is played at.

Note that this looks very similar to the way you add animations to a sprite object. Because it is exactly the same thing!

Sequences are automatically added as a new Animations to EVERY GameObject that uses that TextureAtlas when you create a new Sprite. This way you are defining sequences which can be used by many objects at once.

How to Add JSON Texture Atlases to you Kiwi.JS game

Now that we have created the JSON file we will need to add it to the game attached to the texture atlas so we can draw animations and images from the atlas. This is done the same way as you would add a sprite sheet or an image but with a texture atlas you have to add the JSON file as a parameter to the addTextureAtlas method. This looks like this:

This will add the texture atlas and the JSON to the cache of the game. Once you have added this you will then want to either add an animations to a sprite or one of the sequences that you created in the JSON.

For an single frame:

For a sequence:

Now that you know how to write your own JSON Texture Atlas file, have a go at using one in your game.

Share the joy
Comments 2
  1. There are a few tools out there for generating texture atlases, like TexturePacker, but we have not implement any translation/conversion scripts for them at this point. We do have this planned for the future though.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">