Module ldtk

LDtk level importer for Lua and drawing using LÖVE.

Support most LDtk features, and allow easy usage in LÖVE projects. In particular, this mainly focus only on features and values that are useful for showing the final level – this does not try, for example, to expose every internal identfiers or intermediates values that are only relevant for editing.

Currently up-to-date with LDtk 1.1.3.

Every unit is in pixel in the API unless written otherwise. Colors are reprsented as a table {r,g,b} where r,b,g in [0-1].

This modules returns a single function, LDtk(path).

This modules requires json.lua; a copy of it is included with ubiquitousse in the lib directory for simplicity. This module will first try to load a global module named json – so if you use the same json module in your project ubiquitousse will reuse it. If it doesn’t find it, it will then try to load the copy included with ubiquitousse.

Optionally requires LÖVE love.graphics (drawing Image, SpriteBatch, Quad), for drawing only.

Usage:

    local ldtk = require("ubiquitousse.ldtk")

-- load ldtk project file
local project = ldtk("example.ldtk")

-- can define callbacks when loading: for example to setup entities defined in LDtk
local callbacks = {
	onAddEntity = function(entity)
		-- handle entity...
	end
}

-- load every level, with callbacks
for _, lvl in ipairs(project.levels) do lvl:load(callbacks) end

function love.draw()
	-- draw every level
	for _, lvl in ipairs(project.levels) do lvl:draw() end
end

Functions

LDtk (path) Load a LDtk project.

Entity objects

Entity.layer Layer this entity belongs to.
Entity.iid Unique instance identifier for this entity.
Entity.identifier The entity name.
Entity.x X position of the entity relative to the layer, in pixels.
Entity.y Y position of the entity relative to the layer, in pixels.
Entity.width The entity width, in pixels.
Entity.height The entity height, in pixels.
Entity.sx Scale factor on x axis relative to original entity size.
Entity.sy Scale factor on y axis relative to original entity size.
Entity.pivotX The entity pivot point x position relative to the entity, in pixels..
Entity.pivotY The entity pivot point x position relative to the entity, in pixels..
Entity.color Entity color.
Entity.tile Tile associated with the entity, if any.
Entity.tags Tags associated with the entity: can be used either as a list of tags or a map of activated tags tags[name] == true.
Entity.fields Map of CustomFields of the entity.
Entity:draw () Called for the entity when drawing the associated entity layer (you will likely want to redefine it).

Tileset objects

Tileset.image The tileset LÖVE image object.
Tileset.tags Tags associated with the tileset: can be used either as a list of tags or a map of activated tags tags[name] == true.

Layer objects

Layer:draw ([x=0[, y=0]]) Draw the current layer.
Layer.level Level this layer belongs to.
Layer.iid Unique instance identifier for this layer.
Layer.identifier The layer name.
Layer.type Type of layer: IntGrid, Entities, Tiles or AutoLayer.
Layer.visible Whether the layer is visible or not.
Layer.opacity The layer opacity (0-1).
Layer.order The layer order: smaller order means it is on top.
Layer.x X position of the layer relative to the level.
Layer.y Y position of the layer relative to the level.
Layer.gridSize Size of the grid on this layer.
Layer.gridWidth Width of the layer, in grid units.
Layer.gridHeight Height of the layer, in grid units.
Layer.parallaxFactorX Parallax horizontal factor (from -1 to 1, defaults to 0) which affects the scrolling speed of this layer, creating a fake 3D (parallax) effect.
Layer.parallaxFactorY Parallax vertical factor (from -1 to 1, defaults to 0) which affects the scrolling speed of this layer, creating a fake 3D (parallax) effect.
Layer.parallaxScaling If true, a layer with a parallax factor will also be scaled up/down accordingly.
Layer.entities (Entities layer only) List of Entity in the layer.
Layer.tiles (Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) List of Tiles in the layer.
Layer.tileset (Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) Tileset object associated with the layer.
Layer.spritebatch (Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) LÖVE SpriteBatch containing the layer.
Layer.intTiles (IntGrid without AutoLayer rules layer only) list of IntTiles in the layer.

Tile objects

Tile.layer Layer the tile belongs to.
Tile.x X position of the tile relative to the layer, in pixels.
Tile.y Y position of the tile relative to the layer, in pixels.
Tile.flipX Whether the tile is flipped horizontally.
Tile.flipY Whether the tile is flipped vertically.
Tile.tags Tags associated with the tile: can be used either as a list of tags or a map of activated tags tags[name] == true.
Tile.data Custom data associated with the tile, if any.
Tile.quad Quad associated with the tile (relative to the layer’s tileset).

