The Resolver¶

How every driver's work becomes one face, and how a character's hands stay where the animation put them.

The FaceCue Resolver turns every driver's work into one face. Each driver says what it wants the face to do, and the resolver decides how much of each shows. If you ask it to, it also keeps the character's hands where the animation put them. The OneClick Wizard adds it with the first driver, where it is listed as Face Output.

Its inspector has two titles, one per job: Composition and IK Compensation. Most characters never need either touched.

How the Face Is Shared¶

Several drivers can want the same blendshape at the same moment. Speech opens the jaw for a vowel while an emotion is holding the mouth in a frown.

The resolver shares the face out by region: the lower face, meaning the mouth and jaw, the mid face, meaning the cheeks and the sides of the face, and the upper face, meaning the brow and lids.

On the lower face the words come first. Where speech and an emotion want the same mouth blendshape, speech keeps most of it and the emotion makes room. On the blendshapes speech is not using, the emotion keeps all of it, so a smile survives the phonemes that do not need the corners of the mouth. Higher on the face, the drivers play together.

Emotion and Speech on the Mouth¶

The shipped emotions are authored to sit well on a speaking face, so most of them need nothing here. A few with a strong mouth, Angry the clearest, can still crowd the words, and the Emotion Channel page lists the ways to settle one: When the Character Speaks.

The one you set on the resolver is Lower Scope, under Composition in its Blend Usage section.

Per Shape, the default, decides each mouth blendshape on its own. An emotion only gives way on the blendshapes speech is driving at that moment, and keeps the rest.
Per Region treats the lower face as one piece. While the character is speaking, the emotion eases back across the whole mouth, including blendshapes speech never touches. It comes back gently once the line has ended, after a short wait in case the next line follows.

Per Region is the coarser of the two. It is the quickest fix for an emotion that fights the words, and it suits a rig nobody has had time to tune, at the cost of losing the emotion's mouth for the whole line rather than only where the two collide. Per Shape keeps more of the emotion visible and is the one to aim for once the expressions are tuned.

The mid and upper regions have the same switch at the Expert tier. The expressions there are meant to play together, and there is rarely a reason to change them.

IK Compensation¶

A look that turns the head and chest turns the shoulders with them, and the arm carries a placed hand off its mark. A hand resting on a table slides across it, a hand on a railing lets go of it, and a hand holding a prop moves the prop.

IK Compensation keeps the hand where the animation put it. It undoes only FaceCue's pull on the arm, from the look, the breath and the small sway, so the animation, root motion and any other IK on the arm are left as they were. A hand the animation moves is followed, not frozen in place.

Still Early

This has had less testing than the rest of FaceCue. It works, and it stays off until you switch it on, but check what it does to a hand on your own rig before you rely on it in a scene. The inspector marks it Experimental, and its help says the same.

Setting It Up¶

Set Mode to Enabled. Nothing is captured or corrected while it is Disabled, and Disabled is the default.
Fill in the arms. Under Setup, Source says how.
- Humanoid reads both arms from the character's humanoid avatar. Press Auto Setup and the Left Hand and Right Hand groups are filled in.
- Manual is for a rig without a humanoid avatar. Assign the hand bone in each group, then press Auto Setup, or Fill Chain From Hand inside the group, and the arm above that hand is filled in.
The brain's Auto Setup Character runs this step too, so a character set up there usually has its arms filled already. 3. Raise each hand's Weight. Every hand starts at 0, and a hand at 0 is not held. This is the step that is easy to miss, because the setup above looks finished without it. At 1 the hand is held exactly where the animation put it. In between, it follows part of the body's turn. 4. Check Status under Internal State. It reads Idle, 0 active when nothing is held, and Active, 2/2 pinned once both hands are.

A Hand's Settings¶

Each of the Left Hand and Right Hand groups holds one hand.

Enabled holds this hand. Turn it off to leave the hand to another system, such as Unity's Animation Rigging or an IK package of your own, without losing the arm you set up here.
Hand is the bone that is put back.
Weight is how firmly it is held, from 0 to 1.
Pin Rotation, on by default, puts the hand back at the angle the animation gave it as well as in the right place. It matters wherever the hand grips something and the angle has to read.

Holding Something That Is Not a Hand¶

Additional Effectors holds anything else that should stay where the animation put it, in exactly the way a hand is held. It is not limited to hands and there is no fixed number of them.

Each one is three things: the Effector, the transform that must stay put, its Chain Joints, the bones above it that may bend to keep it there, and its Weight, how firmly.

A hand group holds the hand and nothing else. Every joint above it, the elbow included, is what bends to keep that hand in place, so an arm you have already set up protects exactly one point on it. Anything else that touches the world needs saying.

A worked example. A character rests both forearms on a table, hands open and free, and looks across the room. The look turns the chest, the chest carries the shoulders, and the forearms slide across the table, the hands going with them because nothing holds them. Press Add Effector, assign a forearm as the effector, press Fill Chain From Hand to work out the bones above it, raise Weight to 1, and turn on Pin Rotation so the forearm keeps its angle on the surface as well as its place. Repeat for the other side, and leave both hand groups off, since the hands are not the part touching anything.

Others worth an effector: a limb the hand groups cannot describe, such as a creature's foreleg or a braced wing, and on a rig whose body bones reach the hips, a foot planted on a rung or a step. Hold one point per limb, since pinning a hand and its own forearm sets two holds against the same bones. Most characters need none of this.

Holding a Hand From Code¶

