# tilemap

> Talos next · Since 0.6; changed in next

Use it in a scene entity's `components` list as `{ "type": "tilemap", … }`. The contract writes the fields flat and refuses unknown keys.

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `tileset` | `TilemapTileset` | yes |  |  |  |
| `legend` | `object` | yes |  |  | Which tile each character of the rows draws: one character (not "." or " ", which are empty) to a tile index of the tileset, a whole number from 0, or to an object `{ tile, flipX?, flipY?, rot? }` that draws the tile mirrored and/or turned (rot 0, 90, 180 or 270). A row character that is not a key is `tilemap-tile-unknown`. |
| `layers` | `TilemapLayer[]` | yes |  |  | At least one, at most 16, drawn in `sortLayer` / `order`. Layers may differ in size; all share the entity's origin and `cellSize`. At most 1,048,576 cells over all layers (`tilemap-too-large`). |
| `cellSize` | `Vec2` | no |  |  | [width, height] of one cell in metres, above zero; the entity's scale multiplies it. Default: the tile's pixels at 100 pixels a metre, a sprite's default `pixelsPerMetre` (16 px tiles are 0.16 m). |
| `alphaCutoff` | `number` | no |  |  | 0..1, default 0.5: a tile pixel whose alpha is below it is not drawn. |
| `filter` | `SpriteFilter` | no |  | `nearest`, `linear` | "nearest" (hard pixel edges) or "linear". Absent: the scene's `meta.render.filter`, as for sprites. |
| `lit` | `boolean` | no |  |  | Default false: tiles drawn as painted (unlit), with fog. True: lit by the scene's lights as a surface facing +Z, with the tileset's `normalImage` if it has one. |

## Rules that can refuse it

- `lighting-map-unlit`
- `tilemap-invalid`
- `tilemap-layer-unknown`
- `tilemap-tile-unknown`
- `tilemap-too-large`