Clone wiki

X-UniTMX / Home

X-UniTMX: A TMX importer for Unity3D

X-UniTMX is a TMX file importer to load files from tiled map editor into Unity, originally developed for Twisted Potions: Double Trouble by PolCPP.

This fork used XTiled (XNA) as a base to support many more features from Tiled. It's currently under development, but already supports almost all Tiled 0.11.0 features. Please be aware that this project started using an old version of XTiled, when it was called TiledLib.

Thanks to fontmas for helping me update this project, for the prefab loading code and for the little game examples included!

###Documentation You can access X-UniTMX Doxygen's generated documentation here

There is also a Trello board, where anyone can comment on features and vote for them.

Also, an under construction forum. Please use this forum for support questions, and create issues for any bug you find.


There are 3 branches, Unity2D, trunkDev and old. The Unity2D branch contains the "stable" plugin, and is Unity 4.3+. trunkDev contains features under development, while old contains the plugin version 1.0, for Unity 4.0+, that uses Meshes instead of Sprites.


Basically X-UniTMX can read and import almost all features from Tiled 0.11.0.

  • Fully reads, imports and generates a map created with Tiled Map Editor (Orthogonal, Isometric or Staggered), you don't need to create a mesh neither any material. Please note that the tileset will be set to use the TileWidth as the "Pixels Per Unit" setting, so adjust any other sprite accordingly.
  • Can automatically generate Colliders (or triggers).
  • Exposed tile map informations, layers and objects.
  • Supports XML, CSV, Base64 Uncompressed and Compressed maps.
  • Supports multiple Tile Sets per Tile Layer.
  • Supports Object rotation and Tile Objects.
  • Supports Animated Tiles.
  • Supports Tile Collisions.
  • Supports Rendering Order.
  • Supports Map Loading through WWW (HTTP/StreamingAssets)
  • Partial support of Hexagonal Maps (trunkDev branch only for now)


  • Tile Sets MUST be inside Resources folder! See sample project structure.
  • Any External TileSet (.tsx), if placed in Resources folder, must also have the extension .xml
  • Does not support Tile Collisions made of a polyline with only 2 vertices.


Either copy X-UniTMX folder into your assets folder or download and import X-UniTMX - Unity2D v1.7.1.unitypackage as a Unity Package.

How to Use

There are three ways you can use X-UniTMX: using the TiledMapComponent, directly through code or mixed. Please, take a look at the included example scenes and their code.

There are only three mandatory steps:

  • Save your map as .xml. Do not worry, Tiled can open and edit your map using this extension as well, so you can use it freely and delete the tmx file.
  • Setup your 2d Scene for 2d sprites (orthographic camera etc), if you want take a look on how is the scene built on Twisted potions: Double trouble or in the included examples. Please note that the tilesets will have the "Pixels Per Unit" setting adjusted to the Map's TileWidth, so adjust any other sprite accordingly!
  • Important: Use Sprite as your tilesets texture type!

You can follow these small guides:

Custom Tiled Properties

X-UniTMX can automatically read and parse some custom properties from Map Objects. Here is a small guide on using them.


To use the Examples included in the package, you will need to:

  • Add Example Scenes to Build Settings by selecting the menu X-UniTMX->Add Example Scenes
  • Add the following Sorting Layers to Edit->Project Settings->Tags and Layers->Sorting Layers:

    • BG
    • Background
    • Layer 0
    • Layer 1
    • Layer 2
    • Midground
    • Foreground
  • Add the following Layer to Edit->Project Settings->Tags and Layers->Layers:

    • passthrought
  • Add the following Tags to Edit->Project Settings->Tags and Layers->Tags:

    • PlayerShoot
    • HealDrunks_Blue
    • HealDrunks_Red
    • Branch

This is needed as Unity3D does not allow adding these Layers and Scenes at runtime (yet), so you must manually add them...

Now you should be able to open StartingScene inside X-UniTMX Examples folder and run all scenes with no problems.

Important Notes

The importer will try to give each Tile Layer its own Sorting Layer, based on the Tile Layer's name. To define Sorting Layers, go to Edit -> Project Settings -> Tags and Layers and, inside the Sorting Layers foldout add any name you will need. Remember to order them by their zIndex order, with the top-most layer being the lowest one on this list. Here's an example:

Sorting Layers