crashRig.package
- .metadata114 B
- CrashRig.component
- README.md13.9 KB
- crashRig.testSuite
- examples
- launch.module
- measure.module
- package.yaml558 B
- recorder.module
This package holds more than this page lists. See all of its files in its world.
README.md
crashRig
A crash-test rig that every player in a world shares. Put one CrashRig component on a scene entity
and any player can set up a test (car, dummy, belt, obstacle, speed), run it, read the results and watch a
slow-motion replay. The rig builds on three sibling parts:
- crashCars (the crumpling cars),
- crashDummies (the ragdoll dummies and belts),
- crashObstacles (walls, barriers, poles, trees, moving barriers).
What it does on each run:
- Spawns the car, the dummy in its seat and the obstacle, all synced. Every player sees the same things, and the dents and loose panels replicate.
- Launches the car one of four ways:
- a tow on a guide cable: speed builds over the first 60 % of the run-up and is released 1 m before contact, as real tow rigs work;
- drive: the car drives itself, with rear-wheel drive, cruise control and a lane keeper;
- a moving barrier launched into a parked car's rear, for rear hits;
- a side slide into a pole, with the tyres' side grip released, for side impacts.
- Measures the dummy's head and chest and the car's pulse at the driver's seat. Motion probes sample at the solver substep rate. Each channel is resampled to 1 kHz and filtered SAE J211-style: CFC 1000 for the head, CFC 180 for the chest, CFC 60 for the car. From those come peak g, HIC15, the 3 ms clip, the car's peak and mean g, pulse length, crush (maximum and residual), energy, panels that came off, and a star rating with good / acceptable / marginal / poor bands for head, chest and structure. Each channel is filtered whole, then cut to the crash itself, from 120 ms before the rig sees the tested face start to crush to 300 ms after (the brakes come on at +300 ms), so the tow and the braking never set a peak.
- Sets the seat up for the dummy: after it settles, the rig hands the dummy's bodies to the car as
occupants (
setOccupants) and fits the seat back's foam and the head restraint to it (fitSeats). - Publishes a
CrashResultin the syncedresultfield, so every player gets the same numbers. - Records what each player saw, so each player can replay it in slow motion. Pair it with crashCams' director to show the replay from two or more angles.
Install
Install crashRig, crashCars, crashDummies and crashObstacles; crashCams and crashReadouts are
the natural companions. Every part is required by its bare name (require("crashRig.measure")), so they
can sit in any folder.
First example
Paste this into a scene's entrypoint. It works in play, in an empty world with any floor at y = 0 covering x -10..10 and z -15..60, at the world's default 30 physics steps a second or at 60 (see "Physics rate" under Known limits: the numbers this README quotes are at 60):
function onLoad()
local e = entity.find("CrashRig") or entity.spawnSynced("CrashRig")
local rig = e.component.get("crashRig.CrashRig") or e.component.add("crashRig.CrashRig", { origin = { 0, 0, 0 } })
task.spawn(function()
rig:request("prepare", { car = "hatch", carLook = "realistic", dummy = "adult50", dummyLook = "classic",
belt = "threePoint", obstacle = "wall", speedKmh = 56, mode = "tow" })
while rig.state ~= "ready" do task.wait(0.2) end
rig:request("run")
while rig.state ~= "results" do task.wait(0.2) end
local r = rig.result
if r.invalid then
print("invalid run, no rating: " .. r.invalidNote)
else
print(string.format("%.0f km/h: head %.0f g (HIC15 %.0f), chest %.0f g, crush %.0f cm, %d stars",
r.impactSpeedKmh, r.headPeakG, r.headHIC15, r.chest3msG, r.crushMaxM * 100, r.rating.stars))
end
local pb = rig:replay({ speed = 0.25 }) -- this player's slow-motion replay, as ghosts
end)
end
API
CrashRig fields (all synced):
| field | meaning |
|---|---|
origin | world point of the obstacle's impact face; the track runs toward +Z from it |
runup | metres of tow (46) |
countdown | seconds counted down before a launch (3) |
config | { car, carLook, dummy, dummyLook, belt, obstacle, speedKmh, mode = "tow" | "drive" } |
state | idle, preparing, ready, countdown, running, settling or results |
result | the last CrashResult (below) |
message | one human line about what the rig is doing |
carId, shellId, dummyRoot, dummyHead, dummyBodies, obstacleRoot, moverId, spawned | what is on the track now |
testId | how many tests have run |
Methods:
rig:request(action, config?)works from any player.- The rig's owner acts on it at once; anyone else's request reaches the owner over
multiplayer.send. - Actions:
"prepare"(set the test up, thenready),"run"(count down, launch, measure,results),"reset"(set the same or a new test up again),"clear".
- The rig's owner acts on it at once; anyone else's request reaches the owner over
rig:replay({ speed = 0.25, loop, onDone, onFrame })replays the last run on this peer only.- It returns a playback with
stop(),time(),playing()andghostOf(id), which gives the ghost standing in for a live entity, for camera targets. - The live crash entities are on the render layer
crashONLY (notdefaultas well: a camera draws an entity that shares any layer with it, so a wreck left ondefaultshowed under its own replay ghost as a doubled car), so a replay camera draws"all !crash"and sees only the ghosts.
- It returns a playback with
rig:stopReplay(),rig:replayImpactTime()andrig:isBusy().
Modules:
crashRig.measureholds the signal processing as pure functions:channel,resample,cfc(SAE J211),hic,clip3ms,peak,decimateandrate.crashRig.recorderrecords any hierarchy's drawn poses and soft-body particles, and plays them back as local ghosts:new{ roots, track },start,stop,trim,play.
CrashResult
id, config, names{car,dummy,belt,obstacle}, mode, face, impactSpeedKmh, headPeakG,
headHIC15, head3msG, chestPeakG, chest3msG, carPeakG, carMeanG, crushMaxM, crushResidualM,
crushShare, energyKJ, structureKJ, energyNote, partsDetached, pulseMs,
rating{stars, head, chest, structure, score}, traces{dt, head, chest, car} (filtered, ≤160 points
each), plus invalid / invalidNote when the solver diverged.
- Energy:
energyKJis the kinetic energy lost in the crash, ½mv² before minus after, with the moving barrier included for rear hits.structureKJis how much of it the car's crumple zone took, from the crashCars lane model.
Measured
Hatchback, 50th-percentile adult in a 3-point belt, rigid wall, 56 km/h, three runs:
| measure | result |
|---|---|
| crush | 0.56–0.61 m |
| car pulse | 34–42 g peak, 18–21 g mean, over ~100 ms |
| energy | 146–149 kJ (½mv² is 151 kJ) |
| head | 42–74 g, HIC15 70–450 |
| chest (3 ms) | 47–57 g |
| rating | 3–4 stars |
Multiplayer
- One peer, the owner of the rig entity, runs each test. Everyone sees the same car, dummy, dents, loose panels and numbers.
- If the owner leaves, the next owner finds the test half-run and sets it up again.
- Replays are per peer: each peer replays what it drew.
Known limits
- No simulation playback (#20544). The engine can't record and play back the simulation, so the replay is rebuilt from the poses and soft-body particles each peer drew. It is a faithful picture of what that peer saw, not a re-simulation.
- Ragdoll poses on other players' screens. A ragdoll is drawn at physics-tick poses (#21188), and may not show ragdolled for other players at all (#18554). Their replay of the dummy shows what they received.
- Kinematic first step (#21187). A kinematic body covers a frame's motion in its first step, so the rig tows with velocities, never kinematically.
- Waits are capped (#19849). Long engine waits are capped, so a script waiting on a run should poll
statein short waits, as the example does. - Barrier energy (#20539). Soft bodies don't report energy absorbed, so a crushable barrier's own share
of the energy is not in
structureKJ;energyKJ(the kinetic energy lost) covers it. - Probe sample rate. Probes sample at the physics substep rate, 240 Hz at a 60 Hz tick. Head and chest are therefore band-limited by the physics rate: CFC 1000 / 180 filter nothing above roughly 120 Hz. HIC15 and the 3 ms clip are computed on the 1 kHz resample.
- Invalid runs get no rating. The rig publishes a run as
invalid(withinvalidNotesaying why, andrating = nil: no stars) when its numbers can't be a crash test: the solver diverged (NaN, a head over 1000 g, a car over 400 g, a chest over 600 g); the car went much faster than the test asked before the hit (peakSpeedKmhover 1.4x the target: a launch blow-up); or the car didn't arrive at the test speed (more than 20 % off, 30 % for a ramp). The status line then starts "INVALID RUN (no rating)". crashReadouts draws such a run with an INVALID stamp and no stars. - Physics rate. A fresh world steps physics 30 times a second (
physics.tick_rate); this world runs 60. The rig works at either: every spring the rig and crashCars apply themselves (the positioning hold, the seat, head-restraint, door and wheel foam, the airbag) is capped by the physics step and the body's mass, so it can't overshoot and blow up at 30, and is untouched at 60. (Before that cap, at 30 the positioning hold diverged a second into the tow and threw the car off at thousands of km/h.) The readings do depend on the rate: family saloon, adult, 3-point, bollard, at 30 steps a second two series read head 16-18 / 23-39 / 38-42 g and chest 12-14 / 16-26 / 30-31 g at 30 / 50 / 70 km/h (crush 0.34 / 0.78-0.82 / 1.32-1.36 m), against 26-29 / 37-40 / 49-54 g (one run in five at 70 km/h read 77) and 13-14 / 21-22 / 30-36 g at 60. At 60 every reading rises with speed and repeats within 20 %; at 30 the crush and chest rise, but the head spreads more from run to run and a 50 km/h run can read as high as a 70 km/h one. For the readings this README and crashCars' tables quote, setphysics.tick_rate = 60in the world's settings (/source/.world_settings,[physics]); the rig can't change the rate itself and warns once in the log when it is lower. Each result carriestickRate. - Web build untested. An agent can't start a browser engine to check the web build (#20946).
- Wheels (#20543). A car's wheels are WheelColliders: they have no volume and can't come off.
- Publishing.
zm pushcan misreport its result (#21207, #21206, #21025): after a push, check the world's published commit rather than trusting the message.
Multiplayer checks (2026-10-26)
- Reset clears everything: three resets in a row left the world exactly as before (entities, bodies, colliders, soft bodies), each new car undented to within 0.03 mm, and no replay ghosts left over.
- Every live test entity (car, shell, dummy, obstacle, moving barrier, and loose panels as they come off) is kept on
the render layer
crashon every peer: layer membership isn't replicated, so each peer sets it, and re-applies it as children stream in. A replay camera drawing"all !crash"then shows only the ghosts. - What a second player needs is synced and verified with
multiplayer.explain: the rig'sstate,result,message, and the car's crush fields. No second client was connected for this check (#20946); a ragdoll may not show ragdolled for other players (#18554).
Round 3 (version 0.3.2): repeatable readings, three launch modes, airbags, 10–120 km/h
- Repeatable readings. The dummy settles counted in physics steps (until it is still relative to the car), the seat is fitted, and from the start of the tow until the crush begins a positioning hold (the breakaway tape a lab uses: a stiff, critically damped spring per dummy segment, in the car's frame) keeps the dummy where it sat, so every test meets the obstacle from the same posture. The data window (−120 / +300 ms) hangs off the physics step the crush began in, not off a frame. Family saloon, adult, 3-point belt, bollard, two runs each: head 28/26, 40/37, 63/58 g and chest 14/13, 22/20, 38/36 g at 30/50/70 km/h (crashCars README has the table).
- Launch modes (
config.mode):tow(cable tow, lets go 1 m before the barrier),drive(the car drives itself in) andramp: the tow lets go 0.5 m before a 3 m steel ramp whose lip stands 8 m out, angled 2–12° (crashRig.launch) so the car comes down just short of the barrier; the impact speed is read when the crush starts (a 50 km/h ramp test hits at 47.9 km/h). Frontal obstacles only; side and rear hits use the tow. - Airbags (
config.airbag = "front"ortrue): the car is spawned with crashCars' front airbags; the result carriesairbag = { fitted, firedMs }and the restraint name gains "+ airbag". - Speed: any
speedKmh; the game offers 10–120 km/h. Above about 80 km/h the car's crush and pulse stay believable but the dummy's head reading does not (its neck runs into its joint stop): see crashCars' README. synced(default true): false runs the whole test on this peer only (offline, and the test suite, whose play session holds no relay ownership).- Gallery
examples/rigGallery.scene: the three launch modes (with the ramp the rig builds) and every restraint, each labelled, plain Models only (examples/rigGalleryLayout). - Tests
crashRig.testSuite(10): CFC filter, HIC15 against its closed form, 3 ms clip, monotonic readings, decimation, star bands, recorder bookkeeping, and a whole 30 km/h wall test with airbags in play that publishes a sane result and clears everything it spawned. Runzero tests run crashRigin edit mode.