v0.1

• Setup and Extended Examples
• Accessing Raw LDtk Data
• Global and Helpers
  • translateCoords
• LDtkProject
  • loadFile
  • getAllLevels
  • getLevel
  • getAllTilesets
  • getTileset
  • pushTilesToDisplay
  • getAllEnums
  • getEnum
  • getEnumValue
  • defaultGridSize
  • levelSize
• Layer
  • name
  • gridToIndex
  • getAllTiles
  • pushTilesToDisplay
  • initTileDisplay
  • getIntGridAt
  • indexToCoords
  • indexToCoordsRaw
  • allIndexOfValue
  • allCoordsOfValueRaw
  • allCoordsOfValue
  • appendIntGridToObj
• Level
  • getAllEntities
  • getEntity
  • name
  • position
  • positionRaw
  • size
  • gridSize
  • getLayer
  • getIntGridAtRaw
  • getIntGridAt
• Entity
  • positionRaw
  • position
  • getAllFields
  • getField
  • getFieldValue
• Tile
  • positionRaw
  • position

• No built-in support yet for LDtk layers with auto-layer rules.
• No built-in support for level/world transitions — recommended to manually manage world navigation logic in your game loop.

However all properties are accessible and in combination with convenient helpers, implementations becomes easy. Contributions are welcome!

// Ensure project is loaded
project = new LDtkProject
project.loadFile("res/world.ldtk")

level = project.getLevel("Level_1")
player = level.getEntity("Player")

// Get the layers from Level
collisionLayer = level.getLayer("Collision")
environmentLayer = level.getLayer("Environment")
furnitureLayer = level.getLayer("Furnitures")

// You can also append Int Grid to a map/object and access helper functions that way
house = {}
furnitureLayer.appendIntGridToObj house
house.chairs = house.allCoordsOfValue(1)
house.desks = house.allCoordsOfValue(2)

// Convenient single function to directly send tiles to to display
display(5).mode = displayMode.tile
display(5).tileSet = file.loadImage("/usr/tilesets/environment.png")

environmentLayer.initTileDisplay display(5)
environmentLayer.pushTilesToDisplay display(5)

furnitureLayer.initTileDisplay display(5)
furnitureLayer.pushTilesToDisplay display(5)

// Ex: Bounds checking using IntGrid
isWall = collisionLayer.getIntGridAt(10, 5) == 1

pprint "Player at: " + player.x + ", " + player.y

  // Raw LDtk/JSON data can be found in
  raw = LDtkProject.data

  // Access
  raw.levels[0]
  raw.defs.layers
  raw.defs.entities

  // Also all expected nested data exists in every get methods
  firstLevel = raw.getLevel("Level_1")
  enemies = firstLevel.getLayer("Enemies")

  firstLevel.worldX
  firstLevel.__bgColor

  enemies.__opacity
  enemies.visible
  enemies.optionalRules
    

Converts a coordinate map between LDtk (top-down) and MiniMicro/Cartesian (bottom-up) systems.

• coords: A coordinate map containing {x, y}
• levelHeight: The height of the level in pixels

A new {x, y} map with Y-axis flipped or adjusted.

ldtkPos = {"x": 100, "y": 120}
worldPos = translateCoords(ldtkPos, 240)

This is helpful for placing objects correctly when LDtk and your minimicro disagree on coordinate orientation.

Loads an LDtk file from the given directory. supersimple not yet implemented.

project = new LDtkProject
project.loadFile("game/levels.ldtk", true)

Returns a list of all levels.

for level in project.getAllLevels
  pprint level.name
end

Returns a level by its identifier, iid, or uid.

level = project.getLevel("Level_1")

Returns all tilesets.

Returns a tileset by identifier or UID.

Convenient global helper. Grabs the specified level and layer, then calls pushTilesToDisplay.

project.pushTilesToDisplay("Sample", "Environment", TILE_DISP)

Returns all enum definitions.

Returns enum by name or UID.

Returns a specific enum value by its ID and enum name or UID.

Returns the project's default grid size.

Returns size of the specified level.

size = project.levelSize("Level_1")
ppprint [size.width, size.height]

Returns the name of the layer.

pprint layer.name --> "Collision"

Converts grid coordinates (x, y) into a 1D array index.

index = layer.gridToIndex(3, 5)

Returns a list of all tiles in the layer.

for tile in layer.getAllTiles
  x = tile.x
  y = tile.y
  id = tile.tileId
end

Pushes all the tiles from this layer to a given TileDisplay.

layer = level.getLayer("Environment")
layer.pushTilesToDisplay(TILE_DISP)

The target disp must be a valid TileDisplay and an image tileset must be loaded.

Initializes a TileDisplay to match the tile size of this LDtk layer.

This is a convenient helper for setting up a MiniMicro TileDisplay with the correct tileSetTileSize and cellSize based on the LDtk layer's grid size.

Returns the int grid value at the specified (x, y) position.

if layer.getIntGridAt(10, 12) == 1 then
  pprint "Wall here!"
