Skip to content

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);

An IkConstraint (ikConstraint) goes on the chain’s end bone, a shin or a forearm:

FieldWhat it is
targetThe entity the tip goes to. Put it under the rig’s top, not under a bone, so it stays where it is.
bones1: the end bone alone turns to point at the target. 2: that bone and the one it hangs from.
bendWhich side the joint between 2 bones goes (see below).
mix0: the bones’ own rotations. 1: the tip on the target. Anything between blends the two.
lengthThe 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.

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.

  • IkSystem runs in PostUpdate, 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.

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.