Happy New Year 2019! Over the holidays I got back into my hobby projects and put something together that others may find useful. Yesterday, I made it available for the public under the pay-what-you-want-or-free model.

I love Unity but working with the built-in sprite and animation editors has long been an annoyance for me. So, I took what I consider to be the best 2D sprite authoring tool (Aseprite) and created a scripted importer for it.

My latest tool, Aseprite2Unity, drills into .ase or .aseprite files and creates sprites and animation clips automatically. The resulting prefab is ready to go with SpriteRenderer and Animator components filled out.

You can download and learn more about this tool on the Aseprite2Unity page. Enjoy!

Tiled2Unity is dead. Long live SuperTiled2Unity.

Since May of 2014, Tiled2Unity has been a popular piece of software, mostly due to Tiled Map Editor being an essential 2D authoring tool and because Unity has been slow to support tile-based assets.

However, in the past year I’ve accumulated significant fatigue with further Tiled2Unity development due to these factors:

• The external Tiled2Unity exporter (a C# Windows Forms application) was a huge pain to support for both Windows and Mac.
• A small subset of Mac users kept running into crashes I wasn’t able to resolve involing managed wrappers of native graphic libraries.
• Tiled2UnityLite never took hold as a viable solution for Linux users.
• Tiled files were external to Unity which made debugging difficult. (Users often had maps, tilesets, and textures all over the place which made sharing a pain.)
• Graphical seams was an ongoing drain on support and the fix for these artifacts was unsatisfying.
• Unity support for tiles and tilemaps was maturing, thereby deprecating Tiled2Unity (which uses Wavefront object meshes).

For a time I had decided to toss Tiled2Unity to the side but have you tried using Unity as tilemap editor? I think it’s a bit of a mess. Further, I’ve built up a lot of Tiled data that I didn’t want to recreate in Unity’s editing environment.

So instead I’ve recreated Tiled2Unity from the ground up taking advantage of new Unity features such as Scripted Importers and Tilemaps. The result is SuperTiled2Unity which is now ready for public consumption.

But beware: This is an early release. Even Unity considers their new classes as experimental and subject to change.

SuperTiled2Unity Improvements

Starting over with a Tiled importer allowed me to resolve these issues:

• No more external exporter. Tiled files are now treated as true Unity assets that are automatically imported into prefabs as you make changes in Tiled.
• Support for all platforms. Running everything in the Unity Editor puts Windows, Mac OS, and Linux users on an even playing field.
• Seams fixed once and for all. Tiles are grouped into a texture atlas during import and padded appropriately so that mathematical imprecision with UV coordinates does not lead to these annoying artifacts.
• New Unity classes supported. The Tilemap class is a welcome addition to Unity. No more meshes!

SuperTiled2Unity strives to compliment all Tiled features including isometric or hexagonal maps, colliders, flipped tiles, animated tiles, templates, objects, groups, etc.. If a feature is missing let me know and I’ll try to support it.

SuperTiled2Unity is distributed as a single Unity package. And, yes, it is free but dontations are always apprecated.

I also encourage everyone to make a contribution towards further Tiled Map Editor development. Thorbjørn Lindeijer has put years of effort into Tiled. It’s a great program that he easily could have charged real money for. Please give him your support.

Thanks and enjoy!

The new Object Types Editor in Tiled allows you create type templates with default properties. With Tiled2Unity 1.0.5.0 these types can automatically be broken up into distinct collision “layers”. Default properties can also be passed on to custom importers in Tiled2Unity.

Additionally, the Tile Collision Editor now allows you to set properties on an Object Group or Collision basis.

With the new Tile Collision Editor you can assign types to each rectangle, polygon, or polyline collider you add to a tile. You can even have collisions of different types on any tile.

What doess this mean for Tiled2Unity? With earlier versions of the utility it could be cumbersome to manage the different collision types you have on your map. For example, say you had a map in Tiled that contained three different collision types …

Even though all these tiles could be easily placed on the same Tiled layer you would be forced to put them into separate layers, each with a unity:layer custom property on them, in order for them to be exported to Unity as separate Default, Ladders, and Spikes collision objects.

Now, with the latest Tiled and Tiled2Unity, you can simply create new types in the Object Types Editor …

Here I'm adding new object types for the kinds of colliders I'm interested in (Default, Ladders, and Spikes). The exported TMX map will result in a prefab that breaks out collider objects into these categories.

… and use those types in the Tile Collision Editor …

Through the Collision Editor we can select the ladder tile and add a collider that uses the Ladders type. Now I can use that tile on any Tile Layer and let the export process do the rest.

… and the collision tiles will be combined into PolygonCollider2d objects of the same type for you automatically …

Here you can see how the tiles are combined with other colliders of the same type. Note you will need to make Tiled2Unity aware of your Object Types XML file in order to use the same color scheme you set in Tiled.

This is done without the need for a custom unity:layer property. Note that the unity:layer property is still obeyed however if used. This is useful if you have a special Tile Layer that you want to force into a particular collision type.

Note that in order to see the collision type colors in the previewer that you will need to point Tiled2Unity to an Object Types XML file. I suggest you export that file (from the Object Types Editor in Tiled) to the same folder you keep your maps in and keep it updated.

You only need to set the Object Types XML file if you a) Want to see object type colors in the Previewer or b) You have default object property settings you want passed on to custom importers in your Unity project during export.

