Retargeting and procedural rigs

Follow joint coordinate frames, rest-space retargeting, inverse-kinematics solvers, ground adaptation, and spring controls.

Asterune represents a rig as a hierarchy of motor joints with explicit parent and child attachment frames. Retargeting converts a sampled source pose into that hierarchy. Procedural controls then adjust the blended pose before the engine writes motor transforms. Their output changes rig articulation while world movement and collision remain separate simulation concerns.

Animation evaluation and blending describes the clip and graph contributions that supply the starting pose.

Joint frames and hierarchy evaluationCopy link

For a joint with parent placement P, attachment frames C0 and C1, and animated transform T, the child placement is P × C0 × T × inverse(C1). A local pose therefore belongs to the joint's attachment frame, rather than directly to world space or the child part's origin.

The runtime layout places parents before children and records the joint that places each parent part. World-pose evaluation can then walk forward through the layout. A procedural solver that selects a world-space orientation must convert that orientation back through the parent and attachment frames before writing a local transform.

Rig construction retains enabled Motor6D joints whose referenced parts exist inside the rig. Joints disconnected from the chosen root can remain in the layout without a parent layout index. Name-only lookup excludes ambiguous child names, while parent-qualified clip binding can still distinguish them. A matching bone count alone does not establish a compatible skeleton.

Rest-space retargetingCopy link

A retarget binding precomputes how source rest frames correspond to target rest frames. The source skeleton records rest orientations and parent indexes; the target supplies its motor attachment frames. Each mapped target joint receives a carry rotation built from source rest orientation, facing alignment, and target rest orientation. Optional rest matching also incorporates the source and target bone directions.

During sampling, the runtime reconstructs each source joint's orientation in rig space, accumulating its parent's orientation, rest-relative rotation, and sampled local rotation. It then applies facing alignment and the precomputed carry rotation. Converting that result through the target's current parent frame produces the target local rotation.

This parent-relative reconstruction matters when proportions or rest axes differ. Copying the source's local quaternion directly would assume that both rigs use the same joint axes. An unmapped target joint keeps zero sampled coverage, allowing another contribution to control it.

Translation has its own rule. When translation retargeting is enabled, source travel is rotated from its source frame through facing alignment into the target frame and multiplied by the profile scale. When disabled, the retargeted translation is zero. A nonfinite or nonpositive scale falls back to 1. The source joint's sampled coverage carries through to the mapped target.

The runtime can choose native clip binding when a clip already uses the target rig's names. A retarget profile does not force every clip through source-rig conversion. Bindings are cached against the profile definition and target layout signature, so changing the mapping requires a new conversion binding.

Control order, smoothing, and pose ownershipCopy link

Enabled controls with positive weight run after track and graph composition, in ascending control-priority order. Each control reads the pose produced by the preceding control. Later controls can therefore alter an earlier solve rather than independently solving against the original animation.

The solver first computes a candidate local pose. The control weight then blends changed joints between the preceding and candidate transforms. Nonfinite candidate transforms are skipped, and changed joints gain coverage at least as large as the control weight.

Target smoothing retains a target between frames and uses the response 1 - exp(-dt / smooth_time). It smooths target movement before the chain solve, rather than smoothing every joint independently afterward. Disabling a control clears its retained runtime state, so re-enabling it starts without the old target or spring history.

Runtime inverse kinematicsCopy link

Inverse kinematics (IK) starts with a chain of joint pivot positions and an endpoint offset. The endpoint need not be the center of the final part. A hand attachment or an ankle pivot can define a different point for the same chain to reach.

Solver selection depends on chain structure:

The analytic solver forms a triangle from the 2 segment lengths and target distance. It clamps distance just inside the reachable interval to avoid a singular fully straight or folded configuration. The pole defines the bending plane; without a usable pole, the solver preserves the existing bend direction or selects an orthogonal fallback.

FABRIK preserves segment lengths while moving points. An unreachable target straightens the chain toward that target. A reachable target alternates a backward pass from the endpoint with a forward pass from the fixed root. The solve stops within 0.001 studs or after 16 passes. A pole then rotates intermediate bends around their neighboring-point axis.

The solved points become joint rotations in parent-first order. Each rotation aligns a segment with its solved direction while preserving the joint pivot. CCD instead walks joints from tip toward root, rotating the endpoint direction toward the target at each joint. It uses the same 16-pass and 0.001-stud bounds. An optional endpoint orientation is applied after the positional solve.

Look-at limits in rig spaceCopy link

A look-at control converts its desired direction into root space and compares it with the final part's rest-facing axis. Yaw and pitch limits apply relative to that rest direction, so rotating the whole character does not redefine the allowed local head turn.

The control distributes the remaining orientation change through the chain. After each joint turns, it recomputes the endpoint's direction before choosing the next joint's share. This lets a neck and torso cooperate rather than applying the full requested turn independently at every joint.

Ground-adapted feet and pelvisCopy link

Foot placement raycasts from above each sole down through twice the configured probe height. The query excludes the rig itself and respects collision-enabled surfaces. The sampled ground point determines a bounded vertical lift, which is smoothed per foot.

Optional pelvis adjustment lowers toward the lowest negative foot offset and returns toward the animated baseline when that offset clears. It does not raise the pelvis above that baseline. Each leg then solves toward a target corrected for that pelvis motion. This reduces the amount of leg extension required when the feet stand on different heights. The bending pole follows the rig's facing direction.

Ground alignment can rotate a foot toward the hit normal, with tilt capped at 35 degrees. The implementation's probe and lift directions use world Y. It does not derive that direction from a character's arbitrary gravity or up vector, so its ground-adaptation frame can differ from the movement motor's.

Spring state and bounded integrationCopy link

A spring control retains an endpoint and velocity for each chain segment. The animated endpoint supplies its target. Each integration step applies stiffness toward that target, velocity damping, and the configured gravity, then constrains the resulting point to the segment's original length.

Integration clamps frame duration to 0.05 s. It chooses up to 8 substeps from ceil(dt × 240), reducing the step size for stiff motion. The resulting endpoint direction rotates the joint about its pivot. This is a procedural pose solve, not a Rapier rigid body or collision-constrained physical chain.

A chain-length change resets incompatible spring storage. An endpoint that becomes nonfinite or moves more than 8 segment lengths from its animated target also resets to that target with zero velocity. Those resets prevent an old pose discontinuity from becoming a long-lived spring displacement.