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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.tsindex 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.mdindex 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: numberenabled: 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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();+ }+ });+});