Default Object Type Properties Exported Too

Many users won’t need to worry about setting the Object Types XML when exporting their Tiled maps. However, if you want default properties to be exported with any Tile Objects to be consumed by a Custom Importer then you will need this setting.

Note: For Tiled2UnityLite users (Mac and Linux) you will want to pass the path to your Object Types XML as a command line option. For example:

Tiled2UnityLite.cs <span style="color: #333399;">-o=/Your/Path/To/objecttypes.xml</span> $TMXPATH $UNITYDIR

Tiled2UnityLite.cs <span style="color: #333399;">--object-type-xml=/Your/Path/To/objecttypes.xml</span> $TMXPATH $UNITYDIR

Bug Reports Always Welcome

I like to think I do a pretty good job of testing new features added to Tiled2Unity, but, because of reasons, the magnitude of this update is larger than normal. If you experience odd behavior or a fatal crash please send me an email so I can be aware of it.

I’ve said this before but I think the single best feature in Tiled2Unity is the PolygonCollider2D instances that are created from Tiled layers, where the colliders on each tile are merged into one big polygon. Concave edges? Holes? Not a problem.

In this scene from Wonder Boy in Monster World, the room colliders are just one big polygon with concave edges and a hole in the middle. It's a great way to represent the collisions but some code may not work with it.

However, some users would like to use the PolygonCollider2D instances created by Tiled2Unity and feed them into another Unity script or plugin that performs pathfinding, or real-time lighting, or whatever. The problem is, these other plugins commonly only work with polygons that are convex.

And by the way, if that’s a plugin you bought with actual money from the Unity Asset Store then I think that’s weak sauce. Tell those guys to fix their tools!

But I digress … with the latest Tiled2Unity version you can now set an option to have only convex polygons exported.

Note: Convex polygon output can be also be set through the -c or --convex options for those of you using the command line.

This will increase the number of PolygonCollider2D components in your Tiled prefabs but through the Hertel-Mehlhorn Algorithm I’ve made that number “reasonably” low. For most cases I’d be surprised if there was a noticeable change in performance.

With the Convex Polygon Colliders option enabled we have replaced the one “complex” polygon with seven convex polygons. This is an increase in prefab complexity but at least we can use it with other scripts that are limited to convex polygons.

Different Ways to Set Convex Polygon Output

There is some flexibility when it comes to enabling convex polygon exporting:

• Tiled2Unity Utility: Either use the Convex Polygon Colliders checkbox in the Win32 utility or use the -c|--convex command line option. This will be the preferred setting for exporting polygons for all maps.
• Tiled Map: Add a property named unity:convex to your Map Properties in Tiled set to true or false. This will be the preferred setting for all the layers in your map and will override the setting from the Tiled2Unity utility.
• Tiled Layer: Add the unity:convex property to your Layer Properties. This will be the final word on how the polygons in your layer will be exported, overriding the map and utility preferences.

Make sure to keep these precedence rules in mind. If you set unity:convex to true or false in a Tiled layer, for instance, then this will always be obeyed, no matter how you “prefer” to export maps in the Tiled2Unity Utility.

As always (and especially with a new feature such as this) you can email me any bugs you come across and I’ll find the spare time to address them. Just be aware a full-time game development which slows me down at times. 🙂

Special thanks go to the Poly2Tri contributors. Their polygon triangulation library came in handy for this feature.

Happy New Year’s Eve!

