# crashDummies
Ragdoll crash test dummies for vehicle crash tests. Installing it gives a world six dummy kinds in
five looks, made of rigid bodies with realistic segment masses, anatomical joint limits and
"muscle tone". They sit in any vehicle that carries a seat frame and belt anchors, held by
compliant seat belts you can see, with accelerometers on the head, chest and pelvis. It also ships
a tow-sled test rig as a working example.
- `dummies.module`: the API, `require("crashDummies.dummies")`.
- `sled.module`: a test sled + tow rig, `require("crashDummies.sled")` (example / standalone tests).
The tow brakes the sled to rest within about 0.5 s of the rebound, so it settles at the wall.
- `CrashDummy.component`: on each dummy root; draws the webbing (every peer) and runs the belts (simulating peer).
- `examples/DummySledDemo.component` + `examples/dummiesDemo.scene`: the first working example.
- `materials/`: 21 `.material` assets (five looks, webbing, buckle, booster, child seat).
## Install
Install the package into the world (`zeromind.install` with its guid), then
`require("crashDummies.dummies")` works from any script by its bare name.
## First working example
Copy-paste into a script or an `execute` call while the world is in play. It builds a test lane at
the origin, seats a belted Hybrid III 50th on the package's sled, tows it into the wall at 50 km/h
and prints the peaks. (This exact code passes the strict checker.)
```lua
local Dummies = require("crashDummies.dummies")
local Sled = require("crashDummies.sled")
-- a test lane at the origin: rigid wall face at z = 0, sled 75 m up the lane
local rig = Sled.build({ x = 0, y = 0, wallZ = 0, startZ = 75 })
local d = Dummies.spawn({ kind = "adult50", look = "classic", belt = "threePoint",
vehicle = rig.sled, seat = "seat_driver", synced = true })
task.wait(1.5) -- let the dummy settle into the seat first: a dummy still slumping reads differently every run
-- accelerometers on the head, chest and pelvis, read every physics step
local probes = Dummies.instrument(d)
local stopReading = Physics.onAfterStep(function() probes.read() end)
-- tow to 50 km/h, let go 1 m before the wall; zero the peaks at the release. `hold = d` keeps the
-- dummy where it sits until the crush starts (a lab's breakaway tape), so runs repeat
Sled.tow(rig, 50, function() probes.reset() end, { hold = d })
task.wait(25)
print(string.format("head %.0f g, chest %.0f g, pelvis %.0f g",
probes.peak.head, probes.peak.chest, probes.peak.pelvis))
print("belt loads (N):", probes.belt())
stopReading()
probes.stop()
```
Or open `examples/dummiesDemo.scene` and press play: its `DummiesDemo` rig does the same and writes
the results to its synced `lastHeadG` / `lastChestG` / `lastPelvisG` / `lastSledG` / `lastBeltN`
fields.
## Gallery
`examples/dummiesGallery.scene` shows the whole catalog in one static hall: every kind (rows: adult50,
adult5, adult95, child6 on its booster, toddler in its child seat, sid) in every look (columns: classic,
modern, cartoon, wooden, scifi), each on a test seat buck with a placard naming the kind and the look,
and in front a restraint row: each belt (none → racing harness) on a classic 50th male, then the
6-year-old with the car's 3-point belt through its booster and the toddler in its 5-point harness. It is
built with `Dummies.spawnVisual`, so nothing simulates; its `galleryCamera` frames the hall. Load it
additively (or open it) to browse the dummies.
## API
```lua
local d = Dummies.spawn({
kind = "adult50", -- see Kinds
look = "classic", -- see Looks
belt = "threePoint", -- see Belts
vehicle = chassisId, -- the vehicle's rigid body entity (id or proxy)
seat = "seat_driver", -- name of the seat-frame child entity
synced = true, -- entity.spawnSynced: every player sees the dummy
tone = 0.5, -- joint resistance 0 (limp) .. 1 (stiff)
handsInLap = false, -- true: hands rest on the thighs instead of the wheel
})
```
Returns a handle:
| field | what |
|---|---|
| `d.root` | root entity (`CrashDummy_<kind>`), carries the `CrashDummy` component |
| `d.bodies` | `{ head, neck, chest, abdomen, pelvis, upperArmL/R, forearmL/R, thighL/R, shinL/R }` entity ids (`sid` has no forearms) |
| `d.head`, `d.chest`, `d.pelvis` | the instrumented bodies |
| `d.spec` | `{ id, name, mass, stature, seat, belt, look }` |
| `d.belt` | the restraint id actually used (a `child6` asked for `harness` uses `threePoint`) |
| `d.straps` | each strap: `{ name, body, anchor, k, L, force, peak }` (force / peak in N) |
| `d.joints` | the Joint components by name (`lumbar`, `thorax`, `neckLow`, `neckHigh`, `hipL`, `kneeL`, `shoulderL`, `elbowL`, ...) |
| `d.booster` / `d.childSeat` | the child restraint prop's entity, for `child6` / `toddler` |
- `Dummies.despawn(d)` removes the dummy and its booster or child seat.
- `Dummies.spawnVisual({ kind, look, belt = "none", parent?, position?, yaw?, synced = false, name? })` builds the
dummy's LOOK only, in its seated pose (H-point at `position`, facing local -Z turned by `yaw` degrees), with its
booster / child seat and, for a `belt`, the webbing drawn once from anchors it places itself (driver's door on
-X). No physics, joints or collision filters, so it works inside a scene build (galleries, showrooms, menus).
Returns `{ root, kind, look, belt, bodies, booster?, childSeat? }`; the root carries attribute
`crashDummyVisual = kind`. Remove it with `entity(v.root):despawn()`.
- `Dummies.setTone(d, x)` sets joint resistance live (0..1).
- `Dummies.instrument(d)` returns `{ read(), reset(), peak = { head, chest, pelvis }, trace = { head = {g...}, ... }, belt(), stop() }`.
Motion probes (`Physics.probeMotion`) on the three bodies sample every solver substep
(240 Hz at the 60 Hz tick). Call `read()` every step (from `Physics.onAfterStep`) or at least
every few frames (4096 samples are kept).
- `Dummies.catalog()`, `Dummies.looks()`, `Dummies.belts()` list the variants (below).
- `Dummies.COLLISION_GROUP` = `2097152` (bit 21): the membership every dummy, booster and child-seat
collider carries (filter: everything). A car's soft crumple shell leaves bit 21 out of its filter so it
never touches the occupant.
## What the vehicle must supply
`Dummies.spawn` works on any vehicle body carrying these **child entities** (names exact):
- `seat_<x>` (e.g. `seat_driver`): the seat's **H-point** (hip-joint centre of a seated occupant),
its local -Z = the car's forward, +Y up.
- `belt_<seat>_lapOuter`, `belt_<seat>_lapInner`, `belt_<seat>_shoulder` (the D-ring), and optionally
`belt_<seat>_buckle` (else the diagonal strap ends at `lapInner`). Both `belt_seat_driver_lapOuter`
and `belt_driver_lapOuter` spellings are found. Outer/inner are decided by which side of the seat
each anchor is on, so left- and right-hand drive both work.
- `steering_wheel` (rim centre), for a driver seat: hands are lightly taped to the rim
(breakable ball joints, ~220 N, they let go in the crash). No wheel: hands rest on the thighs.
The **colliders are the car's**, on its chassis body:
a seat cushion whose top is about **0.10 m below the H-point**; a seat back whose front face runs
about **0.15 m behind the H-point at hip height**, reclined about 23°; a floor about **0.39 m below
the H-point** for the feet; a knee bolster / dash about 0.6 m ahead; the steering wheel. A rigid
steering hub reads 250 g on an unbelted chest. Make it collapse (the sled's hub is a 0.5 kg pad on a
spring-damped column capped at 6 kN over 0.35 m) or add an airbag.
## Catalog
### Kinds (masses in kg; forearm includes the hand, shin includes the foot)
| id | dummy | total | stature | head | neck | chest | abdomen | pelvis | upper arm (each) | forearm (each) | thigh (each) | shin (each) | seat |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| `adult50` | Hybrid III 50th male | 77.6 | 1.75 m | 4.5 | 1.5 | 17 | 7 | 16 | 2.0 | 2.3 | 6.0 | 5.5 | vehicle seat |
| `adult5` | Hybrid III 5th female | 50.0 | 1.51 m | 3.7 | 1.0 | 10.7 | 4.5 | 9.8 | 1.3 | 1.45 | 3.9 | 3.5 | vehicle seat |
| `adult95` | Hybrid III 95th male | 101.9 | 1.88 m | 5.0 | 1.8 | 22.5 | 9.5 | 21.5 | 2.7 | 3.0 | 8.0 | 7.1 | vehicle seat |
| `child6` | Hybrid III 6-year-old | 23.0 | 1.17 m | 3.2 | 0.6 | 4.9 | 2.0 | 3.9 | 0.55 | 0.55 | 1.65 | 1.45 | booster cushion (supplied) + car belt |
| `toddler` | Q3 3-year-old | 15.0 | 0.95 m | 2.7 | 0.4 | 3.0 | 1.3 | 2.5 | 0.35 | 0.35 | 1.0 | 0.85 | child seat (supplied) with its own 5-point harness |
| `sid` | SID side-impact dummy | 77.0 | 1.75 m | 4.5 | 1.5 | 21 | 8 | 16 | 1.5 (stub) | none | 6.0 | 5.5 | vehicle seat; shoulder/rib module, arm stubs |
The booster and the child seat are rigid bodies fixed to the vehicle at the seat frame (an
ISOFIX-style fixed joint) and kept out of the car's own collisions. Child kinds use their seat's
restraint: `child6` takes the car's belt through the booster (`harness` falls back to
`threePoint`); `toddler` uses the child seat's 5-point harness for any belt but `none`.
### Looks
| id | look |
|---|---|
| `classic` | yellow vinyl, black joints and neck, black-and-yellow quadrant targets on head and hips, sternum plate |
| `modern` | grey THOR-style skin, exposed rib stack, orange instrumentation accents |
| `cartoon` | bright blue / red / yellow, chunky limbs, big head with eyes and grin |
| `wooden` | artist's mannequin: pale beech segments, walnut joint balls |
| `scifi` | gloss white shell, black joints, cyan emissive visor, rings and spine light |
### Belts
| id | restraint | webbing stiffness | slack + spool-out | pretension | load limiter |
|---|---|---|---|---|---|
| `none` | unbelted | none | none | none | none |
| `lap` | 2-point lap belt | 60 kN/m per strap | 1 cm | none | none |
| `threePoint` | lap + diagonal shoulder strap | 50 kN/m | 2 cm lap / 4 cm shoulder | none | none |
| `pretensioner` | 3-point + pyro pretensioner + load limiter | 50 kN/m | as 3-point | 6 cm shoulder / 3 cm lap in 50 ms after the car passes 4 g | shoulder straps pay out above 4 kN |
| `harness` | racing 6-point (2 shoulder straps from behind the seat, lap, crotch) | 75 kN/m | 0.8 cm / 0.4 cm | none | none |
## How the belts work
Each strap runs from a point on a dummy body (pelvis front for the lap, clavicle and lower sternum
for the diagonal, tops of the shoulders for a harness) to an anchor, as a solver **spring joint**.
Every physics step, on the peer that simulates the dummy, the `CrashDummy` component sets each
spring's rest length so the strap is **one-sided webbing**: it pulls with `k * stretch` (plus damping)
once the webbing is taken up, never pushes, and stays slack until then. The pretensioner shortens
the webbing when the vehicle's deceleration passes 4 g; the load limiter lets webbing pay out to keep
the shoulder force at its limit. A rigid rope instead gives 1000 g spikes. Anchors are read on the
rigid body that carries them, so the belt follows the car at the physics rate.
Strap loads are in `d.straps[i].force` / `.peak` and `probes.belt()`.
The webbing you see is cosmetic: thin dark straps (local to each peer) that follow each anchor and
body point at their drawn pose every frame, plus the lap and chest runs and the buckle.
## How the dummy is built
15 rigid bodies (13 for `sid`): head, neck, chest, abdomen, pelvis, upper arms, forearms + hands,
thighs, shins + feet; capsule / box / sphere colliders; `collideConnected = false` between
neighbours. Spine, neck, hips and shoulders are generic joints with anatomical per-axis limits
(flexion / extension / side bend / twist; e.g. neck 48° + 38° flexion, lumbar 28° flexion / 10°
extension); elbows and knees are hinges limited from straight to fully bent. Every joint carries a
capped spring-damper motor toward the seated pose (the dummy's "tone": heavy and floppy, not a noodle;
`setTone` scales it). Colliders are members of collision bit 21 only.
## Measured (sled, adult50)
The package's sled has a progressive crush-can nose; its pulse peaks at about 18 g at 30 km/h,
31 g at 50 km/h and 58 g at 70 km/h (0.39 / 0.76 / 1.14 m of crush). Peak g at the probes, raw
substep samples.
**The first example as written** (3-point, 50 km/h, 1.5 s settle, `hold = d`), measured 2026-10-26 (version 1.0.3):
| physics rate | head | chest | pelvis |
|---|---|---|---|
| 60 steps a second, with the hold (3 runs) | 69 / 105 / 81 g | 43 / 57 / 29 g | 42 / 38 / 41 g |
| 60, settle but no hold (3 runs) | 63 / 136 / 103 g | 41 / 31 / 48 g | 45 / 34 / 32 g |
| 30 (a fresh world's default), settle, no hold (3 runs) | 121 / 63 / 69 g | 35 / 34 / 32 g | 35 / 39 / 31 g |
| 30, no settle, no hold (2 runs) | 111 / 58 g | 36 / 48 g | 31 / 38 g |
**What changes the numbers, biggest first:**
- **Settling.** A dummy towed while it is still slumping into its seat meets the wall from a different posture each
run; a run straight after spawning can read head 150 g and chest 120 g. Wait about 1.5 s after `Dummies.spawn`.
- **The sled is a bare test sled.** Its head meets a small collapsing hub with no foam, belt geometry or airbag
around it, so where the head lands on the hub varies and the **head** reading spreads by up to about 1.5x run
to run even with the hold; pelvis repeats within about 10 % and chest within about 30 %. For repeatable
head and chest readings (within 20 %) put the dummy in a crashCars car on the crashRig rig, which seats it
against padded foam, a collapsing wheel and a door pad: there a saloon at 30 / 50 / 70 km/h reads head
about 26-29 / 37-40 / 49-63 g and chest 13-14 / 21-22 / 30-36 g.
- **Physics rate** (`physics.tick_rate` in the world's settings: 30 in a fresh world). The probes sample at the
physics substeps, so the rate changes the peaks the dummy reads; numbers in this README are at 60 unless a
row says 30.
- **The positioning hold** (`Sled.tow(rig, kmh, onRelease, { hold = d })`) keeps the dummy where it sat until the
crush starts, as a lab's breakaway tape does; it narrows the spread a little.
Older figures (60 steps a second, before the settle, from an earlier version; run-to-run spread not measured
then, so read them as one sample each):
| | 30 km/h | 50 km/h | 70 km/h |
|---|---|---|---|
| 3-point: head / chest / pelvis | 61 / 19 / 26 | 57-64 / 44-56 / 31 | 93 / 65 / 55 |
| unbelted: head / chest / pelvis | 44 / 13 / 22 | 78 / 33 / 55 | 191 / 61 / 81 |
At 50 km/h the other kinds and belts read (head / chest):
harness 55 / 72, lap belt 267 / 55 (jack-knife into the knees and wheel), pretensioner 120-167 / 33-40
(the limiter's pay-out lets the head reach the hub; pair it with an airbag), adult5 88 / 40,
adult95 47 / 26, child6 on booster 125 / 52, toddler in child seat 47 / 58, sid 121 / 30.
In a crashCars hatch at 50 km/h (1.05 m crush): head 23, chest 19, pelvis 31 g.
Unbelted chests read lower than belted on the sled because they land on its collapsing hub.
## Multiplayer
`synced = true` (the default) spawns every body, collider and visual with `entity.spawnSynced`, so
call `spawn` on one peer only (the rig's authority). Rigid bodies replicate as poses; the belts run
on the spawning peer (it holds the strap state); every other peer's `CrashDummy` rebuilds the
strap plan from its synced fields and the entity names and draws the same webbing. `Physics.*`
writes (tone, impulses) only take effect on the simulating peer.
## Known limits
- A ragdoll is drawn at physics-tick poses (engine issue **#21188**): the dummy steps at 60 Hz on
screen rather than blending between ticks.
- A ragdoll may not show ragdolled for other players (**#18554**): remote peers can see the dummy
hold a stale pose. Not worked around.
- A kinematic body covers a frame's motion in its first step (**#21187**). The tow rig therefore
drives a dynamic sled with `Physics.setVelocity` every step instead of a kinematic carrier.
- CCD makes the solver jitter by hundreds of g on a body riding a fast vehicle (a dummy coasting at
50 km/h read 400 g with it, 1.0 g without), so dummy bodies run without CCD. Segments are thick
enough not to tunnel at occupant-to-cabin speeds.
- A body whose own entity carries no collider gets a default 1 m box from the engine even when
its children carry colliders, so every dummy body carries a small core sphere itself.
- Ball joints here enforce only their twist limit (the swing cone is not applied), so every
multi-axis joint is a `generic` joint with explicit per-axis limits.
- Peaks are raw substep samples (no SAE J211 filtering here). The crashRig part filters.
- Hand-taping joints are re-created per spawn and break on impact; they are not re-armed.
- Arms do not collide with the head or neck (flailing forearms hitting the head swamped the head
accelerometer). They still hit everything else.
## Belts and the load limiter (version 1.0.2)
The plain 3-point belt now has the load limiter every modern 3-point belt carries: its shoulder strap pays out
above 6 kN (the pretensioner variant keeps its 4 kN limiter). The neck's muscle tone is unchanged; a stiffer
neck was tried for high-speed tests and made the solver diverge, so above about 80 km/h the head whips into its
joint stop and its reading is the model's limit, not a measurement.