Godot C# LDTK Importer

An editor import plugin for Godot 4.5+ (C#) that allows you to import LDTK level editor projects (.ldtk) as Godot scenes. This addon is designed to provide a seamless bridge between LDTK's powerful level design features and the Godot engine.

Features

• Direct Import: Imports .ldtk files as native Godot PackedScene resources.
• TileMap Layers: Automatically creates and configures TileMapLayer nodes for LDTK's "Tiles" and "AutoLayer" layers.
• World Layout: Respects the worldX and worldY coordinates of your levels, preserving your world layout from the LDTK editor.
• Entity Instancing: Provides a flexible mapping system to replace LDTK entities with your own Godot scenes (.tscn files).
• Custom Data Transfer: Transfers custom fields from LDTK entities to your instanced Godot scenes as metadata, making them easily accessible in scripts.

---

Installation

1. Get the Addon:
   • Manual (Recommended): Download this addon's repository. Create an addons folder in your Godot project if you don't have one, and place the csharp_ldtk_importer folder inside it. Your project structure should look like this:

     - res://
     - addons/
     -     csharp_ldtk_importer/
     -         plugin.cfg
     -         ... other files
     

2. Build the C# Project:
   • Open your project in Godot. You will see a Build button appear in the top-right corner of the editor. Click it to compile the addon's C# code.
3. Enable the Plugin:
   • Go to Project -> Project Settings.
   • Navigate to the Plugins tab.
   • Find "C# LDTK Importer" in the list and check the Enable box on the right.

The importer is now active and will handle any .ldtk files in your project.

---

Basic Usage

1. Add Your LDTK Files: Copy your .ldtk project file and its corresponding tileset image(s) (e.g., .png) into your Godot project's file system.
2. Automatic Import: Godot will automatically detect the files and run the importer.
3. Use the Scene: You can now use the imported .ldtk file as if it were a native Godot scene:
   • Double-click the .ldtk file in the FileSystem dock to open the generated scene and view its structure.
   • Drag and drop the .ldtk file into another scene to instance your entire LDTK world.

---

Advanced Usage: Entity Instancing

This is the most powerful feature of the addon. It allows you to replace LDTK's abstract entities with your actual game scenes (like players, enemies, items, etc.).

Step 1: Create an Entity Map Resource

The importer needs a "map" to know which LDTK entity corresponds to which Godot scene.

• In the FileSystem dock, right-click on a folder.
• Select New Resource....
• In the dialog, search for and select LdtkEntityMap.
• Save it as a .tres file (e.g., MyEntityMap.tres).

Step 2: Configure the Map

• Select your newly created MyEntityMap.tres resource.
• In the Inspector, you will see the "Entity Scene Map" property.
• Add new entries to the dictionary:
  • Key: The exact string identifier of your entity in LDTK (e.g., Player, Coin, Bat). This is case-sensitive.
  • Value: Drag the corresponding Godot scene (.tscn file) from the FileSystem dock into the PackedScene slot.

Step 3: Link the Map to your LDTK File

• Select your .ldtk file in the FileSystem dock.
• Go to the Import tab (next to the "Scene" and "History" tabs).
• You will see the importer's options. Find the Entity Map property.
• Drag your MyEntityMap.tres resource into the property slot.
• Click the Reimport button at the bottom of the Import dock.

Your LDTK project will be re-imported, and this time, all mapped entities will be replaced by instances of your scenes!

Step 4: Accessing Custom Data in Scripts

Any custom fields you add to an entity in LDTK are automatically attached to your instanced Godot scene as metadata. You can access this data easily from a script attached to your entity's scene.

Example (C#):

Let's say you have an "Enemy" entity in LDTK with a custom integer field named health and a boolean field named is_flying.

// In a script attached to your Enemy.tscn's root node.
using Godot;

public partial class Enemy : Node2D
{
    public override void _Ready()
    {
        // Get the metadata. The second argument is a default value if the meta isn't found.
        int health = GetMeta("health", 100).AsInt32();
        bool isFlying = GetMeta("is_flying", false).AsBool();
        
        GD.Print($"Enemy spawned with {health} HP. Is it flying? {isFlying}");
    }
}

---

License

This addon is provided under the WTFPL License. See the LICENSE file for more details.