Crumple Zone: Crash Test Dummy Simulator
README.md
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
crashSetuppanel: 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) intorig: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
crashReadoutsReadoutPanel in the chosen style, then an automatic slow-motion replay (rig:replay, ¼ speed) cut between the pickedcrashCamscameras in order, with the camera's render layers set toall !crash(live wreck hidden, recorded ghosts shown) and back toallafter; 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 marksinvalidis 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:
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):
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.