IntTile objects

IntTile.layer Layer the IntTile belongs to.
IntTile.x X position of the IntTile relative to the layer, in pixels.
IntTile.y Y position of the IntTile relative to the layer, in pixels.
IntTile.identifier Name of the IntTile.
IntTile.value Integer value of the IntTile.
IntTile.color Color of the IntTile.

Level objects

Level:draw ([x=0[, y=0]]) Draw this level.
Level:drawBackground ([x=0[, y=0]]) Draw this level background.
Level:load ([callbacks]) Load the level.
Level:unload ([callbacks]) Unload the level.
Level.project Project this level belongs to.
Level.loaded Whether this level is currently loaded or not.
Level.iid Unique instance identifier for this level.
Level.identifier The level name.
Level.depth Depth of the level in the world, to properly stack overlapping levels when drawing.
Level.x The level x position in pixels.
Level.y The level y position in pixels.
Level.width The level width.
Level.height The level height.
Level.fields Map of CustomFields of the level (table).
Level.layers List of Layers in the level (table).
Level.background Level background.

Project objects

Project.levels List of Levels in this project.

CustomFields objects

Type conversion.



Functions

LDtk (path)
Load a LDtk project.

Parameters:

  • path string to LDtk project file (.ldtk)

Returns:

    Project the loaded LDtk project

Entity objects

Entities are regular tables that get processed by Systems.

The idea is that entities should only contain data and no code; it’s the systems that are responsible for the actual processing (but it’s your game, do as you want).

This data is referred to, and organized in, “components”.

Entity.layer
Layer this entity belongs to.

Type:

    Layer
Entity.iid
Unique instance identifier for this entity.

Type:

    string
Entity.identifier
The entity name.

Type:

    string
Entity.x
X position of the entity relative to the layer, in pixels.

Type:

    number
Entity.y
Y position of the entity relative to the layer, in pixels.

Type:

    number
Entity.width
The entity width, in pixels.

Type:

    number
Entity.height
The entity height, in pixels.

Type:

    number
Entity.sx
Scale factor on x axis relative to original entity size.

Type:

    number
Entity.sy
Scale factor on y axis relative to original entity size.

Type:

    number
Entity.pivotX
The entity pivot point x position relative to the entity, in pixels..

Type:

    number
Entity.pivotY
The entity pivot point x position relative to the entity, in pixels..

Type:

    number
Entity.color
Entity color.

Type:

    table {r,g,b} with r,g,b in [0-1]
Entity.tile
Tile associated with the entity, if any. Is a table { tileset = associated tileset object, quad = associated quad }. quad is a LÖVE Quad if LÖVE is available, otherwise a table { x, y, width, height }.

Type:

    table
Entity.tags
Tags associated with the entity: can be used either as a list of tags or a map of activated tags tags[name] == true.

Type:

    {"tag",["tag"]=true,...}
Entity.fields
Map of CustomFields of the entity.

Type:

    CustomFields
Entity:draw ()
Called for the entity when drawing the associated entity layer (you will likely want to redefine it).

By default, this draws the tile associated with the entity if there is one, or a rectangle around the entity position otherwise, assuming we are currently in layer coordinates (i.e. layer top-left is at 0,0).

Requires:

    love

Tileset objects

Tileset object. Stores the image associated with the tileset; can be shared among several layers and levels.
Tileset.image
The tileset LÖVE image object. If LÖVE is not available, this is the path to the image (string).
Tileset.tags
Tags associated with the tileset: can be used either as a list of tags or a map of activated tags tags[name] == true.

Type:

    {"tag",["tag"]=true,...}

Layer objects

Layer object.

Part of a Level.

Layer:draw ([x=0[, y=0]])
Draw the current layer.

Assumes we are currently in level coordinates (i.e. level top-left is at 0,0). You can specify an offset if your level top-left coordinate is not at 0,0 (or to produce other effects).

Requires:

    love

Parameters:

  • x number offset X position to draw the layer at (default 0)
  • y number offset Y position to draw the layer at (default 0)
Layer.level
Level this layer belongs to.

Type:

    Level
Layer.iid
Unique instance identifier for this layer.

Type:

    string
Layer.identifier
The layer name.

Type:

    string
Layer.type
Type of layer: IntGrid, Entities, Tiles or AutoLayer.

