# pitConcrete
Grey concrete for the walls of a glass-floor camera pit. Part of the crashCams camera props (`Cams.dressing`).
# hazardYellow
Safety-yellow paint for stands and pit edges. Part of the crashCams camera props (`Cams.dressing`).
# camBody
Charcoal powder-coated aluminium for the body of a high-speed lab camera. Part of the crashCams camera props (`Cams.dressing`).
# cars
The crashCars public API, required as `require("crashCars.cars")`. It reads the catalog
(`catalog`, `looks`, `spec`, `derive`), exposes the structure model every car crushes by
(`structure(m)`, `crushForce(m, S, x, face)`), and `spawn`s a whole car: a dynamic chassis with four
`WheelCollider`s, cabin colliders (floor pan, seat cushions and backs, dash, steering wheel, toe
board, firewall, rear bulkhead, door rings), seat H-point and belt-anchor children, a car-shaped
custom `SoftBody` shell held to the cabin, a bumper and a bonnet, and the `CrashCar` component that
runs the crush. Also `whenReady`, `fromChassis`, `despawn`, `setVelocity` (tow or launch the chassis
and shell together), the frame helpers `worldToLocal` / `localToWorld` / `localDir`, and the
collision bits in `GROUPS` (shell = bit 20, dummy = bit 21).
Called by games and rigs (crashRig, crashObstacles' `parkedCar`, the package example). Spawn on ONE
peer; everything it creates is synced unless `synced = false`. See the package README for the full
reference and measured numbers.
# carsDemoLineup
A crashCars car as a still picture. `Lineup.place(model, look, position, yaw?, name?)` places the
shell, interior, windscreen, bumper, bonnet and wheel meshes where `Cars.spawn` puts them, as plain
`Model` entities with no `Physics` and no `SoftBody`, so they cost nothing to simulate and can be
baked into a scene. `Lineup.row(start, look, gap)` stands every catalog model side by side along +X.
The shell is drawn undeformed.
Called by `carsDemo.scene`'s build for its catalog line-up, and usable for any showroom or menu.
Spawn the real car with `Cars.spawn` when it has to crash.
# cams
The crashCams API (`require("crashCams.cams")`): `Cams.kinds()`, `Cams.use(camera, kind, targets, fields?)` to switch a Camera to one of the six crash-test camera behaviours, `Cams.setTargets`, `Cams.current`, `Cams.director(camera, { shots, cut, targets, clock, overlay, onCut })` returning a director with `:start()`, `:stop()`, `:next()`, `:current()`, `:cutTo()`, `Cams.overlay` for the REC / timecode burn-in, `Cams.impactShake` (juiceKit when installed), and `Cams.dressing(position, "tripod" | "boom" | "pit", opts)` to spawn physical camera props. Called by game code, test rigs and scene builds; the package README documents every call.
# CamsGallery
Shows every crashCams camera kind live at the same time. Put it on an entity whose children include
one camera per `Cams.kinds()` entry, each named after its kind id (`highSpeedSide`, `overhead`,
`barrierFace`, `dummyView`, `chase`, `underCar`) and carrying a `Camera`.
In play, `start` gives each child its kind with `Cams.use(camera, kind, { car, head, impact })` and
points it at a render texture of its own. A local screen lays the six pictures out side by side:
3 x 2 on a wide screen, 2 x 3 on a narrow portrait one. Each picture has a title strip with the
camera number, the kind's name and its id. The behaviours place their cameras every frame, which
only happens while the gameplay clock runs. In edit mode the cards show "PRESS PLAY TO ROLL" with
each kind's description instead of six unplaced cameras.
Fields: `car`, `head` (entity refs), `impact` (the obstacle face point relative to this entity) and
`layer`. The screen and the textures are released in `onDestroy`. It needs no sibling components.
Used by `examples/camsGallery.scene`.
# labFloor
Satin grey epoxy floor of a crash-test hall, used by the crashCams example scene.
# labLamp
Bright white face of a lab flood lamp. Part of the crashCams camera props (`Cams.dressing`).
# tripodBlack
Black anodised aluminium for tripod legs, stands and booms. Part of the crashCams camera props (`Cams.dressing`).
# lensGlass
Dark multi-coated front element of a lens: a deep blue mirror. Part of the crashCams camera props (`Cams.dressing`).
# camAccent
Signal-red trim on a high-speed lab camera body. Part of the crashCams camera props (`Cams.dressing`).
# screenGlow
Dim blue glow of a camera's side monitor. Part of the crashCams camera props (`Cams.dressing`).
# tallyRed
Glowing red recording tally lamp. Part of the crashCams camera props (`Cams.dressing`).
# rubberBlack
Matte rubber for tripod feet, grips and cables. Part of the crashCams camera props (`Cams.dressing`).
# body_realistic
Car body_realistic surface for crashCars: a white PBR base so the mesh's baked vertex colours (paint, trim, lights, glass tint) show as authored.
# windscreen
Tinted transparent glass for crashCars windscreens.
# wheel
Car wheel surface for crashCars: a white PBR base so the mesh's baked vertex colours (paint, trim, lights, glass tint) show as authored.
# lensBlack
Glossy black anodised lens barrel. Part of the crashCams camera props (`Cams.dressing`).
# trim
Car trim surface for crashCars: a white PBR base so the mesh's baked vertex colours (paint, trim, lights, glass tint) show as authored.
# crashCams
**The six cameras of a crash-test lab, a director that cuts between them for slow-motion replays, a "REC" burn-in, and physical camera props (a high-speed camera on a tripod, an overhead boom, a glass-floor pit) — for any crash, impact or vehicle test scene.**
Version **1.0.0** (`Cams.VERSION`). Part of *Crumple Zone: Crash Test Dummy Simulator*; usable on its own.
Every camera is a camera behaviour (a component `Camera.behavior` names), so switching the shot is one write on the camera you already have. Each one reads its subjects where they are **drawn** this frame (`Physics.drawnPose`), so a car the simulation moves between physics ticks holds still on screen: measured in play, the chase camera's car moves at most 0.05° of frame jerk per frame and the onboard dummy camera's head 0.002°.
Cameras are per player: each peer drives its own view, and nothing in this package syncs (the props are scenery; see `synced` below).
## Install
Install the `crashCams` package into your world. Require it by its bare name:
```lua
local Cams = require("crashCams.cams")
```
Optional: the **Juicebox juiceKit** package. With it installed, `Cams.impactShake()` kicks the camera on screen; without it the call returns `false` and does nothing else.
## First example
A component that puts a camera on a car, frames it with the high-speed side camera, and replays from two angles once the car stops. Put it on any entity, set its three fields (or let it fall back to entities named `car`, `head`, `DemoCamera`), and press Play.
```lua
local Cams = require("crashCams.cams")
declare {}
public = {
car = Field.entityRef(nil, NoSync, "The car's chassis."),
head = Field.entityRef(nil, NoSync, "The dummy's head (optional)."),
camera = Field.entityRef(nil, NoSync, "An entity carrying a Camera."),
}
local director: any = nil
function start()
local cam = public.camera or entity.find("DemoCamera")
local car = public.car or entity.find("car")
if cam == nil or car == nil then return end
local targets = { car = car, head = public.head or entity.find("head"), impact = { 0, 0.5, 0 } }
-- One live shot...
Cams.use(cam, "highSpeedSide", targets)
Cams.overlay(cam, true, { label = "CAM 1 · HIGH-SPEED SIDE" })
-- ...then a replay that cuts between two angles every 1.6 s of wall clock.
director = Cams.director(cam, {
shots = { "highSpeedSide", "barrierFace", "dummyView" },
cut = 1.6,
targets = targets,
overlay = true,
})
task.delay(4, function() director:start() end)
end
function onDestroy()
if director ~= nil then director:stop() end
end
```
The full example is the scene `examples/camsDemo.scene`: a lane, a concrete block, a box car with a sprung head towed into the block at 50 km/h (velocity held with `Physics.onBeforeStep` + `Physics.setVelocity` until 1 m before contact, then released), the lab's props, and a director cycling all six cameras, one run per camera, with slow motion around the impact. Load it and press Play. Its layout is `examples/camsDemoLayout.module` (`Layout.build(origin)`), so the same lane can be built anywhere in a live world for testing.
## Camera catalog
| id | name | what it shows |
|---|---|---|
| `highSpeedSide` | High-speed side | Fixed low camera square to the track at the impact zone on a long lens (20°); its aim pans a little to hold the arriving car, then settles on the crush zone. |
| `overhead` | Overhead | Straight down from 9.5 m above the impact zone on a 54° lens, under a lab's light rig (at 13 m it saw the back of the lab's rig light panel); the crash as a plan (line, yaw off the barrier, shortening). Slides a little with the car. |
| `barrierFace` | Barrier face | Low at the side of the obstacle face, looking back up the track at the oncoming car on a wide lens. |
| `dummyView` | Dummy view | Onboard, bolted to the passenger side of the dash, watching the dummy's head whip into the belt or the wheel. Rides the car rigidly; aims at the drawn head in the car's frame. |
| `chase` | Chase | Low behind the car on its line; matches its speed with a short reaction lag, so it punches in when the car stops dead, then settles back. |
| `underCar` | Under car | From a glass-floor pit under the impact zone, looking up at the underside as the front folds. Needs a see-through floor above it (see Known limits). |
Every behaviour takes the same targets as fields — `car` (empty falls back to `Camera.follow`), `head`, `impact` — plus its own tuning fields (distance, height, lens `fov`, smoothing). Read them with `entityOps.component("CrashCamChase")`, or pass them as `fields` to `Cams.use`.
## API (`require("crashCams.cams")`)
Targets are `{ car = chassisId, head = dummyHeadId, impact = {x,y,z} }`: ids or entity proxies, and `impact` is the obstacle face point (`{x,y,z}` or `{x=,y=,z=}`). The track runs along world **-Z** (car starts at +Z, obstacle face points +Z), up is +Y; the ground is taken as `impact.y - 0.5`.
- `Cams.kinds() -> { { id, name, description } }` — the six cameras in catalog order.
- `Cams.use(cameraEntity, kind, targets?, fields?) -> component` — switch the Camera's behaviour to `kind` and set its targets (missing keys keep what the camera had) and any tuning `fields` (`{ side = -1 }`, `{ fov = 30 }`). Also sets `Camera.follow` to the car. `cameraEntity` is a proxy, id or name.
- `Cams.setTargets(cameraEntity, targets)` — change what the current shot frames.
- `Cams.current(cameraEntity) -> kind?`
- `Cams.component(kind) -> assetRef` — the behaviour component for `Camera.behavior`.
- `Cams.director(cameraEntity, opts) -> director` with `opts = { shots, cut = 1.6, targets, loop = true, clock = "real" | "sim", overlay = false, onCut = function(kind, index) }`. A shot is a kind id or `{ kind, hold?, targets?, fields?, label? }`. `clock = "real"` (default) cuts on the wall clock, so a slow-motion replay still cuts at a watchable pace; `"sim"` cuts on the simulation clock.
- `director:start(index?)`, `director:stop()`, `director:next()`, `director:current() -> (kind?, index)`, `director:cutTo(index)`, `director:setTargets(targets)`.
- The cutting task belongs to whoever called `start` (a component's hook: it ends with that component).
- `Cams.overlay(cameraEntity, on?, opts?) -> component` — the recording burn-in: blinking REC dot, label, `fps`/shutter, timecode and a 1000 fps frame counter, corner marks. The counter runs on the simulation clock, so slow motion counts slowly like real high-speed footage. `opts = { label, fps = 1000, shutter = 2000, showFrame = true, tint }`; the component has `:resetClock()` and `:elapsed()`. Local UI on this peer.
- `Cams.impactShake(intensity?) -> boolean` — a heavy local camera shake through juiceKit (`shakeHeavy`, scope local), when it is installed.
- `Cams.dressing(position, kind?, opts?) -> rootEntity` — spawn a camera prop: `"tripod"` (default; a high-speed camera with lens, focus ring, coated front element, heat-sink fins, side monitor, red tally lamp, handle, pan bar, three splayed legs with locks, spreaders and rubber feet, and a cable), `"boom"` (a counterweighted overhead boom with a camera hung lens-down and a flood lamp), `"pit"` (a concrete glass-floor pit sunk below `position`, yellow steel frame, a glass pane with a collider, two floods with point lights and its own camera on a stand). `opts = { aimAt = {x,y,z}, yaw, height, reach, width, length, depth, glass = true, collider = false, synced = false, name, parent }`. Built from the builtin primitives and this package's materials; call it from a scene build (baked, every peer gets it) or from code every peer runs; `synced = true` spawns with `entity.spawnSynced` from one peer instead.
- `Cams.dressingKinds() -> { "tripod", "boom", "pit" }`
## How replays use the director
The engine has no record and playback of the simulation (**#20544**). The replay is recorded by the test rig (the `crashRig` part records poses and replays them locally); the cameras only frame it. Point the director's `targets` at the entities the rig moves during playback (the replayed car and head), set the rig's playback time scale for slow motion, and call `director:start()`: with the default `clock = "real"` each angle holds `cut` wall-clock seconds whatever the replay speed. `onCut` tells the rig when an angle changes, so it can restart the replay for each angle (the classic "same crash, three angles").
## Contents
| asset | what it is |
|---|---|
| `cams.module` | The API above. |
| `camCore.module` | Shared internals of the behaviours: drawn-pose reads, placement, lens. |
| `CrashCamHighSpeedSide`, `CrashCamOverhead`, `CrashCamBarrierFace`, `CrashCamDummyView`, `CrashCamChase`, `CrashCamUnderCar` (components) | The six camera behaviours, tagged `cameraBehavior`. |
| `CrashCamOverlay` (component) | The REC / timecode burn-in. |
| `camBody`, `camAccent`, `lensBlack`, `lensGlass`, `tripodBlack`, `rubberBlack`, `tallyRed`, `screenGlow`, `labLamp`, `pitConcrete`, `hazardYellow`, `labFloor` (materials) | The props' and example's surfaces. |
| `examples/camsDemo.scene`, `examples/camsDemoLayout.module`, `examples/CamsDemo` (component) | The runnable example. |
## Gallery
`examples/camsGallery.scene` shows all six cameras live at the same time. The crash moment stands
still: a hatchback (crashCars meshes, no physics) with its bumper on the block, a dummy in the
driver's seat, the glass pit and the lab props. The `Gallery` entity holds one child camera per
kind, named by kind id. In play, the `examples/CamsGallery` component calls `Cams.use` on each one
and renders it into a texture. The six pictures share one screen, 3 x 2 on a wide screen and 2 x 3
on a narrow one, each titled with its camera number and name. In edit mode the tiles ask you to
press play, because the behaviours place their cameras only while the clock runs. Tests:
`crashCams.testSuite` (`tools.use("tests", "run", "crashCams")`).
## Known limits
- **No simulation record/playback (#20544):** the director frames whatever moves; the replay itself is the rig's job.
- **A ragdoll is drawn at physics-tick poses (#21188):** `dummyView` follows the head where it is drawn, so on a ragdoll dummy the head can step at the 60 Hz tick even though the camera itself is smooth. `dummyView`'s `aimTime` (35 ms) softens it.
- **`underCar` needs a see-through floor:** leave a hole in your floor over the pit (`Cams.dressing(p, "pit")` fills it with glass and a collider), or put the floor slab over the pit on a render layer and name it in the behaviour's `hideLayers`.
- **The time scale is one number for the whole engine:** the example only slows time when nobody else holds a scale, and only puts back a scale it set itself.
- **The overlay draws in the viewport camera's picture:** show it only on the camera that is on screen.
- The checker reports `asset-unresolved` warnings for the package's own `~.` references; they resolve when running (the same harmless warning juiceKit documents, #12937).
# 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.
# crashCars
Crash-test cars whose bodies crumple and stay crumpled. There are nine cars (city car, hatchback,
family saloon, estate, SUV, pickup, sports coupe, people carrier and a 1960s steel saloon), each in
three looks (realistic, toy, low-poly). A car is a real `WheelCollider` chassis. Its cabin has
seats, a dash, a steering wheel, a toe board, a firewall and door rings that a crash dummy can sit
in and hit. The body is a car-shaped soft-body shell whose crush zones keep their dent. The bumper
and bonnet slide and fold with the crush, then tear off as loose bodies. Every piece is synced, so
every player sees the same car, the same dent and the same panels flying.
The crash load follows a per-face **lane model** of the car's structure, with a force law tuned per
model. Into a rigid wall a hatchback crushes about 0.2 m at 30 km/h, 0.65–0.75 m at 50 km/h and
1.1–1.25 m at 70 km/h. The energy its structure absorbs (`energyJ`) comes out at the car's ½mv².
## Install
Install the package `crashCars` from ZeroMind. It lands at `/source/parts/crashCars.package`, or
wherever you install it. Require it by its bare name:
```luau
local Cars = require("crashCars.cars")
```
It depends on nothing but the engine.
## First example
Paste this where only one peer runs it, during play: an `execute` call, a host-only scene
`onHostLoad`, or behind `multiplayer.isHost()`. It lays down a floor and a static wall whose face
is the plane z = 0, spawns a hatchback 12 m up the lane and tows it at 50 km/h. It lets go 1 m
before the wall, then brakes and prints what the crash did.
```luau
--!strict
local Cars = require("crashCars.cars")
local cube = asset.resolve("cube", "mesh")
local floor = entity.spawnSynced("TestFloor", { position = { 0, -1, 0 } })
floor.localScale = { 12, 2, 40 } -- top surface at y = 0
floor.component.add("Model", { model = cube })
floor.component.add("BoxCollider", { friction = 0.8 })
-- a rigid wall: no Physics body, so it is static; its face is the plane z = 0, facing +Z
local wall = entity.spawnSynced("TestWall", { position = { 0, 1, -1 } })
wall.localScale = { 4, 2, 2 }
wall.component.add("Model", { model = cube })
wall.component.add("BoxCollider", {})
-- the car faces -Z (forward) and comes from +Z
local car = Cars.spawn({ model = "hatch", look = "realistic", position = { 0, 0, 14 }, yaw = 0 })
assert(Cars.whenReady(car, 5), "car shell did not build")
car.component:track(true, "front")
local v = 50 / 3.6
local towing = true
local stop = Physics.onBeforeStep(function()
if not towing then
return
end
local bumperZ = car.chassis.position.z - car.frontOffset
if bumperZ <= 1 then -- let go 1 m before the wall
towing = false
return
end
Cars.setVelocity(car, 0, 0, -v) -- tows chassis and shell together
end)
task.wait(2)
stop()
car.component:brake(6000)
local c = car.component:settle("front")
print(("crush %.2f m max / %.2f m mean, peak %.0f g, structure absorbed %.1f kJ, off: %s"):format(
c.max, c.mean, car.component.peakForceN / (car.spec.mass * 9.81), car.component.energyJ / 1000,
table.concat(car.component.detached, ", ")))
```
It passes the strict checker and runs. A hatchback at 50 km/h crushes 0.55–0.75 m at 24–28 g peak, and
`bumper, bonnet` come off. Its structure absorbs about 115 kJ of the 120.6 kJ ½mv² by the moment it stops. Read the open issues under Known limits before you trust
the numbers *after* the stop.
`examples/carsDemo.scene` is the same test as a scene: a hall floor, a concrete wall, a camera and the
`CarsDemo` component (`examples/CarsDemo.component`). The component runs one real car on the host only
and prints the result. Beside the lane, `examples/carsDemoLineup.module` stands one car of every
model as a still picture: meshes only, no physics. Use it for a showroom or menu instead of nine
simulated cars.
## Gallery
`examples/carsGallery.scene` is a showroom of the whole catalog: every model in every look, a 9 × 3
grid of 27 cars (models in catalog order left to right; realistic, toy and low-poly rows front to
back). Each car stands on a plinth with a name placard in world-space text (`Text3D`), such as
"Family saloon · Toy", and each row has its look as a header. It is visual only, built with
`carsDemoLineup`: no physics, no soft bodies, no `CrashCar`. Its camera (`galleryCamera`) frames the
whole grid.
Open it from the Scenes list in the editor, or in Luau with `layers.load("crashCars.examples.carsGallery")`
(a root load replaces the open scene; pass `{ additive = true, origin = { x, y, z } }` to set it
beside your own scene instead). Its `build.luau` lays the grid out from `Cars.catalog()` and
`Cars.looks()`, so a new model or look shows up on the next build.
The package's regression suite is `crashCars.testSuite`: run it in edit mode with `zero tests run crashCars`.
## API
```luau
Cars.spawn(opts) -> Car
```
| option | meaning |
|---|---|
| `model` | catalog id (below). Default `"hatch"` |
| `look` | `"realistic"` (default), `"toy"`, `"lowpoly"` |
| `position` | `{x, y, z}` or `{x=, y=, z=}`: on the ground under the middle of the car |
| `yaw` | radians about +Y. 0 = the car faces **−Z** |
| `synced` | `true` (default): every piece is spawned with `entity.spawnSynced`, so call it on ONE peer. `false` for a local-only car |
| `name` | chassis entity name (default `CrashCar_<model>`); the shell is `<name>_shell` |
`Car` handle (also rebuilt on any peer with `Cars.fromChassis(chassisId)`):
- `id`, `chassis`: the chassis entity id and entity (dynamic `Physics`, four `WheelCollider`s, the
cabin colliders, the `CrashCar` component).
- `shell`: the soft body shell's entity id (a separate root entity held to the cabin).
- `parts = { bumper, bonnet }`: the panels' entity ids while they are attached (children of the
chassis). Once they come off, `component.looseBumper` / `looseBonnet` hold the loose bodies.
- `spec = { id, name, class, mass, length, width, height, wheelbase, frontOverhang, crushable }`,
`derive` (car-local stations, see `specs`), `structure` (see `Cars.structure`), `model`, `look`.
- `component`: the chassis' `CrashCar` component. `wheels`: the four wheel entity ids.
- `frontOffset` / `rearOffset`: metres from the chassis origin to the front face (bumper) along
forward, and to the rear face along back. The bumper's world position along the lane is
`chassis.position.z - frontOffset` for a car facing −Z.
Children of the chassis that a dummy or a rig uses, named exactly:
- `seat_driver`, `seat_passenger`, `seat_rear_left`, `seat_rear_right`: H-points (the hip joint
centre of a seated occupant), facing forward. The rear seats are absent on the pickup.
- `belt_seat_<seat>_lapOuter`, `_lapInner`, `_shoulder`, `_buckle`: belt anchor points.
- `steering_wheel`: centre of the rim (its collider is `col_steering_wheel`).
Everything else in `Cars`:
| call | what it does |
|---|---|
| `Cars.catalog()` | `{ {id, name, class, mass, length, width, height, wheelbase} }` |
| `Cars.looks()` | `{ {id, name, description} }` |
| `Cars.spec(id)` | the raw spec table from `specs` (nil for an unknown id) |
| `Cars.derive(id)` | car-local stations: axles, windscreen, firewall, roof end, H-points, steering wheel centre |
| `Cars.structure(m)` | the structure of a spec `m`: `frontG`/`rearG`/`sideG` = `{g at 0 crush, g at 85 % travel}`, `frontTravel`/`rearTravel`/`sideTravel` (m), face positions, shell zone settings |
| `Cars.crushForce(m, S, x, face)` | crush force (N) of a whole face at crush depth `x` m. `face` = `"front"`, `"rear"` or `"side"` |
| `Cars.whenReady(car, timeout?)` | yields until the shell is built (default 5 s); returns true/false |
| `Cars.fromChassis(id)` | the handle, read back from a chassis id (any peer) |
| `Cars.despawn(car)` | removes the chassis, shell and any loose panels |
| `Cars.setVelocity(car, vx, vy, vz)` | sets chassis **and** shell velocity (world m/s): how a tow or launcher drives the car. Simulating peer only |
| `Cars.worldToLocal(e, p)`, `Cars.localToWorld(e, l)`, `Cars.localDir(e, l)` | frame helpers for any entity (arrays in, `{x,y,z}` out) |
| `Cars.GROUPS` | collision bits: `shell` = bit 20, `dummy` = bit 21. Put a dummy's colliders in bit 21 **only**: the shell fills the car's volume and is filtered against that bit |
| `Cars.mesh(model, look, part)`, `Cars.material(name)` | the package's authored mesh and material refs |
### The `CrashCar` component (on the chassis)
Methods (the ones that write are for the simulating peer):
- `:measureCrush(face?)` → `{ max, mean, lanes = {a, b, c}, left, centre, right }`, in metres,
for `"front"` (default), `"rear"`, `"left"` or `"right"`. On the owner it reads live values.
Other peers read the synced `lanes`, updated every 0.1 s.
- `:worstFace()` → `face, depth`.
- `:track(on, face?)`: while on, keeps the deepest crush of `face` in `crushMax`. Switching it on
resets `crushMax`, `energyJ` and `peakForceN`.
- `:settle(face?)`: stores the current crush in `crushResidual` and returns it.
- `:setExclude(ids)`: bodies the lanes look past, for example a dummy's bodies or a rig's props.
- `:brake(torque?)`: clamps every wheel's brake (default 6000 N·m); `0` releases it.
- `:repair()`: back to the built shape and forgets the crush. Panels that came off stay off.
Synced fields: `crushMax`, `crushResidual`, `lanes`, `energyJ` (J), `peakForceN` (N), `detached`
(`{"bumper", "bonnet"}`), `looseBumper`, `looseBonnet`, `ready`, and the tunables `reboundShare`
(0.06), `bumperOffAt` (0.26 m), `bonnetOffAt` (0.38 m) and `shapeZones` (true).
Events: `onPartDetached { part }` and `onImpact { face, speed, target }` (closing speed in m/s at
first contact, and the entity id of what the face met).
```luau
car.component.events.onImpact:connect(function(e)
print(e.face, "hit", e.target, "at", e.speed * 3.6, "km/h")
end)
```
## Catalog
Mass in kg, sizes in metres. *Front law* is the crush force as deceleration of the whole car, from
first touch to 85 % of the crush travel. Past 85 % the structure bottoms out and stiffens sixfold.
| id | name | class | mass | length | width | height | wheelbase | front law | front travel | seats |
|---|---|---|---|---|---|---|---|---|---|---|
| `city` | City car | A-segment city car | 950 | 3.60 | 1.64 | 1.50 | 2.40 | 15–42 g | 1.01 m | 4 |
| `hatch` | Hatchback | C-segment hatchback | 1250 | 4.10 | 1.78 | 1.46 | 2.62 | 15–42 g | 1.23 m | 5 |
| `saloon` | Family saloon | D-segment saloon | 1450 | 4.75 | 1.82 | 1.45 | 2.80 | 15–42 g | 1.39 m | 5 |
| `estate` | Estate | D-segment estate | 1550 | 4.80 | 1.82 | 1.48 | 2.80 | 15–42 g | 1.40 m | 5 |
| `suv` | SUV | mid-size SUV | 1850 | 4.60 | 1.88 | 1.70 | 2.75 | 17–48 g | 1.22 m | 5 |
| `pickup` | Pickup | full-size pickup | 2100 | 5.30 | 1.90 | 1.80 | 3.20 | 19–53 g | 1.23 m | 5 (2 seat frames) |
| `coupe` | Sports coupe | 2+2 sports coupe | 1500 | 4.40 | 1.85 | 1.30 | 2.55 | 16–44 g | 1.50 m | 4 |
| `mpv` | People carrier | MPV / minivan | 1750 | 4.80 | 1.88 | 1.75 | 2.95 | 15–42 g | 0.84 m | 7 (4 seat frames) |
| `classic60s` | 1960s steel saloon | 1960s body-on-frame saloon | 1300 | 4.60 | 1.75 | 1.42 | 2.70 | 39–109 g | 0.92 m | 5 |
`classic60s` has a stiff, short front and a weak cabin (`front = 2.6`, `cabin = 0.45`): it stops
harder, and its passenger cell deforms more. Rear faces use 12–34 g and sides 8–30 g, the side
travel growing with cabin strength. Seat frames are the `seat_*` children: `driver` and
`passenger`, plus `rear_left` and `rear_right` on every model but the pickup.
## Looks
The look changes how a car is drawn, never its physics.
| id | name | what it looks like |
|---|---|---|
| `realistic` | Realistic | Smooth production body, metallic paint, crash-test target stickers |
| `toy` | Toy | Rounded glossy plastic, saturated colours, chunky wheels |
| `lowpoly` | Low-poly | Faceted flat-shaded body in a flat palette |
Each model has its own paint per look. Paint is baked into the meshes' vertex colours and drawn
through white PBR materials (`materials/body_<look>`, `trim`, `wheel`, `windscreen`).
## How the crush works
- **Lanes.** Each face (front, rear, left, right) is three lanes. On the simulating peer, every
physics step, rays from inside the body find what stands in front of each lane. They see any
collider and soft-body surfaces. Where a lane's face meets something, the car is pushed back
with that lane's third of `Cars.crushForce(m, S, depth, face)`. If the obstacle is dynamic or
soft, it gets the opposite force. A pole meets one lane, an offset barrier one side, a wall all
three.
- **Force law.** In g of the car's weight, the force rises linearly from the first value of
`frontG` at no crush to the second at 85 % of `frontTravel`, then stiffens to 3x (`1 + Cars.BOTTOM_OUT`)
as the crumple zone bottoms out and the cabin structure takes over. Hit faster than 70 km/h, every lane
resists harder by `Cars.DYNAMIC` (strain rate, more members folding at once): 1.5x more per 15 m/s above
19.5 m/s, so a 120 km/h car is stopped by its crumple zone (1.39 m, 39 g mean) rather than by its cabin.
- **Never more than stops it.** The force is capped so it never more than stops the closing speed
in one step. When the face stops against the obstacle, it gives back `reboundShare` (6 %) of
the impact speed, the way crushed metal does. Against a moving body (a parked car, a moving
barrier, a loose panel) the cap uses the two masses together, so a light thing is not flung off.
- **Depth.** A lane's crush depth only grows: it is how far the obstacle has moved into the face.
- **Energy.** `energyJ` is the work the crush forces did on the closing motion, which is the
energy the car's structure absorbed. It is this part's own model: soft bodies don't report
absorbed energy (#20539).
- **Shape.** The shell's crush zones take the lanes' depths. `Physics.setSoftParticles` writes
their positions and their rest shape, so the dent stays, and it replicates to every peer like
any soft-body dent. The folds bow the sides out and the top up where the metal packed.
- **Panels.** While attached, the bumper slides back with the mean crush and the bonnet folds up
from its hinge. The bumper comes off past `bumperOffAt` (0.26 m), or when one side is crushed
0.12 m deeper than the other. The bonnet comes off past `bonnetOffAt` (0.38 m). Both become
loose synced bodies thrown off the car.
Measured through crashRig (hatchback, belted 50th-percentile adult, 2026-10-26).
Version 0.3.2, family saloon, belted 50th-percentile adult (classic), bollard, tow, two runs at each speed
(head = peak, chest = 3 ms clip):
| speed | crush | car pulse (peak / mean) | head | chest | with front airbags: head / chest |
|---|---|---|---|---|---|
| 30 km/h | 0.36 m | 12 / 9 g | 28 / 26 g | 14 / 13 g | 25 / 14 g |
| 50 km/h | 0.82 m | 16 / 11 g | 40 / 37 g | 22 / 20 g | 43 / 20 g |
| 70 km/h | 1.28 m | 29–30 / 16 g | 63 / 58 g | 38 / 36 g | 54 / 29 g |
| 90 km/h | 1.30 m | 59 / 28 g | 349–413 g (see below) | 61–63 g | — |
| 120 km/h | 1.39 m | 89 / 39 g | 600+ g (see below) | 195–360 g | — |
From 10 to 70 km/h every channel rises with speed and two runs agree within 8 %. Above about 80 km/h the
car's own numbers (crush, pulse) stay believable, but the dummy's head reading does not: its neck runs into its
joint stop and the head whips into it in one physics step. A stiffer neck made the solver diverge at 70 km/h,
so it was left as it is; the head reading above 80 km/h is the dummy model's limit, not a measurement.
Earlier the same day, with seat foam and a padded wheel but no positioning hold, door foam or load limiter
(hatchback, bollard):
| test | crush | car pulse (peak / mean) | head | HIC15 | chest 3 ms | energy |
|---|---|---|---|---|---|---|
| bollard 30 km/h | 0.35–0.36 m | 12 / 8–9 g | 26 g | 40–46 | 12–13 g | 43 kJ |
| bollard 50 km/h | 0.79 m | 17 / 11 g | 45–56 g | 157–250 | 22–30 g | 120 kJ |
| bollard 70 km/h | 1.14–1.15 m | 46–51 / 19–21 g | 97–125 g | 1007–1192 | 49–57 g | 235 kJ |
The rows below were measured earlier the same day, before the seat foam and the padded wheel; rear hits and
64–70 km/h frontal hits read higher on the head and chest then (rigid seat backs, rigid wheel).
| test | crush (max) | car pulse (peak / mean) | head | chest 3 ms | panels | energy |
|---|---|---|---|---|---|---|
| rigid wall 30 km/h | 0.21–0.22 m | 20 / 12 g | 16–32 g | 21–22 g | stay on | 43 kJ (= ½mv²) |
| rigid wall 50 km/h | 0.50–0.52 m | 24–29 / 16–19 g | 23–31 g | 27–31 g | bumper + bonnet off | 120 kJ |
| rigid wall 56 km/h | 0.57–0.61 m | 27–42 / 15–19 g | 34–67 g | 29–40 g | bumper + bonnet off | 145–149 kJ |
| rigid wall 70 km/h | 0.70–0.83 m | 38–69 / 23–27 g | 33–177 g | 40–73 g | bumper + bonnet off | 226–234 kJ |
| offset barrier 64 km/h | 0.75 m (0.66 on the far side) | 34 / 21 g | 86 g | 38 g | bumper + bonnet off | 186 kJ |
| small overlap 64 km/h | 1.21 m on the struck side, 0.19 on the other | 64 / 20 g | 114 g | 61 g | bumper + bonnet off | 193 kJ |
| side pole 32 km/h (side-impact dummy) | 0.25 m, the pole's lane only | 38 / 19 g | 53 g | 44 g | — | 47 kJ |
| rear moving barrier 50 km/h | 0.29 m | 13 / 8 g | 21 g | 24 g | — | 70 kJ |
Crush, car pulse and energy rise steadily with speed and repeat within a few percent. The head reading
varies more from run to run, as in real tests without an airbag: it depends on whether the head strikes
the steering wheel.
## Multiplayer
- Spawn on **one** peer (the host or the test rig's authority). `Cars.spawn` uses
`entity.spawnSynced` for every piece, so other peers receive the car and never spawn their own.
- The car simulates on the peer that spawned it. Only that peer runs the lanes and may call
anything that writes physics: `Cars.setVelocity`, `:brake`, `:track`, `:settle`, `:setExclude`,
`:repair`. `Physics.*` writes only work on the simulating peer.
- The dent replicates natively as soft-body particles. The chassis and loose panels replicate as
poses. The crush numbers replicate through the component's synced fields. `measureCrush` on a
replica reads them, up to 0.1 s behind.
- Every mesh and material is an authored asset inside the package, so every peer draws the same
car. Regenerate the meshes in edit mode after changing `specs` or `shape`, with
`require("crashCars.build").all(); require("crashCars.build").refs()`.
## Known limits
- **Wheels have no volume and can't come off** (engine issue #20543). They are `WheelCollider`s, so
a wheel hit is a hit on the body.
- **Soft bodies don't report the energy they absorbed** (#20539), so `energyJ` comes from the lane
model, not from the shell.
- **A kinematic body covers a frame's motion in its first step** (#21187). If a rig drives a car
kinematically, its first contact lands a frame early. Tow it as the dynamic body it is, with
`Cars.setVelocity` every step, as the example does.
- **The crush is a lane model**, three lanes per face. A narrow pole crushes a whole lane's width
(about a third of the car).
- **Two lane-model cars:** in a car-to-car side hit, each car's own lanes push, so the two forces add.
- **Rays need a surface:** the lanes only see an obstacle that has a collider or a soft-body
surface. A mesh with no collider is passed through. Give a pole a pole-sized collider: a convex
hull round a pole and its frame is as wide as the frame.
- **Side tests:** spawn the car with `noTrim = "left"` (or `"right"`) for the struck side. The door
trim that stops the occupant in other crashes is rigid, and an obstacle that accepts every
collision group would stop dead on it.
- **The shell touches nothing.** It is skin: light (3 % of the car), held to the cabin, shaped by
the lanes. It has no underside and no surface round the wheel arches, because a `WheelCollider`'s
ray reads no collision filter and would stand the wheel on its own body.
- **Don't despawn a car's child colliders during play.** A collider removed from a synced body
that way was seen to stay in the physics world under a dead id until the whole car was despawned.
## Seats, foam and the steering wheel
- `Cars.seatLayout(m)` lists each seat (`driver`, `passenger`, and `rear_left`/`rear_right` where the model has
them) with its seat back and head restraint, and for the driver the steering wheel. Each pad is
`{ face, n, up, rigid, halfX, halfUp, foam }` in the car's frame: `face` is the foam surface, `n` points out
of it, and `rigid` is the centre of the rigid frame behind it. The seat back leans back 23°, the torso angle
crashDummies seats at; nothing stands behind the rear bulkhead, where the rear crush zone is.
- `Cars.FOAM` holds the pad depths (m) and spring-damper rates: seat back 8 cm, head restraint 6 cm, wheel hub
on a collapsing column 10 cm.
- Every pad (foam, wheel column, door, airbag) is an explicit spring-damper applied once a physics step, so its
stiffness and damping are capped by the step and the body's mass (k·dt²/m <= 1.6, c·dt/m <= 1.1): at the
world default of 30 steps a second the pads stay stable, and at 60 every pad is exactly as tuned.
- `car.component:setOccupants(bodyIds)` registers an occupant's rigid bodies. Each step the foam pushes them out
along `n` (`k·penetration + c·closing speed`) and the car takes the reaction. Owner only.
- `car.component:fitSeats()` sets the seat up for the settled occupant, as a test lab does: the back's foam to
touch the torso (5 mm preload), the head restraint to a 4 cm backset. Call it after the occupant settles.
- `car.component:padState()` reports each body's gap to its pad and the peak foam force (debug).
- `Cars.GROUPS`: `shell`, `dummy`, `carBody` (every collider of a car's body) and `panel` (a loose panel, which
leaves `carBody` out of its filter so it never touches its own car). Collision groups apply per rigid body, not
per child collider.
- Frontal airbags (`Cars.spawn{ airbags = true }`, CrashCar field `airbags`): the driver's bag fills out of the
wheel hub, the passenger's out of the dash. They fire 15 ms after a frontal hit closing faster than 4.2 m/s
(15 km/h), fill in 30 ms, hold 100 ms, then vent over 120 ms; `airbagFiredMs` says when they fired (-1: not).
While a bag stands it pushes on each occupant body that meets it with a near-steady gas pressure over the
body's area plus a vent-flow term on its closing speed (`Cars.AIRBAG`), and gives back little on the way out.
The bag is drawn as a white cushion (a synced child `airbag_<seat>`) and stays draped after it vents.
- The door's inner trim beside each front occupant is foam too (`door` pad, sill to window frame), and the
steering wheel has no rigid collider: hub, collapsing column and rim are one pad that bottoms out on a stiff
spring (`kWheelBottom`), so nothing the occupant meets is met in a single physics step.
- A cramped rear bench (city car, coupe 2+2) keeps its foam where the occupant sits and leaves out the rigid
seat-back frame, so nothing rigid stands in the rear crush zone (`seat.noRigid`).
## After a test
- `car.component:park(true)`: the lanes stop, so the dent stays exactly what was measured and nothing the car rests
against (the wall, a replay ghost) can push it. The seat foam keeps holding the occupant. `park(false)` or
`repair()` resumes. crashRig parks the car as soon as it has taken its readouts.
- The lanes look through a soft body that collides with nothing (`collisionFilter` or `collisionMemberships` 0),
such as a replay ghost: rays meet every soft surface, whatever its collision groups.
- A car on WheelColliders doesn't sleep, even standing still, so its shell never "comes to rest" either.