Over the holidays I decided I was finally going to do something about helping our friends on OSX and Linux systems get Tiled2Unity working within their development environments. I’m now happy to say that a command-line version of Tiled2Unity (named Tiled2UnityLite) is now available that gives any platform running Mono and CS-Script the capability of exporting Tiled maps into Unity.

Don’t let the name fool you:  The ‘Lite’ part simply means there is no GUI like in Tiled2Unity proper. You still get the exporting options we’ve been enjoying on Windows for some time now. The only thing you’re really missing is the previewer in the Tiled2Unity GUI but I suspect that feature isn’t used all that much anyhow.

The Tiled2Unity Previewer takes great screenshots but once your map is set up for rapid edit-and-export it becomes less useful.

A benefit of Tiled2UnityLite is that it is distributed as a single C# file. This makes it useful for making Tiled2UnityLite part of an automated build pipeline as well.

Below I explain how I got Tiled2UnityLite to run from Tiled Map Editor on a MacBook running Yosemite. Eventually, the goal is to have it set up where you press F5 to automatically export TMX files to Unity. This can be a (one-time) pain for some depending on how comfortable they are with environment variables and shell scripting. (I’m by no means an OSX power user so if someone comes up with better instructions I’ll be happy to post them.)

The main gist is this:

• Install Mono (Windows users don’t need to do this, nor invoke mono on the command line)
• Install CS-Script
• Download Tiled2UnityLite.cs
• Run a command from the terminal that runs Tiled2UnityLite.cs through CS-Script

The command should resolve to something like this:

mono cscs.exe Tiled2UnityLite.cs YourMap.tmx YourProject/Assets/Tiled2Unity

Installing Mono

Just go to the Mono website and follow their instructions. Piece of cake.

Installing CS-Script

CS-Script is a clever utility that allows you to use C# as a scripting language. Time was I used Ruby for all my scripting needs but I find myself writing C# and executing it at runtime through CS-Script more and more now. It’s a great tool — and it’s the key to having Tiled2UnityLite work on systems I hadn’t planned on supporting.

However, I did have some difficultly getting CS-Script running on OSX. This is likely due to my weak sauce Mac-fu but perhaps my instructions will be of help to others anyhow (El Capitan users and others wanting to install CS-Script to a directory of their choosing see import update below):

• Download CS-Script from their website
• Unzip, rename folder from cs-script to CS-Script and copy folder to usr/share/
  • The CS-Script executable should be as this location: /usr/share/CS-Script/cscs.exe
• Give usr/share/CS-Script execute and write permissions
  • In the terminal: sudo chmod 777 /usr/share/CS-Script

I also needed to update my .bash_profile file so that CS-Script was in my PATH:

export CSSCRIPT_DIR=/usr/share/CS-Script
export PATH=$PATH:$CSSCRIPT_DIR

At this point you should be able to run CS-Script from the terminal:

mono $CSSCRIPT_DIR/cscs.exe -v

C# Script execution engine. Version 3.9.20.0.
Copyright (C) 2004-2014 Oleg Shilo. www.csscript.net

   CLR:            4.0.30319.17020
   System:         Unix 14.0.0.0
   Architecture:   x86
   Home dir:       /usr/share/CS-Script

With that achieved we’re ready to run C# files as a script.

Update for El Capitan users: The directions above won’t exactly work because El Capitan does not allow write access to /usr/share. Try these modified steps as a work-around:

• Install CS-Script to this location instead: /usr/local/CS-Script
• Add this to your .bash_profile: export css_nuget=/usr/local/CS-Script/nuget
• (Actually, these directions should allow you to install CS-Script anywhere.)

Download and Run Tiled2UnityLite

You can download Tiled2UnityLite from the Tiled2Unity download page as a separate zip. This zip contains two files:

• Tiled2Unity.unityproject - Include this package in your Unity project.
• Tiled2UnityLite.cs - The C# file that contains all the Tiled2Unity source, all 10,000+ lines of it, with all the Windows-specific stuff excised out.

Go to the directory you’ve unzipped Tiled2UnityLite.cs to and run the help command on our script.

mono $CSSCRIPT_DIR/cscs.exe Tiled2UnityLite.cs --help

Tiled2UnityLite Utility, Version: 1.0.1.0
Usage: Tiled2UnityLite [OPTIONS]+ TMXPATH [UNITYDIR]
Example: Tiled2UnityLite -s=0.01 MyTiledMap.tmx ../../MyUnityProject/Assets/Tiled2Unity

