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

Functions

LDtk (path) Load a LDtk project.

Tileset objects

Tileset.image The tileset LÖVE image object.

Layer objects

Layer:draw () 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 (string).
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.offsetX X position of the layer relative to the level.
Layer.offsetY 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.

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 custom fields of the entity.
Entity:draw () Called for the entity when drawing the associated entity layer (you will likely want to redefine it).

Level objects

Level:draw () Draw this level.
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 (boolean).
Level.identifier The level name (string).
Level.x The level x position (number).
Level.y The level y position (number).
Level.width The level width (number).
Level.height The level height (number).
Level.fields Map of custom fields 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 the loaded LDtk project

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 ()
Draw the current layer. Assumes we are currently in level coordinates (i.e. level top-left is at 0,0).

Requires:

    love
Layer.level
Level this layer belongs to.
Layer.identifier
The layer name.
Layer.type
Type of layer: IntGrid, Entities, Tiles or AutoLayer (string).
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.offsetX
X position of the layer relative to the level.
Layer.offsetY
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. nil if LÖVE not available.

Requires:

    love
Layer.intTiles
(IntGrid without AutoLayer rules layer only) list of IntTiles in the layer.

Tile objects

Tile object.

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

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

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). LÖVE Quad if LÖVE is available, otherwise a table { x, y, width, height }.

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

Entity objects

Entity object.

This represent an entity from an Entities layer.

Can be retrived from the entities list or onAddEntity level load callback.

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. 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 }.
Entity.fields
Map of custom fields of the entity.
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.

Requires:

    love

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 ()
Draw this level. Assumes we are currently in world coordinates (i.e. world top-left is at 0,0). The level must be loaded. Will draw the eventual backgrounds and all the layers in the level.

Requires:

    love
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.
Level.loaded
Whether this level is currently loaded or not (boolean).
Level.identifier
The level name (string).
Level.x
The level x position (number).
Level.y
The level y position (number).
Level.width
The level width (number).
Level.height
The level height (number).
Level.fields
Map of custom fields of the level (table).
Level.layers
List of Layers in the level (table).
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
  • image backrgound image information, if any

Project objects

Project object.

Returned by LDtk.

Project.levels
List of Levels in this project.
generated by LDoc 1.4.6 Last updated 2021-12-25 20:46:24