How operators fire
A rig in usdRig is not a pile of nodes with hidden wires. It is a piece of USD namespace, and where a prim sits in that namespace is what decides when it runs. Once you can read the hierarchy, you can predict the frame.
The mental model¶
Everything lives under one RigExecRoot. That prim is the rig: the
partition, the namespace root that controls, joints, solvers and movers are
discovered beneath, and the unit that gets compiled and evaluated.
Inside it there are four jobs:
- Controls carry the animation. A control is the
animator's handle. Keys go on its
avars:*channels, composed over itsrest:space. Its base frame is its posed frame, and only a constraint that targets it revises it, so everything downstream simply follows it. - Solvers and constraints pose joints. An FK chain, a two-bone IK or an aim constraint reads controls and writes frames onto joints. A joint is where solved posing becomes readable data.
- Weights say how much. A static weight is one
scalar per moved point, painted once and held for the shot. Bound through a
mover's
rigExec:weightObject, it scales that mover's effect per point. - Movers move geometry. A matrix mover reads a provider's rest-to-posed delta and carries points by it, per point, under the bound weight.
A frame runs the pose work first and the geometry work after it, so a mover never has to wait in the hierarchy for a solver — it only has to name which version of the joint it wants.
The order you can predict¶
The compiler walks the final composed namespace of the whole rig, and it reverses sibling order: the bottom sibling executes first, the top sibling executes last, and a parent runs after all of its descendants. This is exactly the usdview stack presentation, read from the bottom up.
Two consequences are worth memorising:
- Sibling order comes only from the parent's child order. Not from
relationship-target order, not from plugin registration, not from which
worker finishes first. If you want a different order, change the composed
order —
reorder nameChildren = [...]on the parent, or nest one prim under the other. Layer strength participates in that composed order exactly as a reorder opinion does. - Solvers and constraints on the same joint are one stack, not two
phases.
rigExec:jointsis an ordered write, not an exclusive claim. Any number of solvers may name a joint and any number of pose constraints may name it onrigExec:moves; they are steps of one kind in one stack, in that same bottom-first order. A constraint below a solver runs first and feeds it; a constraint above it revises its output.
Because each step receives the frame the step below it left, a solver takes its
joints' incoming frames as its rest reference. Two-bone IK re-measures
root-to-mid and mid-to-end on every evaluation, so a step below it
re-proportions the limb rather than merely re-orienting it. An FK chain
instead composes its control deltas onto whatever incoming frame it finds. A
joint no earlier step wrote simply hands over its authored rest:space, which
is why a rig whose constraints all sit above its solvers is unchanged by any of
this. Put Solvers near the bottom of the rig root to get the classic
"solve, then revise" shape — that is what every shipped example authors.
The stack is an order of versions, not a queue. Steps run in that order only where they touch the same data: two writers of one joint, or a step and the writer of a frame it reads. Constraints are ordered only by the frames they read and write — stack order decides which version a positional read sees — so constraints, like solvers, that share no joint and no data are independent and may run in parallel. Nothing about that changes the answer, only how fast it arrives.
Read phases: which version a mover sees¶
A mover names the moment it reads its provider with rigExecReadPhase
metadata on the relationship that names the input — rigExec:transform,
rigExec:influences, rigExec:cage, rigExec:surface, rigExec:driverCurve
and so on. Metadata is the only way to declare a phase; there is no schema
attribute for it. With none authored the input reads base.
Arrange the hierarchy first and declare a phase only where it changes the
answer. An input that nothing revises after base (a joint no constraint
revises above its last solver, a mesh no other mover deforms, a property no
math mover revises) reads the same value at every phase, so a marker there
is noise.
Property matrix connections, selected geometry points, Ribbon driver curves,
and phased weight sample targets also use this contract. A float3 input
selects one array element only when it authors the integer
rigExecInputElement; a shorter current array uses the input's typed fallback
and reports a diagnostic. See Cross-domain inputs
for the authoring rules and count recovery behavior.
base— the joint after its last solver. Note that this is not "before every constraint": a constraint that fell below the last solver is already folded in, through that solver's rest reference.preceding— the value standing immediately before this one mover's own application in the point stack. It is only meaningful to a mover that has a place in that stack. On the points of the chain this revision moves, such as a lattice whoserigExec:cageis its own target, that is the points as the movers before it left them; on the stack's first mover it is the authored points. A mover with several targets is a known limitation: its revision on one target reading another chain it also moves atprecedinggets that chain's points from just before its own revision there only when another reader's phase on that chain makes the evaluator keep that record, and otherwise the authored points. One relationship can therefore resolve to different points for the mover's different targets.final— the top of the chain, after every writer of that target.- a checkpoint — an absolute prim path in place of a token, meaning "the
provider as it stood right after that named step". Naming the
Solversscope means "after the last solver" (which is exactlybase); naming theMoversscope means "after the last constraint".
def RigExecMatrixMover "HandSkin" (
prepend apiSchemas = ["RigExecMoverAPI"]
)
{
rel rigExec:moves = </Asset/Geom/Hand.points>
rel rigExec:transform = </Asset/Rig/Joints/Shoulder/Elbow/Wrist> (
rigExecReadPhase = "final"
)
}
Change that one value to base (or delete it) and the hand card follows the
FK solve but ignores the aim constraint stacked above it. Nothing else in the
file moves. Example 13 reads a lattice
cage at final; its notes give the checkpoint that reads the cage halfway
through its movers.
Solver inputs¶
A solver reads its inputs — an IK effector or pole, a root control, a space — where the stack puts them. A constraint above the solver on that input (or on one of its frame ancestors) has not fired yet when the solver runs, so by default the solver sees the frame before the constraint and the constraint then revises the result. To have the solver wait for that constraint instead, put the read phase on the solver's input relationship:
def RigExecTwoBoneIk "ArmIK"
{
rel rigExec:effectorControl = </Asset/Rig/Controls/HandIK> (
rigExecReadPhase = "final"
)
}
final reads the input after every constraint on it; a prim-path checkpoint
reads it as of that step, so only constraints at or before the checkpoint are
waited on. base, preceding and an unannotated relationship all mean the
hierarchy rule. A declared phase cannot make a solver wait on a constraint
that revises a joint the same solver writes — the stack already orders those
two writers — and compiling such a rig fails with a message naming the
solver, the joint and the constraint.
Connected inputs¶
An attribute connection reads a property. When math movers revise that property, an undeclared connection reads its base: the authored value, before any of them, as an unannotated relationship does. The same metadata on the connected input chooses another point in that property's chain:
float inputs:defaultWeight (
rigExecReadPhase = "final"
)
float inputs:defaultWeight.connect = </Asset/Rig/Channels/Dial.rigExec:amount>
base— the property's authored value, before any math mover. What an undeclared connection reads.final— after every math mover on the property. A reader that should follow what the movers computed declares it.- a checkpoint — an absolute prim path: the value as the last math mover at or beneath that prim left it.
A pose interpolator's float output — a pose's outputs:weight, an animated
map's outputs:value (a step table's channel value, say) — follows the same
rule for a math mover's float inputs. Undeclared, the
connection reads the output's authored value. At final it reads what the
interpolator computed in the same evaluation, and the mover runs after the
interpolator; two interpolators that drive each other's inputs this way are
a cycle, set aside in every evaluator. Blend inputs and weight objects read
the computed value without a declaration.
preceding names a position in the reader's own chain, and a connection
reads another property's, so it is refused. The phase applies to the first
revised property along the connection's single-source hops, and the reading
input's own phase decides, whatever a hop along the way declares. A declared
phase needs that property's value type, or float and double either way
round. A refused declaration sets aside the operation that reads the input
— a mover, a solver or a pose interpolator — with a warning that says why.
On an input no such operation reads, such as a control's, a joint's, a
channel's, a space switch's or an expression's, it fails the compile. An
input that only a mover already set aside, or one with no rigExec:moves
targets, reads is not compiled, and its declaration is ignored.
The phase is read on every connected attribute of a prim under the rig root
— a mover's inputs, whatever its type, a solver's, a constraint's, a space
switch's, a pose interpolator's and its poses', a control's or a joint's
avars — on the weight objects and blend inputs an operator names, and on
the attributes an operator names as ones it reads
(rigExec:driverAttributes, rigExec:shaderDialSources,
rigExec:activeSpaceAttribute). The native program, frozen jobs,
the frame cache and the .rigexec runtime all read it the same way. An
unconnected input reads its own value, so a phase there has nothing to
choose and is ignored. An input that math movers revise itself reads its
own chain's result, and a phase declared on it is refused as ambiguous.
A drag on the reading input, or on a property along its connection, is what
that reader gets. A drag on the revised property itself edits its base: the
math movers revise the dragged value as they would the value authored, so
every reader sees during the drag what it sees once the drag is authored.
base readers read the dragged value, checkpoint readers the chain as of
their step, and final readers, like every other reader of the property,
the chain's result. A clamped blink authored at 0.2 and dragged to 1.4
reads 1.4 at its base and 1.0 at final, during the drag and after it is
released. A drag that is not finite skips the chain, as an authored one
does, and readers see the dragged value. The .rigexec runtime's SetInput
sets an avar the same way, as its authored value, an avar math movers revise
included, and takes finite values only. A plugin mover's playback kernel
receives its declared inputs as they are set, so a drag on one moves that
mover's output.
Example 16 reads one dial
three ways, with math movers and with mover envelopes.
A frame, walked through¶