Options:
  -s, --scale=VALUE          Scale the output vertices by a value.
                               A value of 0.01 is popular for many Unity 
                               projects that use 'Pixels Per Unit' of 100 for 
                               sprites.
                               Default is 1 (no scaling).
  -t, --texel-bias=VALUE     Bias for texel sampling.
                               Texels are offset by 1 / value.
                               Default value is 8192.
                                A value of 0 means no bias.
  -v, --verbose              Print verbose messages.
  -h, --help                 Display this help message.

Prefab object properties (set in TMX file for each layer/object)
  unity:sortingLayerName
  unity:sortingOrder
  unity:layer
  unity:tag
  unity:scale
  unity:isTrigger
  unity:ignore (value = [false|true|collision|visual])
  unity:resource
  (Other properties are exported for custom scripting in your Unity project)

Once your environment is configured to run Tiled2UnityLite like this then you are ready to export Tiled maps directly from Tiled Map Editor into your Unity project using the Execute Command GUI.

/bin/sh /MyPath/tiled2unitylite.sh %mapfile /MyProject/Assets/Tiled2Unity

You’ll notice I decided to run a shell script from Tiled when exporting to Unity. I’ll explain that a bit below but for now the command I use in Tiled is broken up into a number of parts:

1. /bin/sh This tells the operating system we’ll be running a shell script.
2. /My/Path/tiled2unitylite.sh This is the path to the shell script that will be running Tiled2UnityLite.cs through CS-Script with the arguments that follow. I use a shell script because I need a bit of help controlling the environment variables of the system (they are different when you launch an app as opposed to using the terminal).
3. %mapfile Tiled will replace this with the full path of the TMX file currently in focus.
4. /MyProject/Assets/Tiled2Unity The path to the Tiled2Unity folder in the Unity project you want to export to.

The tiled2unitylite.sh shell script is pretty standard fare:

#!/bin/sh

THIS_DIR=`dirname $0`
pushd $THIS_DIR > /dev/null 2>&1

CSSCRIPT_DIR=/usr/share/CS-Script
mono $CSSCRIPT_DIR/cscs.exe -nl Tiled2UnityLite.cs "$@" &> tiled2unitylite.log

popd > /dev/null 2<&1

You’ll note that I’m redirecting the output from Tiled2UnityLite.cs into a tiled2unitylite.log file (Quick note: You will have to create this log file before running the script). This helps me track down any errors that may be reported. I use the the tail command in another terminal so that I can track export progress in real time.

tail -f tiled2unitylite.log

With everything finally configured I’m able to, on a Mac, press F5 to export a Tiled map into Unity. Here’s a quick example from one of my most cherished memories in gaming history that old school gamers will quickly recognize.

In Tiled, I can press F5 to execute a command on the currently loaded map. In this example that command will export the map, through Tiled2UnityLite, to my Unity project.

Once exported to Unity, I can put the constructed prefab into my scene. As you can see, the tile layers and colliders have been successfully imported.

Now Accepting Donations for Tiled2Unity Development

Perhaps this is hard to believe but pleased Tiled2Unity users do ask if they could thank me for this tool by making a small monetary contribution. In the past I’ve asked them to support the Tiled Map Editor Patreon instead (which is still a priority, support that first!) but I do believe that Tiled2Unity has now matured into a valuable piece of software. Tiled2Unity will always be free but if you’d like to send a small gift my way I will accept it with pride and appreciation.

And on a personal note, with the new year just a few hours away, I wish you all an enjoyable and productive 2016. Have fun and keep working on your game.

As always, you can find the latest version of Tiled2Unity here.

Tile Animation Performance

I’ve long been embarrassed at how I had originally supported tile animations from Tiled Map Editor. It was a hack that manipulated vertex data at runtime which was a) slow and b) caused garbage collection spikes as vertex and index buffers were be allocated on the fly. Tiled2Unity now controls animation through enabling and disabling MeshRenderer instances. It’s cheap and simple.

I’ve added a new scene to the Mega Dad example suite that shows off tile animations while revisiting our old NES friend, Mega Man 2.

Here I've recreated Flashman's lair from Mega Man 2. The tile animations were made in Tiled and are exported to Unity without any additional work needed. It's meant to be quick and easy.

Note: You can find this example (and others) on GitHub to see how I use Tiled2Unity. All examples have been upgraded to the latest version of Tile2Unity.

Tile Objects Now Supported

