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): a ragdoll's joints are limited by their part of the body (spine stiff, shoulder loose, shin almost a hinge), read from bone names

yhh11f9365d7843
diff --git a/sdk/etc/physics3d.api.md b/sdk/etc/physics3d.api.md
index 32345e8ec..45739044f 100644
--- a/sdk/etc/physics3d.api.md
+++ b/sdk/etc/physics3d.api.md
@@ -1,7 +1,17 @@
# API surface — esengine/physics3d
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 0 public · 0 beta · 69 experimental · 0 deprecated
+Symbols: 0 public · 0 beta · 73 experimental · 0 deprecated
+
+## BONE_LIMITS — const @experimental
+```
+Readonly<Record<BoneClass, { swing: number; twist: number; }>>
+```
+
+## BoneClass — type @experimental
+```
+'spine' | 'neck' | 'head' | 'shoulder' | 'upperArm' | 'forearm' | 'hand' | 'thigh' | 'shin' | 'foot' | 'toe' | 'other'
+```
## BoxCollider3D — const @experimental
```
@@ -373,6 +383,7 @@ ComponentDef<RagdollData>
## RagdollBone — interface @experimental
```
id: number
+name: string | undefined
parent: number | null
position: Vec3
rotation: Quat
@@ -383,6 +394,7 @@ rotation: Quat
active: boolean
friction: number
minBoneLength: number
+profile: number
recoverTime: number
skin: number
swing: number
@@ -398,6 +410,13 @@ connected: number | null
entity: number
halfExtents: Vec3
normalAxis: Vec3
+swing: number
+twist: number
+```
+
+## RagdollProfile — const @experimental
+```
+{ readonly Uniform: 0; readonly Humanoid: 1; }
```
## RigidBody3D — const @experimental
@@ -512,6 +531,11 @@ twistMinAngle: number
(module: unknown): void
```
+## classifyBone — function @experimental
+```
+(name: string | undefined): BoneClass
+```
+
## collider3DWireframe — function @experimental
```
(shape: Collider3DShape, segments?: number): Vec3[][]
@@ -549,7 +573,7 @@ twistMinAngle: number
## planRagdoll — function @experimental
```
-(bones: readonly RagdollBone[], options: { thickness: number; minBoneLength: number; }): RagdollLimb[]
+(bones: readonly RagdollBone[], options: { thickness: number; minBoneLength: number; profile?: number; }): RagdollLimb[]
```
## readCollider3DShapes — function @experimental
diff --git a/sdk/src/physics3d/index.ts b/sdk/src/physics3d/index.ts
index d178666e8..25c8a1a11 100644
--- a/sdk/src/physics3d/index.ts
+++ b/sdk/src/physics3d/index.ts
@@ -107,6 +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';
+export { Ragdoll, RagdollProfile, classifyBone, BONE_LIMITS, planRagdoll, type BoneClass, type RagdollData, type RagdollBone, type RagdollLimb } from './ragdoll';
registerPhysics3DSupport();
diff --git a/sdk/src/physics3d/ragdoll.ts b/sdk/src/physics3d/ragdoll.ts
index ac3a45563..afb759624 100644
--- a/sdk/src/physics3d/ragdoll.ts
+++ b/sdk/src/physics3d/ragdoll.ts
@@ -19,7 +19,7 @@ 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, Children, Transform, type ComponentDef, type ParentData, type ChildrenData, type TransformData } from '../ecs/component';
+import { defineComponent, getComponent, Name, Parent, Children, Transform, type ComponentDef, type ParentData, type ChildrenData, type TransformData } from '../ecs/component';
import type { MeshSkinData } from '../ecs/component.generated';
import { q } from '../math/quat';
import { log } from '../util/logger';
@@ -27,15 +27,25 @@ import { v3 } from '../math/vec3';
import { RigidBody3D, BoxCollider3D } from './Physics3DComponents';
import { SwingTwistJoint3D } from './AdvancedJoint3D';
+/** How a ragdoll's joints are limited. */
+export const RagdollProfile = {
+ /** Every joint gets `swing` and `twist`. */
+ Uniform: 0,
+ /** Each joint gets the share of them its part of a body has, read from the bone's name: a spine stiff, a shoulder loose, a shin almost a hinge. A bone the names do not place gets all of it. */
+ Humanoid: 1,
+} as const;
+
/** 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. 0 looks on this entity and then below it. */
skin: number;
- /** How far a limb may swing from its bone's line, in degrees, either way. */
+ /** {@link RagdollProfile}: whether every joint gets the same limits, or each the limits its part of a body has. */
+ profile: number;
+ /** How far a limb may swing from its bone's line, in degrees, either way. With the humanoid profile this is the most a loose joint (a shoulder, a hip) is given. */
swing: number;
- /** How far a limb may twist about its own line, in degrees, either way. */
+ /** How far a limb may twist about its own line, in degrees, either way. With the humanoid profile this is the most a loose joint is given. */
twist: number;
/** A limb's thickness as a fraction of its length. */
thickness: number;
@@ -52,14 +62,15 @@ export interface RagdollData {
* @experimental
*/
export const Ragdoll: ComponentDef<RagdollData> = defineComponent<RagdollData>('Ragdoll', {
- active: false, skin: 0, swing: 70, twist: 45, thickness: 0.25, minBoneLength: 0.05, friction: 0.5, recoverTime: 0.4,
+ active: false, skin: 0, profile: RagdollProfile.Humanoid, swing: 100, twist: 60, 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 looks on this entity and then below it.' },
- 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.' },
+ profile: { enum: [{ label: 'Uniform', value: RagdollProfile.Uniform }, { label: 'Humanoid', value: RagdollProfile.Humanoid }], category: 'Limits', tooltip: 'Uniform gives every joint the same limits. Humanoid gives each the share of them its part of a body has, read from the bone\'s name: a spine stiff, a shoulder loose, a shin almost a hinge.' },
+ swing: { min: 0, max: 175, category: 'Limits', tooltip: 'How far a limb may swing from its bone\'s line, in degrees. With the humanoid profile, the most a loose joint (a shoulder, a hip) is given.' },
+ twist: { min: 0, max: 175, category: 'Limits', tooltip: 'How far a limb may twist about its own line, in degrees. With the humanoid profile, the most a loose joint is given.' },
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' },
@@ -70,6 +81,8 @@ export const Ragdoll: ComponentDef<RagdollData> = defineComponent<RagdollData>('
/** A bone as the plan reads it: where it is in the world, and the nearest bone above it. */
export interface RagdollBone {
id: number;
+ /** What the bone is called, which is how the humanoid profile tells a knee from a shoulder. */
+ name?: string;
parent: number | null;
position: Vec3;
rotation: Quat;
@@ -85,6 +98,54 @@ export interface RagdollLimb {
/** The twist axis and a reference perpendicular to it, in this bone's own frame. */
axis: Vec3;
normalAxis: Vec3;
+ /** The share (0 to 1) of the component's swing and twist this joint gets. */
+ swing: number;
+ twist: number;
+}
+
+/** The parts of a body whose joints are limited differently. */
+export type BoneClass = 'spine' | 'neck' | 'head' | 'shoulder' | 'upperArm' | 'forearm' | 'hand' | 'thigh' | 'shin' | 'foot' | 'toe' | 'other';
+
+/** The share of the swing and twist each part gets: a trunk bends little, a shoulder and a hip go round, a knee and an elbow are almost hinges. */
+export const BONE_LIMITS: Readonly<Record<BoneClass, { swing: number; twist: number }>> = {
+ spine: { swing: 0.3, twist: 0.35 },
+ neck: { swing: 0.45, twist: 0.6 },
+ head: { swing: 0.4, twist: 0.6 },
+ shoulder: { swing: 0.25, twist: 0.15 },
+ upperArm: { swing: 1, twist: 0.8 },
+ forearm: { swing: 0.8, twist: 0.1 },
+ hand: { swing: 0.45, twist: 0.25 },
+ thigh: { swing: 0.75, twist: 0.4 },
+ shin: { swing: 0.9, twist: 0.08 },
+ foot: { swing: 0.35, twist: 0.2 },
+ toe: { swing: 0.25, twist: 0.08 },
+ other: { swing: 1, twist: 1 },
+};
+
+/**
+ * Which part of a body a bone is, from its name (Rigify's `DEF-upper_arm.L`, Mixamo's `LeftArm`, a plain `forearm_r`). The checks go from the more specific to the less, because
+ * a forearm is also an arm and a shin a leg.
+ *
+ * @experimental
+ */
+export function classifyBone(name: string | undefined): BoneClass {
+ const n = (name ?? '').toLowerCase().replace(/[^a-z]/g, '');
+ if (!n) return 'other';
+ if (/toe/.test(n)) return 'toe';
+ if (/foot|ankle/.test(n)) return 'foot';
+ if (/shin|calf|lowerleg|knee/.test(n)) return 'shin';
+ if (/thigh|upperleg|upleg/.test(n)) return 'thigh';
+ if (/hand|wrist|palm/.test(n)) return 'hand';
+ if (/forearm|lowerarm|elbow/.test(n)) return 'forearm';
+ if (/upperarm|uparm/.test(n)) return 'upperArm';
+ if (/shoulder|clavicle|collar/.test(n)) return 'shoulder';
+ if (/neck/.test(n)) return 'neck';
+ if (/head/.test(n)) return 'head';
+ if (/spine|chest|torso|abdomen|belly/.test(n)) return 'spine';
+ // A bare "arm" or "leg": Mixamo's LeftArm is the upper arm, its LeftLeg the thigh.
+ if (/arm/.test(n)) return 'upperArm';
+ if (/leg/.test(n)) return 'thigh';
+ return 'other';
}
const EPS = 1e-9;
@@ -103,7 +164,7 @@ function perpendicular(a: Vec3): Vec3 {
*
* @experimental
*/
-export function planRagdoll(bones: readonly RagdollBone[], options: { thickness: number; minBoneLength: number }): RagdollLimb[] {
+export function planRagdoll(bones: readonly RagdollBone[], options: { thickness: number; minBoneLength: number; profile?: number }): RagdollLimb[] {
const byId = new Map(bones.map((b) => [b.id, b]));
const children = new Map<number, RagdollBone[]>();
for (const b of bones) {
@@ -157,6 +218,7 @@ export function planRagdoll(bones: readonly RagdollBone[], options: { thickness:
center: { x: local.x / 2, y: local.y / 2, z: local.z / 2 },
axis,
normalAxis: perpendicular(axis),
+ ...(options.profile === RagdollProfile.Uniform ? { swing: 1, twist: 1 } : BONE_LIMITS[classifyBone(bone.name)]),
};
limbs.push(limb);
limbOf.set(bone.id, limb);
@@ -256,13 +318,14 @@ export function installRagdolls(app: App): void {
const t = world.get(j, Transform) as TransformData;
return {
id: j as number, parent: nearestBone(j),
+ name: world.has(j, Name) ? (world.get(j, Name) as { value: string }).value : undefined,
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 limbs = planRagdoll(bones, { thickness: data.thickness, minBoneLength: data.minBoneLength, profile: data.profile });
log.info('physics3d', `Ragdoll on entity ${entity}: ${limbs.length} limbs from ${bones.length} bones`);
- const swing = (data.swing * Math.PI) / 180, twist = (data.twist * Math.PI) / 180;
+ const rad = (deg: number): number => (Math.min(Math.max(deg, 0), 175) * Math.PI) / 180;
for (const limb of limbs) {
const e = limb.entity as Entity;
world.insert(e, RigidBody3D, { bodyType: 2, enabled: true });
@@ -271,7 +334,8 @@ export function installRagdolls(app: App): void {
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,
+ normalHalfConeAngle: rad(data.swing * limb.swing), planeHalfConeAngle: rad(data.swing * limb.swing),
+ twistMinAngle: -rad(data.twist * limb.twist), twistMaxAngle: rad(data.twist * limb.twist),
});
}
}
diff --git a/sdk/tests/ragdoll.test.ts b/sdk/tests/ragdoll.test.ts
index a5cd3b4c8..e216dc415 100644
--- a/sdk/tests/ragdoll.test.ts
+++ b/sdk/tests/ragdoll.test.ts
@@ -4,7 +4,7 @@ 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 type { CppRegistry, ESEngineModule } from '../src/wasm';
-import { Ragdoll, planRagdoll, installRagdolls, type RagdollBone, type RagdollData } from '../src/physics3d/ragdoll';
+import { Ragdoll, RagdollProfile, classifyBone, BONE_LIMITS, 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';
@@ -204,3 +204,38 @@ describe.skipIf(!HAS_SOLVER)('a ragdoll under the real solver', () => {
}
});
});
+
+describe('limits by joint', () => {
+ it('places a bone by its name, whichever rig spelled it', () => {
+ const cases: Array<[string, string]> = [
+ ['DEF-spine.002', 'spine'], ['DEF-neck', 'neck'], ['DEF-head', 'head'], ['DEF-shoulder.L', 'shoulder'],
+ ['DEF-upper_arm.L', 'upperArm'], ['DEF-forearm.R', 'forearm'], ['DEF-hand.L', 'hand'],
+ ['DEF-thigh.L', 'thigh'], ['DEF-shin.R', 'shin'], ['DEF-foot.L', 'foot'], ['DEF-toe.R', 'toe'],
+ ['upperarm.l', 'upperArm'], ['forearm.l', 'forearm'], ['mixamorig:LeftArm', 'upperArm'], ['mixamorig:LeftForeArm', 'forearm'],
+ ['mixamorig:RightUpLeg', 'thigh'], ['mixamorig:RightLeg', 'thigh'], ['mixamorig:LeftToeBase', 'toe'],
+ ['DEF-hips', 'other'], ['root', 'other'], ['', 'other'],
+ ];
+ for (const [name, expected] of cases) expect(classifyBone(name), name).toBe(expected);
+ });
+
+ it('gives a stiff trunk, a loose shoulder and a shin that is nearly a hinge', () => {
+ expect(BONE_LIMITS.spine.swing).toBeLessThan(BONE_LIMITS.upperArm.swing);
+ expect(BONE_LIMITS.shin.twist).toBeLessThan(0.15);
+ expect(BONE_LIMITS.upperArm.twist).toBeGreaterThan(BONE_LIMITS.forearm.twist);
+ for (const l of Object.values(BONE_LIMITS)) { expect(l.swing).toBeGreaterThan(0); expect(l.swing).toBeLessThanOrEqual(1); }
+ });
+
+ it('limits each limb by its part of the body, unless the profile is uniform', () => {
+ const named = (id: number, parent: number | null, y: number, name: string): RagdollBone => ({ ...bone(id, parent, 0, y), name });
+ const chain = [named(1, null, 0, 'DEF-hips'), named(2, 1, 1, 'DEF-spine.001'), named(3, 2, 2, 'DEF-thigh.L'), named(4, 3, 3, 'DEF-shin.L'), named(5, 4, 4, 'DEF-foot.L')];
+ const humanoid = planRagdoll(chain, { ...options, profile: RagdollProfile.Humanoid });
+ const byId = (id: number) => humanoid.find((l) => l.entity === id)!;
+ expect(byId(2).swing).toBe(BONE_LIMITS.spine.swing);
+ expect(byId(3).swing).toBe(BONE_LIMITS.thigh.swing);
+ expect(byId(4).twist).toBe(BONE_LIMITS.shin.twist);
+ // A bone the names do not place takes the whole of it.
+ expect(byId(1).swing).toBe(1);
+ const uniform = planRagdoll(chain, { ...options, profile: RagdollProfile.Uniform });
+ expect(uniform.every((l) => l.swing === 1 && l.twist === 1)).toBe(true);
+ });
+});