WBTMXTool: TMX file HD/SD converter

Recently there has been a big enhancement to cocos2d-iphone code for the Retina Display support. This has made it a lot easier for iPhone developers to support HD and SD graphics in their games. Big Thank You to Riq for this!

When I started supporting HD a few days ago, I have found that there are still some issues when we are using both HD and SD TMX files in the game. Basically I had hoped that cocos2d would return Points by default no matter what format I use based on -hd suffix in the TMX file. The RetinaDisplay wiki page currently indicates that the complex TMX object uses Pixels, not Points. My test has also proved that this is true and that the returned tile object’s coordinate systems are not converted to Points at all. I guess this falls into the 5% exception of the current cocos2d-iphone’s RetinaDisplay support.

There can be several options to work around this issue. One option may be to use a single TMX file for coordinates of objects across HD and SD graphics and to convert coordinates in run time. With this option, when objects are included in the same TMX file along with layers for graphics, they will not be in sync in terms of locations of objects in either one of the HD/SD formats.

To support HD and SD together for my upcoming games going forward,  it is my preference that I start designing everything in HD - i.e. HD graphics, HD coordinates in TMX. When I am ready to support SD at a point, I want to use tools for the HD-to-SD conversion - no manual work again! It’s also ideal to have a command-line tool so that it can be easily integrated with my automatic X-Code build process. Even though I can use the commercial tools such as Zwoptex or TexturePacker to generate SD images, I had no luck to finding a tool for TMX files to meet the needs.

I think my development process may be unique but hope that some of you may also find this article useful when you are developing.

This is a brief background of why I made this tool/prototype.

After many many hours, I have come up with a prototype - two step process.

Basically this tool converts design-time HD/RetinaDisplay-pixel based TMX files to corresponding SD files with SD pixels and vice versa.

1. Convert and prepare HD tmx files to SD by using a new tool WBTMXTool I just created. This will convert all HD pixels to SD pixels (or vice versa if necessary).

Syntax: $WBTMXTool -in <input_file_with_or_w/o_path> -out <output_file_with_or_w/o_path> [-scale <0.5|2.0|any_number>] [-suffixForHD <-hd|any> -suffixAction <none|add|remove>] [ -xmlVersion <1.0|any> -xmlEncoding <UTF-8|any>] [-outCondensed <yes|no>]

The scale option ‘-scale’ applies to the following tag:attribute pairs.

object:x

object:y

object:width

object:height

map:tilewidth

map:tileheight

map:spacing

map:margin

tileset:tilewidth

tileset:tileheight

tileset:spacing

tileset:margin

(Added two more below on 9/28/2011. Thanks to rgbedin for finding the issue!)

image:width

image:height

The suffix option ‘-suffixAction’ applies to the following tag:attribute pairs.

image:source

2. Create a Category class 'CCTMXXMLParser+parser.mm' based on CCTMXMapInfo in CCTMXXMLParser.m to override parseXMLFile and parser. This will do conversion of all pixels to points by using CC_CONTENT_SCALE_FACTOR() in run-time.

My prototype above seems to work now both in non-Retina devices and Retina devices. My posting is already lengthy. I will shorten my posting here.

Please download and unzip the files (free - See LICENSES below):

- ver. 1.0-RC1 (Released on 9/28/2011) the tool WBTMXTool and CCTMXXMLParser_parser files here.

- ver. 1.0-RC0 (Released on 12/8/2010) the tool WBTMXTool and CCTMXXMLParser_parser files here. 

Thanks,

WB

FYI. the original cocos2d forum posting about this is here.

LICENSES:

All the files listed under the 'free' tag is released under a Creative Common attribution license.  Feel free to use in both non-commercial and commercial products as desired.  All that I ask is that you mention where you got them.