@web-engine-dev/ragdoll

Physics-driven ragdoll system with active ragdoll controllers that blend seamlessly between animated and physics-driven states. Characters transition naturally from gameplay animation to ragdoll on impact and can recover back to animated state with configurable blend curves.

Layer 4 · Simulation

Features

• Automatic Ragdoll Generation: Create ragdolls from skeleton hierarchies
• Humanoid Preset: 15-bone ragdoll with realistic mass distribution
• Active Ragdoll: PD controllers drive bones toward animation targets while respecting physics
• Partial Ragdoll: Specific body parts go ragdoll while the rest stays animated
• State Machine: Inactive → Blending In → Active → Blending Out → Inactive
• Per-Joint Control: Independent animation-to-physics blend weight per joint
• Joint Limits: Cone-twist (shoulders), hinge (elbows/knees), ball-socket (spine)
• Recovery Animation: Blend from ragdoll back to animated state

Installation

npm install @web-engine-dev/ragdoll
# or
pnpm add @web-engine-dev/ragdoll

Quick Start

import { RagdollSystem, createHumanoidRagdollDefinition } from '@web-engine-dev/ragdoll';

// Auto-generate a 15-bone humanoid ragdoll
const ragdollDef = createHumanoidRagdollDefinition({
  totalMass: 70, // kg
  scale: 1.0,
});

// Create ragdoll from skeleton
const ragdoll = new RagdollSystem(skeleton, ragdollDef, physicsWorld);

// Activate ragdoll on impact
ragdoll.activate({
  blendDuration: 0.2, // seconds to transition from animation to physics
});

// Partial ragdoll — only the right arm goes limp
ragdoll.setJointStrength('rightShoulder', 0);
ragdoll.setJointStrength('rightElbow', 0);

// Recover back to animation
ragdoll.deactivate({
  blendDuration: 0.5,
  recoveryAnimation: 'getUp',
});

Ragdoll State Machine

Inactive (animation-driven)
    → Blending In (animation → physics)
        → Active (fully physics-driven)
            → Blending Out (physics → animation)
                → Inactive (recovered)

Active Ragdoll (PD Controllers)

Each joint uses a Proportional-Derivative controller to track animation target poses:

torque = kp × rotationError - kd × angularVelocity

• kp (proportional): Pulls bones toward animation target pose
• kd (derivative): Damps oscillation for smooth motion
• Strength (0–1): Per-joint blend weight — 0 = full ragdoll, 1 = tracks animation exactly

Humanoid Preset

createHumanoidRagdollDefinition(totalMass, scale) generates:

• 15 bones with realistic mass distribution (head 8%, torso 46%, limbs proportional)
• Cone-twist joints for shoulders
• Hinge joints for elbows and knees with anatomical limits
• Ball-socket chain for spine
• Collision groups prevent adjacent bones from colliding

Custom skeletons (quadrupeds, robots, tentacles) define their own bone configs with the same joint types.

Dependencies

• @web-engine-dev/math — Vector and quaternion types
• @web-engine-dev/physics3d — Rigid bodies and joint constraints
• @web-engine-dev/animation — Skeleton and pose types