# 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`.

```csharp
// 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.