move-head-and-neck

name	move-head-and-neck
description	Turns, tilts, and nods the head/neck so the character looks in a direction or at something, nods yes, shakes no, tilts curiously, or cranes up/down. Use whenever a command mentions head, neck, look/looking/glance, turn your head, face toward, nod, shake your head, tilt your head, look up/down/left/right, or watch something.
category	head
disable-model-invocation	true

move-head-and-neck

Atomic primitive for the Neck and Head joints. Both are world-aligned at rest ([0,0,0]): local +X = world +X (the character's right), +Y = up, +Z = forward (its facing direction). Angles are ABSOLUTE local euler [x,y,z] deg, XYZ.

Split the motion across BOTH joints for a natural curve — roughly half on Neck, half on Head (the totals below are Neck+Head combined).

Axes (world result, since the head is world-aligned)

• Turn / yaw (look left ↔ right): Y axis. POSITIVE Y turns the gaze toward +X = its right; NEGATIVE Y looks left. A full glance ≈ ±60–80° total.
• Nod / pitch (look down ↔ up): X axis. POSITIVE X drops the chin to look down; NEGATIVE X tips the head back to look up. Range ≈ ±50°.
• Tilt / roll (ear toward shoulder): Z axis. POSITIVE Z tilts the top of the head toward its left; NEGATIVE Z toward its right. Range ≈ ±35°.

Recipes

• Look right: Neck:[0,30,0], Head:[0,30,0] (≈60° right). Look left: negate Y.
• Look up: Neck:[-20,0,0], Head:[-20,0,0]. Look down: positive X.
• Tilt head (curious): Head:[0,0,18].
• Nod "yes": a sequence rocking X between up and down (e.g. Head X -15 → 15 → -15), loop:2.
• Shake "no": a sequence rocking Y left↔right (Head Y -25 → 25), loop:2.
• Look AT a point/place: prefer the Action's top-level lookAt:[x,y,z] (a WORLD point) so the engine aims the gaze; combine with a Y turn if it's far to the side. Locations come from state.locations.

Worked Actions

• "look to your left" → {"durationMs":600,"pose":{"Neck":[0,-30,0],"Head":[0,-30,0]},"say":"Looking left."}
• "look up at the ceiling" → {"durationMs":600,"pose":{"Neck":[-25,0,0],"Head":[-20,0,0]}}
• "nod your head" → {"durationMs":1200,"say":"Mhm.","sequence":{"loop":2,"frames":[{"t":0,"pose":{"Head":[-12,0,0],"Neck":[-6,0,0]}},{"t":0.5,"pose":{"Head":[15,0,0],"Neck":[8,0,0]}},{"t":1,"pose":{"Head":[-12,0,0],"Neck":[-6,0,0]}}]}}

Limits

Keep neck rotation gentle (total yaw within ~|80|, pitch ~|55|, tilt ~|35|) — the head should never spin unnaturally. To turn the WHOLE body to face a new direction, use turn-and-face instead. Emit only Neck/Head here.