PC Games

Lasagne Monsters
Three Guys Apocalypse
Water Closet
Blob Wars : Attrition
The Legend of Edgar
TBFTSS: The Pandoran War
Three Guys
Blob Wars : Blob and Conquer
Blob Wars : Metal Blob Solid
Project: Starfighter
TANX Squadron

Android Games

Number Blocks
Match 3 Warriors


2D shoot 'em up
2D top-down shooter
2D platform game
Sprite atlas tutorial
Working with TTF fonts
2D adventure game
Widget tutorial
2D shoot 'em up sequel
2D run and gun
Medals (Achievements)
2D turn-based strategy game
SDL 1 tutorials (outdated)

Latest Updates

SDL2 turn-based strategy tutorial
Thu, 14th April 2022

Water Closet ported to PlayStation Vita
Tue, 4th January 2022

The Legend of Edgar 1.35
Sat, 1st January 2022

Achievements tutorial
Thu, 2nd December 2021

SDL2 Rogue tutorial
Thu, 30th September 2021

All Updates »


android (3)
battle-for-the-solar-system (9)
blob-wars (9)
brexit (1)
code (6)
edgar (7)
games (39)
lasagne-monsters (1)
making-of (5)
match3 (1)
numberblocksonline (1)
orb (2)
site (1)
tanx (4)
three-guys (3)
three-guys-apocalypse (3)
tutorials (10)
water-closet (4)


The Attribute of the Strong (Battle for the Solar System, #3)

The Pandoran War is nearing its end... and the Senate's Mistake have all but won. Leaving a galaxy in ruin behind them, they set their sights on Sol and prepare to finish their twelve year Mission. All seems lost. But in the final forty-eight hours, while hunting for the elusive Zackaria, the White Knights make a discovery in the former Mitikas Empire that could herald one last chance at victory.

Click here to learn more and read an extract!

« Back to tutorial listing

— Sprite Atlas Tutorial —
Part 3: Creating the atlas meta data

Note: this tutorial assumes knowledge of C, as well as prior tutorials.


In the previous two tutorials, we gathered the details of the images we wanted to add to our atlas, and ran through the process of actually creating it. The final step is to output the meta data, so the atlas can be used by games and applications that require it. We'll be outputting the details of the added images as a JSON array, since the format is easy to read and understand, and is well supported. Using some C code written by Dave Gamble, we can easily marshall our data into JSON (and read it back later). Compile the code using make, and then run it with ./gen03. You'll now see both the atlas.png and an atlas.json file. Open up the JSON file and take a look at the contents. You'll find it matches what was added to the atlas.

Inspecting the code

Outputting the meta data of the atlas is very easy, thanks for Dave's code. After adding the cJSON.h header to our own atlasGen.h, we can call the CJSON functions. All this is done in main. The first thing we want to do is create a JSON array:

rootJSON = cJSON_CreateArray();

Simple enough. Now we need to add the details of the images themselves. Within the main for-loop, after we've added the image to the atlas, we want to create a JSON object, and add the details of the image to it.

entryJSON = cJSON_CreateObject();

cJSON_AddStringToObject(entryJSON, "filename", images[i].filename);
cJSON_AddNumberToObject(entryJSON, "x", dest.x);
cJSON_AddNumberToObject(entryJSON, "y", dest.y);
cJSON_AddNumberToObject(entryJSON, "w", dest.w);
cJSON_AddNumberToObject(entryJSON, "h", dest.h);
cJSON_AddNumberToObject(entryJSON, "rotated", rotated);

The first thing we do is create the JSON object by calling cJSON_CreateObject. With that done, we want to add the image's filename, by calling cJSON_AddStringToObject. The key of the string is "filename", with the value being the image filename itself. Next, we want to add the coordinates where the image resides on the atlas (its x, y, w, and h values). We can do this by calling cJSON_AddNumberToObject, and specifying the appropriate key and value. We also want to add the rotated value (which will either be a 0 or 1) to the object.

The above will create a JSON object that will resemble the following:

	"filename": "gfx/tall/long.png",
	"x": 0,
	"y": 0,
	"w": 34,
	"h": 128,
	"rotated": 0

As you can see, working with cJSON makes things very easy. With all the image data added to the object, we need only add it to the main JSON array. This is a single function call using cJSON_AddItemToArray, passing in the rootJSON variable as the array we wish to use and the entryJSON as the object we want to add:

cJSON_AddItemToArray(rootJSON, entryJSON);

This is done for all the valid images in the atlas (we don't want to add images that we failed to add to the atlas, for whatever reason). When we have completed looping through the images and creating the JSON object, the last thing we need to do is save the data. Once again, cJSON makes this very easy. A call to cJSON_Print, passing in the rootJSON reference, will return use a char array with the nicely formatted JSON:

out = cJSON_Print(rootJSON);

We then just need to save this data by writing it to a file, using the standard C IO calls:

fp = fopen("atlas.json", "wb");
fprintf(fp, "%s", out);

Opening the atlas.json file, we'll see we've got data like this:

	"filename":	"gfx/tall/long.png",
	"x":	0,
	"y":	0,
	"w":	34,
	"h":	128,
	"rotated":	0
}, {
	"filename":	"gfx/misc/pinkTextured.png",
	"x":	35,
	"y":	0,
	"w":	121,
	"h":	123,
	"rotated":	0
}, {
	"filename":	"gfx/cubes/bigGrey.png",
	"x":	157,
	"y":	0,
	"w":	62,
	"h":	63,
	"rotated":	0
}, {
	"filename":	"gfx/cubes/bigGreen.png",
	"x":	0,
	"y":	129,
	"w":	62,
	"h":	63,
	"rotated":	0
}, {

The very final thing we need to do is clean up the memory we used. We can delete the JSON array and all its child objects with one call to cJSON_Delete, passing in the rootJSON variable. We also need to free the char array that was created when we printed it out, with a call to free.



There we have it, a basic sprite atlas generator! The nice thing about this generator is that since the output is JSON, it's very flexible and can be used in a variety of places. In the next tutorial, we'll look into how we can use the atlas in an SDL application.


The source code for all parts of this tutorial (including assets) is available for purchase:

From itch.io

It is also available as part of the SDL2 tutorial bundle:


If you do not wish to create an itch.io account, you can also purchase the tutorial bundle using PayPal, and then download the tutorials directly from the main tutorials page.

SDL2_Tutorials.tar.gz 56.76MB 23rd April 2022

Click here to see the list of files in the archive

Mobile site