Tiled TMX — The Standard 2D Tile Map Format for Indie Game Developers

Tiled TMX is an XML tile map format from Tiled Map Editor, developed by Dutch programmer Thorbjørn Lindeijer since 2008 and now the de-facto standard for 2D indie game development. A TMX file describes a rectangular (or isometric/hexagonal) tile grid, multiple parallel layers with tile data, object groups for metadata (collision boxes, NPC spawn points, triggers), tileset references to pixel-art resources, and custom properties typed by schema. Today TMX is supported by virtually every 2D game engine — Godot, Unity, Phaser, LÖVE2D, Defold, Bevy, GameMaker, PixiJS — and was used in production by Stardew Valley, Celeste, Hyper Light Drifter, and hundreds of other indie projects. On osm2cdr.ru tiled_tmx_exporter.py takes a bbox of an OSM area, quantizes landuse / roads / buildings / water into a tile grid (1 tile = 16×16 or 32×32 meters, configurable), and generates TMX XML with a tileset placeholder ready to import into any compatible game engine for a real-world-inspired game prototype.

History: Lindeijer 2008 → Qt rewrite → Patreon → engine adoption

Tiled was born in 2008 as a personal project of Thorbjørn Lindeijer — a Dutch programmer with a Java game-development background. Lindeijer was working on his own indie RPG and needed a simple editor for tile-based levels; existing solutions (Mappy, Tile Studio) felt dated, and commercial ones were too heavy. The first Tiled 0.1 release shipped in August 2008 on Java/Swing and supported only orthogonal grids and a basic layer system. Lindeijer published the sources under GPL and uploaded binaries to SourceForge.

Within the first months Tiled was picked up by indie developers in #gamedev IRC channels and TIGSource forums, and within a year contributors started joining the project. The Java version hit limitations (UI performance, cross-platform packaging, lack of native look-and-feel), and in 2010 Lindeijer decided to fully rewrite it in C++/Qt. The rewrite took roughly a year but produced three key wins: significantly more responsive UI on large maps (1000×1000+ tiles), native builds for Linux/macOS/Windows without JVM dependency, and access to the Qt ecosystem for future features (plugins, custom widgets, scripting).

By 2013–2015 Tiled had become the de-facto 2D indie tooling standard. In addition to TMX (XML), external tilesets .tsx, object templates, terrain auto-tiling, and animated tiles support were added. ConcernedApe (Eric Barone) used a Tiled-compatible workflow when developing Stardew Valley (released 2016, 20+ million copies sold). Maddy Thorson used Tiled when creating Celeste (2018, BAFTA winner). Heart Machine used Tiled for prototyping Hyper Light Drifter (2016).

In 2018 Lindeijer launched a Patreon campaign for sustainable funding of full-time Tiled development — the model proved successful (~$3000/month today), making Tiled one of the rare open-source tools where the core developer works full-time without a commercial publisher above them. That same year the JSON variant TMJ (.tmj) was added to the XML TMX format — for browser-native game engines like Phaser and PixiJS, where XML parsing imposed excessive overhead. Today Tiled is an active GPL-3.0 project at github.com/mapeditor/tiled with releases every 2–4 months, a JavaScript scripting API, command-line export, and integrations into nearly every modern 2D game engine.

Inside TMX: map, tileset, layer, objectgroup, GID

TMX is an XML document with root element <map>, which aggregates everything: dimensions, orientation, tilesets, layers, properties. The file extension is .tmx, MIME type typically application/xml. The alternative serialization is .tmj (JSON) with identical semantics; format choice is made at export time in Tiled.

Root <map> element. Attributes: version="1.10" (TMX spec version), tiledversion="1.11.0", orientation="orthogonal/isometric/staggered/hexagonal" (grid type), renderorder="right-down/right-up/left-down/left-up" (rendering order for perspective tiles), width/height (in tiles, not pixels), tilewidth/tileheight (in pixels, single cell size), hexsidelength (for hex), infinite="0/1" (chunked infinite map support), nextlayerid/nextobjectid (auto-increment counters).