A hand usually only needs holding for part of a scene: while it rests on the table, not while it reaches for the cup. Set its weight from a script at those moments, and ramp it rather than jumping, so the hand lets go smoothly instead of popping. The calls are on the FaceCue Resolver:

public void SetEffectorWeight(HandSide side, float weight)
public bool SetEffectorWeight(Transform effector, float weight)
public void AddEffector(Transform hand, float weight = 0f)

Member	What it does
`void SetEffectorWeight(HandSide side, float weight)`	How firmly the left or right hand group holds, from 0 to 1
`bool SetEffectorWeight(Transform effector, float weight)`	The same for an effector you declared under Additional Effectors, named by its Transform. False when that Transform is not a declared effector
`void AddEffector(Transform hand, float weight = 0f)`	Declares a new effector at runtime, and fills its chain the way Fill Chain From Hand does. It starts at the weight you give, off if you leave it out. Calling it again for one already declared only changes its weight

using Firecrest.Systems.FaceCue;
using UnityEngine;

public class HoldHandOnTable : MonoBehaviour
{
    [SerializeField] FaceCueResolver resolver;
    [SerializeField] float blendSeconds = 0.25f;

    float _weight;
    bool _holding;

    public void Hold(bool holding) => _holding = holding;

    void Update()
    {
        _weight = Mathf.MoveTowards(_weight, _holding ? 1f : 0f, Time.deltaTime / blendSeconds);
        resolver.SetEffectorWeight(HandSide.Right, _weight);
    }
}

When a Group Warns¶

Each group checks its arm and says so in place.

The chain needs at least two joints. The arm was not filled in. Press Fill Chain From Hand.
A joint is a bone the gaze turns. The arm reaches too high, into the spine or neck bones the Eyes driver turns to look. An arm that includes one would undo the very turn it is compensating for. The arm should start just below those bones, which is where Fill Chain From Hand starts it.

How the Arm Bends¶

Putting a hand back means bending the arm above it, and an arm can reach the same spot in more than one way. The shoulder can help or stay out of it, and the elbow can fold the way the animation had it or find a shape of its own. Solver Mode, under Solver Settings, decides which, and the difference shows most when a look turns the body a long way.

Adaptive¶

The arm does whatever the moment needs, and it is the one to start from. When the body's turn brings the shoulder closer to where the hand is held, the arm has slack to take up, so it folds at the elbow the way the animation bent it. When the turn pulls the shoulder away, the arm has to reach, so the stretch is shared along the whole arm and the shoulder comes forward to help. Each hand decides for itself, and a hand that changes from folding to reaching glides across rather than switching in a frame.

Picture a character seated at a desk with the right hand resting on it, looking left and then right. Looking left brings the right shoulder toward the desk, and the elbow folds in. Looking right draws that shoulder back, and the arm stretches out to keep the hand where it was. One setting gives two different arms, and both read as the same person.

Swivel¶

The arm always folds at the elbow, keeps the elbow turned the way the animation had it, and never moves the shoulder. The shoulder stays wherever the chest carries it, and the upper arm and forearm do all the work.

Pick it when a moving shoulder would read wrong. A hand resting on a hip or a belt, a hand on a sword at the hip, a character standing to attention: in each of these a shoulder that rose or rolled forward to help would read as a shrug. The price is reach. With the shoulder kept out of it, a hand held far from the body runs out of arm sooner, and Reaching Too Far takes over earlier than it would under the other two.

FABRIK¶

The correction is always shared along the whole arm, the shoulder included. It is the most relaxed way to reach: the arm stretches the way an arm does, and it reaches the furthest of the three, because the shoulder can travel too.

What it gives up is the elbow. The arm finds its own shape rather than keeping the animation's, so a hand pulled in close can fold with the elbow somewhere the animation never put it. Pick it for a character that mostly reaches, a hand held on a high shelf or planted across a wide table, where the look keeps drawing the shoulder away. It takes no notice of Swivel Reference, below.

Where the Elbow Points¶

With the hand held still, the elbow could sit anywhere on a circle around the line from the shoulder to the hand, and the hand would not move. The animation chose a place on that circle, and FaceCue keeps the elbow on that side of the arm when it puts the hand back, however the arm happens to point. Swivel Reference decides what the elbow holds its place against while the body moves under the arm: the world around the character, or the character's own chest. It matters wherever the animation's elbow is kept, which is under Swivel and under Adaptive while a hand folds.

World Down¶

The elbow holds its place in the world. When a look turns or leans the chest, the elbows stay where the animation put them and move only as much as the arm has to, which is what an upright body does. Leave it here for a character standing, sitting or leaning on something.

Torso Relative¶

The elbow turns with the character's own chest, so when the chest leans or rolls, the elbows go with it.

It is the one for a body that is not upright: a character lying down, crawling, or leaning far over, where the room around them is a poor guide to where an elbow belongs. On a character lying on their side, the chest still knows, and the arm reads as part of the body. Torso Reference names the chest or upper spine bone to follow, and Auto Setup fills it in on a humanoid rig. Left empty, the elbow holds its place as under World Down.

Reaching Too Far¶

A hand held on a spot near the edge of what the arm can reach would straighten the arm and read as a strain. A held hand is not allowed to detach the arm, so at the limit one of three things has to give, and Over-Reach, under Solver Settings, picks which.

Blend Out fades the hold away over the last stretch of reach, so the hand lets go gradually as the spot moves out of range and takes it up again as it comes back. It is the gentlest and is rarely noticed. Release holds at full strength right to the limit and then stops, which is sharper but keeps every hold before the limit exact. Clamp never lets go, so the arm straightens toward the spot and the hand falls short, visibly wrong but never releasing a grip.