# 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.
# crashSetup test suite
Checks the crashSetup package:
- **Catalog**: each category lists exactly what its part publishes (crashCars cars and looks, crashDummies
dummies, looks and belts, crashObstacles, crashReadouts styles, crashCams kinds), in order, with names and
short labels; the fixed mode and airbag lists; the default set-up uses real ids; `protocol`, `rigConfig`,
`key`, `everything`, `mph`, the 10–120 km/h range.
- **Goals**: stars, HIC15, head g and chest 3 ms read off a result; an invalid run (or one at 0 km/h) meets no
goal; `matches` (speed within 1.5 km/h, looks and launch mode ignored).
- **Panel**: every documented element id with its callback on each tab (chips, speed 10..120 and − / +,
Tow / Drive / Ramp, airbags, readouts, camera cards, RUN / RESET), padlocked chips, the PROGRAMME tab and
strip only with a ladder, the phone bottom sheet, the results bar (SKIP only while replaying), and a screen
of every builder registering with no `gui.validate` errors at desktop and phone sizes.
It leaves the look to the gallery scene. Run with `zero tests run crashSetup` (edit mode).
# SetupGallery
Puts every `crashSetup.panel` piece on one screen, each with a yellow caption: the five set-up tabs side by side (VEHICLE, OCCUPANT, TEST with the 10–120 km/h chooser and Tow/Drive/Ramp, CAMERAS shot list, PROGRAMME with a sample 5-step ladder: two passed, one open, two locked), then the top bar, programme strip, live telemetry, the results bar, the replay bar and a pass toast. Display only (no callbacks handled); runs in play. Used by `crashSetup/examples/setupGallery.scene`. Fields: `screen`, `layer`.
# setupGallery
crashSetup's labelled gallery: in play, `crashSetup.examples.SetupGallery` fills the screen with every panel piece, each under a yellow caption — the VEHICLE, OCCUPANT, TEST (10–120 km/h, Tow / Drive / Ramp), CAMERAS (shot list) and PROGRAMME (sample 5-step ladder: two passed, one open, two locked) tabs side by side, then the top bar, programme strip, live telemetry, the results bar, the replay bar and a pass toast. A dark backdrop and a fixed camera; nothing simulates.
# 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, ... })`.
# 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`.
# 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.
# 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.
# dummies
The crash test dummy API of the `crashDummies` package: `require("crashDummies.dummies")`.
Builds ragdoll crash test dummies out of rigid bodies (capsules, boxes, spheres) joined by hinge and
generic joints with anatomical limits and capped spring-damper "muscle tone", seats them at a
vehicle's `seat_<x>` H-point frame, belts them to the vehicle's `belt_<seat>_*` anchors with
compliant one-sided webbing (slack, retractor spool-out, pyro pretensioner, load limiter), and draws
the webbing on every peer.
- `spawn(opts) -> handle` — `{ kind, look, belt, vehicle, seat = "seat_driver", synced = true, tone = 0.5, handsInLap? }`
- `despawn(handle)`, `setTone(handle, 0..1)`
- `instrument(handle) -> { read, reset, peak, trace, belt, stop }` — motion probes on head / chest / pelvis
- `catalog()`, `looks()`, `belts()` — the variants with their masses and settings
- `COLLISION_GROUP` — the membership bit (21) every dummy collider carries
Called by game code and by the package's `CrashDummy` component (which runs the belts each physics
step on the simulating peer). See the package README for the full contract and measured numbers.
# 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.
# readouts
`require("crashReadouts.readouts")`: the pure display half of crashReadouts. It turns a crash test's
`CrashResult` into a widget tree in one of eight styles, and ships the drawing helpers those styles
are made of. Nothing here measures or derives a crash number; it formats what the result holds.
- `Readouts.styles()`: `{ { id, name, description, tags } }` for the 8 styles.
- `Readouts.render(style, result, { w, h, t?, points? })`: widget tree sized `w × h`. `t` is seconds since
shown and drives the entrance (rows cascading, traces sweeping in, the stamp landing). Leave it out
for the settled look. `points = { car = {x,y,visible}, head = {x,y,visible} }` places the `floating`
labels (UI canvas points).
- `Readouts.layout(style, screenW, screenH, anchor?)`: where a style wants to sit: `{ x, y, w, h, sheet?, full? }`.
- `Readouts.sample(opts?)`: a believable CrashResult with traces (`speedKmh`, `car`, `dummy`, `belt`, `obstacle`).
- `Readouts.rows(result)`: the readouts as `{ key, label, short, value, unit }` rows, already formatted.
- Helpers other UIs can reuse: `traceSvg(result, opts)` (grid + polylines + glow + peak cursors + axis
labels), `sevenSegSvg(text, opts)` (seven-segment digits with ghost segments), `starsSvg(n, opts)`,
`bodySvg(result, opts)` (occupant silhouette coloured by rating).
Called by the `ReadoutPanel` component in the same package, and by any screen that wants to embed a
readout as a child node.
# 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.