# face

> Talos next · Since 0.7

Keeps a face alive: blinks, eye saccades, brows and cheeks that follow the voice (when the entity also has `lipsync`), and head sway and nods.

Needs an `animator`. Shapes are found by ARKit name (eyeBlinkLeft, eyeLookUpLeft, browInnerUp, cheekSquintLeft, mouthSmileLeft, ...); parts the model has no shapes or bones for are skipped and reported once as `face-degraded`.

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

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `blink` | `number` | no | `17` |  | Blinks per minute, 0 to 60. 0 never blinks. Default 17. |
| `gaze` | `number` | no | `8` |  | Size of the eyes' quick jumps (saccades), in degrees, 0 to 25. 0 keeps the eyes still. Default 8. |
| `expression` | `number` | no | `1` |  | How much the brows and cheeks follow the speech, 0 to 2. 0 leaves them alone. Needs `lipsync` on the same entity to have speech to follow. Default 1. |
| `headMotion` | `number` | no | `1` |  | How much the head sways while idle and nods on stressed beats of speech, 0 to 2. 0 is off. Default 1. |
| `head` | `string` | no |  |  | The bone that sways and nods, by the rig's own name. Default: the last bone of the animator's `lookAt`, else a bone named `head` or `Head`. |
| `eyes` | `string[]` | no |  |  | The two eye bones, [left, right], by the rig's own names; they turn to look. Absent: the model's ARKit `eyeLook*` shapes do it. |
| `seed` | `number` | no |  |  | Seeds the blink and gaze timing, 0 to 4294967295. The same seed always gives the same face. Default: a hash of the entity id, so two copies of one face do not blink in step. |

## Rules that can refuse it

- `face-invalid`
- `lipsync-degraded`
- `ui-default-font`
- `ui-font-face-missing`
- `ui.font.face`
- `ui.font.unusable`