<tileset> references. A dictionary of visual tiles. A tileset can be embedded (defined inside <map>) or external (a reference to a separate .tsx file via source="terrain.tsx"). External tilesets are shared across multiple maps in a project — the primary use case. A tileset contains <image source="terrain.png" width="512" height="512"/> or a collection-of-images (each tile a separate PNG), plus tilewidth, tileheight, tilecount, columns, spacing, margin. The firstgid attribute defines from which global tile ID this tileset's tiles begin (important for GID resolution).

<layer> — tile data. Each layer represents one tile plane. A map may contain an unlimited number of layers (background, terrain, decorations, foreground, etc.), rendered in XML order of appearance. Layer attributes: id, name, width, height, opacity, visible, tintcolor, offsetx/offsety (for parallax effects). Tile data is stored inside a <data> element with encoding csv (readable, for small maps) or base64 with optional gzip/zlib/zstd compression (production default for large maps, significantly reducing file size).

GID (Global Tile ID) and flip flags. Each tile in layer data is a 32-bit unsigned integer: lower 28 bits — global tile ID (addresses a tile in a tileset via firstgid offset), upper 4 bits — flip flags: 0x80000000 (horizontal flip), 0x40000000 (vertical flip), 0x20000000 (diagonal flip — for a rotated tile), 0x10000000 (reserved). Value 0 is an empty cell. This lets a single tileset reuse tiles in 8 orientations (4 rotations × 2 mirrors) without extra art.

<objectgroup> — non-tile entities. Object groups describe what doesn't fit a grid: hitboxes, collision shapes, NPC spawn points, triggers, polygonal obstacles, areas of interest. Each <object> has id, name, type (custom string for game-side dispatch), x/y (in pixels, not tiles), width/height, and an optional shape — <ellipse/>, <polygon points="..."/>, <polyline points="..."/>, <point/>, or a tile reference via gid. Object groups sit next to layers in rendering order — the game engine reads them in parallel with tile data.

<imagelayer> — background images. A layer with a single image for skybox, parallax background, or title art. Properties: image, repeatx/repeaty, offsetx/offsety, parallaxx/parallaxy.

Custom properties. Any entity (map, tileset, layer, object, individual tile) can have <properties> with typed values: <property name="hp" type="int" value="100"/>, supporting string/int/float/bool/color/file/object types. The game engine reads properties for game logic (e.g., walking speed override on certain tiles, dialogue ID for NPC objects).

Animation chains. A tileset can define animated tiles through <animation> inside a <tile> element — a list of <frame tileid="5" duration="100"/> with duration in milliseconds. The engine automatically cycles frames — popular for water tiles, animated torches, NPC sprites.

Use cases: Stardew Valley, Celeste, Hyper Light Drifter, learning, prototyping

2D indie games. The primary use case. Stardew Valley, Celeste, Hyper Light Drifter are canonical examples of commercially successful projects whose levels were designed in Tiled or a Tiled-compatible workflow. Add Owlboy, Dead Cells (early prototypes), Hollow Knight (concept levels), and hundreds of pixel-art metroidvanias and RPGs on Steam early access. The chain is standard: artist draws a tileset in Aseprite/Photoshop → imports into Tiled → designs levels visually → exports TMX → game engine loads the map at runtime.

RPG Maker-style projects. Teams making tile RPGs without official RPG Maker use Tiled as a more flexible replacement (animated tiles, custom properties, object groups instead of a built-in event system).

Educational game tutorials. Tiled is the standard editor in 2D game-dev courses on Udemy, Coursera, GameDev.tv. Its open-source nature and availability on all platforms make it required in curricula.

