"Script-Defined" Image Maps (Tech Demo 3)

Hey everyone,

I thought I'd document a few of my tech successes updating the Torque2D engine. This one is about creating ImageMaps (sprite sheets) with variable-sized frames. (Skip to the end for a video.)

This code has been published here: www.garagegames.com/community/forums/viewthread/130503


(Also, if you enjoy this tech demo, please consider "paying forward" with a click on my game's like button, here: facebook.com/RednecksVsRobots. Gonna look for some funding soon and likes will help, I hope!)

torque2D ImageMap types

As you probably know, Torque has two ways to retrieve the frames, or individual images, out of an ImageMap. Those two ways are "cell" and "key" modes:

1. ) Cell Mode - You must make sure all your frames are the same size, say 100x50. Then you use the "cell" mode on an ImageMap and tell Torque2D that your images are each 100x50. It will break the ImageMap down accordingly. If you have varied sized images to store, you'll have to either pad them with empty space or try something else. But I assume many basic sprite animations can use same-sized sprites without much waste. These are also usually easier to "register" or match one to the next on-screen. You simply keep the rectangle positioned so that the animation of the frames plays out "in the middle" like a flipbook.


2. ) Key Mode - You can use a unique "key" color and use the fairly sophisticated "key" mode on an ImageMap. In short, the first pixel of the image defines the key color, say pink. Then frames are stored in rows in the map. If the frames aren't the same height and/or width, that's OK. As long as you follow certain rules, frames will be found. This is better on space, and it does allow you to have different-sized frames; but I haven't found any pro tools that can save in this format! Within Torque Game Builder -- the editor -- key mode seems to be mostly used with bitmaps for GUIs, which are often small little thumb buttons and close boxes and the like all smashed into one small image. Ultimately they should save space but it could be more efficient.

my new "script-defined" image map frames

The idea behind the "scripted" mode ImageMaps is that for every image map Torque should call your code and you will define where the frames are, dynamically. Once an image map is set to script mode, your game (and the Torque Game Builder) will call you once per image map. You'll get a reference to the ImageMap, and the name of the image file passed to your callback, but that's all the engine really knows. From here, you run your method and call addFrame(index,x,y,w,h) once per frame. When your method returns, Torque assumes all the frames are defined and moves on.

Specifically, I use it to read an XML file, which has the same name as the image map, and which acts as a "manifest" of all the frames in the image. So for instance, robotPuppet.png will have a matching robotPuppet.xml. I can then use TorqueScript's XML functions to parse the file and call addFrame() for each frame listed in the manifest.

The idea came about when using Texture Packer. This is a great tool (and cheap) for creating images maps in many different formats. It excels at, well, packing the textures tightly, even allowing for rotation if that helps fit more textures on the sheet. One of its output formats is a "generic XML" format which is what I use now.

I'll show an example in a second, but first I want to be fair about the downsides... asking Torque to call your script can be confusing if your script has bugs or doesn't handle some problem with a corrupted file. The game, or the editor, isn't "up" yet when it preloads images, so the only output is in the console.log file. This is fine for us server programmers, but a little odd when using visual tools. Torque Game Builder, or you game, may start with the images botched. And if you screw something up, it won't be very obvious. In my defense, Torque doesn't have too many easy ways to inform you that it is having troubles and allow you to repair it in real-time.

In any case, I wanted to do something generic, so I stuck with the idea of calling your script and receiving the frames in return. You could, for instance, create many kinds of XML files, or even files in some other format. You could not even have a "manifest" file at all, and instead come up with your own variation of key mode (although you wouldn't have any tools to read the image pixels to find colors and what-not). Or perhaps you want one big manifest for all your images. Whatever works.

demo

So once again, without further philosophizing, here is some demo material. Since I haven't found a way to show images on the GarageGames blog server, I'm going to just show the XML output that goes with a robot file. The images are in the video later. For this robot, the "frames" are the individual components (treads, body, ...) that make up the robot and the robot has two different sets of pieces for two different animation modes, so you'll see "attack" parts and "walk" parts:

<?xml version="1.0" encoding="UTF-8"?>

	...

<TextureAtlas imagePath="generic.png" width="1011" height="1080">
    <sprite n="attack_antenna_1" x="733" y="826" w="27" h="98"/>
    <sprite n="attack_clawBottom_1" x="325" y="939" w="78" h="82"/>
    <sprite n="attack_clawTop_1" x="662" y="826" w="69" h="100"/>
    <sprite n="attack_drill_1" x="650" y="939" w="117" h="75"/>

	... you get the idea

    <sprite n="walk_clawBottom_1" x="2" y="939" w="77" h="85"/>
    <sprite n="walk_clawTop_1" x="512" y="826" w="71" h="107"/>
    <sprite n="walk_foreArmBack_1" x="585" y="826" w="75" h="102"/>
    <sprite n="walk_forearmFront_1" x="179" y="826" w="160" h="108"/>

	... and so forth

</TextureAtlas>

As a bonus, I'd like to keep these names for the parts around. Because Torque allows you to add fields to *any* object, including an ImageMap, I create an array in the ImageMap that was passed to my load function. So I'll have frameNames[0]=attack_antenna_1, etc. I can then cross reference this for the original name.

And here is some snippets (for expediency) from my "Generic XML Loader":

// the generic function that always gets called for all script-defined image maps
function onDefineImageMapFrames(%imageMap, %bitmapPath)
{
	 // record that we got here and why
   echo("onDefineImageMapFrames: ", %imageMap, " from ", %bitmapPath);

	 // build up the file name, such as images/robotPuppet.xml
   %imageMapAtlasName = filePath(%bitmapPath) @ "/" @ fileBase(%bitmapPath) @ ".xml";
   %xml = new SimXMLDocument();
   %xml.loadFile( %imageMapAtlasName ); // skipping error checking

   %xml.pushFirstChildElement( "TextureAtlas" )

	 // basically calls "loadTexturePackerXMLSprite" once every time an XML <sprite> is found
   YepUtil::callPerXMLChild(%xml, "sprite", 0, loadTexturePackerXMLSprite, %imageMap);

   %xml.delete();
}

function loadTexturePackerXMLSprite(%xml, %imageMap)
{
 	// check out the example Texture Packer XML output to see what I'm grabbing here
   %name = %xml.attribute("n");
   %x = %xml.attribute("x");
   %y = %xml.attribute("y");
   %width = %xml.attribute("w");
   %height = %xml.attribute("h");

	 // error checking removed

   // we want the frame "names" so store them in the ImageMap.
   %imageMap.frameNames[$onDefineImageMapFrames::TPFrameNumber] = %name;

   %imageMap.addFrame($onDefineImageMapFrames::TPFrameNumber, %x, %y, %width, %height);
   $onDefineImageMapFrames::TPFrameNumber++;
}

That's it. Here's a video. :)