# sprite

> Talos 0.6 · Since 0.6

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

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `frames` | `SpriteFrame[]` | yes |  |  | Every frame the sprite can show, at least one. Absent an animation, it shows frames[0]. |
| `animations` | `SpriteAnimation[]` | no |  |  |  |
| `animation` | `string` | no |  |  | The animation playing from load, by name (`sprite-frame-missing` when it has none of that name). |
| `pixelsPerMetre` | `number` | no | `100` |  | How many of the pictures' pixels make a metre, above zero; the entity's scale multiplies the result. Default 100. |
| `billboard` | `SpriteBillboard` | no |  | `cylindrical`, `spherical`, `fixed`, `flat` | "cylindrical" (default): turns about the world's up axis to face the camera and stays upright, the classic 2.5D character. "spherical": faces the camera fully, tilting with it (a glow, a particle-like prop). "fixed": does not turn; the picture lies in the entity's XY plane and faces its -Z (a sign, a crossed foliage card). "flat": the 2D sprite; does not turn, lies in the entity's XY plane facing +Z (toward a 2D camera looking down -Z), right along the entity's +X and up its +Y, so a turn about Z turns the picture. Draws views[0] of each frame, and is ordered by `sortLayer` and `order`. |
| `anchor` | `Vec2` | no | `[0` |  | [x, y], each 0..1: the point of every picture that sits on the entity's origin, as a fraction of its width from the left and its height from the top. A view's own `pivot` (pixels) wins. Default [0.5, 1] (the middle of the bottom edge, standing on its origin); [0.5, 0.5] (the centre) for a `flat` sprite. |
| `sortLayer` | `number` | no |  |  | Flat sprites only: the draw layer, -32..32, default 0. A sprite on a higher layer is drawn over one on a lower layer. The engine draws it 1 m nearer +Z per layer (plus `order` / 1024 m), so an orthographic camera looking down -Z shows the order and depth does the rest. |
| `order` | `number` | no |  |  | Flat sprites only: the order within `sortLayer`, -500..500, default 0; higher is drawn over lower. Need not be whole (a top-down game can set it from -y). Two overlapping sprites with the same layer and order have no defined winner: give them different orders. |
| `flipX` | `boolean` | no | `false` |  | Draw every picture flipped left to right about its pivot (a character facing the other way). Combines with a view's `mirror`. Default false; `ctx.sprite.flipX` sets it. |
| `flipY` | `boolean` | no | `false` |  | Draw every picture flipped top to bottom about its pivot. Default false; `ctx.sprite.flipY` sets it. |
| `color` | `string` | no |  |  | `#RRGGBB` (or `#RGB`) tint multiplied into the pictures, as a mesh's `color` is; a room's light level is a grey. A value that is not a hex colour draws untinted with one warning. |
| `opacity` | `number` | no |  |  | 0..1, default 1. Below 1 the sprite is drawn see-through, blended over what is behind it. |
| `alphaCutoff` | `number` | no |  |  | 0..1, default 0.5: a pixel whose alpha is below it is not drawn at all. |
| `filter` | `SpriteFilter` | no |  | `nearest`, `linear` | How the pictures are magnified: "nearest" (hard pixel edges) or "linear" (smooth). Absent: the scene's `meta.render.filter`, so a retro look's nearest filter applies. |
| `lit` | `boolean` | no |  |  | Default false: drawn as painted (unlit), with fog. True: lit by the scene's lights as a surface facing the camera. |
| `visible` | `boolean` | no | `true` |  | Whether the sprite is drawn. Default true. |

## Rules that can refuse it

- `script-call-inapplicable`
- `sprite-frame-missing`
- `sprite-frame-unknown`
- `sprite-image-missing`
- `sprite-invalid`
- `sprite-play-unknown`
- `sprite-rotation-count-invalid`