Module `ldtk`

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

Support most LDtk features, and allow easy usage in LÖVE projects.

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).

No mandatory dependency. 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

Entity objects

Entity.layer	Layer this entity belongs to.
Entity.identifier	The entity name.
Entity.x	X position of the entity relative to the layer.
Entity.y	Y position of the entity relative to the layer.
Entity.width	The entity width.
Entity.height	The entity height.
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.
Entity.pivotY	The entity pivot point x position relative to the entity.
Entity.color	Entity color.
Entity.tile	Tile associated with the entity, if any.
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.

Layer objects

Layer:draw ([x=0[, y=0]])	Draw the current layer.
Layer.level	Level this layer belongs to.
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.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.
Tile.y	Y position of the tile relative to the layer.
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.
IntTile.y	Y position of the IntTile relative to the layer.
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.identifier	The level name.
Level.x	The level x position.
Level.y	The level y position.
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.

Functions

LDtk (path)

Load a LDtk project.

Parameters:

path string to LDtk project file (.ldtk)

Returns:

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.identifier

The entity name.

Type:

string

Entity.x

X position of the entity relative to the layer.

Type:

number

Entity.y

Y position of the entity relative to the layer.

Type:

number

Entity.width

The entity width.

Type:

number

Entity.height

The entity height.

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.

Type:

number

Entity.pivotY

The entity pivot point x position relative to the entity.

Type:

number

Entity.color

Entity color.

Type:

table

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.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).

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.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.entities

(Entities layer only) List of Entity in the layer.

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.

Type:

number

Tile.y

Y position of the tile relative to the layer.

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.

Type:

number

IntTile.y

Y position of the IntTile relative to the layer.

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

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.identifier

The level name.

Type:

string

Level.x

The level x position.

Type:

number

Level.y

The level y position.

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).

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.

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: { 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}.

Ubiquitousse

Contents

Modules

Topics

Module ldtk

Usage:

Functions

Parameters:

Returns:

Entity objects

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Requires:

Tileset objects

Layer objects

Requires:

Parameters:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Requires:

Type:

Type:

Tile objects

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

IntTile objects

Type:

Type:

Type:

Type:

Type:

Type:

Level objects

Requires:

Parameters:

Requires:

Parameters:

Parameters:

Parameters:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Type:

Fields:

Project objects

Type:

Module `ldtk`