Module ldtk

LDtk level importer for 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.

This modules returns a single function LDtk(path).

Requires LÖVE love.graphics (drawing Image, SpriteBatch, Quad).

Usage:

    local ldtk = require("ubiquitousse.ldtk")

local project = ltdk("example.ldtk")

local callbacks = {
	onAddEntity = function(entity)
		-- handle entity...
	end
}

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

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

Tileset

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.

Layer

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.
Layer.intTiles
(IntGrid without AutoLayer rules layer only) list of IntTiles in the layer.

Tile

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

IntTile

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

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
Entity tile, if any. Is a table { tileset = associated tileset object, quad = associated quad }.
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

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.

Requires:

    love

Parameters:

  • callbacks tab (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 tab (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).

Project

Project object.

Returned by LDtk.

Project.levels
List of Levels in this project.

Module

ubiquitousse.ldtk returns a single function, LDtk.
LDtk (path)
Load a LDtk project.

Parameters:

  • path string to LDtk project file (.ldtk)

Returns:

    Project the loaded LDtk project
generated by LDoc 1.4.6 Last updated 2021-12-24 23:49:41