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.

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

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

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

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

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.offsetX
X position of the layer relative to the level.

Type:

    number
Layer.offsetY
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 {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 ()
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.

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}.
generated by LDoc 1.4.6 Last updated 2021-12-26 18:43:30