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