#tiled2unity

Tiled is a great tiled-based 2D map editor, and used to be super essential for Unity projects until recently, as there wasn’t native support for tile maps.

However, Tiled is still a great option, as it allows map files to be authored outside of Unity, allowing artists and level designers to concurrently work on the same scene as developers without merging issues, while making it easier to port the game in the future (should Unity ever become an unideal platform for development).

Thankfully, Seanba has developed a wonderful tool, SuperTIled2Unity that automatically imports Tiled maps into Unity, with tons of bells and whistles to boot. The problem is that it’s documentation is fragmented, with most of the ST2U’s information being buried in Seanba’s blogposts, comments, and forum responses regarding 2T2U’s deprecated predecessor, Tiled2Unity. Yikes!

To untangle this confusing mess, I’ve compiled the links to this fragmented documentation, for posterity. One day I might even build a wiki for this assuming Seanba doesn’t get to it first.  (Continuously update)

Seanba’s Official Documentation. As of this writing, only Sorting, and Object Type and Custom Properties are documented. The Legacy documentation for Object Type support is here.

Tutorial for the original Tiled2Unity, although many of the lessons still apply, including setting up a character controller and how to handle sloping collisions and customer importers.

Retrieving Tile Information At Runtime.

Dealing with scale in unity, and defining the Tag and Layer of the layers of your tile map. An update to this post can be found here.

Additional tileset support.

Edge-Colliders support.

Tile Animations. And an update to this here.

Isometric and hex maps.

Importing maps as a Resource (ignore the top section of this post).

I have been using Tiled to generate easy maps for Unity now with the Tiled2Unity Tool. The issue is, unless I use the ootb shader with Tiled2Unity, you will get nasty gaps in your tiles. I wanted the option to use the Standard Shader in Unity 5 since it gives you the best options and is tied to the engine. The issue is, any legacy shader like Sprite/Diffuse or similar will have gaps between the tiles when using a texture. We’ll get to a fix after the breakdown of the work flow.

The Problem

Here is the issue. You see in the Temporus shot below, there are some tiles that are causing gaps and tiles that are clean. The fix is to have your tile actually have a nice fat edge around that, that is the same as the edge. This means sort of stretching the edges out in all directions but keeping the center the same. In this post, we’ll talk about how to get from the bottom platform to the top.

The Solution

Lets start with a simple 16x16 tileset, no margins or padding. Just a little lake from our good friend Kenny!

Now throw it in your favorite editor, and add a 1 tile (16px in our case) padding. This is to make room for the expanding / adding a gutter. Save it off as a new file.

Now you have two tile sets. A normal one and one with some padding.

Now download Gimp and the Gutter plugin.

Install the Gimp as normal. Then install the plugin per Gimp’s documentation. If you don’t know where to put the Plugin, check your preferences in Gimp, here are mine.

Once you drop in the script and restart Gimp, we can begin.

Import your padded image into Gimp

and then select Filters and find your plugin.

Once this is open it’s time to start playing. This part might require one fudging. It took me a while to get the settings right, and it might take you some time as well. NOTE: Your original Sprite Sheet could have spaces or margins already, this tool should be able to handle it.

For my example, it was quite simple. I just added 4 pixels on each side of my 16x16 tiles.

All this is doing is taking each tile, finding the edge and stretching it out in each direction. Seems to work with slopes too. The result here looks nearly the same, but take a closer look. You will see it’s the same tileset, but now there are 4 px padding in every tile direction. If your tileset isn’t organized well or has more complicated shapes, you will see the difference more. Kenny is just REALLY good at this.

Here is a better example. The original is on the left, the new/stretched is on the right.

Now we have a tileset with padding (or a gutter). Let’s set up our Tiled Project. We set up a normal 16x16 map, and import our new tileset. The key here, is that we specify our 8 pixel spacing. This is to accommodate the 4 and 4 spacing on each side.

Once that is in the tool, check to make sure it lines up. Note: With some fudging I think you can get rid fo the extra white spacing in the tileset.

If you import without the spacing, you will see there are issues. This is the easiest way to check if your settings are correct from the start. Below you can see the tiles are “offset” and not correctly lined up.

Now draw your levels per the Tiled2Unity documentation and add collisions. Note: You can change the collider hotspots in Tiled in the Preferences section. This is helpful if you have slopes that use power of 2 or 3 or want to do more complicated shapes without using the free hand. This also helps Tiled2Unity make meshes, the cleaner your lines, the cleaner the meshes.

Export to Unity using the tool. Use the Vertext scale to help get the mesh to be the right size for your camera in Unity. Also check for errors where the green error is.

Once in Unity, you can now change the shader on the mesh objects to Standard without fear of tearing or gaps. Note: If your collider has issues, make sure you look REALLY close at the Preview Exported Map from Tiled2Unity. You most likely have a bad collider in Tiled, or you just made the map too complicated. It’s really a dance between Tiled, Tiled2Unity and Unity. Collider settings in Tiled can be tricky, if you accidentally stack colliders , it will cause errors. There is no easy way to tell if you have more than one collider set in Tiled, you just have to right click and clear it to be sure.

Below is the output of your work. Have fun playing with it!

Happy Tiling!

Refrerences

http://www.mapeditor.org/

http://www.seanba.com/tiled2unity

http://registry.gimp.org/node/26044