`tecs.tiled`

Tiled TMX maps and TSX tilesets, loaded by the official Rust tiled crate.

Static atlas tiles draw through 16x16 TileChunks; animated and image-collection tiles use sprite entities. The loader retains tile metadata, object classes and properties, animations, nested layers and infinite-map chunks. Coordinates passed to getTile and setTile are zero-based tile coordinates, including negative coordinates in infinite maps. Tileset indices are one-based, and tile IDs are zero-based within their tileset.

const map = tecs.tiled.load("assets/maps/level.tmx")
tecs.tiled.spawn(world, map)
tecs.tiled.setTile(map, 1, 4, 3, {tileset = 1, id = 7})

registerObject binds an authored object class to game code. Spawned objects belong to the map through ChildOf; snapshots preserve their gameplay state. Tile visuals are derived from map data and rebuilt after a snapshot load.

Module contents

Types

Type	Kind	Description
`Cell`	type	One nonempty tile at zero-based map coordinates.
`Frame`	type	One tile animation frame, with duration in seconds.
`Image`	type	A file-backed image and its authored dimensions.
`Layer`	type	A flattened layer, with inherited group offsets, tint and parallax applied.
`Map`	type	A mutable map.
`Object`	type	An object authored in a map or a tile collision layer.
`ObjectFactory`	type	A callback that spawns a gameplay entity for an authored object class.
`Options`	type	Values accepted by the Tilemap constructor.
`Tile`	type	Metadata attached to a tileset's local tile ID.
`Tilemap`	type	The component value for one map instance.
`TileRef`	type	A reference to one tile, including its Tiled flip flags.
`Tileset`	type	A resolved tileset.
`TileSource`	type	Metadata stored with a rendered tile.

Functions

Function	Kind	Description
`getLayer`	function	Finds a flattened layer by name.
`getTile`	function	Reads a tile at zero-based tile coordinates.
`install`	function	Installs tile projection and animation in the world.
`load`	function	Loads a TMX map and resolves its external TSX files and templates.
`registerObject`	function	Registers how a map object class creates its gameplay entity.
`setTile`	function	Changes one tile and invalidates only that cell in live instances.
`spawn`	function	Spawns a loaded map and installs its projection system.
`tileToWorld`	function	Converts zero-based tile coordinates to their top-left local pixels.
`worldToTile`	function	Converts local map pixels to zero-based tile coordinates.

Values

Value	Kind	Description
`Tilemap`	variable	Loads a map as static TileChunks and animated sprite entities.
`TileSource`	variable	Constructs metadata identifying a tile's authored source.
`TileVisual`	variable	Marks generated map visuals, which are replaced on snapshot restoration.

Types#

`Cell`type#

type Cell = {
    x: integer,
    y: integer,
    tileset: integer,
    id: integer,
    flipH: boolean,
    flipV: boolean,
    flipD: boolean
}

One nonempty tile at zero-based map coordinates.

`Frame`type#

type Frame = {
    id: integer,
    duration: number
}

One tile animation frame, with duration in seconds.

`Image`type#

type Image = {
    path: string,
    width: integer,
    height: integer,
    transparent: {integer}?
}

A file-backed image and its authored dimensions.

`Layer`type#

type Layer = {
    id: integer,
    name: string,
    kind: string,
    visible: boolean,
    x: number,
    y: number,
    parallaxX: number,
    parallaxY: number,
    opacity: number,
    tint: {number},
    properties: {[string]: any},
    cells: {Cell},
    objects: {Object},
    width: integer,
    height: integer,
    image: Image?,
    repeatX: boolean,
    repeatY: boolean
}

A flattened layer, with inherited group offsets, tint and parallax applied.

`Map`type#

type Map = {
    source: string,
    parallaxX: number,
    parallaxY: number,
    width: integer,
    height: integer,
    tileWidth: integer,
    tileHeight: integer,
    infinite: boolean,
    properties: {[string]: any},
    tilesets: {Tileset},
    layers: {Layer},
    revision: integer,
    changes: {[string]: integer}
}

A mutable map. Use setTile to notify every live instance of an edit.

`Object`type#

type Object = {
    id: integer,
    name: string,
    class: string,
    x: number,
    y: number,
    width: number,
    height: number,
    rotation: number,
    visible: boolean,
    opacity: number,
    shape: string,
    points: {{number}},
    text: string,
    properties: {[string]: any},
    tile: {
        source: string,
        name: string,
        id: integer,
        flipH: boolean,
        flipV: boolean,
        flipD: boolean
    }?
}

An object authored in a map or a tile collision layer.

`ObjectFactory`type#

type ObjectFactory = function(exclusive world: World, object: Object): integer

A callback that spawns a gameplay entity for an authored object class.

`Options`type#

type Options = {
    path: string?,
    map: Map?,
    collision: boolean?
}

Values accepted by the Tilemap constructor.

`Tile`type#

type Tile = {
    id: integer,
    class: string,
    properties: {[string]: any},
    image: Image?,
    collision: {Object},
    animation: {Frame},
    rect: {integer}?
}

Metadata attached to a tileset's local tile ID.

`Tilemap`type#

type Tilemap = TilemapValue

The component value for one map instance.

`TileRef`type#

type TileRef = {
    tileset: integer,
    id: integer,
    flipH: boolean?,
    flipV: boolean?,
    flipD: boolean?
}

A reference to one tile, including its Tiled flip flags.

`Tileset`type#

