Tiled2Unity: Tiled Support for Unity
Please consider supporting Tiled Map Editor on Patreon. Tiled is a free and essential tool for 2D game development and I’d like to see the author support it and similar tools fulltime. We’d have no Tiled2Unity without it.
Tiled2Unity is a free utility with one goal in mind: Easy exporting of Tiled Map Editor TMX files into your Unity projects. Tiled2Unity takes your Tiled files and creates Unity prefabs from them that are easily placed into your Unity scene. Complex collision is supported through Unity’s PolygonCollider2D class. (Windows and Mac)
Tiled2UnityLite is a command line version of the Tiled2Unity utility. It can be used on any platform but was primarily designed to give Linux users a way to use Tiled2Unity on their operating system.
When you install a new Tiled2Unity version you will also want to update the Tiled2Unity scripts in your Unity project folder as well. The easiest way to accomplish this is through the Import Unity Package to Project menu item while your project is open in Unity.
Note: Both the Tiled2Unity output window and the Unity console will complain if there is a mismatch.
All Source is Freely Available on GitHub
Tiled2Unity is made up of two parts:
- The Tiled2Unity utility that exports a Tiled file.
- The Tiled2Unity Unity scripts that imports the
*.tiled2unity.xmlfiles and puts the textures, meshes, and prefabs into your Unity project.
Both components are publicly available on GitHub.
I’ve tried to make Tiled2Unity simple to use and understand. Here’s some links that may help you out:
- Introduction: Use the test TMX files supplied with Tiled2Unity to create two simple scenes in your Unity project (one with sloped collision).
- Tiled2Unity Scale: By default, Unity 2D sprites use a coordinate system where 100 pixels equals 1 unit in Unity. I think that’s crazy but this link will show you how to live in that world.
- Mega Dad Adventures: A good number of “advanced” examples of using Tiled2Unity in your Unity projects. Set tags and layers on your imported prefabs and add custom, game-specific behavior.
- Tile EdgeCollider2D Support: Shows you how you can use polylines in the Tile Collision Editor to export EdgeCollider2D objects in your Unity prefab.
- Getting Tile Information at Runtime: Useful for Strategy and RPG style games.
- Introducing Tild2UnityLite: Use Tiled2Unity as a command line utility on PC, Mac, or Linux.
Feel Free to Contact Me
If you’re making something with Tiled2Unity I’d love to hear about it. I also welcome bug reports with big hugs — although my real life schedule may keep me busy at times. In any case, email me your suggestions or awesome stuff.
Tiled2Unity Version History
- New Feature: Added object type components
PolylineObjectthat contain raw data from exported TMX files. Pre-existing component
TileObjectwas updated to contain such data.
- Bug Fix: Under some conditions, exported convex collision polygons would be missing a vertex.
- Update: Clipper library updated to version 6.4.1
- New Feature: Added default materials for sprites that want to use depth values.
- New Feature:
SpriteDepthInMapcomponent has an inspector button that will update the depth value (z component of transform position) of a sprite while in the editor.
- Bug Fix: Depth value was not being set on Tile or Object layers correctly.
- Bug Fix: Previewer was not using layer offset.
- New Feature: Tiled2UnityMac writes logs to be captured by the Console app to help debug crashes or bugs.
- New Feature: Background color of map is exported.
- Bug Fix: Object Layers were not using
unity:ignoreproperty correctly when set to
- Bug Fix: Maps needing materials with closely matching names would sometimes fail to be imported correctly.
- New Feature: Added
ObjectLayercomponents to imported prefabs.
- Bug Fix: Protect against the same texture being exported multiple times.
- Bug Fix: Object Layers using
- Update: Importing process now does a better job of reporting warnings and errors.
- Update: Tiled2Unity scripts compliant with Unity 5.5
- Update: Tiled2UnityMac now uses icons.
- New Feature: Tiled2UnityMac writes to OSX logs when using in auto-export mode.
- Bug Fix: Fixed compile error in Tiled2UnityLite.
- Bug Fix: Tile Object locations were wrong when using a Pixels Per Unit value that was not 1.
- Update: Importing multiple maps at the same time in Unity now supported.
- Update: Cleanup of Tiled2Unity import process. Only files that are explicitly imported by the
*.tiled2unity.xmlfile are processed by the scripts.
- New Feature: Materials may be exported as resources (and placed in a Resource directory)
- Bug Fix: Fixed crashing bug when auto-exporting in Tiled2UnityMac
- Bug Fix: Isometric Tile Objects that are scaled are exported to the proper position.
- Bug Fix: Simplified depth buffer calculations on Tile Layers and Object Groups to reduce z-fighting
- Bug Fix: Fixed bug with polyline objects of 2 vertices being rejected during export.
- Bug Fix: Tile Objects are ordered by y-position when exported, similar to Tiled.
- Bug Fix: In some cases, polyline objects were not being exported properly as
- New Feature: Color and File property types from Tiled now supported.
- Bug Fix: Tiled2UnityMac was crashing under some conditions when loading a TMX file.
- New Feature (Advanced): Use
--writeable-verticescommand line option to create Tiled map meshes that can be manipulated through script. Note: This increases the memory used by the mesh significantly.
- Bug Fix: Animation fix for when multiple animations loop at different times.
- Bug Fix: Stretched Tile Objects collision offsets set correctly now.
- Bug Fix: Animation frames can be on different images now.
- Bug Fix: Fixed math on texture coordinates for rotated tiles (was causing seams)
- Bug Fix: Isometric tiles that were added to Tiled as a collection of images were being placed incorrectly in generated prefab
- Bug Fix:
Clear Object Typesbutton Tiled2UnityMac was not hooked up.
- Bug Fix: Decomposing polygons into convex groups would sometimes throw an exception in the triangulation stage.
- Bug Fix: Exporting Tiled files that reference “internal textures” (i.e. textures already part of the Unity project) has been fixed.
- Improved Feature: Vertex Scaling was replaced with “Pixels Per Unit” so that it mapped exactly with what Unity is using to scale sprites.
- Bug Fix: Fixed exception when importing textures that used an alpha color key.
- Bug Fix: Maps that were referencing the same texture were being invalidated upon export.
- New Platform: Tiled2UnityMac is now available. Mac users can now use Tiled2Unity in the same way that Windows users have long enjoyed.
- New Feature: Can now use depth buffer shaders in cases where you want a sprite to draw above or below a tile depending on its position in the world. (Sprite will need to set its z-position, see
- Bug Fix: Tile Objects in Isometric maps have their position and collision geometry properly set now.
- Bug Fix: Recently added support for Object Types introduced a crashing bug when using
- New Feature: Object Types now supported. Default property values for Objects will be exported to Unity.
- New Feature: Multiple collider types on same Tile Layer. You no longer have to manage separate layers for specific collision types.
- Bug fix: No longer crashes if Tiled map file layers reference tiles that no longer exist.
- Bug fix: TMX files with extra periods in their file name can be successfully imported now.
- Bug fix: Fixed shader issue with some Android hardware by simplifying and re-arranging shaders.
- New 64 bit version: Provides better stability with large maps that could run out of memory in the 32 bit version.
- Bug fixes: Reduction in memory usage reduces risk of running out of memory while opening or exporting TMX files.
- Improved previewer: Rendering map previews is 2-3 times faster now.
- Improved reporting: Users trying to import while using the Unity Web Player should have a clearer message now.
- Unity 4.x Support: By popular demand Tiled2Unity will work with Unity 4.x installs.
- Bug fix: Unity scripts no longer throw exception when trying to re-import a Tiled2Unity folder
- New Installer: The NSIS-based installer was being falsely flagged as malicious by some anti-virus software. Now using an MSI installer package.
- Improved reporting: Will now be warned if you try to export a Tiled map that has a
PolygonCollider2Dthat is “too complicated”. (This usually means you set up colliders in Tiled without using “Snap to (Fine) Grid”.
- Bug fix: Removed GDI+ library dependency that was crashing some Mac users in Tiled2UnityLite.
- Bug fix: Fixed crash with Tiled maps that contain only Image Layers.
- Bug fix: Fixed
unity:convexnot being interpreted as a boolean.
- New Feature: Now supports rotated Tile Collision Editor colliders from Tiled.
- Bug fix: No longer crashes if Tiled2Unity cannot find installed Tiled2Unity.unitypackage file.
- New Feature: Can now choose to export polygon collisions as a series of convex polygons instead of one “complex” polygon that may have holes and convex edges.
- Bug fix: Fixed crashing bug when extra tile data remained in a TMX file for a tile that has been removed from a tileset.
- Bug fix: Will no longer crash if
unity:sortOrderproperty value is not an integer (reports an error instead).
- Improved Feature: Tile Objects can set their own sort layer name and sort order.
- Bug fix: Fixed exporter crash when tileset image file cannot be found.
- Bug fix: Fixed exporter crash when old tile data remains in TMX file from a tile that has been removed.
- Bug fix: Fixed exporter crash after removing tile from “Collection of Images” tileset.
- Bug fix: Reverted normal on map meshes back to (0, 0, -1) as positive-z goes “into” the screen.
- Bug fix: Generated meshes are using the proper normal vector for lighting. (This was a mistake. Reverted in 184.108.40.206)
- Improvement: Tiled2Unity can be used in WebPlayer builds again. However, you must import your Tiled maps using another build target first (Standalone Windows/Mac/Linux will do).
- Bug fix: Fixed compile error with Unity 5.0
- Bug fix: Fixed string exception being thrown when (re)importing Tiled2Unity.xml.txt marker file.
- New Feature: Added support for unity:resourcePath custom property on Tiled maps. This instructs Tiled2Unity to build the map prefab at
- Bug Fix: Fixed bug with importer getting stuck when saving a prefab to the Resources folder.
- Bug Fix: Replace compile error CS0234 with notification that Unity Web Player is no longer supported.
- Bug Fix: Fixed compile error when importing with earlier versions of Unity 5.x (5.0, 5.1, and 5.2)
- Big Fix: Fixed compile error when building the Unity player.
- Bug Fix: Textures used only for Tile Objects were not being exported to Unity
- Bug Fix: Tile Objects were not placed correctly when used with vertex scaling
- Optimized: Animated tiles no longer manipulate vertex data. This is a significant optimization. Additionally, tile animations no longer cause garbage collection spikes.
- Optimized: Importing
*.tiled2unity.xmlfiles is now significantly faster, especially for larger maps.
- Bug Fix: Colliders on Tile Objects now alligned properly with the origin of the Object.
- New Feature: Tile Objects now supported visually.
- Deprecated: Unity 4.x versions no longer supported.
- Bug Fix: Tiles that were rotated and/or flipped could introduce seams depending on camera settings.
- New Feature: Tileset Offset property is considered in placing tiles (Note: This could lead to overlapping tiles that don’t sort as you may expect. Prefer to use Layer Offset instead.)
- Modified Feature:
unity:ignorecustom property can be assigned to
true(ignores whole layer),
collision(ignores collision on layer but exports visuals), and
visual(ignores visual tiles on layer, exports collision only).
- Bug Fix: Image Layers with no image no longer crash Tiled2Unity
- Bug Fix: Fixed compile issue with older versions of Unity
- New Feature: Tiled Image Layers are now supported.
- New Feature: Layer Opacity is now supported.
- New Feature: Layer Horizontal and Vertical Offset is now supported. (Currently only in the Tiled daily build. Will automatically work in Tiled2Unity when feature goes live.)
- Bug Fix: Command line argument that selected your Tiled2Unity export folder has been fixed (broken by 0.9.11.0).
- Bug Fix: Scripts updated for Unity 5.1 (previous versions of Unity 5 and Unity 4.x are back supported).
- New Feature: Tiled2Unity now works at any location in your Unity project. It no longer has a hard-coded dependency on being located at
- New Feature: Add the
unity:resourceproperty to your collection of Map properties in Tiled so that the prefab is saved to the
.../Tiled2Unity/Prefabs/Resourcesdirectory. This allows you to instantiate the prefab via script in your Unity game.
- Potential Bug Fixes: All
DLLImportunmanaged code has been removed from the Tiled2Unity utility. This should make life easier on anyone porting Tiled2Unity to a non-Windows platform.
- New Feature: Isometric and Hexagonal maps now supported.
- Bug Fix: Using NonZero polygon fill rules when combining collision geometry now so that overlapping polygons don’t create holes.
- Bug Fix: Some animated tiles were still broken when using vertex scaling.
- Bug Fix: Animated tiles are working again in maps that use vertex scaling.
- Bug Fix: Fixed script compile errors while using Unity 4.x.
- New Feature: Updated to work with Unity 5 without any modifications.
- New Feature: Added Preview Options to previewer. Improved the look of collision geometry in the previewer.
- New feature: Object rotation now supported.
- New feature: New
unity:collisionOnlyproperty on Tiled layers will export only the collision data from the given. Meshes will not be generated.
- Improvement: Previewer no longer contains seams when using zoom.
- Improvement: UI added for modifying vertex scale. No longer have to rely on
-–scalecommand line arguments alone.
- Bug fix: Tiled2Unity would crash if you entered a value for a boolean property which didn’t resolve to
- New feature: Vertex scaling through command-line argument (
-–scale). The vertices of the exported maps and collision maps will be multiplied by this value. For some users this will be a better way to control the size of map instead of scaling the whole prefab.
- New feature: Texel bias setting exposed through command line-argument (
-–texel-bias). This helps when using some shaders that under certain conditions give the appearance of seams in the tiled map.
- Bug fix: Exporting would crash if you had a Tile Object in an Object Layer that had no custom properties.
- Bug fix: Gizmo selection of TiledMap prefab takes scale into consideration.
- Bug fix: TMX files with extra period characters in the file name are supported.
- Bug fix: Texture files referenced by Tiled maps with extra period characters in the file name are supported.
- Bug fix: Gizmo selection of TiledMap prefab now takes world position of game object into account.
- New feature: Preview in Tiled2Unity exporter supports 1/8th to 800% zoom. Allows preview of maps that were once too large to preview.
- New feature: New
unity:ignoreproperty allows you to have layers in Tiled that are ignored by the exporter.
- New feature: New
TiledMapcomponent is added to imported map prefabs automatically, containing dimensions of map.
- Bug fix: SortingLayerExposedEditor class no longer collides with Editor namespace.
- Bug fix: Changes made to texture importers by hand are not overwritten on subsequent exports to Unity.
- New feature:
- Bug fix: Fixed bug with rotated tile collision geometry in cases where collision data had a non-zero position relative to the tile.
- Bug fix: Animated tiles were not working if Unity split the mesh into smaller sub-meshes
- Bug fix: On some graphics hardware and resolutions, dark edges were appearing on the upper and left side of tile boundaries
- New feature: Render order of tiles supported
- New feature: Animated tiles supported through Tiled Animation Editor
- Bug fix: Margin settings for textures follow same rules as Tiled.
- Bug fix: Rotated tiles often had incorrect texture coordinates in generated mesh.
- Bug fix: Added a bias to generated texture coordinates. This should resolve issues with seams that some users were seeing.
- Bug fix: Unity was renaming our generated meshes under some conditions.
- Fixed bug where textures with whitespace in their name we’re not being assigned to their matching material and meshes during import.
- Exported *.tiled2unity.xml files are always re-imported now when exported, even if the data hasn’t changed.
- Fixes texture coordinate bug with some flipped or rotated tiles.
- Tiles (including collisions) that are flipped or rotated in Tiled Map Editor are now supported.
- Tiled maps with flipped or rotated tiles no longer crash Tiled2Unity.
- Several speed improvements. Useful for viewing and exporting “large” Tiled maps.
- Polylines added to tiles in the Tile Collision Editor (in Tiled) are exported as EdgeCollider2D objects.