SuperTiled2Unity Documentation

Custom Importers provide a programmatic way to completely transform the generated prefab during the import process. This is the most powerful extension method but requires writing C# code.

To implement a custom importer, inherit from CustomTmxImporter and override the TmxAssetImported method.

Important Requirements:

• Determinism: Any modifications made to the GameObjects or components must be deterministic; the same prefab must be produced every time the import runs.
• Accessing the Map: Use args.ImportedSuperMap to access the root of the imported prefab.
• Application: You can use the [AutoCustomTmxImporter] attribute to force the importer to always be applied, or omit it to select the importer from a drop-down list in the Unity Inspector.

  // The AutoCustomTmxImporterAttribute will force this importer to always be applied.
  // Leave this attribute off if you want to choose a custom importer from a drop-down list instead.
  [AutoCustomTmxImporter()]
   public class MyTmxImporter : CustomTmxImporter
   {
       public override void TmxAssetImported(TmxAssetImportedArgs args)
       {
           // Note: args.ImportedSuperMap is the root of the imported prefab
           // You can modify the gameobjects and components any way you wish here
           // Howerver, the results must be deterministic (i.e. the same prefab is created each time)
           var map = args.ImportedSuperMap;
           Debug.LogFormat("Map '{0}' has been imported.", map.name);
       }
   }

Tiled's predefined properties (defined via the Object Types Editor) are not recognized by SuperTiled2Unity by default. To enable support for these predefined properties, you must export the Object Types XML file from Tiled and link it to your Unity project settings.

1. Export Object Types from Tiled

1. In Tiled, go to the File menu.
2. Select Export Object Types....
3. Save the resulting XML file inside your Unity project's Assets directory.

2. Configure SuperTiled2Unity Project Settings

1. In Unity, go to Edit -> Project Settings....
2. Locate the SuperTiled2Unity settings section.
3. Find the Object Types Xml field.
4. Drag and drop your exported XML file into this field (or use the asset selector).

3. Verify Imported Properties

1. Click the View Custom Properties button located just below the XML field in the settings window.
2. This opens the Custom Object Types Properties window, which lists all imported custom object types, their properties, and their custom colors.

Once configured, any updated map assets in your project will include these predefined properties in their SuperCustomProperties instances.

To achieve an overhead view where sprites dynamically sort against tiles (e.g., a player moving behind a column), follow these three steps:

1. Import the map using the Custom Sort Axis sorting mode in the SuperTiled2Unity importer.
2. Configure Unity Project Settings: Set the Transparency Sort Mode to Custom Axis and set the Transparency Sort Axis to an axis with increasing values (typically Vector3.up for Y-axis sorting).
3. Match Sorting Properties: Ensure that both your Unity sprites and your Tiled tiles are assigned the same Sorting Layer and have the same Order in Layer values. If these do not match, the dynamic sorting will not work correctly.

// Example: Setting the transparency sort axis via script
var camera = GameObject.FindGameObjectWithTag("MainCamera").GetComponent<Camera>();
camera.transparencySortMode = TransparencySortMode.CustomAxis;
camera.transparencySortAxis = Vector3.up;