Sometimes you want a single tile placed in your map without the hassle of having it as part of a Tile Layer. These Tile Objects were being exported as a simple transform (no visual tile) with earlier versions of Tiled2Unity. Now they are fully supported.

Object Layers are a good way to add extra, level-specific images and tags to your map without managing a whole Tile Layer.

Objects are generally exported as colliders by Tiled2Unity but the Tile Object is a special type that lets you place a single tile anywhere in your map. Colliders on that Tile Object are also exported.

Some Caveats

This was a significant change to Tiled2Unity compared to earlier updates. Here are some things to be aware of:

• Unity 4.x support has been removed. Sorry, but supporting older versions of Unity has become unwieldy. For what it’s worth, Sony and Microsoft (and I suspect Nintendo too) are phasing out support for Unity 4.x as well.
• Prefab GameObject heirarchy has been changed. In order to better support animations and object rotation and scaling I have changed how Tiled2Unity prefabs are constructed. You may have some scripts that were taking for granted a particular parent-child relationship that will need to be updated. (I recommend using tags to avoid issues like this in the future, not just when using Tiled2Unity, but as a general rule.)

Which approach you take will depend on the specific needs of your game measured against performance and memory usage. In my opinion, a good rule of thumb is to ask if your game is more like Advance Wars and Fire Emblem (use GameObject approach) or more like Final Fantasy and Dragon Warrior (use PolygonCollider2D approach).

Tiled Automapping Feature

Both approaches make use of the powerful, yet regrettably arcane, automapping capabilities of Tiled. I recommend boning up on this feature as a prerequisite, and not just for this exercise. You will likely use this feature extensively once you understand how to create automapping rules for your Tiled maps.

Note: If you’re having a hard time figuring out how to use automapping, I found this video to be helpful in making sense of it all. It’s 10 minutes well spent.

Example Project Files

Tiled map files and C# source used in these examples is available on GitHub as a Unity project that you can run and experiment with yourself.

TileObject Approach (Strategy Games)

Turn-based strategy and board game style games typically require each tile on a map to be a central part of the gaming logic. Each tile instance, although similar to others of the same “type” has to know where it is on the board as well as manage other game state (say, which units are standing on it, or how it influences other tiles or sprites around it). This is best handled in Unity by having each separate tile be associated with a GameObject made up of Components unique to the game you are making.

To achieve this we’ll have our Tiled map automatically generate Tile Objects that, when imported, are consumed by a custom importer script. During this custom import step we will attach GameObjects to our map prefab that is simply placed into a scene to do it’s job.

For this example I’ll use Fire Emblem as inspiration. Here’s the map from the first chapter of that game in Tiled:

For now, I’ll focus on the trees. What we want to do in Tiled is set up a rule that will place an object with custom properties on it in an output layer every time it sees a tree tile as input:

Working with automapping rules in Tiled at first can seem tricky. See fe-rules.tmx in the example files to see how I'm setting up rules for the Fire Emblem example.

Applying that rule you can see how a Tiled Object was placed upon every tree tile in the map:

Once our automapping rule is created we see that objects are automatically added to our map.

Upon export into our Unity project, those objects are added to the map prefab as Unity GameObjects. There isn’t much to them originally besides a BoxCollider2D so that’s where our custom import script will come in.

[Tiled2Unity.CustomTiledImporter]
public class CustomImporter_StrategyTiles : Tiled2Unity.ICustomTiledImporter
{
    public void HandleCustomProperties(GameObject gameObject,
        IDictionary<string, string> customProperties)
    {
        if (customProperties.ContainsKey("Terrain"))
        {
            // Add the terrain tile game object
            StrategyTile tile = gameObject.AddComponent<StrategyTile>();
            tile.TileType = customProperties["Terrain"];
            tile.TileNote = customProperties["Note"];
        }
    }

    public void CustomizePrefab(GameObject prefab)
    {
        // Do nothing
    }
}

The CustomImporter_StrategyTiles.HandleCustomProperties method is invoked for every Tiled Object in our map file. As you can see from the code above we are looking for the custom properties we’ve added to our Tiled map and, once found, we shove them into a custom component to be used by our game.

After filling out our automapping rules for all other tile types (mountains, water, grass, etc..) and re-exporting we now have a prefab, fully constructed by Tiled2Unity, that has unique data associated with every tile. In the example provided, I simply do a raycast off of mouse button click to find out which tile we’ve “selected”. I also keep a count of how many times you’ve clicked on that tile to demonstrate that game state is kept on a per-tile basis.

