Skip to content


Repository files navigation

Please note, I am no longer actively maintaining this plugin as of 04/09/2023. There are several forks of this project that are more up to date, as well as other similar plugins that are available on GitHub. I'll be leaving the project up for those that want to view the code and/or build from it, but do note that it most likely will be outdated.



  • Godot version: 3.4.4
  • LDtk version: 1.1.3

Basic GDscript for importing LDtk files into the Godot game engine.



  • New feature: Post Import Script (thanks to univeous)
  • Level metadata is now imported when "Import Metadata" option is enabled (thanks to univeous)
  • Fixed entities not saving CollisionShape2D's


  • Updated to Godot version 3.4.4
  • Updated to LDtk version 1.1.3
  • Fixed collision layer import.
  • Rewrote some of the information below on how to use the importer.


  • Added option to import entities layer as YSort.


  • Added option to import custom entities.
  • Added option to import metadata.
  • Added option to import collisions.


  • Updated for new version of LDtk.
  • Changed import style: instead of making a new scene you can just open the ldtk file.


  • removed import files.


  • The Importer is now an addon/plugin.
  • Added basic import options for Entities.


  • Added basic functionality for autolayers and intgrid layers.

Can now create tilemaps from autolayers and intgrid layers with tilesets. Intgrid layers without tilesets are ignored currently.


  • Currently this script has very basic functionality. Only Tile Layers are currently working.

How to use:

  1. Copy the addons folder to your godot project folder.
  2. Enable LDtk Importer under Project Settings/Plugins.
  3. Add a .ldtk map file and any spritesheets you're using to your project folder.
  4. Select your .ldtk file and open the Import menu to toggle importing collisions, custom entities, metadata, and YSort.


  • IntGrid, Tiles, and AutoLayers are imported as TileMap Nodes.
  • Currently Entities have very basic functionality, checkout the testmap.ldtk for examples.

Import Menu Options:

  • Import_Collisions: Import collisions from IntGrid layer (see import collisions below).
  • Import_Custom_Entities: Import your own Resources (see entities). Keep in mind that this will remove the other node options (they will still be imported, but only as Node2D).
  • Import_Metadata: Import any fields set on entities or levels. For entities, If they have an exported property with the same name, it will set the value of the property with the value on LDtk, if they don't (or the plugin can't find it), they will be imported as metadata (using 'set_meta()') and can be retrieved later using 'get_meta()' on the imported object. Level's fields will all be imported as metadata.
  • Import_YSort_Entities_Layer: Any Entities Layer whose name begins with "YSort" will be imported as a YSort node, and all the entities will be set as children of this YSort node.
  • Post_Import_Script: The selected script will have it's post_import(scene) method run. This enables you to change the generated scene automatically upon each reimport. The post_import method will receive the built scene and must return the changed scene.

Importing Collisions:

  • Create an IntGrid layer called "Collisions", tiles on this layer will be made into CollisionShape2D and added to a StaticBody2D node.


You can set up how your entities are imported:

  1. Create a new Entity
  2. Add a String Field Type
  3. Set the Field Identifier to: NodeType
  4. Set the Default Value to the type of Node
  5. Any fields added to the entity on LDtk can set properties on the object or be added as metadata if the option is set when importing (retrieve using the function 'get_meta()' on the object after importing).

If your entity does not have a NodeType field, it will be imported as a Node2D node and all fields will be imported as metadata. You can set up post-import scripts to handle the imported entities yourself.

Current node options are:

  1. If not using Custom Entities:

    • Position2D
    • Area2D
    • KinematicBody2D
    • RigidBody2D
    • StaticBody2D
  2. If using Custom Entities:

    • Set the Default Value to the resource path (eg: 'res://Player.tscn').


  • The example is using the tileset that comes with LDtk: Cavernas_by_Adam_Saltsman.png
  • The conversion functions: coordId_to_gridCoords(), tileId_to_gridCoords(), tileId_to_pxCoords() are from the LDtk documentation.


Basic GDscript for importing LDtk files into the Godot game engine.







No releases published


No packages published