Type:

    string
Layer.visible
Whether the layer is visible or not.

Type:

    boolean
Layer.opacity
The layer opacity (0-1).

Type:

    number
Layer.order
The layer order: smaller order means it is on top.

Type:

    number
Layer.x
X position of the layer relative to the level.

Type:

    number
Layer.y
Y position of the layer relative to the level.

Type:

    number
Layer.gridSize
Size of the grid on this layer.

Type:

    number
Layer.gridWidth
Width of the layer, in grid units.

Type:

    number
Layer.gridHeight
Height of the layer, in grid units.

Type:

    number
Layer.parallaxFactorX
Parallax horizontal factor (from -1 to 1, defaults to 0) which affects the scrolling speed of this layer, creating a fake 3D (parallax) effect.

Type:

    number
Layer.parallaxFactorY
Parallax vertical factor (from -1 to 1, defaults to 0) which affects the scrolling speed of this layer, creating a fake 3D (parallax) effect.

Type:

    number
Layer.parallaxScaling
If true, a layer with a parallax factor will also be scaled up/down accordingly.

Type:

    boolean
Layer.entities
(Entities layer only) List of Entity in the layer. Each entity in the list is also bound to its IID in this table, so if ent = entities[1], you can also find it at entities[ent.iid].

Type:

    {Entity,...}
Layer.tiles
(Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) List of Tiles in the layer.

Type:

  • {Tile,...}
  • nil if not applicable
Layer.tileset
(Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) Tileset object associated with the layer.

Type:

  • Tileset
  • nil if not applicable
Layer.spritebatch
(Tiles, AutoLayer, or IntGrid with AutoLayer rules layers only) LÖVE SpriteBatch containing the layer.

Requires:

    love

Type:

  • SpriteBatch
  • nil if LÖVE not available.
Layer.intTiles
(IntGrid without AutoLayer rules layer only) list of IntTiles in the layer.

Type:

  • {IntTile,...}
  • nil if not applicable

Tile objects

Tile object.

This represent the tiles from a Tiles, AutoLayer or IntGrid with AutoLayer rules layer.

Can be retrived from the Layer.tiles list or onAddTile level load callback.

Tile.layer
Layer the tile belongs to.

Type:

    Layer
Tile.x
X position of the tile relative to the layer, in pixels.

Type:

    number
Tile.y
Y position of the tile relative to the layer, in pixels.

Type:

    number
Tile.flipX
Whether the tile is flipped horizontally.

Type:

    boolean
Tile.flipY
Whether the tile is flipped vertically.

Type:

    boolean
Tile.tags
Tags associated with the tile: can be used either as a list of tags or a map of activated tags tags[name] == true.

Type:

    {"tag",["tag"]=true,...}
Tile.data
Custom data associated with the tile, if any.

Type:

    string
Tile.quad
Quad associated with the tile (relative to the layer’s tileset).

Type:

  • LÖVE Quad if LÖVE is available
  • table { x, y, width, height } if LÖVE not available

IntTile objects

IntTile object.

This represent the tiles from a IntGrid without AutoLayer rules layer.

Can be retrived from the intTiles list or onAddIntTile level load callback.

IntTile.layer
Layer the IntTile belongs to.

Type:

    Layer
IntTile.x
X position of the IntTile relative to the layer, in pixels.

Type:

    number
IntTile.y
Y position of the IntTile relative to the layer, in pixels.

Type:

    number
IntTile.identifier
Name of the IntTile.

Type:

    string
IntTile.value
Integer value of the IntTile.

Type:

    number
IntTile.color
Color of the IntTile.

Type:

    table {r,g,b} with r,g,b in [0-1]

Level objects

Level object.

Levels are not automatically loaded in order to not waste ressources if your project is large; so before drawing or operating on a level, you will need to call its Level:load method.

Part of a Project.

Level:draw ([x=0[, y=0]])
Draw this level. Will draw the eventual backgrounds and all the layers in the level.

Assumes we are currently in world coordinates (i.e. world top-left is at 0,0). You can specify an offset if your world top-left coordinate is not at 0,0 (or to produce other effects).

The level must be loaded.

Requires:

    love

Parameters:

  • x number offset X position to draw the level at (default 0)
  • y number offset Y position to draw the level at (default 0)
Level:drawBackground ([x=0[, y=0]])
Draw this level background.

