Tilemap Converter (TMX, Tiled JSON, PNG, collisions)

What it is for

You built a level in Tiled, Flipline's Tilemap Desk or another editor, and now your game framework wants something else: Tiled JSON instead of TMX, base64 layers instead of CSV, a plain JSON list of cells, or simply a picture of the level for a design document. This converter reads a map once and writes it in the format you choose, using the same code that Tilemap Desk runs in the browser, so both give byte-identical files.

It also solves a chore that every platformer has: collision. Feeding a physics engine one box per solid tile is slow and causes snagging on seams. The converter merges solid tiles into a few large rectangles.

It reads maps whose tilesets are embedded in the map file. External .tsx/.tsj tilesets, hexagonal or staggered maps, text objects and zstd-compressed layers are reported instead of being guessed. It is a converter, not a game engine.

Worked example

The second built-in example is a 12 × 6 platform map saved as Tiled JSON. It has a solid block tile, a one-way wooden ledge (a 4-pixel collision strip with a oneWay property) and a slope polygon, and one slope is horizontally flipped, so its cell stores gid 2147483651: tile 3 with the 0x80000000 flip bit.

Converting it to TMX with base64 + gzip layers returned: "Converted Tiled JSON (1 layer, 25 tiles) to TMX; 3 merged collision rectangles." There were 17 solid cells, and the rectangle table listed (160, 48, 32 × 48), (144, 64, 16 × 32) and (0, 80, 144 × 16) in pixels. So the nine-tile floor became one box and the stepped block on the right became two. One warning said the tileset image platforms.png had no embedded copy, so the PNG preview used placeholder colours.

Running the same map as TMX with zlib layers and the target Collision rectangles (JSON) gave the same three rectangles. It also returned eight extra shapes: five one-way ledge strips such as (48, 16)–(64, 20) and three slope polygons. The flipped slope's points were mirrored inside its cell.

How to read the result

• Metrics: source format, map size, placed tiles, solid cells and merged rectangles. Solid cells divided by rectangles shows how much merging saved.
• Download: the converted file. TMX and Tiled JSON refer to tileset images by file name, so keep the PNGs next to the map.
• Flattened PNG: visible tile and image layers drawn like Tiled draws them, with flips and layer opacity. Objects are not drawn.
• Merged solid rectangles: x, y, width and height in pixels (isometric maps: tile cells).
• Code block: the start of the converted text, useful for checking the encoding.

Tips and common mistakes

• Upload the tileset PNGs (one PNG, or a ZIP of several) with the map. They are matched by file name. Without them, the PNG preview uses placeholder colours.
• A tile counts as solid only if its collision rectangle covers the whole tile. Partial shapes stay separate polygons.
• Mark one-way platforms with a oneWay boolean property on the collision object in Tiled; the converter keeps that flag.
• If Tiled saved the tileset externally, use Map › Embed Tilesets before converting.
• CSV is easiest to diff in version control; base64 + zlib is the most compact.

FAQ

Are the flip flags kept?

Yes. Horizontal, vertical and anti-diagonal flips (bits 31, 30 and 29 of the gid) survive every conversion and are applied in the PNG. Tiled's hexagonal 120° flag is dropped with a warning.

Why are my tile ids different after converting?

Tilesets are renumbered without gaps from firstgid 1. The tiles themselves are the same; only the global numbering is compacted.

Can it read infinite maps?

Yes. Chunks are read at any position, including negative ones, and written back as 16 × 16 chunks.

Is the greedy merge minimal?

Not always. It takes the widest run in a row and grows it downwards. That is optimal for rectangles, L and T shapes and usually close otherwise. Every solid cell is covered exactly once.