# 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.