LDtk importer plugin for Godot 4
/ldtk-importer/
into the /addons/
folder in your Godot project.Project > Project Settings > Plugins
.ldtk
files can now be opened in the Editor!LDTKEntity
nodes.With the .ldtk
file selected in FileViewer
, go to the Import
dock to view the following import options:
LDTKWorldLayer
nodes, sorted by worldDepth
.LDTKEntity
nodes that emulate entities inside LDTK.LDtk allows you to add custom data to individual tiles in any given tileset.
This data can either be numbers, text, JSON, XML, etc. Basically, any tile related info you would like to pass to your game engine.
If the import option Tileset Custom Data
is selected, a Custom Data Layer is added and the data is stored on the tile as a String
. If you need to further parse your tile data, write a Tileset Post-Import script.
You can hook up custom scripts that run during importing that further modify the resulting Scene/Resource.
Currently, there are four points where a post-import script can be inserted, in order of execution:
Example post-import scripts are included to cover common use cases; feel free to edit/expand on them to suit your project.
@tool
func post_import(tilesets: Dictionary) -> Dictionary:
# Behaviour goes here
return tilesets
@tool
func post_import(entity_layer: LDTKEntityLayer) -> LDTKEntityLayer:
var definition: Dictionary = entity_layer.definition
var entities: Array = entity_layer.entities
for entity in entities:
# Perform operations here
pass
return entity_layer
@tool
func post_import(level: LDTKLevel) -> LDTKLevel:
# Behaviour goes here
return level
@tool
func post_import(world: LDTKWorld) -> LDTKWorld:
# Behaviour goes here
return world
While it is possible to add tileset collisions via a post-import script, this plugin is designed so that it is easy to manually edit the generated TileSets inside the project directly - reimporting the LDtk file will preserve these changes.
tilesets/tileset16x16.res
)TileSet
pane, select the TileSetAtlasSource
and go to the Select
view.Physics
submenu and select the created Physics Layer
.TIP: A quick way to do this is to click+drag to select multiple tiles, and press F to use the default tile shape.
Import Options
, make sure you have selected Atlas Texture Type
to Canvas Texture
tilesets/tileset16x16.res
)Tileset
pane, select the TileSetAtlasSource
go to the Setup
viewTexture
, and add the corresponding normal map.This was quite tricky to get right, and still needs some testing! I might expand this into its own section, but it's probably best if I explain how these are currently handled by the importer.
LDTK uses instance ids to refer to unique instances of levels, entities, etc. They look this:
{
"iid": "c27f1f10-3b70-11ee-8b24-732c4cff2bf2"
}
There are two things to consider when converting the JSON into a scene:
instance_references
)unresolved_references
)EntityRef fields are unresolved when they are encountered by the importer, because the node it points to might not exist yet (e.g. an entity from Level_1 may point to an entity in Level_2).
To solve this, this LDTK importer provides utility functions for you to add/update these references, which the importer will then try to resolve them after all the post-import scripts have run, before saving the scene.
These functions are:
update_instance_reference(iid, scene)
add_unresolved_reference(scene, property_name)
Check out the following Entity Post-Import script to see how they are used:
@tool
## Entity Post Import Example, showcasing how to handle EntityRefs.
const Util = preload("res://addons/ldtk-importer/src/util/util.gd")
const SceneTest = preload("res://node_test.tscn")
func post_import(entity_layer: LDTKEntityLayer) -> LDTKEntityLayer:
var entities: Array = entity_layer.entities
for entity in entities:
# Create entity node (simple example)
var scene = SceneTest.instantiate()
entity_layer.add_child(scene)
# Update 'iid' to reference this entity node
Util.update_instance_reference(entity.iid, scene)
# Add unresolved reference (e.g. EntityRef field)
if "Entity_ref" in entity.fields:
var ref = entity.fields.Entity_ref
if ref != null:
scene.ref = ref
Util.add_unresolved_reference(scene, "ref")
return entity_layer
Here is the example SceneTest scene:
@tool
extends Node2D
@export var ref: NodePath # The EntityRef we are updating via post-import
The entity scene holding an EntityRef variable must have the
@tool
annotation in its attached script, otherwise variables cannot be updated this way in the Editor.
If you run into any problems, please file an issue!