LDtkToUnity Documentation

The imported LDtk project generates a nested hierarchy of GameObjects in Unity that mirrors the LDtk JSON structure. This hierarchy allows you to navigate your level data through the Unity Hierarchy window using the following structure:

• Project Root
  • Worlds
    • Levels
      • Layers
        • Entity/Tilemap GameObjects

This structure ensures that the spatial and organizational relationships defined in LDtk are preserved in your Unity scene.

LDtkToUnity provides several advanced features for integrating LDtk into Unity workflows:

• Automated Importing: Uses ScriptedImporter for automatic re-imports on file save.
• Tile Support: Supports Animated Tiles and optimizes import speeds by separating tileset generation and packing them into a SpriteAtlas.
• Entity Management: Supports entity prefab replacements and imports fields from both entities and levels.
• Collision & Scripting: Includes collision options and supports custom Post-import scripting to customize import results.
• Data Integration: Automatically generates enums and provides properties/functions for LDtk data to improve Unity context.
• Level Management: Supports separate level files and Unity's Configurable Enter Play Mode.

For every definition in your LDtk project, the importer generates a corresponding Unity ScriptableObject. These objects act as data containers for your definitions (such as Entities, Layers, or Tilesets) and are automatically referenced by the appropriate components in the GameObject hierarchy.

This mapping allows you to use Unity's native asset system to manage and reference LDtk metadata.

When configuring an IntGrid Tile, you can choose from three Collider Type options to define how collision is handled:

1. None: No collision is generated. If rendering IntGridValues is enabled in the importer, it will render a square.
2. Sprite: Uses the physics shape(s) of a designated sprite for collision. If rendering IntGridValues is enabled, it will render the sprite.
3. Grid: Uses square collision. If rendering IntGridValues is enabled, it will render a square.

The import process follows a specific execution order. By default:

1. Import Interfaces (e.g., ILDtkImportedFields) are processed first (Priority 0).
2. Postprocessors (e.g., LDtkPostprocessor) are processed second (Priority 1).

All these events invoke at the end of the import process, meaning all GameObjects are fully accessible when they run.

Customizing Order

You can change the execution order by overriding the following methods in your custom classes:

• LDtkPostprocessor.GetPostprocessOrder
• ILDtkImported.GetPostprocessOrder

To debug the execution sequence, enable verbose logging in the project Preferences.

To improve usability within Unity, several data types from the LDtk JSON are automatically converted during import:

Additionally, some component fields are restructured for better Unity integration, such as the level's layers being represented as an array of components.