Tilemap Component

The Tilemap component loads and renders a Tiled map.

Basic Usage

world:spawn(
    tiled.Tilemap.new({ path = "maps/level1.tmj" }),
    tecs.builtins.Transform.new({ x = 0, y = 0 })
)

Component Properties

Property	Type	Default	Description
path	string	-	Asset path to the .tmj file (sync loading)
data	TilemapData	nil	Pre-loaded tilemap data (from async loading)

Either path or data should be provided:

• path: The component loads the map synchronously on first render. Simple but may cause frame drops.
• data: Use pre-loaded data from loadTiledMap. No loading delay.

Required Components

• Transform - Position in world space. The layer field controls which render layer the tilemap renders to.

Render Layer Mapping

Each Tiled layer renders at an incrementing layer number starting from Transform.layer.

TilemapData Structure

After loading, tilemap.data contains:

record TilemapData
    width: integer           -- Map width in tiles
    height: integer          -- Map height in tiles
    tilewidth: integer       -- Tile width in pixels
    tileheight: integer      -- Tile height in pixels
    layers: {LayerData}      -- Array of layers
    tilesets: {TilesetData}  -- Loaded tilesets
    properties: {string: any} -- Custom properties from Tiled

    -- Methods (see Utility Functions)
    worldToTile(worldX, worldY): integer, integer
    tileToWorld(tileX, tileY): number, number
    getTile(layerIndex, tileX, tileY): integer
    getTileAt(layerIndex, worldX, worldY): integer
    setTile(layerIndex, tileX, tileY, gid)
    setTileAt(layerIndex, worldX, worldY, gid)
    getLayer(name): LayerData
    getLayerProperties(layerIndex): {string: any}
    getTileProperties(layerIndex, tileX, tileY): TileData
    toJSON(pretty): string
end

Chunk Size

Static tiles are rendered using 16×16 TileChunks. This is handled automatically by the tiled plugin.

Parallax Support

Tiled's parallax settings are automatically applied:

• parallax = 1.0: Normal movement (moves with camera)
• parallax = 0.5: Half-speed (appears further away)
• parallax = 0.0: Static (doesn't move with camera)