Working with Tiled and Unity

In our previous game (Eventful Horizon) we attempted to use the built-in tile editor. We encountered some major issues with the tooling, namely:

  • Tile collisions didn't behave as we expected  (self inflicted)
  • Drawing on the correct layer was constantly an issue 

The first issue seems to have been entirely on us. In the midst of a game jam, sometimes you don't read all the documentation properly. As this was the team's first time using the tilemap tooling, we overlooked the "composite collider" component entirely. What this resulted in was each individual tile having its own collider. This is problematic because the seams between each tile can 'snag' the player and/or the teleball. For the player, this just looks like buggy collisions where sometimes the player can get stuck inside the floors and walls.

Each tile has an entirely separate collider

A New Tool Is Found

The second issue was much more frustrating, at least through the development phase. We had six different collision materials, the three terrains and their corresponding "non-stick" counterparts. What this looked like in our project was 6 different collision layers. We had built collisions so that each layer had the properties assigned to it instead of each tile having the properties. If, during level design, you forgot to switch layers when you switched to a different tile, it would lead to having to erase and redraw everything. This happened more than just a couple of times (again, a sleep deficit can lead to a lot of mistakes at times).

All of this is to say, we did some looking around and found Super Tiled2Unity (ST2U from here on). It's a pretty new tool that takes advantage of the recently added Scripted Importers and works directly with Tiled. This immediately enticed us as we have used Tiled for multiple projects in that past.

Adding ST2U to a project is quite straight forward. Just download the file from their site and open it. The file should be picked up by Unity and you'll be prompted to import the package into your project. With that, let's get into how we used it and the benefits/frustrations it gave us.


Tiled has support for defining collisions on a per-tile basis. We took full advantage of this. Our ship tileset was fairly complex and allowed for a huge variety of ships to be built. Unfortunately, we weren't able to show off the flexibility of the tileset in the released version of the jam. Once the collisions were configured in Tiled,  everything loaded mostly as you'd expect.

Collisions for the tutorial ship

ST2U automatically stitched the individual tile hitboxes together into single Compound Collider. These mostly behaved perfectly, though we did run into some strange behavior when Compound Colliders were combined with the more basic Box Colliders. This mostly became apparent once we started adding cargo into the game. The player uses a Circle Collider, and when the cargo had Box Colliders, we had issues getting them to collide as expected. Due to the time-crunch nature of the jam, we found a workaround rather than a solution. We built each of the cargo hitboxes as concave polygons to force the import to parse them as Compound Colliders. After doing this, everything worked perfectly.

Note the small notch in the top of the rectangular cargo items

Notice that we rounded the corners, even on perfectly square objects. This allowed for a more forgiving interaction when trying to slide objects past each other.

We did find that sometimes the collisions would inexplicably import strangely after making changes to the TMX tilemap file. This was typically fixed by deleting the map object from the hierarchy and re-adding it to the scene.

Note how the 'S' piece has no hitbox and the top piece hitbox is now more of a 'T' shape

Layers and Objects

The map layers are imported with the same names and all of the objects come over nearly for free into Unity.

Left: Tiled Editor Layers, Right: Unity Object Hierarchy

We wanted to control the drop order of the cargo by ordering it from within the tiled Object Layer. ST2U imports objects based on name, rather than by the order they are in the object layer, so we had to come up with a different strategy. We resorted to naming the objects alphabetically so we could know for sure what order things would be given to the player.

Piece 'a' would drop first, followed by 'b', followed by 'c', etc.

This felt far from optimal, and we would have much preferred that ST2U preserved the order they are in the Objects list within Tiled.


Tiled allows for a lot of power when Properties are used. For our game, we used these to keep all cargo information self-contained in the Tiled object.

Each cargo had custom properties

These provide a ton of useful benefits. For example, 'material' actually controlled what sound each piece of cargo made when the player drags it around the deck of the ship. We could control how many points each cargo was worth, it's description, and much more all from within Tiled as we were building each level. The icing on the cake is that on the Tileset, all of the properties can be set to their normal values, then each individual instance can have it's properties customized as they are placed into a tilemap. This allows us to change things like the 'bonus' and 'innate' flags on a per-level basis without having to have separate tiles. In case you're wondering, 'bonus' controls if that piece is the bonus piece for the stage and 'innate' tells the piece if it is already on the deck when the level starts.

All of these properties get brought into Unity automatically by ST2U as a "Super Custom Propterties" Component.

Each property has its name, type, and value imported

These aren't too terribly hard to get to from the other scripts in our project. We had to do a little bit of checking and casting since everything comes over as a string, but that's easy to deal with.

We also used these properties to control things for each level. We put properties directly on the cargo layer to let the game know how many points the player has to score to get each star rating.

The Final Touches

We were able to control much more with objects and properties, though admittedly not as much as we would have liked. Most of the things we missed were just do to lack of time. Other things we were able to control through the level on tiled were:

Rat Spawn. The rat was technically a piece of cargo that the game knew how to handle, so we just had to order it to drop right when we wanted it to

Note that the rat has the object name 'e2' which would cause it to be dropped right after piece 'e'

Crane drop zone. This allowed the level designer to make sure the pieces came down right where they wanted them to for each level

A script in unity would parse out this object and properly place the in-game drop zone

Level Center. The player renders different based on where he is relative to the 'center' of the boat. We allowed this to be placed in the tilemap so that the designer could make sure the visuals behaved as expected.

This point triggers the player to render differently depending on which side they are on.

Overall, this tool worked very well for us. It also allows us to use another powerful tool we are already familiar with. ST2U is quite new, so I look forward to seeing the progress it makes.

Get Roustabout

Leave a comment

Log in with to leave a comment.