Rig simulation properties

The rig simulation family: a rig layer's simulation hold - enabled, a boolean hold track over the whole rig's dynamics (the springs and the physics bodies). Off, every dynamics item reads its animated pose; on, the fold seeds from that frame and the simulation runs live (no reset - the fold's invalidation is the reset). The pattern reads, keyframes AND drives - and the simulation follows the KEYED hold: key it on at a cue to start the hair swinging from that frame; a script's drive of the hold is a read-side signal (scripts and the evaluated sample see it, the summary and the fold do not).

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 SIMULATION hold is one boolean track over the whole rig's dynamics (RIG-W5 DYNAMICS): rig.simulation.enabled reads true while the springs and physics bodies simulate and false while every dynamics item follows its animated pose. The hold reads, keyframes AND drives - with one rule: the simulation follows the KEYED hold (switching it on at a frame seeds the bodies from that frame's pose, a fold-consistent history), so a script's DRIVE of the hold is a read-side signal - scripts and the evaluated sample see the driven value, the summary and the simulation do not. To cue the simulation, key the hold; to react to it, read it.

Worked example: Turn the head while the hair swings#

The scene. A Stage comp with a three-bone Hair rig hanging from (320, 120) - Strand 1 pointing straight down, Strand 2 and Strand 3 chained under it, 40 / 35 / 30 px - every strand carrying a spring item (stiffness 30, damping 50, drag 5, follow 25, inertia 60) so the hair swings under the comp's gravity when the head turns; a Head solid at the root and three Strand solids rigidly bound to the bones; the rig's Simulation hold keyed ON at frame 0 and OFF at frame 30.

• The comp Stage: 640 by 360 at 24 fps, 48 frames (2 seconds).
• Hair: a rig layer, at [320, 120].
  • The skeleton: Strand 1 (bone_1, a root) at 90 degrees for 40 px; Strand 2 (bone_2, under Strand 1) at 0 degrees for 35 px; Strand 3 (bone_3, under Strand 2) at 0 degrees for 30 px.
  • The items: rigging_1 - a spring on the Strand 1 (stiffness 30, damping 50, drag 5, follow 25, inertia 60); rigging_2 - a spring on the Strand 2 (stiffness 30, damping 50, drag 5, follow 25, inertia 60); rigging_3 - a spring on the Strand 3 (stiffness 30, damping 50, drag 5, follow 25, inertia 60).
  • Keyframe rig.simulation.enabled at frame 0: true (hold).
  • Keyframe rig.simulation.enabled at frame 30: false (hold).
• Head: a solid layer, at [320, 120], 60 by 60, filled #ffe66d.
• Strand 1: a solid layer, at [320, 120], 40 by 8, filled #ff6b6b.
  • The rigging stack: rigging_4 - a rigid binding to the Hair rig's Strand 1.
• Strand 2: a solid layer, at [320, 160], 35 by 8, filled #ff8e8e.
  • The rigging stack: rigging_5 - a rigid binding to the Hair rig's Strand 2.
• Strand 3: a solid layer, at [320, 195], 30 by 8, filled #ffb3b3.
  • The rigging stack: rigging_6 - a rigid binding to the Hair rig's Strand 3.

The script. Add a project script named Head turn and paste:

export const outputs = ["layer_1:transform.rotation"];

export function frame() {
  const simulating = prop("Hair:rig.simulation.enabled").value;
  return simulating ? linear(time, 0, 1, 0, 60) : 0;
}

Line by line:

• Line 1: One output: the Hair rig layer's own ROTATION - the head turn the strands hang from.
• Line 4: rig.simulation.enabled read through prop() is the hold's value at the current frame: keyed on at frame 0 and off at frame 30 in this scene, so it reads true for the first 30 frames and false after. A hold reads exactly as keyed - a script may drive it too, but a driven hold never cues the simulation (the fold follows the keys), which is why this script READS it instead.
• Line 5: While the hold reads true the rig turns from 0 to 60 degrees over the first second and holds there - the three springs lag the turn, the strands swinging out behind the head; from frame 30 the hold reads false, the script returns 0, the head snaps straight and the strands follow the animated pose rigidly (the simulation is off).

What you see. The head turns 60 degrees clockwise over the first second with the three strands swinging out behind it and settling; at frame 30 (1.25 seconds) the simulation hold keys off, the head snaps back upright and the strands hang straight under it - at half a second the rotation reads 30, at one second 60.