diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ad1989f --- /dev/null +++ b/LICENSE @@ -0,0 +1,13 @@ + DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE + Version 2, December 2004 + + Copyright (C) 2004 Sam Hocevar + + Everyone is permitted to copy and distribute verbatim or modified + copies of this license document, and changing it is allowed as long + as the name is changed. + + DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. You just DO WHAT THE FUCK YOU WANT TO. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..1ef2ffb --- /dev/null +++ b/README.md @@ -0,0 +1,107 @@ +# 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. \ No newline at end of file diff --git a/addons/csharp_ldtk_importer/LICENSE b/addons/csharp_ldtk_importer/LICENSE new file mode 100644 index 0000000..ad1989f --- /dev/null +++ b/addons/csharp_ldtk_importer/LICENSE @@ -0,0 +1,13 @@ + DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE + Version 2, December 2004 + + Copyright (C) 2004 Sam Hocevar + + Everyone is permitted to copy and distribute verbatim or modified + copies of this license document, and changing it is allowed as long + as the name is changed. + + DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. You just DO WHAT THE FUCK YOU WANT TO. \ No newline at end of file diff --git a/addons/csharp_ldtk_importer/README.md b/addons/csharp_ldtk_importer/README.md new file mode 100644 index 0000000..1ef2ffb --- /dev/null +++ b/addons/csharp_ldtk_importer/README.md @@ -0,0 +1,107 @@ +# 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. \ No newline at end of file diff --git a/ldtk-importer.csproj b/ldtk-importer.csproj index e6cdef7..e99cb50 100644 --- a/ldtk-importer.csproj +++ b/ldtk-importer.csproj @@ -5,4 +5,10 @@ true ldtkimporter + + + + + + \ No newline at end of file