# crashSession
The **player-facing loop of a crash-test game**, as a package: everything between "the player opens the
world" and "the player watches their crash back in slow motion", running locally on every peer off one
synced `crashRig.CrashRig`.
- **Title** (menusKit) with Play / Test Programme / Settings / Credits; pause menu on the gear.
- **Set-up** with the `crashSetup` panel: car, look, dummy, look, belt, airbags, barrier, 10–120 km/h,
Tow / Drive / Ramp, readout style and a 2–4 camera replay shot list. Edits are debounced (0.8 s) into
`rig:request("prepare", config)`, so the car and dummy are already in place when RUN TEST is pressed;
RESET rebuilds it. Locked options explain which programme test unlocks them.
- **Run**: a MatchFlow countdown, a chase camera that cuts to the high-speed side camera just before
contact, live km/h and metres to the barrier, an impact sound scaled by speed, juiceKit shake and flash.
- **Results**: the `crashReadouts` ReadoutPanel in the chosen style, then an **automatic slow-motion replay**
(`rig:replay`, ¼ speed) cut between the picked `crashCams` cameras in order, with the camera's render layers
set to `all !crash` (live wreck hidden, recorded ghosts shown) and back to `all` after; REPLAY / NEXT TEST /
SKIP / SET-UP.
- **Programme**: with an `unlockLadder`, each result is credited to the active protocol (or any open one);
passes unlock options, saved per player, with toasts. A run the rig marks `invalid` is never credited:
the toast says "Run invalid: <note>. Run it again."
- **Input**: mouse / touch, keyboard (arrows, Enter, Space = run, Q / E tabs, Backspace), gamepad.
- **Multiplayer**: any player can drive the shared rig; every peer follows its synced state, config and
result, so everyone sees the same test, results and replay.
## First example
`crashSession/examples/sessionDemo.scene` is this, ready to open. In a scene's `build.luau`:
```lua
function content()
require("crashLab.lab").build({ origin = { 0, 0, 0 }, style = "modern" }) -- the hall
entity.spawnSynced("CrashRig").component.add("crashRig.CrashRig", { origin = { 0, 0, 0 }, runup = 46 })
entity.spawn("Game").component.add("crashSession.CrashSession", { title = "MY CRASH LAB" })
end
```
Press Play, press **Play** on the title, press **RUN TEST**: the hatchback is towed into the wall at 50 km/h,
the results appear, and the replay plays from three cameras.
## A game with its own programme
Build a thin component on `crashSession.session` (this is all of Crumple Zone's `game.CrashGame`):
```lua
local Session = require("crashSession.session")
local session
function start()
session = Session.new({
prefix = "cz", screen = "myGame",
ladder = require("myGame.programme"), -- an unlockLadder (crashSetup.goals for the goal kinds)
brand = { title = "MY GAME", sub = "CRASH TEST LAB", lab = "LAB 01" },
sounds = { metal = function() return asset.resolve("myGame.sounds.hit", "soundClip") end },
title = { title = "MY GAME", items = { "play", "settings" } }, -- menusKit showTitle options
})
session:start()
end
function update(dt) session:update(dt) end
function onCallback(id, data) session:callback(id, data) end
function onDestroy() session:destroy() end
```
## Options (`Session.new`)
| Option | Default | |
|---|---|---|
| `rigName` | `CrashRig` | entity with the synced CrashRig |
| `cameraName` | `GameCamera` | local camera entity (made, priority 100, when missing) |
| `screen`, `layer` | `crashSession`, 40 | the game screen |
| `prefix` | `crash` | element / callback id prefix (crashSetup README lists the ids) |
| `brand` | `CRASH LAB` | `{ title, sub, lab }` on the top bar and panel |
| `title` | a generic title | menusKit `showTitle` options (`theme` filled in) |
| `theme`, `showTitle` | `military`, true | menusKit look; open on the title |
| `countdownStyle` | `trafficLight` | MatchFlow countdown look |
| `replaySpeed`, `replayDelay` | 0.25, 2.5 s | replay speed; seconds of results before it starts |
| `replayLayers`, `liveLayers` | `all !crash`, `all` | camera render layers during / after the replay |
| `ladder` | free lab | an `unlockLadder`; without one every option is open and there is no programme tab |
| `saveKey`, `store` | `crashSession`, the player's store | where the free lab saves prefs (`store`: an `unlockLadder` store, e.g. for tests) |
| `sounds` | none | `{ metal, crunch, glass }`: soundClip refs or functions returning them |
| `prepareDebounce` | 0.8 s | wait after the last edit before rebuilding the set-up |
| `getRig`, `clock` | | stand-ins for tests |
Methods: `start`, `update(dt)`, `callback(id, data)`, `enter()`, `state()`, `destroy()`.
## Tests
`crashSession` suite (`zero tests run crashSession`, edit mode), against a stand-in rig: the screen and
title, the debounced prepare and RUN TEST (prepare first, run when ready), following another player's set-up,
locked picks, the shot list's 2–4 limit, loading a protocol, results credited to the programme with unlocks,
an invalid run credited to nothing with its toast, a replay with no recording falling back to the results,
NEXT TEST resetting the rig, and clean-up.