Assumes we are currently in level coordinates (i.e. level top-left is at 0,0). You can specify an offset if your level top-left coordinate is not at 0,0 (or to produce other effects).

The level must be loaded.

Requires:

    love

Parameters:

  • x number offset X position to draw the background at (default 0)
  • y number offset Y position to draw the backgroud at (default 0)
Level:load ([callbacks])
Load the level. Will load every layer in the level and the associated images.

You can optionally specify some callbacks for the loading process:

  • onAddLayer(layer) will be called for every new layer loaded, with the Layer as sole argument
  • onAddTile(tile) will be called for every new tile loaded, with the Tile as sole argument
  • onAddIntTile(tile) will be called for every new IntGrid tile loaded, with the IntTile as sole argument
  • onAddEntity(entity) will be called for every new entity loaded, with the Entity as sole argument

These callbacks should allow you to capture all the important elements needed to use the level, so you can hopefully integrate it into your current game engine easily.

Parameters:

  • callbacks table (optional)
Level:unload ([callbacks])

Unload the level. Images loaded by the level will be freed on the next garbage collection cycle.

You can optionally specify some callbacks for the unloading process:

  • onAddLayer(layer) will be called for every new layer unloaded, with the Layer as sole argument
  • onAddTile(tile) will be called for every new tile unloaded, with the Tile as sole argument
  • onAddIntTile(tile) will be called for every new IntGrid tile unloaded, with the IntTile as sole argument
  • onAddEntity(entity) will be called for every new entity unloaded, with the Entity as sole argument

Parameters:

  • callbacks table (optional)
Level.project
Project this level belongs to.

Type:

    Project
Level.loaded
Whether this level is currently loaded or not.

Type:

    boolean
Level.iid
Unique instance identifier for this level.

Type:

    string
Level.identifier
The level name.

Type:

    string
Level.depth
Depth of the level in the world, to properly stack overlapping levels when drawing. Default is 0, greater means above, lower means below.

Type:

    number
Level.x
The level x position in pixels. For Horizontal and Vertical layouts, is always -1.

Type:

    number
Level.y
The level y position in pixels. For Horizontal and Vertical layouts, is always -1.

Type:

    number
Level.width
The level width.

Type:

    number
Level.height
The level height.

Type:

    number
Level.fields
Map of CustomFields of the level (table).

Type:

    CustomFields
Level.layers
List of Layers in the level (table). Each layer in the list is also bound to its IID in this table, so if lay = layers[1], you can also find it at layers[lay.iid].

Type:

    {Layer,...}
Level.background
Level background.

If there is a background image, background.image contains a table {image=image, x=number, y=number, sx=number, sy=number} where image is the LÖVE image (or image filepath if LÖVE not available) x and y are the top-left position, and sx and sy the horizontal and vertical scale factors.

Fields:

  • color backrgound color {r,g,b} with r,g,b in [0-1]
  • image backrgound image information, if any

Project objects

Project object.

Returned by LDtk.

Project.levels
List of Levels in this project. Each level in the list is also bound to its IID in this table, so if lvl = levels[1], you can also find it at levels[lvl.iid].

Type:

    {Level,...}

CustomFields objects

Custom fields: map of each field name to its value.

LDtk allows to defined custom fields in some places (Entity.fields, Level.fields). This library allows you to access them in a table that map each field name to its value {["fieldName"]=value,…}.

Type conversion.

Here is how the values are converted to Lua values:

  • Integers, Floats are converted into a Lua number.
  • Booleans are converted into a Lua boolean.
  • Strings, Multilines are converted in a Lua string.
  • Enum are converted into a Lua string giving the currently selected enum value.
  • Filepath are converted into a Lua string giving the file path.
  • Arrays are converted into a Lua table with the elements in it as a list.
  • Points are converted into a Lua table with the fields x and y, in pixels: { x=number, y=number }.
  • Colors are converted into a Lua table with the red, green and blue components in [0-1] as a list: {r,g,b}.
  • Tiles are converted into a Lua table { tileset = associated tileset object, quad = associated quad } where quad is a LÖVE Quad if LÖVE is available, otherwise a table { x, y, width, height }.
  • EntityRef are converted into a Lua table { level = level, layerIid = layer IID, entityIid = entity IID, entity = see explanation }. If the entity being refernced belongs to another level and this level is not loaded, entity will be nil; otherwise (same level or the other level is also loaded), it will contain the entity.
generated by LDoc 1.4.6 Last updated 2022-10-13 00:23:58