In the example demo, you can click on any tile and see what game state data is associated with it. Here, the game state is simply the number of times each tile has been selected.

Word of warning: Keep in mind that in this example we are (automatically) creating an object for every single tile placed in Tiled. This works well for games with smaller maps where you’ll have on the order of several hundred such objects. However, for larger maps the number of game objects in your scene could easily affect memory and performance. Remember that a 256×256 map will have 65,536 such objects which is likely too much complexity for Unity projects.

PolygonCollider2D Approach (RPG Games)

In RPG style games we are often more concerned by the “type” of tile our player is standing on as opposed to the exact tile instance. (In other words, we want to know if the player is in a forest, but we don’t care about a specific tree.)

This is a great job for the polygon colliders that Tiled2Unity creates from the Tile Collision Editor in Tiled. However, polygon colliders are created on a per-layer basis and it’s a total pain in the ass to have to manage separate layers for each type of tile we may have in our game.

Again, this is where automapping can help us and in this case the mapping rules are dead simple. All we need to do is take every tile from a single input layer and output the exact same tile to a particular output layer — one for each type of tile.

Our working layer is the only layer we need to manipulate in Tiled. However, it is exported as one big collision. We can't tell if we collide against water or mountain or grass tiles.

By setting up rules to automatically create output layers for each tile type we can export the map with separate colliders for each type of tile in our game.

Setting up our rules this way allows us to work in only one layer and have all the output layers created for us automatically. The example contains part of the Dragon Warrior overworld (Charlock Island) with the polygon colliders set up for each tile type. We just do a raycast from the mouse position to see what kind of tile we selected.

In the Dragon Warrior example we can select which type of tile we are interested in.

You can see how this would work for a proper RPG style game, giving you the ability to spawn monsters that belong to a particular type of terrain. You get the added bonus of having collision detection for parts of the world you want to keep your character out of. (Also note we don’t need custom importer scripts for this example.)

Can’t There Be An Easier Way?

All things considered? I don’t think so. I often get requests from developers that “just want to get a tile” at runtime thinking that data should be right there waiting for us. I see two problems with that:

1. Maps grow with quadratic complexity. One of the chief benefits of Tiled2Unity is the simplicity of minimal meshes and polygon collider objects that are made to work with Unity.  Managing objects on a per-tile basis, for all Tiled2Unity users, would undo that.
2. What would per-Tile information look like anyhow? In my mind, there is no way to make a general, one-size-fits-all offering for this. All data in Tiled is text but when we consume it in our game it must be in a format that makes sense for our specific application.

Having said that, with some clever use of features already available to us and maybe a little tool-side scripting you should be able to make Tiled and Tiled2Unity work for you in ways that are unique to your game development needs.

You Can Now Put Tiled2Unity Anywhere In Your Unity Project

I had originally hardcoded all the scripts that build a prefab from Tiled2Unity to exist at the Assets/Tiled2Unity directory. However, many developers prefer to gather all third-party libraries in a common location and I totally can’t blame them for wanting to put Tiled2Unity in a location like Assets/Scripts/ThirdParty/Tiled2Unity along with everything else. That is now supported with the latest build of Tiled2Unity.

One caveat: I had to change the way the Tiled2Unity exporter is made aware of your Unity project in order to export the right files to the right location. You will now have to explicitly select your Tiled2Unity scripts location in your Unity project instead of just selecting the project root folder. This is done by finding the Assets/Your/Path/To/Tiled2Unity/Tiled2Unity.export.txt file in your Unity project.

The “Export To ...” button allows you to choose where to export Tiled maps within your Unity project.

Each install of Tiled2Unity in Unity contains an export marker file that must be selected as the export destination.

You will need to traverse into your Unity project to find the Tiled2Unity/Tiled2Unity.export.txt file. This will instruct the Tiled2Unity exporter where all the textures, materials, meshes, and prefabs will be created for use in your Unity project.

This is just a tiny bit more complicated than earlier builds of Tiled2Unity but I think the trade-off is worth it. Tiled2Unity will remember your last export destination so you won’t have to select this every time you export a Tiled map into your project.

Mark Tiled Maps as Resources For Object Instantiation

Most Tiled2Unity users will simply drop a Tiled2Unity generated prefab into their scene but some developers may want to instantiate a map prefab through script. However, Unity forces developers to place such assets in a Resources folder. This meant users would need to export a Tiled map into Unity then move the generated prefab into another folder by hand — which breaks automation.

