A simple LDtk loader for LÖVE.
It was tested with LDtk v0.9.3
Place ldtk.lua anywhere in the project and make sure you have json.lua in the same folder.
json.lua is needed because LDtk relies on json.
You can put your tilesets and .ldtk files freely anywhere relative to main.lua.
I recommend turning on "Minify JSON" and "Save levels to separate files" in project settings to save space and increase loading speed.
-- Require the library
local ldtk = require 'path/to/ldtk.lua'
-- Load the .ldtk file
ldtk:load('path/to/file.ldtk')
-- Override the callbacks with your game logic.
function ldtk.onEntity(entity)
-- A new entity is created.
end
function ldtk.onLayer(layer)
-- A new layer is created.
--[[
The "layer" object has a draw function to draw the whole layer.
Used like:
layer:draw()
]]
end
function ldtk.onLevelLoaded(level)
-- Current level is about to be changed.
end
function ldtk.onLevelCreated(level)
-- Current level has changed.
end
-- Flip the loading order if needed.
ldtk:setFlipped(true) --false by default
-- Load a level
ldtk:goTo(2) --loads the second level
ldtk:level('cat') --loads the level named cat
ldtk:next() --loads the next level (or the first if we are in the last)
ldtk:previous() --loads the previous level (or the last if we are in the first)
ldtk:reload() --reloads the current levelCheck main.lua for a detailed example on how to use this library.
callbacks gives you the extracted data from LDtk project file in order.
| name | description | arguments |
|---|---|---|
| onEntity | called when a new entity is created | entity object |
| onLayer | called when a new layer object is created | layer object |
| onLevelLoaded | called just before any other callback when a new level is about to be created | levelData object |
| onLevelCreated | called just after all other callbacks when a new level is created | levelData object |
| property | description | type |
|---|---|---|
| entity | ||
| x | x position | integer |
| y | y position | integer |
| id | the entity name | string |
| width | the width of the entity in pixels | integer |
| height | the height of the entity in pixels | integer |
| visible | whether the entity is visible or not | boolean |
| px | the x pivot of the entity | integer |
| py | the y pivot of the entity | integer |
| order | the order of the entity layer. | integer |
| props | a table containing all custom properties defined in LDtk | table |
| property | description | type |
|---|---|---|
| layer | ||
| x | x position | integer |
| y | y position | integer |
| width | width in tiles | integer |
| height | height in tiles | integer |
| gridSize | size in pixels of each tile | integer |
| tiles | array of tile instances | table |
| intGrid | integer array of grid values. nil if layer is not an IntGrid. | table | nil |
| id | the layer name | string |
| visible | whether the layer is visible or not | boolean |
| order | the order of the entity layer. | integer |
| color | The color of the layer. usually used for opacity. default: {1, 1, 1, 1} (white) | table |
| draw | draws the current layer | function |
| property | description | type |
|---|---|---|
| levelData | ||
| backgroundColor | the background color. {r, g, b} like {0.47, 0.14, 0.83} | table |
| id | the name of the level | string |
| worldX | the level x in the world | integer |
| worldY | the level y in the world | integer |
| width | the width of the level | integer |
| height | the height of the level | integer |
| neighbours | a table containing all nearby levels (ie. levels that touch the current one) | |
| props | a table containing all custom properties defined in LDtk | table |
loads the .ldtk project file.
ldtk:load('path/to/file.ldtk')returns nothing
loads a level by its index starting at 1 as the first level
ldtk:goTo(3) --loads the third levelreturns nothing
loads a level by its id (name)
ldtk:level('menu') --loads the level named menureturns nothing
loads the next level or the first if we are in the last
ldtk:next() --loads the next levelreturns nothing
loads the next level or the last if we are in the first
ldtk:previous() --loads the previous levelreturns nothing
reloads current level
ldtk:reload() --reloads current levelreturns nothing
gets current level index. can be accesed as ldtk.current
ldtk:getCurrent() --gets current level indexreturns integer
gets current level name.
ldtk:getCurrentName() --gets current level namereturns string
gets a level index by its name
ldtk.getIndex('menu') --gets the index of the level named menureturns integer
gets a level name by its index
ldtk.getName(3) --gets the name of the third levelreturns string
removes the cached images and quads. you may use it before loading another .ldtk file
ldtk.removeCache() --remove the cached images and quadsreturns nothing
gets an RGB color (on a scale of 0 to 1) from a HEX color
ldtk.getColorHex('#316f1b') --gets the rgb color of #316f1breturns table (r, g, b) like (0.2, 1, 0.49)
makes the path relative to main.lua instead of the .ldtk file
ldtk.getPath('../tilesets/tiles.png') --gets the the relative path to main.luareturns string
whether to flip the order or not. false by default and can be accessed like ldtk.flipped
ldtk.setFlipped(true) -- flips the order and the top layer will be created lastreturns nothing
gets whether the order is flipped or not. same as ldtk.flipped
ldtk.getFlipped() -- is the order flipped ?returns boolean
Have Fun!