Physics · interface

Ragdoll

Explained in Your first game, Rigid bodies.

interface Ragdoll

import type { Ragdoll } from '@driftengine/physics';

Properties

Name	Type	Description
`bodyOf`readonly	`Int32Array`	Body index per joint, or −1 where the joint has no bone.
`boneCount`readonly	`number`	How many bones were built.

Methods

`writePose`

writePose(out: PoseTarget): void

Write the ragdoll's current shape into a pose.

Parameter	Type	Description
`out`	`PoseTarget`

Each joint is turned by the bone that starts at it, which is the joint a skinned limb follows — the forearm's body turns the elbow — and a joint with no bone below it rides the one it hangs off. Translations are the rig's own, in each parent's frame. A root's rotation is written in the frame the character's node is placed in, at rootX, rootY and rootZ, with no rotation of its own; a joint no bone reaches is left as the pose had it.

`drive`

drive(world: PhysicsWorld, pose: PoseTarget, weight: number): void

Steer the bodies toward a pose. Weight 1 tracks it, weight 0 goes limp.

Parameter	Type	Description
`world`	`PhysicsWorld`
`pose`	`PoseTarget`
`weight`	`number`

`sync`

sync(world: PhysicsWorld, worldMatrices: Float32Array): void

Put every body back on its bone and clear its velocity.

Parameter	Type	Description
`world`	`PhysicsWorld`
`worldMatrices`	`Float32Array`

A hit reaction starts from the pose the character is in now, and this is how it says so. A ragdoll is built once, because building one allocates bodies and joints and a hit is not the moment for that — but between reactions the character keeps moving and the bodies do not. They sit where the last reaction left them, or where they were on the frame the ragdoll was built, and a reaction that begins by blending toward that snaps the character to a stale shape somewhere else before it starts.

worldMatrices is the same sixteen-floats-a-joint array ragdollFromBones took. The joints are left alone: they connect bones and the bones have not changed length.

`rootX`

rootX(): number

Where the first bone's parent end is now, so a caller can move the character's node.

The head of that bone, which is a different point from the body holding it: a capsule is built about its bone's middle, so the two are half a bone apart — 0.46 m for a root bone of 0.92 m, which is a character standing in the air. Read all three or none; there is nothing else here that answers a centre, and a caller wanting one reads world.bodies directly.

Two of these answered the centre until 2026-08-28 and the third only looked as if it did not. Reported from outside, where the symptom was a body drawn half a metre above the physics holding it — which reads exactly like a pose that never arrived, and cost the reporter two weeks of looking for one. rootX reached the centre through a helper named boneHeadX, so the name answered the question and the arithmetic did not. What would make this wrong is a rig whose first bone is not the one a caller wants to place a node by; bodyOf is the door to any other bone, and this is the convenience for the common case.

`rootY`

rootY(): number

`rootZ`

rootZ(): number