TilemapLdtkParser

View source
ceramic.TilemapLdtkParser (Class)

Parser that converts LDtk level data into Ceramic tilemap data structures.

This class handles:

  • Parsing raw LDtk JSON data
  • Converting LDtk tilesets to Ceramic tilesets with proper GID mapping
  • Converting LDtk layers (Tiles, IntGrid, AutoLayer, Entities) to tilemap layers
  • Loading external level data for multi-file projects
  • Optimizing tile stacking for rendering performance

The parser maintains compatibility between LDtk's tile ID system and Ceramic's global tile ID (GID) system.

See: LdtkData, Tilemap

Static Members

ldtk
refreshAutoLayerData(layerInstance: LdtkLayerInstance, ?skipEmptyTiles: Bool = true): Void

Rebuilds the TilemapLayerData of an auto layer after its autoLayerTiles or IntGrid changed (see LdtkRuleRunner). Visuals displaying this data must then be marked dirty.

Name Type Default
layerInstance LdtkLayerInstance
skipEmptyTiles Bool true

Instance Members

ldtk
skipEmptyTiles: Bool

When true (default), tiles whose pixels are all fully transparent are not converted at all: they render nothing, so dropping them saves geometry and keeps them from taking a stacking slot. Requires tileset pixels to have been read (see computeTilesetsPixelData()), otherwise no tile is considered empty. Set to false if a project relies on invisible tiles as data markers.

ldtk
parseLdtk(rawLdtkData: String, loadExternalLdtkLevelData: Function): LdtkData

Parses raw LDtk JSON data into an LdtkData structure.

Name Type Description
rawLdtkData String The raw JSON string from an LDtk project file
loadExternalLdtkLevelData Function Callback to load external level files (for multi-file projects)
Returns Description
LdtkData The parsed LdtkData object, or null if parsing fails
ldtk
loadLdtkTilemaps(ldtkData: LdtkData, ?loadTexture: Function, skip: Array<String>): Void

Loads and converts all tilesets and tilemaps from LDtk data.

This method:

  • Converts LDtk tilesets to Ceramic tilesets with proper GID assignment
  • Loads tileset textures through the provided callback
  • Creates tilemap data for all levels (if not using external levels)
Name Type Default Description
ldtkData LdtkData The parsed LDtk data
loadTexture Function (optional) Optional callback to load tileset textures
skip Array<String> Array of texture paths to skip loading
ldtk
loadLdtkLevelTilemaps(ldtkData: LdtkData): Void

Builds the tilemap data of every level.

Meant to run once tileset textures are loaded and computeTilesetsPixelData() has succeeded, so that tile filtering can rely on actual pixels.

Name Type Description
ldtkData LdtkData The parsed LDtk data
ldtk
computeTilesetsPixelData(ldtkData: LdtkData): Bool

Reads back each tileset texture once and records, per tile, whether it is fully transparent or fully opaque. Results are cached on LdtkTilesetDefinition, which survives level unload/reload, so this runs once per asset load.

The cache is refreshed when a tileset texture is hot reloaded, so later conversions see the new image. Already converted levels keep their tiles until they are converted again: unloading them here would destroy tilemap data a displayed Tilemap may still use.

Tilesets without a texture (skipped, or no image) are left unknown. When the backend can't read pixels back, nothing is computed and no tile gets filtered. Otherwise a failed read is a failed asset load.

Name Type Description
ldtkData LdtkData The parsed LDtk data, with tileset textures loaded
Returns Description
Bool false if a texture that should be readable could not be read
ldtk
loadLdtkLevelTilemap(level: LdtkLevel): Void

Converts an LDtk level into Ceramic tilemap data.

This method:

  • Creates TilemapData with level properties
  • Converts each layer instance to TilemapLayerData
  • Handles different layer types (Tiles, IntGrid, AutoLayer, Entities)
  • Optimizes tile stacking and alpha blending

The resulting tilemap data is stored in level.ceramicTilemap.

Name Type Description
level LdtkLevel The LDtk level to convert
ldtk
new(): Void

Private Members

ldtk
sameTileFlags(a: haxe.ds.Vector<Bool>, b: haxe.ds.Vector<Bool>): Bool
Name Type
a haxe.ds.Vector<Bool>
b haxe.ds.Vector<Bool>
Returns
Bool
ldtk
resolveAutoSourceLayer(level: LdtkLevel, layerInstance: LdtkLayerInstance): LdtkLayerInstance
Name Type
level LdtkLevel
layerInstance LdtkLayerInstance
Returns
LdtkLayerInstance
ldtk
fillAutoLayerData(level: LdtkLevel, layerInstance: LdtkLayerInstance, tilemapLayerData: TilemapLayerData, skipEmptyTiles: Bool): Void

Fills the tiles of an auto layer's TilemapLayerData from the IntGrid of its source layer and from its current autoLayerTiles.

Name Type
level LdtkLevel
layerInstance LdtkLayerInstance
tilemapLayerData TilemapLayerData
skipEmptyTiles Bool
ldtk
convertLdtkTiles(ldtkTiles: Array<Int>, tileset: LdtkTilesetDefinition, cols: Int, rows: Int, gridSize: Int, tilesAlpha: Array<Float>, tilesOffsetX: Array<Int>, tilesOffsetY: Array<Int>, skipEmptyTiles: Bool): Array<TilemapTile>

Converts LDtk tile data to Ceramic tilemap tiles.

LDtk stores tiles as flat arrays with [tileId, flipBits, x, y, srcX, srcY, alpha] for each tile. This method converts that to Ceramic's TilemapTile format.

Special handling:

  • Stacks multiple tiles at the same position
  • Optimizes opaque tiles by removing hidden tiles beneath
  • Preserves tile offsets and alpha values
Name Type Description
ldtkTiles Array<Int> Raw tile data from LDtk (7 integers per tile)
tileset LdtkTilesetDefinition The tileset definition for GID mapping
cols Int Number of columns in the layer
rows Int Number of rows in the layer
gridSize Int The grid cell size in pixels
tilesAlpha Array<Float> Output array for tile alpha values
tilesOffsetX Array<Int> Output array for tile X offsets
tilesOffsetY Array<Int> Output array for tile Y offsets
skipEmptyTiles Bool
Returns Description
Array<TilemapTile> Array of TilemapTile objects, or null if no tiles
ldtk
readTilesetPixelData(ldtkTileset: LdtkTilesetDefinition, texture: Texture): Bool

Reads the pixels of one tileset texture and fills emptyTiles and opaqueTilesFromPixels of its definition.

Name Type Description
ldtkTileset LdtkTilesetDefinition The tileset definition to fill
texture Texture Its loaded texture
Returns Description
Bool false if pixels could not be read