TiledMapPacker
Warning: While the latest TiledMapPacker is available for download, you must be using the latest SNAPSHOT version of libGDX, currently 1.13.2-SNAPSHOT, to load maps created with it.
You can download the runnable JAR release of TiledMapPacker, here.
Offline tool for preparing Tiled maps (.tmx or .tmj) to use a single optimized TextureAtlas for rendering
in libGDX, by combining tilesets, image layers, and individual images. Designed for use with AtlasTmxMapLoader or AtlasTmjMapLoader.
Why use TiledMapPacker?
TiledMapPacker is designed to optimize your Tiled maps for better runtime performance:
- Fewer draw calls – By combining multiple tilesets, images, and layers into a single optimized
TextureAtlas, your game can render entire maps faster with fewer texture switches. This is especially helpful for parallax backgrounds made using imagelayers, and maps that use a variety of tilesets. - Optional tile stripping – Unused tiles can be omitted to reduce file size and memory use.
Running TiledMapPacker
Standalone JAR
# Creates an output directory named "output" next to INPUTDIR
java -jar runnable-tiledmappacker.jar ./maps
# Explicit output directory
java -jar runnable-tiledmappacker.jar ./maps ./maps-packed
# Explicit output directory, as well as loading maps that require .tiled-project files
java -jar runnable-tiledmappacker.jar ./maps ./maps-packed ./customClass.tiled-project
# Various options are available as well such as verbose logging and stripping unused tiles
java -jar runnable-tiledmappacker.jar ./maps ./maps-packed -v --strip-unused
Note: TiledMapPacker internally uses
TmxMapLoaderandTmjMapLoader, which require a valid OpenGL context. The runnable JAR automatically creates a minimal LwjglApplication that opens a small window.
Positional arguments
| Argument | Description |
|---|---|
| INPUTDIR | Folder that contains the maps. Searches recursively for .tmx and .tmj files. |
| OUTPUTDIR | (optional) Directory where the processed maps and atlases are written. Defaults to a sibling directory named output. |
| PROJECTFILEPATH | (optional) Path to a Tiled .tiled-project file when your maps rely on custom classes. |
Flags
| Flag | Effect |
|---|---|
--strip-unused |
Omit tiles that never appear in any layer. |
--combine-tilesets |
Combine all tilesets from all maps into a single mega‑atlas (not recommended). |
--ignore-coi |
Skip “collection‑of‑images” tilesets. |
-v |
Verbose output (lists every tile or image that is packed/stripped). |
Default Per‑Map Atlases vs Combined
-
Per‑map (default) – Each individual map gets its own atlas.
Command:
java -jar tiledmappacker.jar ./maps. -
Combined – All tilesets across every map are packed into a single giant atlas, so you only need one atlas for all maps. This option has been around since the inception of the TiledMapPacker but still not recommended for use as nested folders and absolute tileset paths may break it.
Option:
--combine-tilesets.
Typical Workflow
- Design your map(s) in Tiled as usual.
- Run TiledMapPacker whenever your art or map files change.
- The packer creates updated map files (
.tmxor.tmj) and atileset/directory containing the generated.atlasand images. - Make sure you keep your original tileset definitions (
.tsxor.tsj) and place them alongside the newly generated map and atlas files. - Then load the map exactly as you would a regular map:
TiledMap map = new AtlasTmxMapLoader().load("maps/testLevel.tmx");Or through the AssetManager class as well, like any other map.
assetManager.setLoader(TiledMap.class, new AtlasTmxMapLoader(new InternalFileHandleResolver())); assetManager.load("maps/testLevel.tmx", TiledMap.class);
Handling ImageLayers
Image‑layers are detected automatically. Each image is renamed to a safe region
ID (prefixed with atlas_imagelayer_), packed into the atlas, and the map file
is rewritten. The modified atlas map loaders resolve these names automatically.
Limitations
- XML tile‑layer encoding is not supported – stick to CSV or Base64 layers.
- Having a
.tmxand.tmjwith the same basename in the same folder (e.g.level1.tmxandlevel1.tmj) will cause region‑name collisions and the packer will abort. - Collection‑of‑images tilesets are packed automatically, but if they are
not used in tile layers and not meant to be rendered you can exclude them with
--ignore-coi. --combine-tilesetsis experimental. Complex folder hierarchies or absolute tileset paths may fail to resolve correctly.
Results
In a worst-case scenario, we have a map that uses three different tilesets, including a “collection-of-images” tileset, along with eight image layers for parallax background effects.
You can see the amount of draw calls being wasted if this map were loaded through the TmxMapLoader.
In the below example we range 12 to 14 depending on where we are on the screen.
But by using the TiledMapPacker and an AtlasTmxMapLoader, we can significantly reduce our draw calls. In this case, down to 1.
Example Tests
Asset Credits
- Example .gifs use free assets from the SunnyLand Tileset.