# obstacles
The crashObstacles API: `require("crashObstacles.obstacles")`. `spawn({ kind, position, synced, vehicle })`
builds one of eleven crash-test obstacles (wall, offset, smallOverlap, bollard, pole, tree, guardrail,
cushion, parkedCar, sidePole, rear) with its impact face at `position` pointing +Z, and returns a handle
with the obstacle's `spec` (mode frontal / side / rear, real-world test, crushable), the car's lateral
`alignX` for the overlap and, for rear tests, the `mover` trolley the rig launches. Also `despawn`,
`catalog`, `kinds`, `spec`, `alignX`, `dent` (permanent dent in metres) and `repair`. Called by a crash
rig or any game that needs something to crash into; see the package README for the full contract.
# 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).