<a id="tecs.tiled"></a>
# `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.

```nupp
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.

## Types

<a id="tecs.tiled.Cell"></a>
### `Cell` _type_

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

One nonempty tile at zero-based map coordinates.

<a id="tecs.tiled.Frame"></a>
### `Frame` _type_

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

One tile animation frame, with duration in seconds.

<a id="tecs.tiled.Image"></a>
### `Image` _type_

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

A file-backed image and its authored dimensions.

<a id="tecs.tiled.Layer"></a>
### `Layer` _type_

```nupp
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.

<a id="tecs.tiled.Map"></a>
### `Map` _type_

```nupp
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.

<a id="tecs.tiled.Object"></a>
### `Object` _type_

```nupp
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.

<a id="tecs.tiled.ObjectFactory"></a>
### `ObjectFactory` _type_

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

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

<a id="tecs.tiled.Options"></a>
### `Options` _type_

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

Values accepted by the Tilemap constructor.

<a id="tecs.tiled.Tile"></a>
### `Tile` _type_

```nupp
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.

<a id="tecs.tiled.Tilemap"></a>
### `Tilemap` _type_

```nupp
type Tilemap = TilemapValue
```

The component value for one map instance.

<a id="tecs.tiled.TileRef"></a>
### `TileRef` _type_

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

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

<a id="tecs.tiled.Tileset"></a>
### `Tileset` _type_

```nupp
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.

<a id="tecs.tiled.TileSource"></a>
### `TileSource` _type_

```nupp
type TileSource = TileSourceValue
```

Metadata stored with a rendered tile.

## Functions

<a id="tecs.tiled.getLayer"></a>
### `getLayer` _function_

```nupp
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?` |  |

<a id="tecs.tiled.getTile"></a>
### `getTile` _function_

```nupp
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 |

<a id="tecs.tiled.install"></a>
### `install` _function_

```nupp
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` |  |

<a id="tecs.tiled.load"></a>
### `load` _function_

```nupp
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

- when the library cannot load the map or its orientation is unsupported

<a id="tecs.tiled.registerObject"></a>
### `registerObject` _function_

```nupp
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` |  |

<a id="tecs.tiled.setTile"></a>
### `setTile` _function_

```nupp
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

- when the layer, coordinate, tileset or tile ID is invalid

<a id="tecs.tiled.spawn"></a>
### `spawn` _function_

```nupp
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 |

<a id="tecs.tiled.tileToWorld"></a>
### `tileToWorld` _function_

```nupp
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` |  |

<a id="tecs.tiled.worldToTile"></a>
### `worldToTile` _function_

```nupp
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

<a id="tecs.tiled.Tilemap"></a>
### `Tilemap` _variable_

```nupp
const Tilemap: ComponentDefinition<TilemapValue>
```

Loads a map as static TileChunks and animated sprite entities.

<a id="tecs.tiled.TileSource"></a>
### `TileSource` _variable_

```nupp
const TileSource: ComponentDefinition<TileSourceValue>
```

Constructs metadata identifying a tile's authored source.

<a id="tecs.tiled.TileVisual"></a>
### `TileVisual` _variable_

```nupp
const TileVisual
```

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