Log inGet started
World

Crumple Zone: Crash Test Dummy Simulator

Branchmain
Commit8d4e06b8c8

README.md

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.

StylebarsKit lookShows
scifiring (scaled to the slot, hologram tint)head peak / 80 g, HIC15 / 1000, chest peak / 60 g, each coloured by its rating
lcdsegmented, 5 cells, LCD inkthe star rating
lowerThirdline (compact)head / 80 g, chest / 60 g, crush / 1 m under those stats
floatingghost (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):

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:

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

FunctionReturns
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

idnamelook
labPrintoutLab printoutDot-matrix report on tractor-feed paper: header, test no., config, channel table, three mini traces, rubber PASSED/FAILED stamp with stars
oscilloscopeOscilloscopeGreen-phosphor CRT: graticule, head / chest / car g traces sweeping in, peak cursors, measurement boxes, bezel knobs
lowerThirdTV lower thirdBroadcast bar that wipes in: CRASH TEST tag, headline, star badge, stats strip, scrolling data ticker
plainPlainClean white card, big legible numbers
lcdRetro LCDBeige data logger, backlit seven-segment LCD with ghost segments, annunciators, rating bar, membrane buttons
scifiSci-fi hologramTranslucent blurred panel, corner brackets, ring gauges, glowing trace, moving scanline
starsStar ratingEuro-NCAP-style: stars, body diagram with head/neck, chest, legs in good / acceptable / marginal / poor colours, key numbers
floatingFloating labelsCallouts 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.