end

Returns flipped Y coordinates suitable for cartesian or MiniMicro (bottom-left origin).

coords = layer.indexToCoords(42)  // {x: 10, y: 11}

Returns the raw LDtk-style coordinates (top-left origin) for an IntGrid cell index.

coords = layer.indexToCoordsRaw(42)  // {x: 10, y: 4}

Returns a list of all indices in the IntGrid where the cell equals the specified value.

indices = layer.allIndexOfValue(3)  // [5, 20, 33, 87, ...]

Returns all raw LDtk-style coordinates where the IntGrid cell equals value.

coords = layer.allCoordsOfValueRaw(1)
// [{x: 3, y: 2}, {x: 10, y: 6}, ...]

Returns all flipped/cartesian-style coordinates where the IntGrid cell equals value.

coords = layer.allCoordsOfValue(2)
// [{x: 1, y: 13}, {x: 8, y: 7}, ...]

Appends the layer’s IntGrid data and helper methods to a separate object.

This is useful when you want to extract a layer’s IntGrid logic for sandboxing or transformations.

obj = {}
layer.appendIntGridToObj(obj)

val = obj.at(5, 3)
coords = obj.allCoordsOfValue(2)

The object will get a copy of the IntGrid CSV and a copy of the helper functions.

All helper functions appended:

obj.indexToCoords(index)
obj.indexToCoordsRaw(index)
obj.at(x, y)        // alias of getIntGridAt (MiniMicro)
obj.atRaw(x, y)     // alias of getIntGridAtRaw
obj.allIndexOfValue(value)
obj.allCoordsOfValue(value)
obj.allCoordsOfValueRaw(value)

Returns all entities in the level.

for ent in level.getAllEntities
  pprint ent.identifier
  pprint [ent.x, ent.y]
end

Returns the first matching entity by identifier or iid.

player = level.getEntity("Player")

Returns the level name.

pprint level.name --> "Level_1"

Returns the level's position in Cartesian/MiniMicro coordinates, where Y increases upward.

This is useful for rendering in environments where the origin is bottom-left, such as MiniMicro.

pos = level.position
print(pos.x, pos.y)

Internally, this subtracts the LDtk Y-coordinate from the level height.

Returns the level's raw LDtk position, exactly as it appears in the .ldtk file. In LDtk, the origin is top-left.

rawPos = level.positionRaw
print(rawPos.x, rawPos.y)

Use this if you need to work in screen-space or match LDtk’s layout directly.

Returns the size of the level in pixels.

sz = level.size
// output: {sz.width, sz.height}

Returns the grid dimensions of the level.

grid = level.gridSize 
// output: {"width": 20, "height": 30}

Returns a specific layer by its identifier or iid.

collision = level.getLayer("Collision")

Returns the int grid value at (x, y) for the specified layer. (Top-left origin, same as LDtk)

if level.getIntGridAt("Collision", 5, 5) > 0 then
  pprint("Blocked!")
end

Returns the int grid value at (x, y) for the specified layer. (Uses bottom-left origin same as MiniMicro Tiles)

if level.getIntGridAt("Collision", 5, 5) > 0 then
  pprint("Blocked!")
end

Returns the raw position of the entity, as stored in LDtk. This reflects the pixel position from the top-left corner (LDtk screen space).

pos = entity.positionRaw
pprint pos
// output: {x: int, y: int}

Use this when working directly with LDtk's coordinate space or tile-aligned rendering.

Returns the converted position of the entity in Cartesian or MiniMicro coordinates, where the Y-axis increases upwards.

This uses translateCoords internally and requires the entity’s levelHeight to be defined (automatically set when parsing through levels).

pos = entity.position
pprint pos
// output: {x: int, y: int}

Returns a list of all field instances on this entity.

fields = entity.getAllFields
for field in fields
    pprint field.__identifier
    pprint field.__value
end for

> Each field instance is a map with metadata like `__identifier`, `__type`, and `__value`.

Returns the raw field object matching the given field name (identifier). You can optionally pass the defuid if needed to disambiguate multiple field definitions with the same name.

field = entity.getField("Speed")
field.__type
field.__value

Returns only the value of the field.

speed = entity.getFieldValue("Speed")
pprint("Speed is: " + speed)

Returns the raw position of the tile in pixels, based on LDtk's coordinate system (top-left origin).

pos = tile.positionRaw
// output: pos = {"x": 0, "y": 0}

Use this for working with LDtk-native layouts or matching tiles directly to visual assets.

Returns the converted position of the tile in Cartesian/MiniMicro coordinates, where Y increases upward.

pos = tile.position
// output: pos = {"x": 0, "y": 0}

Internally uses translateCoords() and the tile’s associated level height to flip the Y-axis appropriately.

These methods are useful when drawing or calculating logic for tiles in engines that use bottom-left origins (like MiniMicro), or when transforming LDtk data for grid-based gameplay systems.

• iid refers to instance ID (unique per level/layer/entity).
• uid refers to unique ID used by LDtk internally.