# attach

> Talos next · Since 0.7; changed in next

Follows a bone of another entity's animated skeleton (a held prop; with a trigger collider, a sensor reporting `overlap` events): world = owner * bone * (position, rotation), after the owner's animator samples each tick.

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

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `to` | `string` | yes |  |  | The entity whose animator's skeleton carries this one. It needs an `animator` component. |
| `bone` | `string` | no |  |  | A bone of that skeleton, by the rig's own name (for a rig that is retargeted, the canonical name from `retarget.map` also works). Resolved once when the scene loads: a name the rig does not have is reported as `attach-bone-unknown` and the entity stays where it is. Give this or `socket`, not both (`attach-bone-or-socket`). |
| `socket` | `GripSocket` | no |  | `rightHandGrip`, `leftHandGrip`, `rightForearmShield`, `leftForearmShield` | A grip socket instead of a bone: the place and turn a held prop takes on the canonical humanoid, carried onto this rig through the owner's `retarget.map` (or, with no map, by the rig's canonical bone names). Then no frame is worked out from the rig's bones, and a rig whose bones are rolled differently holds the prop the same. `position` and `rotation` are an offset in the socket's frame. A rig the socket cannot be read on is reported at load as `attach-socket-unavailable`. |
| `position` | `Vec3` | no | `[0,0,0]` |  | Offset from the bone (or the socket), metres, in its frame. Default [0, 0, 0]. |
| `rotation` | `Quat` | no | `identity` |  | Turn relative to the bone (or the socket), a quaternion [x, y, z, w] in its frame. Default identity. |
| `activeWhile` | `string` | no |  |  | For a sensor (a trigger collider on this entity): query only while the owner's animator has its window of this name open (an animator `events` entry with `until`). |

## Rules that can refuse it

- `attach-bone-or-socket`
- `attach-bone-unknown`
- `attach-owner-missing`
- `attach-owner-no-animator`
- `attach-skeleton-missing`
- `attach-socket-unavailable`
- `script-module-state`