With the latest version of Tiled2Unity you can mark a Tiled map with the unity:resource property like so …

Add a custom property with the name unity:resource (set value of True) to mark the map as a Unity resource. This will allow you to instantiate the map prefab via script.

Normally, Tiled map prefabs are constructed in the .../Tiled2Unity/Prefabs folder but with the unity:resource property they will reside in .../Tiled2Unity/Prefabs/Resources instead. With this you can easily instantiate the prefab in realtime via a Unity script, for example …

using System.Collections;

public class MapCreator : MonoBehaviour
{
    void Start()
    {
        UnityEngine.Object prefab = Resources.Load("MyTiledMapPrefab");
        GameObject.Instantiate(prefab);
    }
}

Developers employing some kind of procedural generated content scheme should find that useful.

Added Potential Bonus: Win32 Specific Code Removed

With this latest build I have gone through and removed all dependencies on unmanaged Win32 code (the old export dialog was a big offender). The Tiled2Unity exporter still doesn’t officially support any non-Windows platform but people wanting to make Mac or Linux versions run via Mono should have an easier time at it now.

(Note: Isometric artwork is attributed to Yar via OpenGameArt.org)

Since Tiled2Unity’s release I’ve held firm on not supporting isometric maps due to two reasons:

1. The game developers of days gone were limited to square tilesets and depended on artwork to give the illusion of their view whether it be top-down, side-view, 2.5D, whatever. Isometric (and hexagonal) were no different – you just bake the effect into the pixels.
2. It’s a pain in the ass to implement.

However, my inbox tells me my fellow developers would really like to export their isometric maps to Unity with the same relative ease that their orthographic brothers and sisters enjoy. Also, I couldn’t go on pretending Tiled2Unity was the perfect companion app to Tiled for Unity developers when a major feature was not being supported.

Tiled2Unity: Isometric and Hexagonal Maps

If you download the latest version of Tiled2Unity you will find support for the following map types (in addition to orthographic):

• Isometric
• Isometric Staggered
• Hexagonal (including all 4 variations of the coordinate system)

That’s every map type that Tiled is capable of creating right now, and, just like with orthographic maps, you can export collision objects into your Unity projects.

(Note: Hexagonal artwork is attributed to Steffen via TilemapKit)

Object Colliders in Isometric Mode

The isometric map mode in Tiled skews your collision objects so that rectangles becomes parallelograms and circles become ellipses. This complicates things a bit for us in Unity.

For all other map types (including isometric staggered) the rectangle object will be exported as a BoxCollider2D and the circle a CircleCollider2D. Easy.

For the isometric map type the rectangle will be exported as a PolygonCollider2D and will keep the shape as displayed in the image above. The circle, however, will be lost. Note that ellipses with uneven width and height have never been supported in Tiled2Unity due to the lack of an EllipseCollider2D in Unity. Now that the circle in the example above is really an ellipse it falls into that category. Sorry, no cheap circle collisions here. If you really need a circle collider I suggest you go with an isometric staggered map instead.

Beware of Visual Seams

Depending on how your isometric and hexagonal tilesets are authored you may see a lot of visual seams in your Unity project with some camera settings and shaders.

Here’s an example of an 8×8 isometric tile …

… and how you’d expect tiles like this to be rendered together …

However, due to mathematical imprecision with the texture sampler you may end up with something that looks like this under certain conditions …

The best way to avoid this is to add extra pixels that bleed outside the isometric shape …

Generally, those extra pixels will be overlapped by the “proper” pixels of a neighboring tile but in the case where the texture sampling goes a bit out of bounds you’ll be covered.

Important Note: Do no increase the size of your tiles in Tiled to make up for those extra pixels. That’s what the margin setting is for in your tileset. Even though the “bleeding” tiles above may now be 10×10, they are really 8×8 tiles with 1 pixel margins.

What if You’ve Found a Bug?

I generally don’t work with isometric or hexagonal maps so at this time I can’t say this tech is too battle tested. If you’ve found an issue you can always leave a comment below or email me. I’m a fulltime game developer by day and a hobbyist programmer by night so keep in mind I can’t always reply right away.

Please Support Tiled on Patreon

