# CrashSession
Drop-in crash-test game layer. Put it on one scene entity beside an entity carrying a synced `crashRig.CrashRig` (named by `rigName`). Runs locally on every peer: title, set-up panel with every option open (free lab, no programme), countdown, live cameras, results, slow-motion replay, REPLAY / NEXT TEST / SKIP / SET-UP. Fields: `rigName`, `cameraName`, `title`, `theme`, `showTitle`, `countdownStyle`, `replaySpeed`, `replayDelay`, `layer`, `screen`, `prefix`, and three optional impact sounds (`metalSound`, `crunchSound`, `glassSound`). For a test programme, your own title menu or branding, build a component on `crashSession.session` (package README).
# crashSession test suite
Drives `crashSession.session` against a stand-in CrashRig (records every request, never spawns a car) with a
controllable clock and a memory-store ladder, so it never touches the live rig or a real player's progress:
- **Set-up**: the screen is shown and the idle rig is prepared with the default set-up; edits are debounced
into one prepare and the speed clamps to 10..120; RUN TEST prepares first and runs once the rig is ready
with that set-up; another player's set-up is followed; a locked pick is refused with a LOCKED toast naming
the step; the shot list keeps 2..4 cameras; loading a protocol copies its set-up and prepares.
- **Results**: a matching result passes the active protocol (saved, reward unlocked, PASSED toast); an invalid
run is credited to nothing and its toast reads "Run invalid: <note>. Run it again."; the auto replay with
no recording falls back to the results with the camera on `all`; NEXT TEST resets the rig; `destroy`
cleans up.
It leaves the real crash, cameras and replay to playing the game (or `crashSession/examples/sessionDemo`).
Run with `zero tests run crashSession` (edit mode).
# sessionDemo
crashSession's first example: the crashLab hall in its modern mood, one synced `CrashRig` at the origin and an entity carrying `crashSession.CrashSession` (title "CRASH LAB", free lab: every car, dummy, belt, barrier, speed 10–120 km/h, launch mode, readout and camera open, no programme). Press Play, then Play on the title, then RUN TEST: the hatchback is towed into the wall at 50 km/h, the results panel shows, and a ¼-speed replay cuts between three cameras. Players spawn in the spectator gallery beside the track. Needs crashSession and the crash parts it builds on.
# session
`Session.new(config)` builds a crash-test game session for the local player: `:start()` registers the screen, the countdown and readout panel and shows the title; `:update(dt)` follows the synced `CrashRig` (state, config, result), runs the debounced prepare, the camera orbit, live telemetry, results, credit and the auto replay; `:callback(id, data)` handles `<prefix>:…` ids (returns true when it was one); `:enter()` opens the lab as the title's Play does; `:state()` snapshots it; `:destroy()` cleans up. Options are in the package README. Used by `crashSession.CrashSession` and games (Crumple Zone's `game.CrashGame`).
# 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.
# 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, ... })`.
# 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.
# lab
`require("crashLab.lab")` — builds the crashLab crash-test hall as static scene entities: `Lab.build(opts)`
spawns the hall, track, pit, gantries, control room, screens, signage, props, lights and colliders from
the package's authored meshes and materials, and returns the impact point, track start, camera spots,
screens and entity ids; `Lab.clear(root)` removes it. Called from a scene's `build.luau` or a host-only
setup step. See the package README for options, the layout contract and the styles.
# 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.
# 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.
# 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.
# 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.