two_bone_ik.usda is a two-card arm. Under the rig root, in composed order:
Controls, Solvers, Joints, Weights, Movers.
At frame 1001 the HandIK control sits at its rest, x = 5.85, just inside
full reach of the 3 + 3 unit chain, so the arm holds a slight bend. By frame
1006 its avars:tx spline has reached -2.35 and avars:ty 1.5.
- Controls are read.
HandIKcomposes its avars overrest:spaceand publishes a posed frame.ElbowPoleandShoulderRootpublish their rests unchanged — they are unanimated, and they are still real inputs. - The solver fires.
ArmIKis the only step in the pose stack. It measures its two bones from the framesShoulder,ElbowandWristcarry on entry — here, their authored rests, because nothing sits below it — then solves the chain in the plane through the pole, withinputs:softnessat0.15shaping the approach to full extension. - Joints are written. All three joints in
rigExec:jointsget new frames: the shoulder stays planted, the elbow swings out into the pole plane, the wrist lands on the effector. - Movers read them.
UpperSkinreadsShoulderandForeSkinreadsElbow, both atfinal, each scaled by a constant1.0static weight — the rigid-attachment idiom. Each four-point card is carried by its joint's rest-to-posed delta. - The viewer sees the orange upper card and the green forearm card hinge at the elbow as the hand swings in and lifts, then unwind by 1012.
Common mistakes¶
- "My constraint does nothing." It is probably below the solver that
overwrites the joint. Move its scope above the
Solversscope — i.e. earlier in composed order — or accept that it is now feeding the solve. - "My skinning ignores the constraint." The mover is reading
base, the joint after its last solver, and the constraint revises the joint after that. DeclarerigExecReadPhase = "final"on that one input. Leave inputs that no constraint revises unmarked: theirbaseis already theirfinal. - "Two movers on one mesh fight." They do not fight; they stack, bottom sibling first, descendants before their parent. Reorder or renest to choose. Stacking matrix movers is how you layer rigid follows, not how you blend influences on one point — use the skin mover for that.
- "I changed the relationship order and nothing happened." Target-list permutation changes neither mapping nor result. Change the namespace.
- "Editing a joint rest changed my limb proportions." It is meant to: IK measures bone lengths from rests every evaluation and caches nothing.
Glossary¶
- Avar — an animator-facing scalar parameter on a control, such as
avars:txor an IK blend. - Rest — the bind-pose frame a prim carries in
rest:space, measured against its namespace parent's rest. - Posed — the evaluated frame for the current time.
- Provider — anything that publishes a frame other things can read: a control or a joint.
- Aggregate — one packed array of frames published by a solver, whose
element N is written to
rigExec:joints[N]. - Stack — the ordered list of steps writing one target, be it a joint's solvers and constraints or a mesh's movers.
- Phase — which version of a provider a reader asks for:
base,preceding,final, or a named checkpoint.
Where this is specified¶
Traversal order is _GetPoseStackOrder in
libs/rigExec/rigEvaluatorInputs.cpp, the one walk that numbers the pose
stack over solvers and constraints and the mover stack, and that the
structure digest also takes. base/preceding/final and AtPrim
checkpoints are RigExecReadPhaseKind in libs/rigExec/moverGraphTypes.h.
Cross-domain inputs gives the producer
each phase selects for property, pose, geometry and weight reads.