# programme
The Crumple Zone TEST PROGRAMME as data: 15 ordered real-style protocols (calibration run, city car 50, unbelted 50, bollard 40, Euro NCAP ODB 64, IIHS small overlap, side pole 32, rear MDB 50, child in booster, toddler seat, crash cushion 80, guardrail 70, tree 70, 1960s saloon vs parked car, lamp post 90), each with its set-up (`crashSetup.catalog.protocol`), a goal (`run`, `stars`, `hic`, `headG`, `chest3ms` from `crashSetup.goals`) and the free-lab items it unlocks, plus what a new player starts with. Returns an `unlockLadder` saved per player under `crumpleZone/done/<testId>` and `crumpleZone/prefs/`. Used by `game.CrashGame`.
# 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.