107 lines
4.7 KiB
Markdown
107 lines
4.7 KiB
Markdown
# 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. |