Level design in production engines. Unity 2D developers use Tiled plus the SuperTiled2Unity plugin to import TMX into the Unity tilemap system. Godot 4 has a native Tilemap node plus godot-tiled-importer plugin. Phaser 3 has a native TMX loader, using the JSON variant for browser parsing performance. Defold (Linux/Mac/Win/web) has a native Tiled importer.

Prototype mapping for tabletop RPG. Foundry VTT — a popular virtual tabletop platform for D&D/Pathfinder sessions — supports TMX import. Game masters build maps in Tiled and load them into Foundry for online sessions with player tokens, fog of war, ambient lighting.

Procedural content generation testing. Researchers in procedural content generation (PCG) often export generated dungeons to TMX for visual inspection in Tiled and statistical analysis of level metrics.

Software and engines: Tiled, Godot, Unity, Phaser, LÖVE2D, Bevy

Tiled Map Editor — the primary tool, GPL-3.0, cross-platform (Linux, macOS, Windows, AppImage, Snap, Flatpak, MS Store). Available free from mapeditor.org or for voluntary donation on Patreon ($5+/month) — support is discrete from commercial use. Has a full JavaScript scripting API (ES6+) for automation: bulk export, custom validators, procedural generators.

Godot 4 — open-source 2D/3D game engine (MIT, godotengine.org), a popular Unity alternative for indie. The native Tilemap node supports orthogonal/isometric/hexagonal grids. For TMX import — the community godot-tiled-importer plugin (via AssetLib), or Godot 4.3+ has a built-in basic TMX importer.

Phaser 3 — JavaScript HTML5 game framework from Photon Storm. Native TMX/TMJ loader through this.load.tilemapTiledJSON(...). Supports all layer types, object groups, custom properties. The leading engine for browser-based indie games (itch.io, mobile HTML5).

Unity Tilemap2DExtras — for Unity 2D developers. Two paths: commercial SuperTiled2Unity (free with a paid pro version) or open-source Tiled2Unity. Converts TMX into a Unity GameObject hierarchy with Tilemap components.

LÖVE2D — Lua game framework (zlib license, love2d.org), popular for prototyping. Standard solution — STI (Simple Tiled Implementation) library, supports all TMX features including animated tiles, object groups, multiple layers. Tutorials and community on LÖVE Forums.

Defold — cross-platform engine (Apache 2.0, defold.com) from former King developers. Native Tiled importer, support for collection tile groups, optimized for mobile.

Bevy — Rust ECS-based game engine (MIT, bevyengine.org), actively growing since 2020. The bevy_ecs_tilemap crate supports TMX import via bevy_ecs_tiled integration, using an ECS-native data model for performance.

PixiJS — 2D WebGL renderer for browser. The pixi-tilemap plugin for efficient rendering of large TMX maps via batching and culling.

Additional tools. tmxlite — header-only C++ library for TMX parsing (used in C++ engines like SFML, Raylib). tiled-c-parser — a C99 minimal parser. python-tmx — Python bindings for tooling. Experimental tiled-binary-format extensions exist for very large maps. There are also procedural generators (e.g., cogmind-style dungeon generators) that output directly to TMX for inspection in Tiled.

OSM2CDR integration: OSM → tile grid → TMX

Our tiled_tmx_exporter.py generates a TMX skeleton with meaningful tile assignment from OSM data — an inception point for indie game developers making real-world-inspired games (city builder in a specific district, RPG in a historical neighborhood, educational geography games).

Step 1: Load OSM features. PostGIS query through local_osm_loader.py for a bbox filtering relevant features: landuse (grass, forest, residential, commercial), natural (water, beach, wood), building (any footprints), highway (roads of various classes), amenity (POI for object groups).

Step 2: Tile grid quantization. The bbox is split into a regular grid with a user-configurable tile size: 16×16 meters (fine, typical for top-down RPG), 32×32 (city builder standard), or 64×64 (large-scale strategy). For each cell the dominant feature class is determined via PostGIS spatial intersection — which landuse covers the largest area of the cell. On collision (e.g., a road crosses a forest) road wins (higher priority).

