WBTMXTool is a tool that makes it easy to scale TMX assets between HD and SD. It has been created by WasabiBit and made available publicly for free to be used as a useful tool for game developers.

A Story - Background

[Note: Original post written back in 2010]

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.

How WBTMXTool works

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

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.

(Added two more below on 9/28/2011. Thanks to rgbedin for finding the issue!)
(Added the following on 1/8/2013 to uptake new tags in Tiled)

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


How to Run

Here is how to run WBTMXTool from command line:

From SD to HD:

./WBTMXTool -in sample.tmx -out sample-hd.tmx -scale 2.0 -suffixForHD -hd -suffixAction add

FRom HD to SD:

./WBTMXTool -in sample-hd.tmx -out sample.tmx -scale 0.5 -suffixForHD -hd -suffixAction remove


Download the latest version(ver1.0-RC3) of WBTMXTool and example files from this website:

Executable: WBTMXTool (Mac OSX)

Example files:

Or from the Github repository here.

Hope this small tool helps.



Did you like the tool?

Please visit WasabiBit and Like it or follow us on Twitter and/or Facebook. If you have any questions or enhancement requests, please visit the original post here and add comments on the page.

History of Changes

Version Released Changes
1.0-RC3 1/9/2013 Support poligon
1.0-RC2 1/8/2013 Support polyline and tileoffset
1.0-RC1 9/28/2011  
1.0-RC0 12/8/2010 init checkin

References : Who is using this tool (as of November 2017):