LDtk Tilemap Level

Full LDtk level renderer for grid-based tile layers, auto-layering, and entity placement.

Type: LdtkLevelNode · Category: Graphics & Rendering · Also found as: ldtk, ldtklevel

Properties

Property	Type	Default	Description
enablePhysics	boolean	true	Build colliders from IntGrid cells whose collision rule is Solid / One Way.
spawnEntities	boolean	true	Spawn the level’s entities (mapped to components) when ready.
parallax	boolean	true	Apply the LDtk layers’ parallax factors.
drawBackground	boolean	true	Draw the level’s background colour / image.
drawEntityTiles	boolean	false	Draw entities’ LDtk tiles (editor visuals for unspawned entities).
tintColor	color	#ffffffff	Multiplies every layer’s colours.
drawDebugColliders	boolean	false	Outline the generated colliders.
drawDebugEntities	boolean	false	Outline entity bounds with their names.

Plus the common properties every node has.

Lua methods

Call them on the node (self.node in its script, or self.node:get_node("path")). Every node also has the Node methods.

LdtkLevelNode:connect(event, handler)

Connects a handler to one of this node’s events: level_loaded (The LDtk level was built), entity_spawned (An LDtk entity was spawned); the tree events; custom ones.

self.node:connect("level_loaded", function(value, source) Log.info("level_loaded") end)

• event LdtkLevelNodeEvent|string
• handler fun(value: any, source: LdtkLevelNode)

Returns integer id Connection id for disconnect

LdtkLevelNode:get_property(path)

Reads an Inspector property by its path (vectors and colours as tables); “script.” reads a field of the node’s script.

local value = self.node:get_property("enablePhysics")

• path LdtkLevelNodeProperty|string

Returns any

LdtkLevelNode:set_property(path, value, y)

Sets an Inspector property by its path: vectors as {x, y} or x, y; colours as {r, g, b[, a]} 0..1 or “#rrggbb[aa]”; enums by name; “script.” a field of the node’s script.

self.node:set_property("enablePhysics", true)

• path LdtkLevelNodeProperty|string
• value any
• y? number

LdtkLevelNode:ldtk_get_level_identifier()

Gets the current level identifier.

local lv = Scene.find_node("Level"); Log.info("In " .. lv:ldtk_get_level_identifier())

Returns string

LdtkLevelNode:ldtk_get_levels(world)

Lists level identifiers (every level, or one world’s).

local lv = Scene.find_node("Level"); for _, id in ipairs(lv:ldtk_get_levels()) do Log.info(id) end

• world? string

Returns string[]

LdtkLevelNode:ldtk_load_level(identifier)

Switches to another level (identifier or iid); colliders and entities are rebuilt.

local lv = Scene.find_node("Level"); local ok = lv:ldtk_load_level("Level_2")

• identifier LdtkLevel|string

Returns boolean ok

LdtkLevelNode:ldtk_get_level(level)

Gets a level’s details (the current level by default).

local lv = Scene.find_node("Level"); local info = lv:ldtk_get_level(); Log.info(info.width)

• level? LdtkLevel|string

Returns LdtkLevel?

LdtkLevelNode:ldtk_get_level_size()

Gets the current level size in pixels.

local lv = Scene.find_node("Level"); local w, h = lv:ldtk_get_level_size(); Log.info(w, h)

Returns number width, number height

LdtkLevelNode:ldtk_get_level_field(name, level)

Gets a level field value (nil if absent or null).

local lv = Scene.find_node("Level"); local music = lv:ldtk_get_level_field("music")

• name string
• level? LdtkLevel|string Another level (default: the current one)

Returns any

LdtkLevelNode:ldtk_get_level_fields(level)

Gets every field of a level.

local lv = Scene.find_node("Level"); local fields = lv:ldtk_get_level_fields(); Log.info(fields.music)

• level? LdtkLevel|string

Returns table<string, any>

LdtkLevelNode:ldtk_get_neighbours(level)

Lists a level’s neighbours.

local lv = Scene.find_node("Level"); for _, n in ipairs(lv:ldtk_get_neighbours()) do Log.info(n.dir) end

• level? LdtkLevel|string

Returns LdtkNeighbour[]

LdtkLevelNode:ldtk_level_at(x, y)

The level at a world position (world mode: any loaded level; otherwise looked up in the world layout).

local lv = Scene.find_node("Level"); local id = lv:ldtk_level_at(self.node:get_position())

• x number
• y number

Returns string?

LdtkLevelNode:ldtk_get_worlds()

Lists the project’s worlds.

