Tuesday, October 9, 2012

Sprite Atlas Tool - Part II: Data Exports



 This is second part of article describing our tool for creating sprite atlases (SBC PicOpt). In Part I I described features of the tool as well as the way how to add custom properties like collision boxes to your sprites. It was also described how to create animations from the frames. If you followed it the tool created directory "export" during exporting and there are three files:
  • MyProj_N.png
  • MyProj_N.dat
  • MyProj_N.anm


Exported data

 First let us look at MyProj_N.dat. The header is very simple:
 short width  
 short height  
 short count  

width and height are dimensions of exported texture atlas and count in number of individual sprites in it. Next, blocks follow - each for every single sprite. Blocks have the same size but its total length can change depending custom on properties you created. Basic structure is like this:

 short x  
 short y  
 short width  
 short height  
 short offsetX  
 short offsetY  
x and y are position of top left corner of sprite within sprite atlas. Width and height are dimensions of the sprite - note that empty space around sprite is trimmed in export. OffsetX and offsetY is relative position against the central point (the red one). First time you import sprites the offset is decided by tool based on sprite position within imported grid (if you do not understand what I call grid read Part I). This allows you to create animations like this:
 and only one ball will be exported into final atlas while in data all three frames will be preserved. The only difference between them will be the offset part of data block.

Custom properties export

 If you created any custom properties your data block will be longer. Let's say you created the properties like this:

 then your export will look like this:

 // basic data  
 short x  
 short y  
 short width  
 short height  
 short offsetX  
 short offsetY  
 // ColBox  
 byte x1  
 byte y1  
 byte x2  
 byte y2  
 // MarkerPoint  
 short x  
 short y  
where all custom properties coordinates are relative to central point (the red one).

Animation data export

  If you do not have any animations the MyProj_anm will be 2 bytes long and it will contain zeros. It is because first short is the total number of animations exported. After that every animation is exported with very simple structure. First short says how many frames it contains and then so many times pairs of shorts follow for frame and delay. From the this table it will be very clear:

 // total number of all animations included in export  
 short number_of_animations
  
 // animation 0  
 short number_of_frames_for_animation_0  
 // frame 0  
 short sprite_index_within_atlas_data_export  
 short delay  
 // frame 1  
 short sprite_index_within_atlas_data_export  
 short delay  
  :  
  :  

 // animation 1  
 short number_of_frames_for_animation_1  
 // frame 0  
 short sprite_index_within_atlas_data_export  
 short delay  
 // frame 1  
 short sprite_index_within_atlas_data_export  
 short delay  
  :  
  :  

Conclusion

 As you can see the exports are very simple but flexible in adding your custom properties. Loading them is then very straightforward.