# crashObstacles
The things a crash-test car is launched into, built like a real crash lab: a load-cell rigid wall,
the Euro NCAP 40 % offset deformable barrier, the IIHS 25 % small-overlap barrier, a security
bollard, a lighting column, a tree, a W-beam guardrail, a water-barrel crash cushion, a parked car,
the 254 mm side-impact pole and a 1400 kg moving deformable barrier for rear impacts. The crushable
ones are real soft bodies with plasticity, so a ~1300 kg car at 50 km/h leaves a dent that stays,
and the dent replicates to every player. The rigid ones do not move.
Every obstacle tells you how the car meets it (`frontal`, `side` or `rear`), where the car's
centreline should sit for the right overlap (`alignX`), and, for the rear test, which body the rig
launches instead of the car (`mover`).
## Install
Install the package `crashObstacles` from ZeroMind (it lands at `/source/parts/crashObstacles.package`
or wherever you install it) and require it by its bare name:
```luau
local Obstacles = require("crashObstacles.obstacles")
```
`crashCars` is an **optional** dependency: with it installed, the `parkedCar` obstacle is a
crashCars `saloon`; without it, crashObstacles uses its own compact saloon (rigid chassis + soft
denting body shell).
## First example
Paste into a host-only spot (a scene's `onHostLoad`, or an `execute` while playing). It spawns the
offset barrier, lines a 1300 kg test sled up 40 % offset, tows it at 50 km/h, lets go 1 m before the
face and prints the dent the honeycomb kept (0.14 to 0.15 m at 50 km/h: two runs read 0.136 and 0.154 m in a
fresh world at 30 physics steps a second; the example scene's sled measured 0.138 m at 60). The dent varies a
centimetre or two from run to run because the sled meets the honeycomb's particles at a slightly different
point of a physics step each time; the physics rate (`physics.tick_rate`) changes it by about as much:
```luau
--!strict
local Obstacles = require("crashObstacles.obstacles")
local o = Obstacles.spawn({ kind = "offset", position = { 0, 0, -20 }, synced = true,
vehicle = { width = 1.8, length = 4.2 } })
-- a 1300 kg box sled, its nose 3 m from the barrier face, lined up 40 % offset
local sled = entity.spawnSynced("Sled", { position = { o.alignX, 0.8, -20 + 2.1 + 3 } })
sled.localScale = { 1.8, 1.0, 4.2 }
sled.component.add("Model", { model = asset.resolve("cube", "mesh") })
sled.component.add("BoxCollider", {})
sled.component.add("Physics", { kind = "dynamic", mass = 1300 })
local towing = true
local stop = Physics.onBeforeStep(function()
if not towing then return end
if sled.position.z - 2.1 <= -20 + 1 then -- let go 1 m before the face
towing = false
return
end
Physics.setVelocity(sled.id, 0, 0, -50 / 3.6)
end)
task.wait(3)
stop()
print(("offset barrier kept a %.2f m dent"):format(Obstacles.dent(o)))
```
The package's example scene `examples/obstaclesDemo.scene` lays out all eleven obstacles in a lab
and runs the same test on play (component `ObstaclesDemoSled`), printing peak g, mean g and the
dent.
## Gallery
`examples/obstaclesGallery.scene` stands every obstacle in catalog order in one static test hall
(wall, offset, smallOverlap, bollard, pole, tree in front; guardrail, cushion, parkedCar, sidePole,
rear behind), each on its own pad with its impact face toward the camera and a placard giving its
name, id and mode. Each is the real `Obstacles.spawn` build (`synced = false`) stripped to its drawn
parts, so no soft body, rigid body or collider runs; the parked car is crashCars' drawn-only lineup car
when crashCars is installed. Its `galleryCamera` frames both rows. Load it additively (or open it) to
browse the obstacles.
## API
```luau
Obstacles.spawn(opts) -> Handle
```
| option | meaning |
|---|---|
| `kind` | one of the catalog ids below (required) |
| `position` | `{x, y, z}` on the ground at the centre of the impact face; the face points **+Z** (the car comes from +Z travelling toward −Z). Default `{0,0,0}` |
| `synced` | `true` (default) spawns with `entity.spawnSynced` / `addSynced` so every player has it: call on ONE peer (the rig authority). `false` for local or scene-build use |
| `vehicle` | `{ width, length, seatZ? }` of the car that will hit it, used for `alignX` (defaults 1.8 × 4.2 m) |
| `name`, `parent` | root entity name / parent |
| `car`, `builtinCar` | `parkedCar` only: `{ model, look }` passed to crashCars, or `builtinCar = true` to force the built-in car |
| `tune` | advanced: SoftBody field overrides for the crushable part (e.g. `{ stiffness = 5e4 }`) |
Handle: `{ root, kind, spec, alignX, mover, soft, parts, car }`
- `root` — the obstacle's root entity id (`attribute crashObstacle = kind`).
- `spec` — `{ id, name, mode, test, description, crushable, carYaw, alignX = function(vehicle) }`
plus extras (`rear.moverMass`, `rear.moverStart`, `rear.moverFaceOffset`, `sidePole.poleDiameter`,
`offset.barrier`).
- `alignX` — metres along +X the car's centreline should take (already computed for `vehicle`).
- `mover` — `rear` only: the trolley's dynamic body (1400 kg) that the rig launches along −Z.
- `soft` — ids of the soft (crushable) parts; `parts` — named child ids; `car` — crashCars handle.
Also: `Obstacles.despawn(o)`, `Obstacles.catalog()` → list of `{ id, name, mode, description, test,
crushable }`, `Obstacles.kinds()`, `Obstacles.spec(kind)`, `Obstacles.alignX(kind, vehicle)`,
`Obstacles.dent(o)` (deepest permanent dent in metres, read on the simulating peer) and
`Obstacles.repair(o)` (back to the built shape, on every peer).
## Catalog
| kind | mode | real-world test it represents | crushable? | measured at 50 km/h, 1300 kg rigid sled |
|---|---|---|---|---|
| `wall` | frontal | Full-width rigid barrier (FMVSS 208 / Euro NCAP FW) — 3.6 × 1.8 m block, steel face, 32 load-cell plates | rigid | does not move |
| `offset` | frontal | Euro NCAP / ECE R94 ODB, 40 % overlap: 1000 × 650 mm honeycomb (+ stiffer bumper element) 200 mm up | **yes** | 0.39 m dynamic crush, **~0.14 m permanent dent** (0.138 m in the example scene), 28 g mean / 66 ms |
| `smallOverlap` | frontal | IIHS small overlap, 25 %: 1.5 m rigid steel barrier, 150 mm radius edge | rigid | does not move |
| `bollard` | frontal | Narrow-object hit: 273 mm concrete-filled steel bollard | rigid | does not move |
| `pole` | frontal | Lighting column, 8 m octagonal galvanised, 240 mm at the root | rigid | does not move |
| `tree` | frontal | Run-off-road tree: mature Scots pine, 540 mm trunk | rigid | does not move |
| `guardrail` | frontal | W-beam guardrail, 3.81 m span between posts on the centreline | **yes** | 1.8 m dynamic deflection, rail stays bent (plastic 0.82), 7.4 g mean / 260 ms |
| `cushion` | frontal | Crash attenuator: 3 × 4 water-filled barrel array | **yes** | 2.8 m dynamic, **~2.0 m permanent crush**, 6 g mean / 250 ms |
| `parkedCar` | frontal | Car-to-car T-bone into a stationary car | **yes** (car shell) | built-in car: 0.17 m door dent, car shoved sideways, 17 g mean |
| `sidePole` | side | Euro NCAP / FMVSS 214 pole, 254 mm rigid; collides as a 254 × 254 mm box, 3.2 m tall, on the pole axis | rigid | does not move |
| `rear` | rear | Rear MDB (FMVSS 301 / R34 style), 1400 kg, 1700 × 500 mm face | **yes** | 0.13 m permanent face dent into a 1300 kg standing sled |
Peak g read on a rigid sled is a single 200–400 g sample at first contact (a rigid box has no
crumple zone); a car's own crush spreads it. Filter it (SAE J211) as a rig would.
## How the car meets each obstacle
- **Frontal** (`mode = "frontal"`): the car faces −Z (`carYaw = 0`) and travels −Z into the face at
`position`. Put its centreline at `position.x + o.alignX`.
- **Offset / small overlap**: `alignX` puts the barrier's inner edge on the 40 % (`offset`:
`0.5 + 0.1·width`) or 25 % (`smallOverlap`: `0.5 + 0.25·width`) line measured from the driver's
side. The driver sits on the left, i.e. −X when the car faces −Z.
- **Side pole** (`mode = "side"`, `carYaw = -90`): turn the car so its driver's side leads (local
−X → world −Z) and launch it along −Z. `alignX` puts the driver's H-point on the pole axis: it is
`vehicle.seatZ` (the seat's local Z, negative = ahead of centre) or −6 % of the length.
The pole's collider is a rigid 254 mm square `BoxCollider` (3.2 m tall, front face at
`position`) on the pole axis alone: the frame and base plate around it are visual only, so the
door meets a pole-width contact rather than a door-wide wall.
- **Rear** (`mode = "rear"`): park the car facing −Z with its rear bumper at `position`. The rig
launches `o.mover` (the 1400 kg trolley, its face `spec.moverFaceOffset` ahead of the body's
origin and starting `spec.moverStart` m behind `position`) along −Z into it, and releases it
1 m before contact like any tow.
- **Parked car**: the target car stands broadside, its side at `position`; the test car hits it
frontally (T-bone). It is dynamic and gets pushed.
## Multiplayer
Spawn with `synced = true` on one peer (the rig authority, e.g. behind `multiplayer.isHost()`).
Every mesh is an authored `.mesh` asset and every material a `.material` asset inside the package,
so every peer draws the same thing. Soft-body dents replicate natively from the simulating peer
(a replica never dents on its own, and late joiners get the settled shape). Rigid bodies (the
trolley, the parked car) replicate as poses. Push / tow only from the simulating peer.
`Obstacles.dent` reads the local solver, so read it there; `Obstacles.repair` goes through the
`SoftBody` component and reaches everyone.
## Built from
- Concrete (`concreteSmooth`) textures: **Brick and Mortar** masonry collection (MIT, ZeroMind).
- Aluminium, galvanised and raw steel textures: **Forge and Patina** metals collection (MIT, ZeroMind).
- Tree: **RAINLINE realistic mature coastal Scots pine** bundle from AFTERCURRENT (MIT, ZeroMind).
- Everything else (meshes, hazard stripes, chevrons, load cells, barrels, rails, trolley, fallback
car) is generated by `crashObstacles.meshgen` — run `require("crashObstacles.meshgen").buildAll()`
in edit mode to re-author the meshes after changing it.
## Known limits
- **Soft bodies don't report the energy they absorbed** (engine issue #20539). `Obstacles.dent`
gives the permanent dent; an energy figure has to come from the car's speed change.
- **A kinematic body covers a frame's motion in its first step** (#21187): a rig that drives the
trolley kinematically will deliver its first contact a frame early. Tow it as a dynamic body
with `Physics.setVelocity` each step (as the example does).
- The crushable faces are tuned soft bodies, not cell-level honeycomb: the crush force is right in
order of magnitude (pulses of 6–30 g on a rigid sled) but not certified to the 0.342 / 1.711 MPa
ODB spec.
- The offset honeycomb and the MDB face rest on a 30 mm steel tray (it carries their weight; a soft
body this soft would otherwise creep under gravity). On the ODB the tray is set 150 mm back from
the face at 170–200 mm height, so only a car part lower than 200 mm that crushes more than
150 mm reaches it.
- The guardrail's posts are rigid and the rail is bolted (pinned) to them; the car meets the
3.81 m span between the two centre posts. A hit on a post itself is a rigid hit.
- `rear`: the trolley slides on a low-friction skid rather than rolling on wheels.
- `parkedCar` with crashCars depends on that package's car; its own limits apply
(wheels have no volume and can't come off, #20543).
# 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.