Step 3: Tile type assignment. Mapping OSM features → tile IDs in the placeholder tileset: grass tile (id 1) for landuse=grass/meadow/recreation_ground, forest tile (id 2) for natural=wood + landuse=forest, water tile (id 3) for natural=water + waterway=river, road tile (id 4) for highway=primary/secondary/tertiary, residential tile (id 5) for landuse=residential + building footprints, commercial tile (id 6) for landuse=commercial/retail, and so on. The specific tile-ID set is documented in the exporter README — the user replaces the placeholder tileset with their pixel art at the same mapping.

Step 4: Object groups for POI. Amenity nodes (school, hospital, restaurant, park benches, etc.) are output as objects in a separate <objectgroup> with type=amenity and custom properties amenity_type, name, osm_id — letting the game engine use them as NPC spawn points, quest triggers, or POI markers.

Step 5: TMX XML serialize. Output is a standard TMX 1.10 XML with external tileset reference <tileset source="osm2cdr_placeholder.tsx" firstgid="1"/> (replaced by the user), one base <layer> with CSV-encoded tile data, an optional <objectgroup> with POI objects, and map metadata properties (bbox, source OSM date, generation parameters).

Applications. City builder set in a specific district (Dorogomilovo in a SimCity-like game, a real map of Sochi in a management sim), RPG in a historical neighborhood (Brest Old Town with its actual layout), educational geography games (memorize your city's street layout), real-world-themed roguelikes (procedural overlay on an actual street grid), tabletop scenario maps for D&D urban campaigns.

Limitations. We do not provide the tileset — we only generate tile-ID assignment; the pixel art (terrain.png) is created by the user or sourced from free asset packs (OpenGameArt, itch.io). 1-tile granularity loses fine OSM detail (narrow alleys, individual trees, individual buildings inside large compounds) — for high fidelity you need a smaller grid size, but that inflates the map (1000×1000 tiles is the practical limit for browser engines like Phaser; beyond that load and rendering slow down). No isometric perspective generation — orthogonal only (the user can switch to isometric in Tiled afterwards via map property change, but the visual tiles for isometric must be different). No multi-floor buildings (3D extrusion does not translate into a 2D tile map) — building footprints render as a simple "building" tile without interior.

Tiled TMX vs Aseprite vs LDtk vs OGMO Editor

2D level/tile editor matrix:

• Tiled TMX — open-source (GPL), XML/JSON, all 2D engines, the widest integration. Strength: industry standard, supported everywhere, active development via the Patreon model, scripting API. Weakness: the UI looks somewhat dated (Qt-based, not the most modern), no advanced auto-tiling (only basic terrain brushes).

• Aseprite — pixel-art editor with a tile mode (paid $19.99, MIT source code), aseprite.org. Strength: a single platform for art creation + level design in a pixel-art genre, real-time preview. Weakness: tile maps are a side feature, not primary; engine integration is via export plugins, not native.

• LDtk (Level Designer Toolkit) — modern free editor by Sébastien Bénard (Dead Cells lead designer), ldtk.io. Strength: modern UX, intelligent auto-tiling (auto-layers), entity instances first-class, readable JSON format. Weakness: younger than Tiled (from 2021), fewer engine integrations (native support in Haxe Heaps, Phaser via unofficial loader; Unity, Godot via plugins), no XML legacy.

• OGMO Editor — open-source level editor (ogmo-editor.com, originally by Matt Thorson — creator of Celeste). Strength: lightweight, no-frills, JSON output, simple workflow. Weakness: smaller community, fewer engine integrations, less feature development after Matt Thorson switched to other projects.

For maximum compatibility and community size — Tiled TMX. For modern UX and auto-tiling — LDtk. For pixel art + level design in one program — Aseprite. For a minimal editor without bloat — OGMO.

FAQ

What's the difference between TMX and TMJ? TMX is XML, historically the original. TMJ (since 2018) is the JSON variant with identical semantics and structure. Tiled can export to both, and many engines support both (Phaser, Godot). TMJ is preferred for browser game engines due to faster parsing and lower overhead. TMX is traditional for native C++/Rust engines and for compatibility with older plugins. The choice is made via File > Export As in Tiled.

Can I use Tiled for free? Yes, fully. GPL-3.0 source on GitHub, binaries from mapeditor.org free on all platforms. Patreon is voluntary support for sustainable full-time Lindeijer development, not required. MS Store/Steam versions for $5–10 are simply a convenience for those who want auto-updates via store; source code and core editor are identical to the free build.

Which game engine to pick for a TMX workflow? Depends on target platform. Browser/HTML5 — Phaser 3 (mature, documentation, large community). Cross-platform with a visual editor — Godot 4 (free, MIT, actively growing). Unity ecosystem — Unity 2D + SuperTiled2Unity (if you already invested in Unity). Performance-critical native — Bevy (Rust) or raw SDL2 + tmxlite (C++). Quick prototyping — LÖVE2D + STI (Lua). Mobile-first — Defold.

Does TMX support isometric and hexagonal grids? Yes. The orientation attribute in <map> accepts orthogonal (square tiles), isometric (diamond tiles for classic isometric), staggered (offset rows for smooth isometric), hexagonal (for hexes with a hexsidelength attribute). Game engines render accordingly. However, our osm2cdr exporter generates orthogonal only; isometric/hex the user converts in Tiled afterwards via map property change.

Can I edit TMX manually in a text editor? Technically yes — the XML is readable, GIDs are computed arithmetically. Practically — that's for tweaking individual values or scripting. Painting a map in a text editor would be agonizingly slow — Tiled provides visual brush painting, copy/paste, undo, real-time preview. Hand-editing more often applies to metadata (properties, object types) or converter scripts.

What is the practical maximum map size? Depends on engine. Phaser 3 (browser) — ~200×200 tiles comfortable, 500×500 with lazy loading. Godot/Unity (native) — 1000×1000+ no problems with proper culling. Tiled infinite maps (chunked storage) — theoretically unlimited, but the editor handles ~10000×10000 split into chunks. Production indie games usually split the world into many small maps (rooms 64×64 or 100×100) with loading transitions, rather than one giant map.

Conclusion

Tiled TMX is an XML tile map format by Thorbjørn Lindeijer, grown from a 2008 personal project into the de-facto standard for 2D indie game development. Its key strengths — a simple XML schema (easy to parse, hand-editable when needed), wide support across all modern 2D engines (Godot, Unity, Phaser, LÖVE2D, Bevy, Defold), active development via the sustainable Patreon model, and a mature tools-and-plugins ecosystem. TMX was used in production by Stardew Valley, Celeste, Hyper Light Drifter, and hundreds of other successful indie projects.

On osm2cdr.ru we provide a TMX skeleton with meaningful tile assignment from OSM data through /api/render with format tiled-tmx — a starting point for indie developers making real-world-inspired games (city builders, RPGs in real districts, educational geography games). The tileset (pixel art) is supplied by the user or sourced from free asset packs.

Try the OSM to Tiled TMX export for your city and open the result in Tiled Map Editor or import it directly into Godot/Phaser for a game prototype.

Related

• SVG — W3C vector graphics for the web and editors
• Minecraft .schem — voxel structures for game worlds
• MVT (Mapbox Vector Tiles) — vector tiles for web maps
• PNG — lossless raster compression for the web and textures

Sources

• Tiled Map Editor official site — mapeditor.org
• Tiled GitHub repository — github.com/mapeditor/tiled
• TMX Map Format specification — doc.mapeditor.org/en/stable/reference/tmx-map-format
• Thorbjørn Lindeijer Patreon — patreon.com/bjorn
• Phaser 3 Tiled support documentation — phaser.io/learn/tilemap