Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(physics3d): Ragdoll turns a skinned character's bones into jointed bodies and blends back to the animation

yhhf95759e034a3
diff --git a/pipeline/src/project/targetSupport.ts b/pipeline/src/project/targetSupport.ts
index 26811c9bd..4d0be7e9a 100644
--- a/pipeline/src/project/targetSupport.ts
+++ b/pipeline/src/project/targetSupport.ts
@@ -61,7 +61,7 @@ export const SUBSYSTEM_COMPONENTS: Readonly<Record<Subsystem, readonly string[]>
physics3d: [
'RigidBody3D', 'BoxCollider3D', 'SphereCollider3D', 'CapsuleCollider3D',
'MeshCollider3D', 'ConvexCollider3D', 'CharacterController3D',
- 'HingeJoint3D', 'DistanceJoint3D', 'SliderJoint3D', 'FixedJoint3D', 'PointJoint3D', 'SwingTwistJoint3D', 'SixDOFJoint3D',
+ 'HingeJoint3D', 'DistanceJoint3D', 'SliderJoint3D', 'FixedJoint3D', 'PointJoint3D', 'SwingTwistJoint3D', 'SixDOFJoint3D', 'Ragdoll',
],
spine: ['SpineAnimation'],
dragonbones: ['DragonBonesAnimation'],
diff --git a/sdk/etc/physics3d.api.md b/sdk/etc/physics3d.api.md
index 86da8dc6d..32345e8ec 100644
--- a/sdk/etc/physics3d.api.md
+++ b/sdk/etc/physics3d.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/physics3d
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 0 public · 0 beta · 64 experimental · 0 deprecated
+Symbols: 0 public · 0 beta · 69 experimental · 0 deprecated
## BoxCollider3D — const @experimental
```
@@ -365,6 +365,41 @@ connectedEntity: number
enabled: boolean
```
+## Ragdoll — const @experimental
+```
+ComponentDef<RagdollData>
+```
+
+## RagdollBone — interface @experimental
+```
+id: number
+parent: number | null
+position: Vec3
+rotation: Quat
+```
+
+## RagdollData — interface @experimental
+```
+active: boolean
+friction: number
+minBoneLength: number
+recoverTime: number
+skin: number
+swing: number
+thickness: number
+twist: number
+```
+
+## RagdollLimb — interface @experimental
+```
+axis: Vec3
+center: Vec3
+connected: number | null
+entity: number
+halfExtents: Vec3
+normalAxis: Vec3
+```
+
## RigidBody3D — const @experimental
```
BuiltinComponentDef<RigidBody3DData>
@@ -512,6 +547,11 @@ twistMinAngle: number
(lines: Vec3[][], position: Vec3, rotation: Quat): Vec3[][]
```
+## planRagdoll — function @experimental
+```
+(bones: readonly RagdollBone[], options: { thickness: number; minBoneLength: number; }): RagdollLimb[]
+```
+
## readCollider3DShapes — function @experimental
```
(world: World, entity: number): Collider3DInstance[]
diff --git a/sdk/src/physics3d/Physics3DPlugin.ts b/sdk/src/physics3d/Physics3DPlugin.ts
index daa7f904d..789d7417b 100644
--- a/sdk/src/physics3d/Physics3DPlugin.ts
+++ b/sdk/src/physics3d/Physics3DPlugin.ts
@@ -5,6 +5,7 @@
* @brief Loads the 3D physics module and drives one world from the ECS.
*/
import { installPlanetGravity } from './planetGravity';
+import { installRagdolls } from './ragdoll';
import { Physics3DRuntime } from './physics3dRuntime';
import type { App, Plugin } from '../app/app';
import { Schedule, defineSystem } from '../ecs/system';
@@ -53,6 +54,8 @@ export class Physics3DPlugin implements Plugin {
app.insertResource(Physics3DRuntime, runtime);
// A planet in the world pulls bodies toward its centre; with none, this does nothing.
installPlanetGravity(app);
+ // A character with a Ragdoll component can go limp; with none, the systems find nothing.
+ installRagdolls(app);
app.subsystems?.transition?.('physics3d', 'initializing');
const initPromise = loadPhysics3DModule(this.wasmUrl_, this.factory_).then((module) => {
diff --git a/sdk/src/physics3d/index.ts b/sdk/src/physics3d/index.ts
index 30c5f69be..d178666e8 100644
--- a/sdk/src/physics3d/index.ts
+++ b/sdk/src/physics3d/index.ts
@@ -107,5 +107,6 @@ export {
// Importing this subpath INSTALLS 3D physics — see spine/index.ts.
import { registerPhysics3DSupport } from './physics3dSupport';
+export { Ragdoll, planRagdoll, type RagdollData, type RagdollBone, type RagdollLimb } from './ragdoll';
registerPhysics3DSupport();
diff --git a/sdk/src/physics3d/ragdoll.ts b/sdk/src/physics3d/ragdoll.ts
new file mode 100644
index 000000000..2ccf4d7df
--- /dev/null
+++ b/sdk/src/physics3d/ragdoll.ts
@@ -0,0 +1,319 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ragdoll.ts
+ * @brief A skinned character that goes limp: its bones become bodies joined by swing/twist limits, and give the pose back to the animation after.
+ *
+ * @details A `Ragdoll` is read off the skeleton a character already has (the joints its `MeshSkin` names), so there is nothing to author beyond the
+ * switch and a few numbers. Turning `active` on gives each bone that is long enough a box along the bone (a box, because a capsule is
+ * aligned to its body's y and a bone is not) and a `SwingTwistJoint3D` to the nearest bone above it that has one, at the pose the animation had that frame,
+ * so nothing snaps. The bodies are the ordinary 3D physics ones: the solver writes each bone's pose back through the hierarchy, and the
+ * skin follows. The animators on the character are held off while it is limp.
+ *
+ * Turning it off removes the bodies and lets the animation drive again, and over `recoverTime` seconds blends from the pose the body
+ * was in to the one the animation gives, so a character does not pop upright. That is the whole of a passive ragdoll; driving the limbs
+ * (a motor, a stand-up pose match) is left for later.
+ */
+import type { App } from '../app/app';
+import type { Entity, Quat, Vec3 } from '../types';
+import { defineSystem, Schedule } from '../ecs/system';
+import { Res, Time, type TimeData } from '../ecs/resource';
+import { playModeOnly } from '../ecs/env';
+import { defineComponent, getComponent, Parent, Transform, type ComponentDef, type ParentData, type TransformData } from '../ecs/component';
+import type { MeshSkinData } from '../ecs/component.generated';
+import { Animator, type AnimatorData } from '../animation/Animator';
+import { q } from '../math/quat';
+import { v3 } from '../math/vec3';
+import { RigidBody3D, BoxCollider3D } from './Physics3DComponents';
+import { SwingTwistJoint3D } from './AdvancedJoint3D';
+
+/** The fields of the `Ragdoll` component. @experimental */
+export interface RagdollData {
+ /** Whether the character is limp. Turn it on when it is knocked down, off to stand it up. */
+ active: boolean;
+ /** The entity that holds the `MeshSkin` whose joints are the skeleton; -1 is this entity. */
+ skin: number;
+ /** How far a limb may swing from its bone's line, in degrees, either way. */
+ swing: number;
+ /** How far a limb may twist about its own line, in degrees, either way. */
+ twist: number;
+ /** A limb's thickness as a fraction of its length. */
+ thickness: number;
+ /** A bone shorter than this (world units) gets no body of its own: a finger, a toe. Its parent carries it. */
+ minBoneLength: number;
+ friction: number;
+ /** Seconds to blend from the limp pose back to the animation once `active` is turned off. 0 pops. */
+ recoverTime: number;
+}
+
+/**
+ * A skinned character that can go limp.
+ *
+ * @experimental
+ */
+export const Ragdoll: ComponentDef<RagdollData> = defineComponent<RagdollData>('Ragdoll', {
+ active: false, skin: -1, swing: 45, twist: 30, thickness: 0.25, minBoneLength: 0.05, friction: 0.5, recoverTime: 0.4,
+}, {
+ entityFields: ['skin'],
+ fields: {
+ active: { category: 'Ragdoll', tooltip: 'Whether the character is limp. Turn it on when it is knocked down, off to stand it up.' },
+ skin: { category: 'Ragdoll', tooltip: 'The entity that holds the skinned mesh, whose joints are the skeleton. Empty is this entity.' },
+ swing: { min: 0, max: 175, category: 'Limits', tooltip: 'How far a limb may swing from its bone\'s line, in degrees.' },
+ twist: { min: 0, max: 175, category: 'Limits', tooltip: 'How far a limb may twist about its own line, in degrees.' },
+ thickness: { min: 0.01, max: 2, category: 'Bodies', tooltip: 'A limb\'s thickness as a fraction of its length.' },
+ minBoneLength: { min: 0, category: 'Bodies', tooltip: 'A bone shorter than this gets no body of its own (a finger, a toe): its parent carries it.' },
+ friction: { min: 0, category: 'Bodies' },
+ recoverTime: { min: 0, category: 'Recovery', tooltip: 'Seconds to blend from the limp pose back to the animation once the ragdoll is turned off.' },
+ },
+});
+
+/** A bone as the plan reads it: where it is in the world, and the nearest bone above it. */
+export interface RagdollBone {
+ id: number;
+ parent: number | null;
+ position: Vec3;
+ rotation: Quat;
+}
+
+/** What one limb is made of: a box in its bone's frame, and the joint to the limb above. */
+export interface RagdollLimb {
+ entity: number;
+ /** The limb whose body this one is joined to; null for the topmost, which hangs from nothing. */
+ connected: number | null;
+ halfExtents: Vec3;
+ center: Vec3;
+ /** The twist axis and a reference perpendicular to it, in this bone's own frame. */
+ axis: Vec3;
+ normalAxis: Vec3;
+}
+
+const EPS = 1e-9;
+
+/** A direction perpendicular to `a`. */
+function perpendicular(a: Vec3): Vec3 {
+ const ref = Math.abs(a.y) < 0.9 ? { x: 0, y: 1, z: 0 } : { x: 1, y: 0, z: 0 };
+ return v3.normalize(v3.cross(a, ref));
+}
+
+/**
+ * The limbs a skeleton is made into. Pure: bones in, limbs out, parents before children.
+ *
+ * A bone points at its longest child; one with no children (a hand, a head) takes its parent's line and half its length. A bone shorter than
+ * `minBoneLength` gets no limb, and what hangs from it hangs from the limb above.
+ *
+ * @experimental
+ */
+export function planRagdoll(bones: readonly RagdollBone[], options: { thickness: number; minBoneLength: number }): RagdollLimb[] {
+ const byId = new Map(bones.map((b) => [b.id, b]));
+ const children = new Map<number, RagdollBone[]>();
+ for (const b of bones) {
+ if (b.parent === null || !byId.has(b.parent)) continue;
+ let list = children.get(b.parent);
+ if (!list) children.set(b.parent, list = []);
+ list.push(b);
+ }
+ const limbs: RagdollLimb[] = [];
+ const limbOf = new Map<number, RagdollLimb>();
+ const lengthTo = (a: Vec3, b: Vec3): number => Math.hypot(b.x - a.x, b.y - a.y, b.z - a.z);
+
+ // Parents before children, from the roots down.
+ const roots = bones.filter((b) => b.parent === null || !byId.has(b.parent));
+ const order: RagdollBone[] = [];
+ const visit = (b: RagdollBone): void => { order.push(b); for (const c of children.get(b.id) ?? []) visit(c); };
+ for (const r of roots) visit(r);
+
+ for (const bone of order) {
+ // Where the bone points: at its longest child, else on along the line its parent came in by.
+ let target: Vec3 | null = null, length = 0;
+ for (const c of children.get(bone.id) ?? []) {
+ const d = lengthTo(bone.position, c.position);
+ if (d > length) { length = d; target = v3.sub(c.position, bone.position); }
+ }
+ if (!target) {
+ const above = bone.parent === null ? undefined : byId.get(bone.parent);
+ if (!above) continue;
+ const run = v3.sub(bone.position, above.position);
+ length = Math.hypot(run.x, run.y, run.z) / 2;
+ target = v3.scale(v3.normalize(run), length);
+ }
+ if (length < Math.max(options.minBoneLength, EPS)) continue;
+
+ // The bone's line and its box, in the bone's own frame (the collider is not scaled by the entity, so this is in world units).
+ const local = q.rotate(q.conjugate(bone.rotation), target);
+ const axisIndex = Math.abs(local.x) >= Math.abs(local.y) && Math.abs(local.x) >= Math.abs(local.z) ? 0 : Math.abs(local.y) >= Math.abs(local.z) ? 1 : 2;
+ const thickness = Math.max(length * options.thickness, 1e-4);
+ const half = [thickness, thickness, thickness];
+ half[axisIndex] = length / 2;
+ const axis = v3.normalize(local);
+
+ // Joined to the nearest bone above that has a limb.
+ let above = bone.parent === null ? undefined : byId.get(bone.parent);
+ while (above && !limbOf.has(above.id)) above = above.parent === null ? undefined : byId.get(above.parent);
+
+ const limb: RagdollLimb = {
+ entity: bone.id,
+ connected: above ? above.id : null,
+ halfExtents: { x: half[0]!, y: half[1]!, z: half[2]! },
+ center: { x: local.x / 2, y: local.y / 2, z: local.z / 2 },
+ axis,
+ normalAxis: perpendicular(axis),
+ };
+ limbs.push(limb);
+ limbOf.set(bone.id, limb);
+ }
+ return limbs;
+}
+
+/** What a ragdoll holds while it is limp: the bodies it made, and the animators it held off. */
+interface Limp {
+ limbs: Entity[];
+ /** Every bone of the skeleton, for the pose to be blended back. */
+ bones: Entity[];
+ animators: Entity[];
+}
+
+/** The pose a bone was left in, to blend from. */
+interface Recovery {
+ elapsed: number;
+ duration: number;
+ from: Map<Entity, { position: Vec3; rotation: Quat }>;
+}
+
+const smooth = (t: number): number => t * t * (3 - 2 * t);
+
+function nlerp(a: Quat, b: Quat, t: number): Quat {
+ const dot = a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w;
+ const s = dot < 0 ? -1 : 1;
+ return q.normalize({ w: a.w + (s * b.w - a.w) * t, x: a.x + (s * b.x - a.x) * t, y: a.y + (s * b.y - a.y) * t, z: a.z + (s * b.z - a.z) * t });
+}
+
+/** Installs the system that turns a `Ragdoll`'s switch into bodies, and back. Called once by the 3D physics plugin. */
+export function installRagdolls(app: App): void {
+ const limp = new Map<Entity, Limp>();
+ const recovering = new Map<Entity, Recovery>();
+ const world = app.world;
+
+ const skeletonOf = (entity: Entity, data: RagdollData): { skin: Entity; joints: Entity[] } | null => {
+ const skin = (data.skin >= 0 ? data.skin : entity) as Entity;
+ // By name: the skin's joints are a variable-length list the component table has no layout for.
+ const skinDef = getComponent('MeshSkin');
+ if (!skinDef || !world.valid(skin) || !world.has(skin, skinDef)) return null;
+ const joints = (world.get(skin, skinDef) as MeshSkinData).joints.filter((j) => world.valid(j) && world.has(j, Transform));
+ return joints.length > 0 ? { skin, joints } : null;
+ };
+
+ /** The animators that would fight the bodies: on the character, its skin, and what they hang from. */
+ const animatorsOf = (entity: Entity, skin: Entity): Entity[] => {
+ const found = new Set<Entity>();
+ for (const start of [entity, skin]) {
+ let e: Entity | undefined = start;
+ for (let guard = 0; e !== undefined && world.valid(e) && guard < 64; guard++) {
+ if (world.has(e, Animator)) found.add(e);
+ e = world.has(e, Parent) ? (world.get(e, Parent) as ParentData).entity : undefined;
+ }
+ }
+ return [...found];
+ };
+
+ const activate = (entity: Entity, data: RagdollData): void => {
+ const rig = skeletonOf(entity, data);
+ if (!rig) return;
+ world.ensureTransformsComposed();
+ const set = new Set<number>(rig.joints as number[]);
+ const nearestBone = (e: Entity): number | null => {
+ let p = world.has(e, Parent) ? (world.get(e, Parent) as ParentData).entity : undefined;
+ for (let guard = 0; p !== undefined && world.valid(p) && guard < 256; guard++) {
+ if (set.has(p)) return p as number;
+ p = world.has(p, Parent) ? (world.get(p, Parent) as ParentData).entity : undefined;
+ }
+ return null;
+ };
+ const bones: RagdollBone[] = rig.joints.map((j) => {
+ const t = world.get(j, Transform) as TransformData;
+ return {
+ id: j as number, parent: nearestBone(j),
+ position: { x: t.worldPosition.x, y: t.worldPosition.y, z: t.worldPosition.z },
+ rotation: { w: t.worldRotation.w, x: t.worldRotation.x, y: t.worldRotation.y, z: t.worldRotation.z },
+ };
+ });
+ const limbs = planRagdoll(bones, { thickness: data.thickness, minBoneLength: data.minBoneLength });
+ const swing = (data.swing * Math.PI) / 180, twist = (data.twist * Math.PI) / 180;
+ for (const limb of limbs) {
+ const e = limb.entity as Entity;
+ world.insert(e, RigidBody3D, { bodyType: 2, enabled: true });
+ world.insert(e, BoxCollider3D, { halfExtents: limb.halfExtents, center: limb.center, friction: data.friction, restitution: 0, isSensor: false, enabled: true });
+ if (limb.connected !== null) {
+ world.insert(e, SwingTwistJoint3D, {
+ connectedEntity: limb.connected, anchor: { x: 0, y: 0, z: 0 }, axis: limb.axis, normalAxis: limb.normalAxis,
+ enableMotor: false, angularVelocity: { x: 0, y: 0, z: 0 }, maxMotorTorque: 10, collideConnected: false, enabled: true,
+ normalHalfConeAngle: swing, planeHalfConeAngle: swing, twistMinAngle: -twist, twistMaxAngle: twist,
+ });
+ }
+ }
+ const animators = animatorsOf(entity, rig.skin);
+ for (const a of animators) {
+ const d = world.get(a, Animator) as AnimatorData;
+ if (d.enabled) world.insert(a, Animator, { ...d, enabled: false });
+ }
+ recovering.delete(entity);
+ limp.set(entity, { limbs: limbs.map((l) => l.entity as Entity), bones: rig.joints, animators });
+ };
+
+ const deactivate = (entity: Entity, data: RagdollData): void => {
+ const held = limp.get(entity);
+ if (!held) return;
+ limp.delete(entity);
+ // The pose the bodies were left in, before they are taken away.
+ const from = new Map<Entity, { position: Vec3; rotation: Quat }>();
+ for (const bone of held.bones) {
+ if (!world.valid(bone)) continue;
+ const t = world.get(bone, Transform) as TransformData;
+ from.set(bone, {
+ position: { x: t.position.x, y: t.position.y, z: t.position.z },
+ rotation: { w: t.rotation.w, x: t.rotation.x, y: t.rotation.y, z: t.rotation.z },
+ });
+ }
+ for (const e of held.limbs) {
+ if (!world.valid(e)) continue;
+ world.remove(e, SwingTwistJoint3D);
+ world.remove(e, BoxCollider3D);
+ world.remove(e, RigidBody3D);
+ }
+ for (const a of held.animators) {
+ if (!world.valid(a)) continue;
+ const d = world.get(a, Animator) as AnimatorData;
+ world.insert(a, Animator, { ...d, enabled: true });
+ }
+ if (data.recoverTime > 0) recovering.set(entity, { elapsed: 0, duration: data.recoverTime, from });
+ };
+
+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {
+ for (const entity of world.getEntitiesWithComponents([Ragdoll])) {
+ const data = world.get(entity, Ragdoll) as RagdollData;
+ const isLimp = limp.has(entity);
+ if (data.active && !isLimp) activate(entity, data);
+ else if (!data.active && isLimp) deactivate(entity, data);
+ }
+ for (const entity of [...limp.keys()]) if (!world.valid(entity)) limp.delete(entity);
+ for (const entity of [...recovering.keys()]) if (!world.valid(entity)) recovering.delete(entity);
+ }, { name: 'RagdollSystem' }), { runIf: playModeOnly });
+
+ // After the animation has written its pose for the frame: the blend is between that and where the body was.
+ app.addSystemToSchedule(Schedule.PostUpdate, defineSystem([Res(Time)], (time: TimeData) => {
+ for (const [entity, r] of recovering) {
+ r.elapsed += time.delta;
+ const w = smooth(Math.min(r.elapsed / r.duration, 1));
+ for (const [bone, was] of r.from) {
+ if (!world.valid(bone)) continue;
+ const t = world.get(bone, Transform) as TransformData;
+ t.position.x = was.position.x + (t.position.x - was.position.x) * w;
+ t.position.y = was.position.y + (t.position.y - was.position.y) * w;
+ t.position.z = was.position.z + (t.position.z - was.position.z) * w;
+ const r2 = nlerp(was.rotation, { w: t.rotation.w, x: t.rotation.x, y: t.rotation.y, z: t.rotation.z }, w);
+ t.rotation.x = r2.x; t.rotation.y = r2.y; t.rotation.z = r2.z; t.rotation.w = r2.w;
+ world.set(bone, Transform, t);
+ }
+ if (r.elapsed >= r.duration) recovering.delete(entity);
+ }
+ }, { name: 'RagdollRecoverSystem' }), { runIf: playModeOnly });
+}
diff --git a/sdk/tests/ragdoll.test.ts b/sdk/tests/ragdoll.test.ts
new file mode 100644
index 000000000..0e190596b
--- /dev/null
+++ b/sdk/tests/ragdoll.test.ts
@@ -0,0 +1,210 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { World } from '../src/ecs/world';
+import { Transform, Parent, getComponent, ensureBuiltinComponentsRegistered } from '../src/ecs/component';
+import { Animator } from '../src/animation/Animator';
+import type { CppRegistry, ESEngineModule } from '../src/wasm';
+import { Ragdoll, planRagdoll, installRagdolls, type RagdollBone, type RagdollData } from '../src/physics3d/ragdoll';
+import { RigidBody3D, BoxCollider3D } from '../src/physics3d/Physics3DComponents';
+import { SwingTwistJoint3D } from '../src/physics3d/AdvancedJoint3D';
+import { HAS_WASM, WASM_DIR, loadWasmModule } from './helpers/loadWasm';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { loadPhysics3DModule, type Physics3DModuleFactory } from '../src/physics3d/Physics3DModule';
+import { stepPhysics3D, DEFAULT_PHYSICS3D_CONFIG } from '../src/physics3d/Physics3DSystem';
+
+const bone = (id: number, parent: number | null, x: number, y: number, z = 0, rotation = { w: 1, x: 0, y: 0, z: 0 }): RagdollBone =>
+ ({ id, parent, position: { x, y, z }, rotation });
+const options = { thickness: 0.25, minBoneLength: 0.05 };
+
+describe('planRagdoll', () => {
+ it('gives each bone a box along the line to its child, joined to the bone above', () => {
+ const limbs = planRagdoll([bone(1, null, 0, 0), bone(2, 1, 0, 1), bone(3, 2, 0, 2)], options);
+ expect(limbs.map((l) => [l.entity, l.connected])).toEqual([[1, null], [2, 1], [3, 2]]);
+ const [pelvis] = limbs;
+ // 1 long, along y: half 0.5 along it and a quarter of the length across.
+ expect(pelvis!.halfExtents).toEqual({ x: 0.25, y: 0.5, z: 0.25 });
+ expect(pelvis!.center).toEqual({ x: 0, y: 0.5, z: 0 });
+ expect(pelvis!.axis).toEqual({ x: 0, y: 1, z: 0 });
+ });
+
+ it('takes the line and half the length of the bone above for one with no child', () => {
+ const limbs = planRagdoll([bone(1, null, 0, 0), bone(2, 1, 0, 2)], options);
+ const hand = limbs.find((l) => l.entity === 2)!;
+ expect(hand.halfExtents.y).toBeCloseTo(0.5);
+ expect(hand.center.y).toBeCloseTo(0.5);
+ });
+
+ it('puts the long side along whichever of the bone\'s own axes the line follows', () => {
+ // Turned a quarter about z, so the bone\'s local x is the world\'s y.
+ const s = Math.SQRT1_2;
+ const limbs = planRagdoll([bone(1, null, 0, 0, 0, { w: s, x: 0, y: 0, z: s }), bone(2, 1, 0, 2)], options);
+ const first = limbs[0]!;
+ expect(first.halfExtents.x).toBeCloseTo(1);
+ expect(first.halfExtents.y).toBeCloseTo(0.5);
+ expect(first.axis.x).toBeCloseTo(1);
+ expect(first.center.x).toBeCloseTo(1);
+ });
+
+ it('leaves a short bone without a limb, and the bone above carries it', () => {
+ // A fingertip 0.01 past the wrist: neither it nor the nub beyond it is long enough for a body.
+ const limbs = planRagdoll([bone(1, null, 0, 0), bone(2, 1, 0, 1), bone(3, 2, 0, 2), bone(4, 3, 0, 2.01)], options);
+ expect(limbs.map((l) => l.entity)).toEqual([1, 2]);
+ expect(limbs.find((l) => l.entity === 2)!.connected).toBe(1);
+ });
+
+ it('joins what hangs from a bone with no limb to the limb above it', () => {
+ // Bone 2 is 0.01 long (to its only child), so it has none; bone 3 is joined straight to bone 1.
+ const limbs = planRagdoll([bone(1, null, 0, 0), bone(2, 1, 0, 1), bone(3, 2, 0, 1.01), bone(4, 3, 0, 2)], options);
+ expect(limbs.some((l) => l.entity === 2)).toBe(false);
+ expect(limbs.find((l) => l.entity === 3)!.connected).toBe(1);
+ });
+
+ it('gives a twist reference that is perpendicular to the twist axis', () => {
+ for (const l of planRagdoll([bone(1, null, 0, 0), bone(2, 1, 1, 1, 0.5), bone(3, 2, 2, 1, 1)], options)) {
+ expect(l.axis.x * l.normalAxis.x + l.axis.y * l.normalAxis.y + l.axis.z * l.normalAxis.z).toBeCloseTo(0, 6);
+ }
+ });
+
+ it('is nothing from nothing, or from a single bone', () => {
+ expect(planRagdoll([], options)).toEqual([]);
+ expect(planRagdoll([bone(1, null, 0, 0)], options)).toEqual([]);
+ });
+});
+
+describe.skipIf(!HAS_WASM)('the Ragdoll system', () => {
+ let engine: ESEngineModule, registry: CppRegistry, world: World;
+ beforeAll(async () => { engine = await loadWasmModule(); });
+ beforeEach(() => { ensureBuiltinComponentsRegistered(); registry = new engine.Registry(); world = new World(); world.connectCpp(registry, engine); });
+ afterEach(() => { for (const e of world.getAllEntities()) world.despawn(e); world.disconnectCpp(); registry.delete(); });
+
+ /** A character: a root with an Animator and a Ragdoll, and a skin whose three joints hang one from the next. */
+ function character(over: Partial<RagdollData> = {}) {
+ const systems: Array<{ _fn: (...a: unknown[]) => void }> = [];
+ const app = { world, addSystemToSchedule: (_s: unknown, def: { _fn: () => void }) => { systems.push(def); } };
+ installRagdolls(app as never);
+ const root = world.spawn();
+ world.insert(root, Transform);
+ world.insert(root, Animator, { controller: '', avatar: '', currentState: '', layerStates: [], enabled: true });
+ const joints: number[] = [];
+ let parent: number = root as number;
+ for (let i = 0; i < 3; i++) {
+ const j = world.spawn();
+ world.insert(j, Transform, { position: { x: 0, y: i === 0 ? 0 : 1, z: 0 } });
+ world.insert(j, Parent, { entity: parent });
+ joints.push(j as number);
+ parent = j as number;
+ }
+ const skin = getComponent('MeshSkin')!;
+ world.insert(root, skin, { joints });
+ world.insert(root, Ragdoll, { active: false, skin: -1, swing: 45, twist: 30, thickness: 0.25, minBoneLength: 0.05, friction: 0.5, recoverTime: 0, ...over });
+ return { root, joints, run: () => { for (const s of systems) s._fn({ delta: 0.016 }); } };
+ }
+
+ it('gives the bones bodies and joints when it goes limp, and holds the animator off', () => {
+ const { root, joints, run } = character();
+ run();
+ expect(world.has(joints[0] as never, RigidBody3D)).toBe(false);
+ world.insert(root, Ragdoll, { ...(world.get(root, Ragdoll) as RagdollData), active: true });
+ run();
+ for (const j of joints) {
+ expect(world.has(j as never, RigidBody3D)).toBe(true);
+ expect(world.has(j as never, BoxCollider3D)).toBe(true);
+ }
+ // The topmost hangs from nothing; the others from the one above.
+ expect(world.has(joints[0] as never, SwingTwistJoint3D)).toBe(false);
+ expect((world.get(joints[1] as never, SwingTwistJoint3D) as { connectedEntity: number }).connectedEntity).toBe(joints[0]);
+ expect((world.get(root, Animator) as { enabled: boolean }).enabled).toBe(false);
+ });
+
+ it('takes the bodies away and gives the animator back when it stands up', () => {
+ const { root, joints, run } = character();
+ world.insert(root, Ragdoll, { ...(world.get(root, Ragdoll) as RagdollData), active: true });
+ run();
+ world.insert(root, Ragdoll, { ...(world.get(root, Ragdoll) as RagdollData), active: false });
+ run();
+ for (const j of joints) {
+ expect(world.has(j as never, RigidBody3D)).toBe(false);
+ expect(world.has(j as never, SwingTwistJoint3D)).toBe(false);
+ }
+ expect((world.get(root, Animator) as { enabled: boolean }).enabled).toBe(true);
+ });
+});
+
+const HAS_SOLVER = HAS_WASM && existsSync(resolve(WASM_DIR, 'physics3d.wasm'));
+
+/** The real solver: a character dropped on a floor falls, comes to rest on it, and stays in one piece. */
+describe.skipIf(!HAS_SOLVER)('a ragdoll under the real solver', () => {
+ let engine: ESEngineModule;
+ beforeAll(async () => { engine = await loadWasmModule(); });
+
+ it('falls onto the floor with its bones still joined', async () => {
+ const raw = (await import(/* @vite-ignore */ pathToFileURL(resolve(WASM_DIR, 'physics3d.js')).href)) as { default: (o: object) => Promise<never> };
+ const wasmBinary = readFileSync(resolve(WASM_DIR, 'physics3d.wasm'));
+ const factory = (() => raw.default({ wasmBinary })) as unknown as Physics3DModuleFactory;
+ const module = await loadPhysics3DModule('', factory);
+ const config = { ...DEFAULT_PHYSICS3D_CONFIG, pixelsPerUnit: 1 };
+ module._physics3d_init(0, -9.81, 0, 256);
+
+ ensureBuiltinComponentsRegistered();
+ const registry = new engine.Registry();
+ const world = new World();
+ world.connectCpp(registry, engine);
+ try {
+ // A floor, its top at y = 0.
+ const floor = world.spawn();
+ world.insert(floor, Transform, { position: { x: 0, y: -1, z: 0 } });
+ world.insert(floor, RigidBody3D, { bodyType: 0, enabled: true });
+ world.insert(floor, BoxCollider3D, { halfExtents: { x: 50, y: 1, z: 50 }, center: { x: 0, y: 0, z: 0 }, friction: 0.5, restitution: 0, isSensor: false, enabled: true });
+
+ // Three bones one above the next, a metre apart, the lowest at y = 3.
+ const systems: Array<{ _fn: (...a: unknown[]) => void }> = [];
+ const app = { world, addSystemToSchedule: (_s: unknown, def: { _fn: () => void }) => { systems.push(def); } };
+ installRagdolls(app as never);
+ const root = world.spawn();
+ world.insert(root, Transform);
+ const joints: Entity[] = [];
+ let parent: Entity = root;
+ for (let i = 0; i < 4; i++) {
+ const j = world.spawn();
+ world.insert(j, Transform, { position: { x: 0, y: i === 0 ? 3 : 1, z: 0 } });
+ world.insert(j, Parent, { entity: parent });
+ joints.push(j);
+ parent = j;
+ }
+ world.insert(root, getComponent('MeshSkin')!, { joints });
+ world.insert(root, Ragdoll, { active: true, skin: -1, swing: 45, twist: 30, thickness: 0.2, minBoneLength: 0.05, friction: 0.5, recoverTime: 0 });
+ for (const s of systems) s._fn({ delta: 1 / 60 });
+
+ const bodies = new Map<Entity, number>(), joint3 = new Map<never, never>();
+ const at = (e: Entity): { x: number; y: number; z: number } => (world.get(e, Transform) as { worldPosition: { x: number; y: number; z: number } }).worldPosition;
+ for (let i = 0; i < 240; i++) {
+ stepPhysics3D({ world } as never, module, bodies, config, new Map(), undefined, joint3 as never, new Map(), null);
+ }
+ world.ensureTransformsComposed();
+
+ for (const j of joints) {
+ const p = at(j);
+ expect(Number.isFinite(p.x + p.y + p.z)).toBe(true);
+ // Fell from 3 to 6, and is lying on or above the floor.
+ expect(p.y).toBeLessThan(6);
+ expect(p.y).toBeGreaterThan(-0.1);
+ }
+ // The topmost bone has come down from where it was.
+ expect(at(joints[0]!).y).toBeLessThan(2.5);
+ // Still one body: each bone about its length from the one above (the joint holds them there).
+ for (let i = 1; i < joints.length; i++) {
+ const a = at(joints[i - 1]!), b = at(joints[i]!);
+ expect(Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z)).toBeGreaterThan(0.7);
+ expect(Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z)).toBeLessThan(1.3);
+ }
+ } finally {
+ for (const e of world.getAllEntities()) world.despawn(e);
+ world.disconnectCpp();
+ registry.delete();
+ module._physics3d_shutdown();
+ }
+ });
+});