Function solveTwoBoneIK

Solves a two-bone chain so its tip reaches target, bending towards poleHint.

The chain is root → joint → end, with |root − joint| = upperLength and |joint − end| = lowerLength always — bones never stretch, which is what makes the unreachable case a clamp rather than a scale.

d      = |target − root|, clamped to [|a − b|, a + b]
cos θ  = (a² + d² − b²) / (2·a·d)              // law of cosines at the root
joint  = root + a·(cos θ · forward + sin θ · pole)
end    = root + d·forward
Copy

where a = upperLength, b = lowerLength, forward is the unit vector from the root to the target, and pole is the unit vector towards poleHint with its forward component removed. θ is measured from forward, and sin θ is taken non-negative, so the joint always lands on the pole side of the root–target line: that is what stops a knee from flipping between frames.

Unreachable targets clamp (decision, WP-8.3)

Both failures clamp the distance and keep the direction, and both report reachable: false:

• Too far (d > a + b): the chain straightens and points at the target, end = root + (a + b)·forward. The tip stops short along the line to the target — the closest a rigid chain can get.
• Too close (d < |a − b|, only possible with unequal bones): the chain folds as far as it goes, end = root + |a − b|·forward, again the closest reachable point.

Clamping rather than throwing is deliberate: a target sliding out of range is an ordinary runtime event (a reaching character, a dragged handle), and the clamped pose is continuous with the reachable ones, so the limb settles at full extension instead of popping.

Degenerate inputs

• Pole hint on the root–target line (or at the root): the bend plane is undefined, so the solver picks a deterministic perpendicular of forward — the world axis least aligned with it, made perpendicular. The pose is valid and repeatable, just not authored; pass a meaningful hint to control it.
• Target coincident with the root: the chain direction is undefined and the solver uses +X as forward (documented, deterministic). With equal bones this is exactly reachable — the chain folds flat and the joint lands at root + a·pole, so the pole hint still chooses the fold direction.
• A zero-length bone is allowed (the chain degenerates to one bone, and the joint coincides with the root or the tip); both bones zero is rejected, because then there is no chain to solve.