type Tileset = {
    name: string,
    source: string,
    alignment: string,
    tileWidth: integer,
    tileHeight: integer,
    columns: integer,
    count: integer,
    spacing: integer,
    margin: integer,
    x: integer,
    y: integer,
    image: Image?,
    tiles: {Tile},
    properties: {[string]: any}
}

A resolved tileset. Paths already include the TSX file's directory.

`TileSource`type#

type TileSource = TileSourceValue

Metadata stored with a rendered tile.

Functions#

`getLayer`function#

function getLayer(map: Map, name: string): Layer?, integer?

Finds a flattened layer by name.

Arguments

Name	Type	Description
`map`	`Map`	the loaded map
`name`	`string`	the authored layer name

Returns

Type	Description
`Layer?`	the layer and its one-based index, or nil
`integer?`

`getTile`function#

function getTile(map: Map, layer: integer, x: integer, y: integer): Cell?

Reads a tile at zero-based tile coordinates.

Arguments

Name	Type	Description
`map`	`Map`	the loaded map
`layer`	`integer`	the one-based flattened layer index
`x`	`integer`	the tile column
`y`	`integer`	the tile row

Returns

Type	Description
`Cell?`	the tile reference, or nil for an empty cell

`install`function#

function install(exclusive world: World): nil

Installs tile projection and animation in the world.

Arguments

Name	Type	Description
`exclusive world`	`World`	the world receiving maps

Returns

Type	Description
`nil`

`load`function#

function load(path: string): Map

Loads a TMX map and resolves its external TSX files and templates.

Arguments

Name	Type	Description
`path`	`string`	the TMX file path

Returns

Type	Description
`Map`	the editable map

Raises

Type	Condition
`string`	when the library cannot load the map or its orientation is unsupported

`registerObject`function#

function registerObject(class: string, factory: ObjectFactory): nil

Registers how a map object class creates its gameplay entity.

Arguments

Name	Type	Description
`class`	`string`	the Tiled class name
`factory`	`ObjectFactory`	a callback returning a newly spawned entity

Returns

Type	Description
`nil`

`setTile`function#

function setTile(map: Map, layer: integer, x: integer, y: integer, tile: TileRef?): nil

Changes one tile and invalidates only that cell in live instances.

Arguments

Name	Type	Description
`map`	`Map`	the editable map
`layer`	`integer`	the one-based flattened layer index
`x`	`integer`	the zero-based tile column
`y`	`integer`	the zero-based tile row
`tile`	`TileRef?`	the replacement, or nil to clear the cell

Returns

Type	Description
`nil`

Raises

Type	Condition
`string`	when the layer, coordinate, tileset or tile ID is invalid

`spawn`function#

function spawn(exclusive world: World, map: Map, options: Options?): integer

Spawns a loaded map and installs its projection system.

Arguments

Name	Type	Description
`exclusive world`	`World`	the target world
`map`	`Map`	the loaded map
`options`	`Options?`	optional collision settings

Returns

Type	Description
`integer`	the parent map entity

`tileToWorld`function#

function tileToWorld(map: Map, x: integer, y: integer): number, number

Converts zero-based tile coordinates to their top-left local pixels.

Arguments

Name	Type	Description
`map`	`Map`	the map whose grid is used
`x`	`integer`	the tile column
`y`	`integer`	the tile row

Returns

Type	Description
`number`	local horizontal and vertical pixels
`number`

`worldToTile`function#

function worldToTile(map: Map, x: number, y: number): integer, integer

Converts local map pixels to zero-based tile coordinates.

Arguments

Name	Type	Description
`map`	`Map`	the map whose grid is used
`x`	`number`	local horizontal pixels
`y`	`number`	local vertical pixels

Returns

Type	Description
`integer`	the tile column and row
`integer`

Values#

`Tilemap`variable#

const Tilemap: ComponentDefinition<TilemapValue>

Loads a map as static TileChunks and animated sprite entities.

`TileSource`variable#

const TileSource: ComponentDefinition<TileSourceValue>

Constructs metadata identifying a tile's authored source.

`TileVisual`variable#

const TileVisual

Marks generated map visuals, which are replaced on snapshot restoration.

tecs.tiled

Module contents

Types

Functions

Values

Types#

Celltype#

Frametype#

Imagetype#

Layertype#

Maptype#

Objecttype#

ObjectFactorytype#

Optionstype#

Tiletype#

Tilemaptype#

TileReftype#

Tilesettype#

TileSourcetype#

Functions#

getLayerfunction#

Arguments

Returns

getTilefunction#

Arguments

Returns

installfunction#

Arguments

Returns

loadfunction#

Arguments

Returns

Raises

registerObjectfunction#

Arguments

Returns

setTilefunction#

Arguments

Returns

Raises

spawnfunction#

Arguments

Returns

tileToWorldfunction#

Arguments

Returns

worldToTilefunction#

Arguments

Returns

Values#

Tilemapvariable#

TileSourcevariable#

TileVisualvariable#

`tecs.tiled`

`Cell`type#

`Frame`type#

`Image`type#

`Layer`type#

`Map`type#

`Object`type#

`ObjectFactory`type#

`Options`type#

`Tile`type#

`Tilemap`type#

`TileRef`type#

`Tileset`type#

`TileSource`type#

`getLayer`function#

`getTile`function#

`install`function#

`load`function#

`registerObject`function#

`setTile`function#

`spawn`function#

`tileToWorld`function#

`worldToTile`function#

`Tilemap`variable#

`TileSource`variable#

`TileVisual`variable#