How body language works
Understand how Body Language directs a Convai character's posture, breathing, and gestures every tick, and how it yields to scripted gestures.
Every tick, ConvaiBodyLanguageController reads the character's dialogue state and emotion, resolves what its behavior should look like right now, and composes that behavior onto the skeleton alongside whatever Body Animation and Gaze are already writing. This page describes what drives that decision, the pieces that produce the motion, and the rule that keeps Body Language from fighting a scripted gesture. For the composition-root model these mechanics build on, see Character embodiment.
What drives the body every tick
In the embodiment Cognition tick, the controller reads the character's current dialogue state and its emotion reading, then resolves the profile's policy for that state — gesticulation intensity, listening lean-in, posture bias, breathing rate and depth, fidget rate. A state change never snaps the policy: values blend over the profile's Policy Transition Seconds so a character does not visibly jolt the instant it starts speaking.
In the later Expression tick, after the Animator or PlayableGraph has posed the skeleton and before Gaze, the controller's solvers spring toward that tick's targets and accumulate every channel — spine, shoulders, pelvis, head-gesture fallback — onto one shared compositor that performs exactly one guarded write per bone. Two Body Language behaviors can never wind up an unbounded delta on the same bone, because there is only ever one writer.
The behaviors that compose onto the body
Internally, ten cooperating pieces each produce one slice of this behavior. None of them are public API — you shape their effect through the profile fields covered in Tune expressiveness and the profile reference, not by calling them directly.
Posture
The sustained openness, lean, and shoulder-tension silhouette for the current state and emotion.
Breathing
The continuous chest and shoulder expansion cycle, plus the catch-breath, sigh, and pre-speech inhale events.
Gesticulation
Head beats and posture pulses timed to speech energy while speaking, and idle hand and wrist micro-motion between gestures.
Listening posture
The lean-in and stillness that engages while the character is listening.
Fidgets
The slow idle weight shift that keeps a still character from reading as frozen.
Stance
The periodic pelvis weight-shift and yaw cycle a standing body performs.
Postural sway
A continuous, sub-degree drift on the spine that reads as constant micro-balancing rather than jitter.
Idle macro-cycle
A very slow, multi-minute drift on breath depth, sway, and fidget cadence so a long idle never settles into a visibly looping baseline.
Reactions
One-shot startle flinches and amused bounces, triggered automatically by a sudden emotion spike or on demand.
Head gestures
Nods, shakes, and tilts, whether from a co-speech beat, a listening tilt-hold, or a scripted request.
A camera-distance scale also runs alongside these behaviors: the further the main camera sits from the character, the larger sway and hand micro-motion read, so a small swing does not disappear at a distance and does not look overplayed in a close-up. It never touches breathing, posture, or gestures — only the ambient texture.
How it shares bones with Gaze and Body Animation
Body Language, Gaze, and Body Animation can all have an interest in the same spine, shoulders, and head. Convai resolves this with coordination rather than one module suppressing another: Gaze's own torso-aim behavior composes through the same shared compositor Body Language writes through, so the two never hold separate write guards that could race on the same bone. When Body Animation plays a walk cycle or a full-body action, it takes the body back for the duration — a deliberate hand-off, not a conflict.
How it yields to scripted gestures
Body Animation's talk-clip system can report a suppression level every tick, and Body Language's entire co-speech system reads it before deciding how much to do:
None (or no performer registered)
Full
Full
Eligible
Full weight
Upper body (an upper-body talk clip or locomotion is playing)
Full
Reduced
Refused
Posture reduced, breathing stays at full weight
Full body (a full-body action or turn is playing)
None
None
Refused
Both fade to zero
This is why the two modules never look like they are fighting: while Body Animation plays an authored upper-body gesture, Body Language keeps the character breathing and keeps its head beats going, but steps back from adding its own posture pulses on top of the same motion. Breathing deliberately never suppresses, even under full suppression's posture and gesture fade — a character that stops breathing while gesturing reads as broken in a way nothing else does.
Next steps
Body language quick startTune expressivenessTroubleshoot body languageLast updated
Was this helpful?