local lv = Scene.find_node("Level"); for _, w in ipairs(lv:ldtk_get_worlds()) do Log.info(w.identifier) end

Returns LdtkWorld[]

LdtkLevelNode:ldtk_get_world()

Gets the current world identifier.

local lv = Scene.find_node("Level"); local world = lv:ldtk_get_world()

Returns string

LdtkLevelNode:ldtk_set_world(world, level)

Switches world (its first level, or level).

local lv = Scene.find_node("Level"); local ok = lv:ldtk_set_world("Dungeon", "Dungeon_Entrance")

• world string
• level? LdtkLevel|string

Returns boolean ok

LdtkLevelNode:ldtk_set_world_mode(on)

World mode: every level of the world at its world position (rebuilds).

local lv = Scene.find_node("Level"); lv:ldtk_set_world_mode(true)

• on boolean

LdtkLevelNode:ldtk_is_world_mode()

Returns true when world mode is on (every level of the world loaded at its world position).

local lv = Scene.find_node("Level"); if not lv:ldtk_is_world_mode() then lv:ldtk_set_world_mode(true) end

Returns boolean

LdtkLevelNode:ldtk_get_layers(level)

Lists a level’s layers (top first).

local lv = Scene.find_node("Level"); for _, layer in ipairs(lv:ldtk_get_layers()) do Log.info(layer.type) end

• level? LdtkLevel|string

Returns LdtkLayer[]

LdtkLevelNode:ldtk_set_layer_visible(name, visible)

Shows or hides a layer (in every loaded level).

local lv = Scene.find_node("Level"); lv:ldtk_set_layer_visible("Background", false)

• name LdtkLayer|string
• visible boolean

LdtkLevelNode:ldtk_is_layer_visible(name)

Returns whether a layer is currently shown.

local lv = Scene.find_node("Level"); lv:ldtk_set_layer_visible("Fog", not lv:ldtk_is_layer_visible("Fog"))

• name LdtkLayer|string

Returns boolean

LdtkLevelNode:ldtk_get_int_grid(layer, x, y)

Gets the IntGrid value at a world position (0 = empty).

local lv = Scene.find_node("Level"); local v = lv:ldtk_get_int_grid("Collisions", self.node:get_position())

• layer LdtkLayer|string IntGrid layer identifier, e.g. “Collisions”
• x number World X
• y number World Y

Returns integer

LdtkLevelNode:ldtk_get_int_grid_name(layer, x, y)

Gets the identifier of the IntGrid value at a world position (“” if none / unnamed).

local lv = Scene.find_node("Level"); local name = lv:ldtk_get_int_grid_name("Collisions", self.node:get_position())

• layer LdtkLayer|string
• x number
• y number

Returns string

LdtkLevelNode:ldtk_get_int_grid_cell(layer, cx, cy, level)

Gets the IntGrid value of a cell.

local lv = Scene.find_node("Level"); local v = lv:ldtk_get_int_grid_cell("Collisions", 4, 7)

• layer LdtkLayer|string
• cx integer
• cy integer
• level? LdtkLevel|string

Returns integer

LdtkLevelNode:ldtk_get_int_grid_values(layer)

Lists an IntGrid layer’s values (name, colour, collision).

local lv = Scene.find_node("Level"); local values = lv:ldtk_get_int_grid_values("Collisions")

• layer LdtkLayer|string

Returns LdtkIntGridValue[]

LdtkLevelNode:ldtk_world_to_cell(layer, x, y)

World position -> layer cell.

local lv = Scene.find_node("Level"); local cx, cy = lv:ldtk_world_to_cell("Collisions", self.node:get_position())

• layer LdtkLayer|string
• x number
• y number

Returns integer cx, integer cy

LdtkLevelNode:ldtk_cell_to_world(layer, cx, cy, level)

Layer cell -> world position of its centre.

local lv = Scene.find_node("Level"); self.node:set_position(lv:ldtk_cell_to_world("Collisions", 4, 7))

• layer LdtkLayer|string
• cx integer
• cy integer
• level? LdtkLevel|string

Returns number x, number y

LdtkLevelNode:ldtk_get_collision(x, y)

Collision at a world position: “solid”, “one_way”, “trigger” or “none”, plus the layer and value name.

local lv = Scene.find_node("Level"); local kind, layer, value = lv:ldtk_get_collision(self.node:get_position())

• x number
• y number

Returns string type, string? layer, string|integer|nil value

LdtkLevelNode:ldtk_get_triggers()

The trigger areas built from IntGrid values set to Trigger (“_” -> AreaNode). Connect to their “body_entered” / “body_exited” events.

