IK constraints
@shell/ik turns a chain of 1 or 2 bones so the end bone’s tip reaches a target. It runs each frame in the game, on
top of the bones’ own rotations. A clip keys where the target is and how much the chain follows it, and game code can
move a target too, for a foot on uneven ground or a hand onto a ledge.
IkPlugin is in Engine2D and Engine2DSimulation. On a world of your own:
import { IkPlugin } from '@shell/ik';
world.addPlugin(IkPlugin);The constraint
Section titled “The constraint”An IkConstraint (ikConstraint) goes on the chain’s end bone, a shin or a forearm:
| Field | What it is |
|---|---|
target | The entity the tip goes to. Put it under the rig’s top, not under a bone, so it stays where it is. |
bones | 1: the end bone alone turns to point at the target. 2: that bone and the one it hangs from. |
bend | Which side the joint between 2 bones goes (see below). |
mix | 0: the bones’ own rotations. 1: the tip on the target. Anything between blends the two. |
length | The end bone’s length, to its tip. The editor keeps it in step with the bone it draws. |
bend is 1 or -1. It is the side of the line from the chain’s start to the target that the middle joint goes: 1
turns clockwise on the screen from that line, -1 the other way, in the chain’s parent’s space. So a mirrored rig bends
mirrored. A character facing +x bends its knees forward with -1.
Out of reach, the chain reaches toward the target as far as it can: straight, or folded when the target is nearer than the two bones’ difference.
In a clip
Section titled “In a clip”A clip keys IK as any other fields. The target’s position places it, and the constraint’s mix blends it in and
out:
{ "target": "Hips/Torso/Arm R/Forearm R", "component": "ikConstraint", "field": "mix", "keys": [ [0, 0], [600, 1, "inOutSine"], [1400, 1, "inOutSine"], [2000, 0, "inOutSine"] ]}The bones a constraint drives keep their own rotations, keyed or not: IK is applied on top of them each frame and never feeds on its own answer. So a Mix of 0.5 holds halfway, and at Mix 0 the bones are their own again.
Order and cost
Section titled “Order and cost”IkSystemruns inPostUpdate, after the clips and the paths and before the hierarchy places what is under the bones. A target a clip or a path moved this frame is where it is now.- Constraints are solved parents first, so a chain under another sees it solved.
- They are found once, and found again when one is added, taken off or gone.
- A frame makes no garbage. A rotation is written, and marked changed, only when it is another.
- 500 rigs of 3 constraints each take about 0.9 ms a frame in Chrome on an M2 Max.
An example
Section titled “An example”examples/editor has a Knight (prefabs/knight.prefab.json): two legs with an IK constraint on each shin, and the
right arm with one on its forearm, their targets under the Knight. Its clip (animations/knight-pick-up.anim.json)
drops the hips and leans the torso over 2 s. The feet stay on their targets, and the hand blends onto its target as the
clip keys its Mix to 1: it reaches toward it, and is on it where the hips are lowest, the one place in the arm’s reach.
The game page shows it at index.html?scene=scenes/knight.scene.json.