Bone 2D¶
API schema that makes a joint one bone of a 2D skeleton.
| Node type | RigExecBone2dAPI |
On this page:
Overview¶
Apply RigExecBone2dAPI to a RigExecJoint that a
Skeleton 2D lists in rigExec:joints. The joint's
namespace parent is the bone's parent when it is a bone of the same skeleton
(otherwise the bone is a root), and its rest:space is relative to that
parent. Composed, the setup frame lies in the skeleton's plane: base at the
origin, the bone along +X, rotation about the plane's +Z only. The bone runs
to its first child joint.
One bone of a 2D skeleton, applied to a RigExecJoint that a RigExecSkeleton2d lists in rigExec:joints.
Hierarchy: the bone's parent is its nearest RigExecJoint namespace ancestor when that joint is a bone of the same skeleton; otherwise the bone is a root of the skeleton and hangs from its start frame. A reparent is a namespace move; an animated parent is a RigExecSpaceSwitch whose rigExec:target is the bone (read by the skeleton, see RigExecSkeleton2d).
Setup: the joint's rest:space is relative to its namespace parent, as for every RigExecXformable. Composed, the bone's setup frame lies in the start frame's XY plane: bone base at its origin, the bone along +X, rotation about the plane's +Z only. rest:tx..rest:rz stay unauthored. The bone's tip is its first RigExecJoint child in namespace order: a child bone, or for a leaf an End joint (a plain RigExecJoint without this API that no solver lists). A bone with no joint child is a pin: its tip is its base.
Channels: avars:tx and avars:ty move the bone in its parent's frame, avars:rz turns it (degrees, as a delta from the setup angle) and avars:sx scales it along the bone, carrying the tip with it. A channel that property movers revise is read as that chain's result. The flip, lock, offset and target-index channels below are animated; the index channel and the lock references are held.
Evaluation never clamps keyed or driven angles to the limits; limits bound the lock solve, and authoring tools clamp the values they write.
How it works¶
The bone's tip is its first RigExecJoint child in namespace order: a
child bone, or for a leaf an End joint (a plain RigExecJoint without this
API that no solver lists). A bone with no joint child is a pin: its tip is its
base. The tip is where a target solve aims and what avars:sx stretches. A
child bone's rest is a value, so editing it re-solves without recompiling; an
End joint's offset is compiled, so editing it recompiles.
Animation lives on the joint's avars: avars:tx and avars:ty move the
bone in its parent's frame, avars:rz turns it (degrees, as a delta from the
setup angle) and avars:sx scales it along the bone. A channel that property
movers revise is read as that chain's result. The flip, lock, offset and
target-index channels are animated too; the index channel and the lock
references are held (stepped) between keys. An animated parent is a
Space Switch on the bone, read by the skeleton.
bone2d:colorTag, bone2d:showLabel and bone2d:shy are display hints for
editors (a colour, a name label, membership of the shy set one view toggle
hides). Evaluation never reads them, so editing one neither recompiles nor
re-solves.
Wiring¶
| Relationship | Points to | Required |
|---|---|---|
bone2d:targetCandidates |
Ordered target bones for a tip-follow target, selected by bone2d:targetIndex. |
no |
bone2d:angleControl, bone2d:posControl, bone2d:scaleControl |
At most one control bone each, in delta form. | no |
Parameters¶
Node parameters¶
bone2d:angleLimits¶
Type: uniform bool. Default: false.
Whether bone2d:minAngle/maxAngle bound the lock solve.
bone2d:minAngle¶
Type: uniform double. Default: 0.
Lower limit in degrees, relative to the setup local angle.
bone2d:maxAngle¶
Type: uniform double. Default: 0.
Upper limit in degrees, relative to the setup local angle.
bone2d:independentAngle¶
Type: uniform bool. Default: false.
Keep the setup world angle while ancestors turn: the world angle is the setup world angle plus avars:rz. The base still follows the parent.
bone2d:scalingMode¶
Type: uniform token. Default: "normal".
Valid values: normal, squashStretch, uniform.
How avars:sx scales bound geometry across the bone: normal leaves it, uniform scales it by sx too, squashStretch by sx^(-bone2d:squashFactor). Children are never scaled across.
bone2d:squashFactor¶
Type: uniform double. Default: 1.
Exponent of the squashStretch cross scale, in [0.01, 100].
bone2d:ignoredByIk¶
Type: uniform bool. Default: false.
Excluded when counting a parent's children for the lock and target chains; pins (bones with no joint child) are always excluded.
bone2d:maxStretch¶
Type: uniform double. Default: 1.
Largest common scale, >= 1, the lock and target solves may give the chain to reach an out-of-range lock point or target.
bone2d:sideFlip¶
Type: bool. Default: false.
Mirrors the bone's local Y (held). Composes down the hierarchy.
bone2d:endFlip¶
Type: bool. Default: false.
Mirrors the bone's local X about its base (held).
bone2d:lock¶
Type: bool. Default: false.
While true, the lock solve keeps the bone's base at (bone2d:lockX, bone2d:lockY) and its world angle at bone2d:lockAngle by turning its ancestors. Authoring tools write the reference with each lock key.
bone2d:lockX¶
Type: double. Default: 0.
Held base X in the skeleton's plane (the start frame's space, asset space without one). Authored as a spline with held knots, one per lock key, so the reference never slides between keys.
bone2d:lockY¶
Type: double. Default: 0.
Held base Y in the skeleton's plane; authored like bone2d:lockX.
bone2d:lockAngle¶
Type: double. Default: 0.
Held world angle in degrees; authored like bone2d:lockX.
bone2d:offsetX¶
Type: double. Default: 0.
Animation offset in the parent's frame, added to the posed local position only (never to the rest used for binding). Authored as a spline with held knots: 0 at the setup frame, the offset elsewhere, so the setup frame shows the bone without it.
bone2d:offsetY¶
Type: double. Default: 0.
Animation offset Y in the parent's frame; authored like bone2d:offsetX.
bone2d:targetCandidates¶
Relationship.
Ordered IK target options (other bones of the skeleton, usually unparented pins). bone2d:targetIndex selects one per frame; empty keeps no target.
bone2d:targetIndex¶
Type: double. Default: -1.
Index into bone2d:targetCandidates (rounded; negative or out of range keeps no target). Authored with held knots. The owner's tip tracks the target bone's base; a lone bone aims at it. A pin owner moves its ancestors so its base meets the target; a pin with a target and no parent bone is a compile error.
bone2d:angleControl¶
Relationship.
At most one bone whose rz drives this bone's rz (delta form). Structural; the factor below scales it.
bone2d:angleControlFactor¶
Type: uniform double. Default: 0.
Added per controller rz degree; 0.5 and -0.5 counter-move.
bone2d:posControl¶
Relationship.
At most one bone whose tx/ty drive this bone's tx/ty (delta form).
bone2d:posControlFactorX¶
Type: uniform double. Default: 0.
Added per controller tx unit.
bone2d:posControlFactorY¶
Type: uniform double. Default: 0.
Added per controller ty unit.
bone2d:scaleControl¶
Relationship.
At most one bone whose sx drives this bone's sx about 1.
bone2d:scaleControlFactor¶
Type: uniform double. Default: 0.
This bone's sx multiplies by 1 + factor * (controller sx - 1).
bone2d:colorTag¶
Type: uniform token. Default: "plain".
Valid values: plain, red, orange, yellow, green, teal, blue, indigo, purple, pink, brown, gray.
Display only: the colour editors draw the bone and its channel rows in. Evaluation never reads it.
bone2d:showLabel¶
Type: uniform bool. Default: false.
Display only: editors draw the bone's name beside it. Evaluation never reads it.
bone2d:shy¶
Type: uniform bool. Default: false.
Display only: editors may hide shy bones together with one view toggle. Evaluation never reads it.
Example¶
A forearm bone nests under the upper arm with the rest:space
(1, 0) relative to it and an End joint one unit along it. avars:rz of 30
turns it 30 degrees from the setup angle. bone2d:angleControl pointing at a
dial bone with bone2d:angleControlFactor -0.5 makes it counter-move at half
the dial's turn.
Tips¶
- A pin (no joint child) is always excluded when counting a parent's children for the lock and target chains; a pin with a target and no parent bone is refused when the rig compiles.
- Evaluation never clamps keyed or driven angles to
bone2d:minAngleandbone2d:maxAngle; authoring tools clamp the values they write. - Order the children (
reorder nameChildren) when a bone has several: the first child joint is its tip.