Rig properties properties

The rig properties family: a rig layer's custom properties - the value of each one, addressed by property id, whose prefix names the kind: number (num_), percent (pct_), angle (ang_), boolean (bool_), dropdown (drop_), colour (col_), slider (slide_), joystick (joy_) and pose selector (psel_). A number, percent, angle or slider value is a scalar (a slider clamps into its range at evaluation), a joystick a point clamped into its axes, a colour a colour, a boolean a hold, a dropdown or pose selector a hold over its vocabulary (an option label, a pose id or ""). Every pattern reads, keyframes AND drives: a script sweeping a slider that a driver reads poses everything the driver reaches, which is the scripted control panel.

Every pattern below is readable from scripts through prop() and layer.prop(); ids in a pattern (like <effect_id>) stand for the entity's real id. Every pattern here is in the drive set: scripts may WRITE each one with set() or a single-output return, per frame.

Worked examples#

A rig layer's custom PROPERTIES are its authored controls (RIG-W4 POSE): each is addressed by its own id, whose prefix names the kind - rig.properties.<property_id>.value with num_ (number), pct_ (percent), ang_ (angle), bool_ (boolean), drop_ (dropdown), col_ (colour), slide_ (slider), joy_ (joystick) or psel_ (pose selector). A number, percent, angle or slider value is a scalar (a slider clamps into its range at evaluation), a joystick a point clamped into its axes, a colour a colour, a boolean a hold, a dropdown or pose selector a hold over its vocabulary (an option label, a pose id or ""). Every value reads, keyframes AND drives - and the rig's drivers read a driven value exactly as a keyed one, so a script on one property poses everything its drivers reach.

Worked example: Sweep the Wave slider#

The scene. A Stage comp with a one-bone Wrist rig at (320, 180) - the Hand bone heading right for 100 px - carrying a Wave slider property (0..1, resting at 1) and a Wave to wrist driver that maps the slider onto the Hand's rotation, -30 to 30 degrees; and a Paddle solid rigidly bound to the Hand, so the bone's driven turn swings it about the wrist.

• The comp Stage: 640 by 360 at 25 fps, 100 frames (4 seconds).
• Wrist: a rig layer, at [320, 180].
  • The skeleton: Hand (bone_1, a root) from [0, 0] at 0 degrees for 100 px.
  • The properties: Wave (slide_1, a slider from 0 to 1, resting at 1).
  • The drivers: Wave to wrist (driver_1): rig.properties.slide_1.value 0..1 onto rig.bones.bone_1.rotation -30..30.
• Paddle: a solid layer, at [320, 180], 100 by 40, filled #4d9de0.
  • The rigging stack: rigging_1 - a rigid binding to the Wrist rig's Hand.

The script. Add a project script named Wave sweep and paste:

export const outputs = ["layer_1:rig.properties.slide_1.value"];

export function frame() {
  return linear(time, 0, 2, 1, 0);
}

Line by line:

• Line 1: One output: the VALUE of the Wrist rig's Wave slider. A custom property is addressed like any other property - rig.properties.<property_id>.value - and the id's prefix says the kind: slide_ is a slider, so the value is a scalar inside the property's range (0..1 here; a value outside it clamps at evaluation).
• Line 4: linear() maps the first two seconds onto 1 down to 0 and holds 0 after that. The rig's Wave to wrist driver reads the slider - a driven value exactly as a keyed one - and maps 0..1 onto the Hand's rotation, -30 to 30 degrees, so the Paddle bound to the Hand swings from 30 degrees clockwise through level to 30 degrees anticlockwise and rests there. The slider's own authored value (1) is dormant while the script drives.

What you see. The Paddle starts turned 30 degrees clockwise (the slider at 1), swings through level at one second and rests 30 degrees anticlockwise from two seconds on - at one second the slider reads 0.5, from two seconds on it reads 0.