local lv = Scene.find_node("Level"); local spikes = lv:ldtk_get_triggers()["Collisions_spikes"]

Returns table<string, Node>

LdtkLevelNode:ldtk_get_tile(layer, x, y)

Gets the tile of a Tiles/AutoLayer layer at a world position.

local lv = Scene.find_node("Level"); local tile = lv:ldtk_get_tile("Ground", self.node:get_position())

• layer LdtkLayer|string
• x number
• y number

Returns LdtkTile?

LdtkLevelNode:ldtk_get_tile_enums(layer, x, y)

Gets the enum values tagging the tile at a world position (tileset enum tags).

local lv = Scene.find_node("Level"); local tags = lv:ldtk_get_tile_enums("Ground", self.node:get_position())

• layer LdtkLayer|string
• x number
• y number

Returns string[]

LdtkLevelNode:ldtk_get_enum(name)

Gets an enum’s values (colour, tile, index).

local lv = Scene.find_node("Level"); for _, v in ipairs(lv:ldtk_get_enum("ItemType") or {}) do Log.info(v.id) end

• name LdtkEnumName

Returns LdtkEnumValue[]?

LdtkLevelNode:ldtk_get_enums()

Every enum: name -> value ids.

local lv = Scene.find_node("Level"); local item_types = lv:ldtk_get_enums()["ItemType"]

Returns table<string, string[]>

LdtkLevelNode:ldtk_get_entities(identifier)

Lists the loaded levels’ entities, optionally only those with an identifier.

local lv = Scene.find_node("Level"); for _, e in ipairs(lv:ldtk_get_entities("Enemy")) do Log.info(e.iid) end

• identifier? LdtkEntity

Returns LdtkEntity[]

LdtkLevelNode:ldtk_get_entities_by_tag(tag)

Lists the loaded levels’ entities with a tag.

local lv = Scene.find_node("Level"); local pickups = lv:ldtk_get_entities_by_tag("pickup")

• tag string

Returns LdtkEntity[]

LdtkLevelNode:ldtk_get_entity(iid)

Gets an entity anywhere in the project by iid.

local lv = Scene.find_node("Level"); local e = lv:ldtk_get_entity(self.target_iid)

• iid string

Returns LdtkEntity?

LdtkLevelNode:ldtk_get_entity_node(iid)

Gets the node spawned for an entity (by iid).

local lv = Scene.find_node("Level"); local door = lv:ldtk_get_entity_node(self.door_iid)

• iid string

Returns Node?

LdtkLevelNode:ldtk_get_entity_defs()

Lists the project’s entity definitions.

local lv = Scene.find_node("Level"); local defs = lv:ldtk_get_entity_defs(); Log.info(defs[1].identifier)

Returns LdtkEntityDef[]

LdtkLevelNode:ldtk_get_links()

Lists the resolved EntityRef links between spawned entities.

local lv = Scene.find_node("Level"); for _, link in ipairs(lv:ldtk_get_links()) do Log.info(link.field) end

Returns LdtkLink[]

LdtkLevelNode:ldtk_entity()

The LDtk entity this node was spawned from (nil otherwise).

local e = self.node:ldtk_entity(); if e then Log.info(e.identifier) end

Returns LdtkEntity?

LdtkLevelNode:ldtk_level_node()

The LdtkLevelNode that spawned this node.

local level = self.node:ldtk_level_node()

Returns Node?

LdtkLevelNode:ldtk_field(name)

A field of this node’s entity.

self.health = self.node:ldtk_field("health") or 3

• name string

Returns any

LdtkLevelNode:ldtk_ref(field)

The node an EntityRef field points to (the first one for arrays).

local door = self.node:ldtk_ref("target_door"); if door then door:set_visible(false) end

• field string

Returns Node?

LdtkLevelNode:ldtk_refs(field)

Nodes referenced by a field, or every reference ({field, iid, node}) without one.

for _, n in ipairs(self.node:ldtk_refs("lights")) do n:set_visible(true) end

• field? string

Returns Node[]|{field: string, iid: string, node: Node?}[]

LdtkLevelNode:ldtk_referenced_by(field)

Entities whose EntityRef fields point at this one.

for _, r in ipairs(self.node:ldtk_referenced_by("target")) do Log.info(r.field) end

• field? string

Returns {node: Node, field: string}[]

In a scene file

{
  "type": "LdtkLevelNode",
  "name": "LDtkTilemapLevel",
  "position": [
    0,
    0
  ],
  "properties": {
    "enablePhysics": true,
    "spawnEntities": true,
    "parallax": true
  }
}