# catalog
Every choice a crash-test set-up offers, read live from the installed crash parts: `car` (crashCars), `carLook`, `dummy` (crashDummies), `dummyLook`, `belt`, `obstacle` (crashObstacles, with the real test names), `readout` (crashReadouts styles), `cams` (crashCams kinds), plus `mode` (Tow / Drive / Ramp) and `airbag` (None / Front). Rows are `{ id, name, short, detail }`. Also: `ORDER`, `LABEL`, `SHORT` (chip labels, editable), `DEFAULT` / `defaultSetup()`, `SPEED_MIN/MAX/STEP` (10 / 120 / 5 km/h), `mph(kmh)`, `rigConfig(setup)` (what `CrashRig:request("prepare", ...)` takes), `protocol(car, dummy, belt, obstacle, kmh, extra?)` (a full set-up in one line), `key(config)` (stable text key), `everything()` (every id open). Used by `crashSetup.panel`, `crashSession.session` and games.
# 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.
# CrashRig
The shared crash-test rig. Put it on **one synced scene entity**. It needs no sibling components: it spawns
everything a test needs through the crashCars, crashDummies and crashObstacles parts.
- **Who runs the test.** The peer that owns the entity is the authority: it spawns the car, the dummy in
its seat and the obstacle (all synced), launches the car, measures it and writes the `CrashResult` into
the synced `result` field. Every player sees the same test and the same numbers.
- **Who can ask.** `rig:request("prepare" | "run" | "reset" | "clear", config?)` works from any peer; a
non-owner's request travels to the owner over `multiplayer.send`.
- **How a run goes.** `state` moves through `idle`, `preparing`, `ready`, `countdown`, `running`,
`settling` and `results`. `message` is one human line for a HUD.
- **How it launches.** Cars are towed (speed builds over 60 % of `runup`, released 1 m out) or driven
(`config.mode = "drive"`). Rear hits launch the moving barrier into the parked car. Side hits slide the car
sideways into the pole.
- **Replay.** Every peer records what it sees; `rig:replay{ speed = 0.25 }` plays it back locally as ghosts,
and `rig:stopReplay()` ends it. The live crash entities sit on the render layers `default crash`.
- **Changing owner.** A new owner that finds a test half-run sets it up again.
Fields: `origin`, `runup`, `countdown`, `config`, `state`, `testId`, `result`, `carId`, `shellId`,
`dummyRoot`, `dummyHead`, `dummyBodies`, `obstacleRoot`, `moverId`, `spawned`, `message`.
See the package README for the `CrashResult` fields and measured numbers.
# panel
Widget-tree builders for a crash-test game screen (graphite panels, hazard-yellow accent, Anton / Arimo / JetBrains Mono). Each takes one state table `S` (`sampleState(opts)` makes one): `setupPanel(S)` (tabs VEHICLE / OCCUPANT / TEST / CAMERAS / PROGRAMME, chip grids with padlocks for locked options, the 10–120 km/h speed chooser, Tow/Drive/Ramp, airbags, readout style, replay shot list, the ladder's test list, RUN TEST / RESET; a left panel or a phone bottom sheet), `setupTab`, `topBar`, `progressStrip` (nil without a ladder), `live`, `actions` (REPLAY / NEXT TEST / SET-UP, SKIP while replaying), `toast`, plus `button`, `hazard`, `statePill`, `icon`, `ICON`, `K` (palette), `TABS`, `tabs(S)`, `tabRows(tab)`. Element ids are `<S.prefix>_…` and callback ids `<S.prefix>:<verb>:…` (default prefix `crash`); the package README lists them. Pure: no screens registered, no state kept. Used by `crashSession.session`.
# CrashCamOverlay
The "recording" burn-in of a lab high-speed camera, as local UI over the picture: a blinking REC dot, the camera `label`, `fps` and shutter, a timecode and a frame counter (simulated seconds x `fps`, so slow motion counts slowly), and corner marks. Put it on a camera entity or call `Cams.overlay(camera, true, opts)`; the director writes `label` on every cut. `:resetClock()` zeroes the counter at the start of a take. Nothing syncs.
# 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.
# goals
Goal kinds read off a crashRig `CrashResult`, shaped for `unlockLadder`: `KINDS.run` (reached the barrier), `stars` (rating ≥ value), `hic` (head HIC15 < value), `headG` (head peak < value g), `chest3ms` (chest 3 ms < value g). Each is `{ text(goal), met(goal, result) -> (ok, measured) }`. A result the rig marked `invalid` never meets a goal; `invalid(result) -> (bool, note)` reads it. `matches(step, result)` says whether a result is a run of `step.config` (car, dummy, belt, obstacle, speed ±1.5 km/h). Use: `Ladder.new({ goals = Goals.KINDS, match = Goals.matches, ... })`.
# camCore
Shared internals of the six crashCams camera behaviours: reads a subject where it is drawn this frame (through the builtin `controller.camera_rig` helpers over `Physics.drawnPose`), resolves the `car` / `head` / `impact` targets (falling back to `Camera.follow`), places and aims the camera with an up hint, converts points to and from a body's frame, and writes the sibling Camera's lens only when it changes. Required by the `CrashCam*` components; not part of the public API (`crashCams.cams` is).
# ReadoutPanel
Shows a crash test's `CrashResult` on THIS player's screen, in any crashReadouts style. Put it on any
entity (it needs no sibling components); UI is local, so every peer calls `:show(result)` on its own
panel with the result the rig shares.
- **Fields:** `style` (8 ids), `visible`, `anchor` (`topRight` / `topLeft` / `bottomRight` /
`bottomLeft`), `carEntity` / `headEntity` (what the `floating` labels follow), `carLabelHeight`,
`headLabelHeight`, `layer`, `closable`, `showSample`.
- **Methods:** `:show(result?, anchors?)`, `:hide()`, `:setStyle(id)`, `:setAnchors({ car, head })`,
`:collapse(on?)`, `:current()`.
- **Events:** `onClosed`, `onCollapsed { collapsed }`.
- **Placement:** about a third of a desktop screen in the chosen corner, beside the 3D view; a bottom
sheet on screens narrower than 640 points (phones); a wide bar for `lowerThird`; the whole screen
for `floating`. Slides in on show; 40-point round collapse and close buttons sit outside the panel
(above the sheet on phones), and collapsing leaves a tappable "CRASH RESULTS ★★★★" pill.
# ladder
`Ladder.new({ id, steps, start, goals, match, store? })` makes an unlock ladder. Steps are passed in order; each one's `reward` list of `{ category, id }` pairs unlocks items on top of `start`. API: `done()`, `complete(id, info)`, `level(done?)`, `unlocked(done?)`, `unlockedBy(cat, id)`, `goalText(goal)`, `goalMet(goal, result)`, `matches(step, result)`, `credit(result, activeId?, extra?)`, `savePref(key, v)`, `loadPref(key, default)`, `count()`, `byId`, `steps`, `session` (unsaved scratch). `Ladder.memoryStore()` gives an in-memory store for tests. Saved per player under `<id>/done/` and `<id>/prefs/` in `runtime_data.player(localId)`. Used by `crashSession` and the Crumple Zone game.
# crashSetup
The **set-up side of a crash-test game**, built on the crash parts this world ships (crashCars, crashDummies,
crashObstacles, crashReadouts, crashCams):
- **`crashSetup.catalog`**: every choice a test can use, read live from the installed parts, so a menu never
drifts from what the parts spawn: 9 cars, car looks, 6 dummies, dummy looks, 5 belts, airbags (None /
Front), 11 barriers with their real test names, launch modes (Tow / Drive / Ramp), readout styles and
replay cameras. Plus the default set-up, the 10–120 km/h range, mph, the rig config it sends and
`protocol(...)`, a whole test set-up in one line.
- **`crashSetup.goals`**: goal kinds read off a `CrashResult` (run, stars, HIC15, head g, chest 3 ms) and the
"is this a run of that protocol" rule, ready for an `unlockLadder` programme. Runs the rig marks invalid
never pass.
- **`crashSetup.panel`**: the screen's widget builders: the tabbed **set-up panel** (side panel on desktop,
bottom sheet under 720 pt) with chip grids and padlocks, a big km/h readout with − / + and a chip per
10 km/h up to 120, a numbered replay shot list, the test programme list, RUN TEST / RESET; the **top bar**,
**programme strip**, **live telemetry**, **results / replay action bar** and **toasts**.
`crashSession` runs all of this as a full game loop; use crashSetup directly to build your own.
## First example
Put this in any scene's `entrypoint.luau` and press Play: the set-up panel appears on the left, and the chips,
the tabs and the speed chooser all work.
```lua
local Catalog = require("crashSetup.catalog")
local Panel = require("crashSetup.panel")
local S = Panel.sampleState({ prefix = "demo" }) -- default set-up, every option open
local function draw()
S.W, S.H = ui.screenSize().width, ui.screenSize().height
S.compact = S.W < 720
ui.updateScreen("setupDemo", { type = "vertical", style = { width = "100%", height = "100%" },
children = { (Panel.setupPanel(S)) } })
end
function onLoad()
ui.registerScreen("setupDemo", { type = "vertical", children = {} }, 40)
ui.showScreen("setupDemo")
draw()
end
function onCallback(id: string)
local p = string.split(id, ":") -- "demo:<verb>:<args>"
if p[1] ~= "demo" then return end
if p[2] == "tab" then S.tab = p[3]
elseif p[2] == "pick" then S.setup[p[3]] = p[4]
elseif p[2] == "speedSet" then S.setup.speedKmh = tonumber(p[3])
elseif p[2] == "speed" then
S.setup.speedKmh = math.clamp(S.setup.speedKmh + (p[3] == "up" and 5 or -5), Catalog.SPEED_MIN, Catalog.SPEED_MAX)
elseif p[2] == "run" then print("send to the rig:", Catalog.key(Catalog.rigConfig(S.setup)))
end
draw()
end
```
## The state table `S`
| Field | What |
|---|---|
| `W`, `H`, `compact` | screen size in points; `compact` = phone layout |
| `prefix` | element id / callback id prefix (default `crash`) |
| `brand` | `{ title, sub, lab }` for the top bar and the panel header |
| `setup` | the set-up: `car, carLook, dummy, dummyLook, belt, airbag, obstacle, speedKmh, mode, readout, cams = {..}` |
| `unlocked` | `{ [category] = { [id] = true } }` (nil = everything open) |
| `ladder`, `done`, `level`, `activeTest` | an `unlockLadder` and its progress (optional: no ladder, no programme tab) |
| `tab`, `focus`, `focusArea`, `progFocus`, `actFocus`, `pad` | navigation highlight for keyboard / gamepad |
| `rig` | `{ present, state, message, testId }` from the `CrashRig` |
| `phase`, `live`, `replay`, `players`, `setupShown`, `panelW`, `toastTop` | what the other builders read |
## Ids
Element ids (for tests, `gui.press`, `gui.clickElement`): `<p>_setup`, `<p>_tab_<tab>`, `<p>_row_<cat>`,
`<p>_chip_<cat>_<id>`, `<p>_speed_<10..120>`, `<p>_speed_up`, `<p>_speed_down`, `<p>_cam_<kind>`,
`<p>_test_<stepId>`, `<p>_run`, `<p>_reset`, `<p>_replay`, `<p>_next`, `<p>_change`, `<p>_skip`, `<p>_free`,
`<p>_topbar`, `<p>_progress`, `<p>_live`, `<p>_actions`, `<p>_toast`, `<p>_menu`.
Callback ids: `<p>:tab:<tab>`, `<p>:pick:<cat>:<id>`, `<p>:speed:up|down`, `<p>:speedSet:<kmh>`,
`<p>:cam:<kind>`, `<p>:test:<stepId>`, `<p>:lockedTest`, `<p>:free`, `<p>:run`, `<p>:reset`, `<p>:replay`,
`<p>:next`, `<p>:setup`, `<p>:skip`, `<p>:hideSetup`, `<p>:showSetup`, `<p>:menu`.
## Gallery
`crashSetup/examples/setupGallery.scene` puts the panel's five tabs side by side, each labelled, with the top
bar, programme strip, live telemetry, the results and replay bars and a toast, drawn by
`crashSetup.examples.SetupGallery`.
## Tests
`crashSetup` suite (`zero tests run crashSetup`, edit mode): the catalog matches the installed parts row for
row, defaults and protocols, the goal kinds (and that an invalid run never passes), protocol matching, and
the panel: every documented element id is present with the right callback, locked chips carry a padlock,
the programme tab appears only with a ladder, speed chips run 10 to 120, the phone sheet layout, and that
every builder's screen registers with no validation errors.
# 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.
# crashRig
A crash-test rig that **every player in a world shares**. Put one `CrashRig` component on a scene entity
and any player can set up a test (car, dummy, belt, obstacle, speed), run it, read the results and watch a
slow-motion replay. The rig builds on three sibling parts:
- **crashCars** (the crumpling cars),
- **crashDummies** (the ragdoll dummies and belts),
- **crashObstacles** (walls, barriers, poles, trees, moving barriers).
What it does on each run:
- **Spawns** the car, the dummy in its seat and the obstacle, all synced. Every player sees the same things,
and the dents and loose panels replicate.
- **Launches** the car one of four ways:
- a **tow** on a guide cable: speed builds over the first 60 % of the run-up and is released 1 m before
contact, as real tow rigs work;
- **drive**: the car drives itself, with rear-wheel drive, cruise control and a lane keeper;
- a **moving barrier** launched into a parked car's rear, for rear hits;
- a **side slide** into a pole, with the tyres' side grip released, for side impacts.
- **Measures** the dummy's head and chest and the car's pulse at the driver's seat. Motion probes sample
at the solver substep rate. Each channel is resampled to 1 kHz and filtered SAE J211-style: CFC 1000 for
the head, CFC 180 for the chest, CFC 60 for the car. From those come peak g, **HIC15**, the **3 ms clip**,
the car's peak and mean g, pulse length, crush (maximum and residual), energy, panels that came off, and a
**star rating** with good / acceptable / marginal / poor bands for head, chest and structure.
Each channel is filtered whole, then cut to the crash itself, from 120 ms before the rig sees the tested
face start to crush to 300 ms after (the brakes come on at +300 ms), so the tow and the braking never
set a peak.
- **Sets the seat up** for the dummy: after it settles, the rig hands the dummy's bodies to the car as
occupants (`setOccupants`) and fits the seat back's foam and the head restraint to it (`fitSeats`).
- **Publishes** a `CrashResult` in the synced `result` field, so every player gets the same numbers.
- **Records** what each player saw, so each player can replay it in slow motion. Pair it with
**crashCams**' director to show the replay from two or more angles.
## Install
Install `crashRig`, `crashCars`, `crashDummies` and `crashObstacles`; `crashCams` and `crashReadouts` are
the natural companions. Every part is required by its bare name (`require("crashRig.measure")`), so they
can sit in any folder.
## First example
Paste this into a scene's entrypoint. It works in play, in an empty world with any floor at y = 0 covering
x -10..10 and z -15..60, at the world's default 30 physics steps a second or at 60 (see "Physics rate" under
Known limits: the numbers this README quotes are at 60):
```lua
function onLoad()
local e = entity.find("CrashRig") or entity.spawnSynced("CrashRig")
local rig = e.component.get("crashRig.CrashRig") or e.component.add("crashRig.CrashRig", { origin = { 0, 0, 0 } })
task.spawn(function()
rig:request("prepare", { car = "hatch", carLook = "realistic", dummy = "adult50", dummyLook = "classic",
belt = "threePoint", obstacle = "wall", speedKmh = 56, mode = "tow" })
while rig.state ~= "ready" do task.wait(0.2) end
rig:request("run")
while rig.state ~= "results" do task.wait(0.2) end
local r = rig.result
if r.invalid then
print("invalid run, no rating: " .. r.invalidNote)
else
print(string.format("%.0f km/h: head %.0f g (HIC15 %.0f), chest %.0f g, crush %.0f cm, %d stars",
r.impactSpeedKmh, r.headPeakG, r.headHIC15, r.chest3msG, r.crushMaxM * 100, r.rating.stars))
end
local pb = rig:replay({ speed = 0.25 }) -- this player's slow-motion replay, as ghosts
end)
end
```
## API
`CrashRig` fields (all synced):
| field | meaning |
|---|---|
| `origin` | world point of the obstacle's impact face; the track runs toward +Z from it |
| `runup` | metres of tow (46) |
| `countdown` | seconds counted down before a launch (3) |
| `config` | `{ car, carLook, dummy, dummyLook, belt, obstacle, speedKmh, mode = "tow" \| "drive" }` |
| `state` | `idle`, `preparing`, `ready`, `countdown`, `running`, `settling` or `results` |
| `result` | the last `CrashResult` (below) |
| `message` | one human line about what the rig is doing |
| `carId`, `shellId`, `dummyRoot`, `dummyHead`, `dummyBodies`, `obstacleRoot`, `moverId`, `spawned` | what is on the track now |
| `testId` | how many tests have run |
Methods:
- `rig:request(action, config?)` works from **any** player.
- The rig's owner acts on it at once; anyone else's request reaches the owner over `multiplayer.send`.
- Actions: `"prepare"` (set the test up, then `ready`), `"run"` (count down, launch, measure, `results`),
`"reset"` (set the same or a new test up again), `"clear"`.
- `rig:replay({ speed = 0.25, loop, onDone, onFrame })` replays the last run on this peer only.
- It returns a playback with `stop()`, `time()`, `playing()` and `ghostOf(id)`, which gives the ghost
standing in for a live entity, for camera targets.
- The live crash entities are on the render layer `crash` ONLY (not `default` as well: a camera draws an
entity that shares any layer with it, so a wreck left on `default` showed under its own replay ghost as a
doubled car), so a replay camera draws
`"all !crash"` and sees only the ghosts.
- `rig:stopReplay()`, `rig:replayImpactTime()` and `rig:isBusy()`.
Modules:
- `crashRig.measure` holds the signal processing as pure functions: `channel`, `resample`, `cfc` (SAE
J211), `hic`, `clip3ms`, `peak`, `decimate` and `rate`.
- `crashRig.recorder` records any hierarchy's drawn poses and soft-body particles, and plays them back as
local ghosts: `new{ roots, track }`, `start`, `stop`, `trim`, `play`.
## CrashResult
`id`, `config`, `names{car,dummy,belt,obstacle}`, `mode`, `face`, `impactSpeedKmh`, `headPeakG`,
`headHIC15`, `head3msG`, `chestPeakG`, `chest3msG`, `carPeakG`, `carMeanG`, `crushMaxM`, `crushResidualM`,
`crushShare`, `energyKJ`, `structureKJ`, `energyNote`, `partsDetached`, `pulseMs`,
`rating{stars, head, chest, structure, score}`, `traces{dt, head, chest, car}` (filtered, ≤160 points
each), plus `invalid` / `invalidNote` when the solver diverged.
- **Energy:** `energyKJ` is the kinetic energy lost in the crash, ½mv² before minus after, with the moving
barrier included for rear hits. `structureKJ` is how much of it the car's crumple zone took, from the
crashCars lane model.
## Measured
Hatchback, 50th-percentile adult in a 3-point belt, rigid wall, 56 km/h, three runs:
| measure | result |
|---|---|
| crush | 0.56–0.61 m |
| car pulse | 34–42 g peak, 18–21 g mean, over ~100 ms |
| energy | 146–149 kJ (½mv² is 151 kJ) |
| head | 42–74 g, HIC15 70–450 |
| chest (3 ms) | 47–57 g |
| rating | 3–4 stars |
## Multiplayer
- One peer, the owner of the rig entity, runs each test. Everyone sees the same car, dummy, dents, loose
panels and numbers.
- If the owner leaves, the next owner finds the test half-run and sets it up again.
- Replays are per peer: each peer replays what it drew.
## Known limits
- **No simulation playback (#20544).** The engine can't record and play back the simulation, so the replay
is rebuilt from the poses and soft-body particles each peer drew. It is a faithful picture of what that
peer saw, not a re-simulation.
- **Ragdoll poses on other players' screens.** A ragdoll is drawn at physics-tick poses (#21188), and may
not show ragdolled for other players at all (#18554). Their replay of the dummy shows what they received.
- **Kinematic first step (#21187).** A kinematic body covers a frame's motion in its first step, so the rig
tows with velocities, never kinematically.
- **Waits are capped (#19849).** Long engine waits are capped, so a script waiting on a run should poll
`state` in short waits, as the example does.
- **Barrier energy (#20539).** Soft bodies don't report energy absorbed, so a crushable barrier's own share
of the energy is not in `structureKJ`; `energyKJ` (the kinetic energy lost) covers it.
- **Probe sample rate.** Probes sample at the physics substep rate, 240 Hz at a 60 Hz tick. Head and chest
are therefore band-limited by the physics rate: CFC 1000 / 180 filter nothing above roughly 120 Hz.
HIC15 and the 3 ms clip are computed on the 1 kHz resample.
- **Invalid runs get no rating.** The rig publishes a run as `invalid` (with `invalidNote` saying why, and
`rating = nil`: no stars) when its numbers can't be a crash test: the solver diverged (NaN, a head over
1000 g, a car over 400 g, a chest over 600 g); the car went much faster than the test asked before the hit
(`peakSpeedKmh` over 1.4x the target: a launch blow-up); or the car didn't arrive at the test speed (more
than 20 % off, 30 % for a ramp). The status line then starts "INVALID RUN (no rating)". crashReadouts draws
such a run with an INVALID stamp and no stars.
- **Physics rate.** A fresh world steps physics 30 times a second (`physics.tick_rate`); this world runs 60.
The rig works at either: every spring the rig and crashCars apply themselves (the positioning hold, the
seat, head-restraint, door and wheel foam, the airbag) is capped by the physics step and the body's mass,
so it can't overshoot and blow up at 30, and is untouched at 60. (Before that cap, at 30 the positioning
hold diverged a second into the tow and threw the car off at thousands of km/h.) The readings do depend on
the rate: family saloon, adult, 3-point, bollard, at 30 steps a second two series read head 16-18 /
23-39 / 38-42 g and chest 12-14 / 16-26 / 30-31 g at 30 / 50 / 70 km/h (crush 0.34 / 0.78-0.82 / 1.32-1.36 m),
against 26-29 / 37-40 / 49-54 g (one run in five at 70 km/h read 77) and 13-14 / 21-22 / 30-36 g at 60. At 60
every reading rises with speed and repeats within 20 %; at 30 the crush and chest rise, but the head spreads
more from run to run and a 50 km/h run can read as high as a 70 km/h one. For the readings this README and
crashCars' tables quote, set `physics.tick_rate = 60` in the world's settings (`/source/.world_settings`,
`[physics]`); the rig can't change the rate itself and warns once in the log when it is lower. Each result
carries `tickRate`.
- **Web build untested.** An agent can't start a browser engine to check the web build (#20946).
- **Wheels (#20543).** A car's wheels are WheelColliders: they have no volume and can't come off.
- **Publishing.** `zm push` can misreport its result (#21207, #21206, #21025): after a push, check the
world's published commit rather than trusting the message.
## Multiplayer checks (2026-10-26)
- Reset clears everything: three resets in a row left the world exactly as before (entities, bodies, colliders,
soft bodies), each new car undented to within 0.03 mm, and no replay ghosts left over.
- Every live test entity (car, shell, dummy, obstacle, moving barrier, and loose panels as they come off) is kept on
the render layer `crash` **on every peer**: layer membership isn't replicated, so each peer sets it, and
re-applies it as children stream in. A replay camera drawing `"all !crash"` then shows only the ghosts.
- What a second player needs is synced and verified with `multiplayer.explain`: the rig's `state`, `result`,
`message`, and the car's crush fields. No second client was connected for this check (#20946); a ragdoll may not
show ragdolled for other players (#18554).
## Round 3 (version 0.3.2): repeatable readings, three launch modes, airbags, 10–120 km/h
- **Repeatable readings.** The dummy settles counted in physics steps (until it is still relative to the car),
the seat is fitted, and from the start of the tow until the crush begins a **positioning hold** (the breakaway
tape a lab uses: a stiff, critically damped spring per dummy segment, in the car's frame) keeps the dummy where
it sat, so every test meets the obstacle from the same posture. The data window (−120 / +300 ms) hangs off the
physics step the crush began in, not off a frame. Family saloon, adult, 3-point belt, bollard, two runs each:
head 28/26, 40/37, 63/58 g and chest 14/13, 22/20, 38/36 g at 30/50/70 km/h (crashCars README has the table).
- **Launch modes** (`config.mode`): `tow` (cable tow, lets go 1 m before the barrier), `drive` (the car drives
itself in) and `ramp`: the tow lets go 0.5 m before a 3 m steel ramp whose lip stands 8 m out, angled 2–12°
(`crashRig.launch`) so the car comes down just short of the barrier; the impact speed is read when the crush
starts (a 50 km/h ramp test hits at 47.9 km/h). Frontal obstacles only; side and rear hits use the tow.
- **Airbags** (`config.airbag = "front"` or `true`): the car is spawned with crashCars' front airbags; the result
carries `airbag = { fitted, firedMs }` and the restraint name gains "+ airbag".
- **Speed**: any `speedKmh`; the game offers 10–120 km/h. Above about 80 km/h the car's crush and pulse stay
believable but the dummy's head reading does not (its neck runs into its joint stop): see crashCars' README.
- **`synced`** (default true): false runs the whole test on this peer only (offline, and the test suite, whose
play session holds no relay ownership).
- **Gallery** `examples/rigGallery.scene`: the three launch modes (with the ramp the rig builds) and every
restraint, each labelled, plain Models only (`examples/rigGalleryLayout`).
- **Tests** `crashRig.testSuite` (10): CFC filter, HIC15 against its closed form, 3 ms clip, monotonic readings,
decimation, star bands, recorder bookkeeping, and a whole 30 km/h wall test with airbags in play that publishes
a sane result and clears everything it spawned. Run `zero tests run crashRig` in edit mode.
# 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).
# crashReadouts
Crash-test results shown eight ways, built for the Crumple Zone crash-test-dummy simulator and usable
by any game that has a `CrashResult`. Installing the package gives you:
- **`readouts` module** (`require("crashReadouts.readouts")`): a pure display. It turns a CrashResult
into a widget tree in one of 8 styles, makes a believable sample result for demos, and ships the
SVG helpers the styles are drawn with (trace plots, seven-segment digits, stars, body diagram).
- **`ReadoutPanel` component**: puts a style on the local player's screen, beside the 3D view (the
crash replay keeps playing behind it). It is a side panel on desktop and a bottom sheet on phones.
It slides in and has touch-sized collapse and close buttons.
- **`ReadoutsDemo` component + `examples/readoutsDemo.scene`**: the sample result in every style,
stepped with Space / ← → or the on-screen arrows.
It computes nothing a CrashResult doesn't already hold: every number on screen is a field of the
result, formatted.
## Install
Install the package (from ZeroMind, by its guid) into `/source`. Everything is required by bare name:
`require("crashReadouts.readouts")`, `asset.resolve("crashReadouts.ReadoutPanel", "component")`.
**Depends on barsKit** (Gaugeworks, ZeroMind guid `c154eb07-ce7c-48ca-8232-4ce1a8754214`, 1.3.0; listed under
`dependencies` in `package.yaml`). Every bar and gauge in the readouts is a barsKit look drawn in the style's own
colours through `barsKit.looks` (`Looks.render(id, Looks.view{...})`) and `barsKit.palette`. Only those two
pure modules are used: no barsKit HUD, Bar component or health kit runs. Install barsKit first (its own
dependencies, SecondWind and Lifeline, come with it), then crashReadouts.
| Style | barsKit look | Shows |
|---|---|---|
| `scifi` | `ring` (scaled to the slot, hologram tint) | head peak / 80 g, HIC15 / 1000, chest peak / 60 g, each coloured by its rating |
| `lcd` | `segmented`, 5 cells, LCD ink | the star rating |
| `lowerThird` | `line` (compact) | head / 80 g, chest / 60 g, crush / 1 m under those stats |
| `floating` | `ghost` (compact) | head: 3 ms value solid, peak as the lingering ghost; car: residual crush solid, max crush as the ghost |
The other four styles (lab printout, oscilloscope, plain, star rating) draw no bars: they are paper, a CRT, a
number card and a body diagram, and a bar would not belong in them.
## First working example
Run in play mode (a script, a component's `start`, or `execute`):
```lua
local Readouts = require("crashReadouts.readouts")
local results = entity.spawn("CrashResults")
results.component.add(asset.resolve("crashReadouts.ReadoutPanel", "component"), { style = "oscilloscope" })
results.component.get("ReadoutPanel"):show(Readouts.sample({ speedKmh = 64 }))
```
With a real test, pass the rig's result and, for `floating`, the car and head entities:
```lua
panel:show(result, { car = car.id, head = dummy.head })
panel:setStyle("floating")
```
To see all eight, open `examples/readoutsDemo.scene` and press play.
## API
### `readouts` module
| Function | Returns |
|---|---|
| `Readouts.styles()` | `{ { id, name, description, tags } }`: the 8 styles, in catalogue order |
| `Readouts.render(style, result, { w, h, t?, points? })` | widget tree sized `w × h`. `t` = seconds since shown and drives the entrance; omit it for the settled look. `points = { car = {x,y,visible}, head = {x,y,visible} }` (UI canvas points) places the `floating` labels. An unknown style falls back to `plain`. |
| `Readouts.layout(style, screenW, screenH, anchor?)` | `{ x, y, w, h, sheet?, full? }`: where the style sits on that screen |
| `Readouts.sample(opts?)` | a CrashResult with traces; `opts = { speedKmh, car, dummy, belt, obstacle, id }`. Default: hatchback, Hybrid III 50th, 3-point belt, rigid wall, 56 km/h (head ≈ 59 g, HIC15 ≈ 360, chest ≈ 43 g, car peak ≈ 45 g / mean ≈ 23 g, crush 55 / 42 cm, ≈ 158 kJ, bumper off, 4 stars) |
| `Readouts.rows(result)` | the readouts as formatted rows `{ key, label, short, value, unit }` |
| `Readouts.traceSvg(result, opts)` | SVG of `result.traces`: grid, lines, glow, peak cursors, axis labels, sweep-in (`reveal`) |
| `Readouts.sevenSegSvg(text, opts)` | seven-segment digits with ghost segments, plus the aspect ratio |
| `Readouts.starsSvg(n, opts)` / `Readouts.bodySvg(result, opts)` | star row / occupant silhouette coloured by rating |
### `ReadoutPanel` component
Fields: `style`, `visible`, `anchor` (`topRight` | `topLeft` | `bottomRight` | `bottomLeft`),
`carEntity`, `headEntity`, `carLabelHeight` (1.6 m), `headLabelHeight` (0.2 m), `layer` (60),
`closable`, `showSample`. All are NoSync: UI is per peer.
Methods: `:show(result?, anchors?)` (opens and replays the entrance; nil keeps the last result, or a
sample if there is none), `:hide()`, `:setStyle(id)`, `:setAnchors({ car, head })`, `:collapse(on?)`,
`:current()`. Events: `onClosed`, `onCollapsed { collapsed }`.
Placement: on a screen ≥ 640 points wide, about a third of it (360–470 points) in the anchor corner,
with the collapse/close buttons outside the panel's inner edge. On a narrower screen (a phone) it is a
bottom sheet about half the height, with the buttons above it. `lowerThird` is a wide bar along the
bottom. `floating` covers the screen and its labels follow the entities each frame. Collapsing
leaves a "CRASH RESULTS ★★★★" pill that reopens on tap.
## Style catalogue
| id | name | look |
|---|---|---|
| `labPrintout` | Lab printout | Dot-matrix report on tractor-feed paper: header, test no., config, channel table, three mini traces, rubber PASSED/FAILED stamp with stars |
| `oscilloscope` | Oscilloscope | Green-phosphor CRT: graticule, head / chest / car g traces sweeping in, peak cursors, measurement boxes, bezel knobs |
| `lowerThird` | TV lower third | Broadcast bar that wipes in: CRASH TEST tag, headline, star badge, stats strip, scrolling data ticker |
| `plain` | Plain | Clean white card, big legible numbers |
| `lcd` | Retro LCD | Beige data logger, backlit seven-segment LCD with ghost segments, annunciators, rating bar, membrane buttons |
| `scifi` | Sci-fi hologram | Translucent blurred panel, corner brackets, ring gauges, glowing trace, moving scanline |
| `stars` | Star rating | Euro-NCAP-style: stars, body diagram with head/neck, chest, legs in good / acceptable / marginal / poor colours, key numbers |
| `floating` | Floating labels | Callouts with leader lines over the car and the dummy's head in the 3D view, plus a summary chip |
## CrashResult fields it reads
From the crashRig contract (`/source/design/SPEC.md`):
`id`, `config.{car, dummy, belt, obstacle}` (shown when `names` lacks one), `names.{car, dummy, belt, obstacle}`,
`impactSpeedKmh`, `headPeakG`, `headHIC15`, `head3msG`, `chestPeakG`, `chest3msG`, `carPeakG`,
`carMeanG`, `crushMaxM`, `crushResidualM` (shown in cm), `energyKJ`, `energyNote` (always shown as the `*`
footnote beside energy), `partsDetached`, `rating.{stars, head, chest, structure}`,
`traces.{dt, head, chest, car}`, `invalid`, `invalidNote`. A missing number shows as "—".
**Invalid runs.** When the rig flags a broken run (`invalid = true`, `invalidNote` = why, `rating = nil`),
every style still prints the numbers but marks the run INVALID, shows the note and draws **no stars**: the lab
printout stamps INVALID / NOT RATED, the oscilloscope shows a red INVALID RUN box and a VOID chip, the lower
third swaps its star badge for a red INVALID badge and leads its ticker with the note, the plain card and the
star rating show a red invalid banner (the star rating an INVALID RUN stamp where the stars were), the LCD lights
its ERR annunciator, the sci-fi panel shows an amber warning, and the floating labels carry an INVALID RUN tag
on each callout and the summary chip. The collapsed ReadoutPanel pill reads INVALID instead of stars.
Body-diagram colours: head uses `rating.head`, neck uses `rating.neck` if present, otherwise
`rating.head`. Chest uses `rating.chest`. Legs use `rating.legs` if present, otherwise
`rating.structure`, labelled "Legs & feet (structure)". The printout stamp reads PASSED when
`rating.stars ≥ 3`.
## Gallery
`examples/readoutsGallery.scene` shows all eight styles at the same time: a grid of cards (4 x 2 on
a desktop, 2 x 4 on a tablet, one scrolling column on a phone), each titled with the style's name and
filled with `Readouts.sample()`. The floating-labels card is a live render of a still hatchback with
a dummy in the driver's seat (crashCars meshes, no physics), with the callouts placed over the car
and the head. The grid is the `examples/ReadoutsGallery` component, and it shows in edit mode as
soon as the scene loads. Tests: `crashReadouts.testSuite` (`tools.use("tests", "run", "crashReadouts")`).
## Known limits
- **Energy is not absorbed energy.** Soft bodies don't report the energy they absorb (#20539), so the
rig reports the car's kinetic energy lost. Every style prints the result's `energyNote` next to it.
- **`floating` needs the scene camera.** It projects entity positions with `worldToScreen` against the
viewport camera. If an anchor is off-screen or behind the camera, its label hides. Without anchors
the labels sit at fixed screen spots. A ragdoll head is drawn at physics-tick poses (#21188), so the
head label can step slightly at low frame rates.
- **Local UI only.** Each peer shows its own panel. Share the CrashResult (the rig does) and call
`:show` on every peer.
- The keyboard shortcuts in `ReadoutsDemo` are raw key polls. Its on-screen arrows cover touch.
`ReadoutPanel` itself needs no keys.
# unlockLadder
An ordered **ladder of challenges** with **unlocks** and **saved progress**, for any game. Each step has a
fixed config, a goal read off whatever result your game produces, and a reward that unlocks items for free
play. Pure rules and data: no UI and no game types, so a racing game, a puzzle game or a crash-test game
uses the same module (Crumple Zone's 15-test programme is built on it, with `crashSetup.goals`).
## First example
Put this in any scene's `entrypoint.luau` and press Play; the Output shows the ladder moving.
```lua
local Ladder = require("unlockLadder.ladder")
function onLoad()
local L = Ladder.new({
id = "demoLadder", -- save key root
store = Ladder.memoryStore(), -- drop this line to save per player
start = { car = { "hatch" } }, -- unlocked from the start
steps = {
{ id = "first", title = "First lap", goal = { kind = "run" }, reward = { { "car", "coupe" } } },
{ id = "fast", title = "Under a minute", goal = { kind = "under", value = 60 }, reward = { { "car", "truck" } } },
},
goals = { under = {
text = function(g) return "Finish under " .. g.value .. " s" end,
met = function(g, r) return r.time < g.value, string.format("%.1f s", r.time) end,
} },
})
print(L:level(), L:goalText(L.steps[2].goal)) -- 1 Finish under 60 s
local c = L:credit({ time = 72 }) -- passes "first" (run)
print(c.step.id, c.met, c.unlocked[1][2]) -- first true coupe
print(L:credit({ time = 55 }).step.id, L:level()) -- fast 3
print(L:unlocked().car.truck, L:unlockedBy("car", "truck").title) -- true Under a minute
end
```
With `store` left out, progress is saved per player: the next session starts at level 3.
## Steps, goals and matching
- A **step** is `{ id, title, sub?, std?, config?, goal = { kind, value? }, reward = { { category, id }, ... } }`.
`index` is filled in. `config` is yours (the set-up the step fixes); the ladder never reads it.
- A **goal kind** is `{ text = function(goal) -> string, met = function(goal, result) -> (boolean, valueText) }`.
`run` (always met) is built in; pass your own in `goals`.
- `match(step, result) -> boolean` says whether a result counts for a step (default: every result does).
`credit(result, activeId?)` tries the active step first, then every open step not yet passed, and returns
`{ step, met, value, already, unlocked, nextStep }` for the first match (nil when none). A met goal is
saved with `complete`.
## API
| Call | Returns |
|---|---|
| `Ladder.new(opts)` | a ladder; `opts`: `id`, `steps`, `start`, `goals`, `match`, `store` |
| `L:done()` | `{ [stepId] = info }` of passed steps |
| `L:complete(id, info?)` | saves a pass |
| `L:level(done?)` | index of the first unpassed step (`count()+1` when all are) |
| `L:unlocked(done?)` | `{ [category] = { [id] = true } }` |
| `L:unlockedBy(cat, id)` | the step that unlocks it, or nil |
| `L:goalText(goal)`, `L:goalMet(goal, result)`, `L:matches(step, result)` | goal rules |
| `L:credit(result, activeId?, extra?)` | the credit record above |
| `L:savePref(key, v)`, `L:loadPref(key, default)` | per-player preferences |
| `Ladder.memoryStore()` | a store for tests (`store = Ladder.memoryStore()`) |
## Saving
`runtime_data.player(runtime_data.localId())`, under `<id>/done/<stepId>` and `<id>/prefs/<key>`. Only the
local player's own store is written, so it works the same on every peer. A guest (no id) keeps progress in
memory for the session. Pass `store` (anything with `get`, `set`, `list`) to keep it elsewhere.
## Tests
`unlockLadder` suite (`zero tests run unlockLadder`, edit mode): levels, unlocks, `unlockedBy`, goals,
matching and crediting (active step first, a failed goal saves nothing, a re-pass is `already`), prefs, a
custom store, and the first example above run as written against a memory store.