I talk about this a lot because I know from Tiled2Unity alone that there is a lot of enthusiasm out there for Thorbjørn Lindeijer’s work with Tiled Map Editor. It is difficult to support the game development community as well as he has with a career and a family so please consider pledging to Bjørn’s Patreon in hopes of making Tiled even better his new fulltime job.

Even a couple of dollars each month adds up quickly so please join me in helping Bjørn reach his goal.

Note: It’s April 8th again which means my friends at 1 More Castle are hosting Review A Great Game Day. I love this as I feel our hobby and craft can always use more positive energy (especially this past year, ffs) so I’m happy to contribute my own review and honor a game I’ve loved for almost 30 years.

Zanac Game Review

It’s no secret to people that know me that I love the 1980s. What other decade can compare culturally to the one that gave us Tears for Fears, Back to the Future, ThunderCats, and the Nintendo Entertainment System? Granted, my children have a good argument in My Little Pony: Friendship is Magic representing their generation well but what if you want to experience a good Transformers movie for once? Sorry kids, you need the 80s for that. (‘Til all are one!)

One throwback from the 80s that we don’t see emulated often these days is the SHMUP game. There are a ton of titles from that time and genre that are awesome from Xevious to 1943: The Battle of Midway and the ever-popular R-Type and Gradius franchises – but there is one game that I consider the very best on any platform: Zanac.

(Zanac’s box art alone makes the game worthy of commemoration.)

The Best of SHMUP Gaming

When it comes to what we love most about the mindless fun in SHMUPs, Zanac has everything going for it.

First of all, Zanac is fast, and I mean blistering. At times the background scrolls by faster in this game then anything I’ve yet to play. Most game developers now do their best to keep the action running at a steady 30 frames per second – a difficult task given the increased complexity of video games today.

But Zanac keeps a steady 60 fps throughout. I’ve been playing the game for decades now I’ve yet to detect any slowdown. The programmers at Compile were wizards of their time.

Zanac also does a great job at pacing. I love how the background scrolling slows down at times (and even stops for boss battles) to give the player a bit of a break from the speed and enjoy the pixelated graphics. This range in movement makes the hectic parts even that more punctuated. It’s perfect.

The weapon power-ups are a lot of fun too and with a few exceptions (more below) each of the 8 special weapon types are useful for a particular style of play or type of enemy or environment – although most players will likely stick with one fully powered-up special weapon and stick with it throughout the game (Special Weapon 7 seems to be the favorite for most gamers).

The developers at Compile took a clever approach to “boss monsters” in the way of fortresses that are made of smaller, reusable parts grouped together into some construct. As a developer I love it when games repurpose assets in a way that doesn’t feel repetitive. In Zanac, each fortress encounter feels unique even though they are essentially made of the same elements.

And oh my god the music in Zanac is fantastic! Each piece of music is super catchy and fits in with the fast-paced sci-fi shooter action masterfully. I have the soundtrack on my iPod and there isn’t a week that goes buy that I don’t listen to it. It’s so good.

An Added Twist that is Almost Perfect

Zanac is also well known for it’s adaptive artificial intelligence that scales the difficulty based on your skill and/or aggression — at least in theory. This can be a useful feature as the game won’t be as punishing if you lose a ship and have to respawn with base weapons.

Where this doesn’t quite work is some special weapons automatically crank up the difficulty when you acquire them. The Special Weapon 2 (shield) is the worst offender that instantly brings about waves of the most powerful enemies in the game if you equip it. This essentially makes that power-up useless and it’s a real drag if you should accidently pick it up – something that is easy enough to do given the frantic pace of the game.

However, this feature does make each play session a bit different than last, adding to replay value. And, I love the way Compile wrote this feature into the fiction of the game: Humanity is at war with “The System”, whose adaptive A.I. would easily destroy a fleet a fighters. Hence, the need for a single pilot to infiltrate and destroy. (Hey, it’s from the 80s.)

A Forgotten Game (and Genre) Worth Revisiting

We seem to be living in a golden age of classic styled video games with titles like Retro City Rampage, Shovel Knight, and now Axiom Verge scratching the itch left behind by the 8-bit and 16-bit glory days. It’s a great time to be a gamer and even better for a developer making these types of games with modern hardware. I only wish that SHMUPs would get a bit of the attention that seems reserved for Metroidvania style games.

Should someone out there decide to revisit SHMUP games I hope they give Zanac a serious look. I consider it to be the most essential game of the genre.

(And yes, I’m totally aware of Konami’s Life Force. It rocks! I just think Zanac is a bit better.)