Log inGet started
Package

crashCars.package

This package holds more than this page lists. See all of its files in its world.

README.md

crashCars

Crash-test cars whose bodies crumple and stay crumpled. There are nine cars (city car, hatchback, family saloon, estate, SUV, pickup, sports coupe, people carrier and a 1960s steel saloon), each in three looks (realistic, toy, low-poly). A car is a real WheelCollider chassis. Its cabin has seats, a dash, a steering wheel, a toe board, a firewall and door rings that a crash dummy can sit in and hit. The body is a car-shaped soft-body shell whose crush zones keep their dent. The bumper and bonnet slide and fold with the crush, then tear off as loose bodies. Every piece is synced, so every player sees the same car, the same dent and the same panels flying.

The crash load follows a per-face lane model of the car's structure, with a force law tuned per model. Into a rigid wall a hatchback crushes about 0.2 m at 30 km/h, 0.65–0.75 m at 50 km/h and 1.1–1.25 m at 70 km/h. The energy its structure absorbs (energyJ) comes out at the car's ½mv².

Install

Install the package crashCars from ZeroMind. It lands at /source/parts/crashCars.package, or wherever you install it. Require it by its bare name:

local Cars = require("crashCars.cars")

It depends on nothing but the engine.

First example

Paste this where only one peer runs it, during play: an execute call, a host-only scene onHostLoad, or behind multiplayer.isHost(). It lays down a floor and a static wall whose face is the plane z = 0, spawns a hatchback 12 m up the lane and tows it at 50 km/h. It lets go 1 m before the wall, then brakes and prints what the crash did.

--!strict
local Cars = require("crashCars.cars")
local cube = asset.resolve("cube", "mesh")

local floor = entity.spawnSynced("TestFloor", { position = { 0, -1, 0 } })
floor.localScale = { 12, 2, 40 } -- top surface at y = 0
floor.component.add("Model", { model = cube })
floor.component.add("BoxCollider", { friction = 0.8 })

-- a rigid wall: no Physics body, so it is static; its face is the plane z = 0, facing +Z
local wall = entity.spawnSynced("TestWall", { position = { 0, 1, -1 } })
wall.localScale = { 4, 2, 2 }
wall.component.add("Model", { model = cube })
wall.component.add("BoxCollider", {})

-- the car faces -Z (forward) and comes from +Z
local car = Cars.spawn({ model = "hatch", look = "realistic", position = { 0, 0, 14 }, yaw = 0 })
assert(Cars.whenReady(car, 5), "car shell did not build")
car.component:track(true, "front")

local v = 50 / 3.6
local towing = true
local stop = Physics.onBeforeStep(function()
	if not towing then
		return
	end
	local bumperZ = car.chassis.position.z - car.frontOffset
	if bumperZ <= 1 then -- let go 1 m before the wall
		towing = false
		return
	end
	Cars.setVelocity(car, 0, 0, -v) -- tows chassis and shell together
end)

task.wait(2)
stop()
car.component:brake(6000)
local c = car.component:settle("front")
print(("crush %.2f m max / %.2f m mean, peak %.0f g, structure absorbed %.1f kJ, off: %s"):format(
	c.max, c.mean, car.component.peakForceN / (car.spec.mass * 9.81), car.component.energyJ / 1000,
	table.concat(car.component.detached, ", ")))

It passes the strict checker and runs. A hatchback at 50 km/h crushes 0.55–0.75 m at 24–28 g peak, and bumper, bonnet come off. Its structure absorbs about 115 kJ of the 120.6 kJ ½mv² by the moment it stops. Read the open issues under Known limits before you trust the numbers after the stop.

examples/carsDemo.scene is the same test as a scene: a hall floor, a concrete wall, a camera and the CarsDemo component (examples/CarsDemo.component). The component runs one real car on the host only and prints the result. Beside the lane, examples/carsDemoLineup.module stands one car of every model as a still picture: meshes only, no physics. Use it for a showroom or menu instead of nine simulated cars.

Gallery

examples/carsGallery.scene is a showroom of the whole catalog: every model in every look, a 9 × 3 grid of 27 cars (models in catalog order left to right; realistic, toy and low-poly rows front to back). Each car stands on a plinth with a name placard in world-space text (Text3D), such as "Family saloon · Toy", and each row has its look as a header. It is visual only, built with carsDemoLineup: no physics, no soft bodies, no CrashCar. Its camera (galleryCamera) frames the whole grid.

Open it from the Scenes list in the editor, or in Luau with layers.load("crashCars.examples.carsGallery") (a root load replaces the open scene; pass { additive = true, origin = { x, y, z } } to set it beside your own scene instead). Its build.luau lays the grid out from Cars.catalog() and Cars.looks(), so a new model or look shows up on the next build.

The package's regression suite is crashCars.testSuite: run it in edit mode with zero tests run crashCars.

API

Cars.spawn(opts) -> Car
optionmeaning
modelcatalog id (below). Default "hatch"
look"realistic" (default), "toy", "lowpoly"
position{x, y, z} or {x=, y=, z=}: on the ground under the middle of the car
yawradians about +Y. 0 = the car faces −Z
syncedtrue (default): every piece is spawned with entity.spawnSynced, so call it on ONE peer. false for a local-only car
namechassis entity name (default CrashCar_<model>); the shell is <name>_shell

Car handle (also rebuilt on any peer with Cars.fromChassis(chassisId)):

  • id, chassis: the chassis entity id and entity (dynamic Physics, four WheelColliders, the cabin colliders, the CrashCar component).
  • shell: the soft body shell's entity id (a separate root entity held to the cabin).
  • parts = { bumper, bonnet }: the panels' entity ids while they are attached (children of the chassis). Once they come off, component.looseBumper / looseBonnet hold the loose bodies.
  • spec = { id, name, class, mass, length, width, height, wheelbase, frontOverhang, crushable }, derive (car-local stations, see specs), structure (see Cars.structure), model, look.
  • component: the chassis' CrashCar component. wheels: the four wheel entity ids.
  • frontOffset / rearOffset: metres from the chassis origin to the front face (bumper) along forward, and to the rear face along back. The bumper's world position along the lane is chassis.position.z - frontOffset for a car facing −Z.

Children of the chassis that a dummy or a rig uses, named exactly:

  • seat_driver, seat_passenger, seat_rear_left, seat_rear_right: H-points (the hip joint centre of a seated occupant), facing forward. The rear seats are absent on the pickup.
  • belt_seat_<seat>_lapOuter, _lapInner, _shoulder, _buckle: belt anchor points.
  • steering_wheel: centre of the rim (its collider is col_steering_wheel).

Everything else in Cars:

callwhat it does
Cars.catalog(){ {id, name, class, mass, length, width, height, wheelbase} }
Cars.looks(){ {id, name, description} }
Cars.spec(id)the raw spec table from specs (nil for an unknown id)
Cars.derive(id)car-local stations: axles, windscreen, firewall, roof end, H-points, steering wheel centre
Cars.structure(m)the structure of a spec m: frontG/rearG/sideG = {g at 0 crush, g at 85 % travel}, frontTravel/rearTravel/sideTravel (m), face positions, shell zone settings
Cars.crushForce(m, S, x, face)crush force (N) of a whole face at crush depth x m. face = "front", "rear" or "side"
Cars.whenReady(car, timeout?)yields until the shell is built (default 5 s); returns true/false
Cars.fromChassis(id)the handle, read back from a chassis id (any peer)
Cars.despawn(car)removes the chassis, shell and any loose panels
Cars.setVelocity(car, vx, vy, vz)sets chassis and shell velocity (world m/s): how a tow or launcher drives the car. Simulating peer only
Cars.worldToLocal(e, p), Cars.localToWorld(e, l), Cars.localDir(e, l)frame helpers for any entity (arrays in, {x,y,z} out)
Cars.GROUPScollision bits: shell = bit 20, dummy = bit 21. Put a dummy's colliders in bit 21 only: the shell fills the car's volume and is filtered against that bit
Cars.mesh(model, look, part), Cars.material(name)the package's authored mesh and material refs

The CrashCar component (on the chassis)

Methods (the ones that write are for the simulating peer):

  • :measureCrush(face?) → { max, mean, lanes = {a, b, c}, left, centre, right }, in metres, for "front" (default), "rear", "left" or "right". On the owner it reads live values. Other peers read the synced lanes, updated every 0.1 s.
  • :worstFace() → face, depth.
  • :track(on, face?): while on, keeps the deepest crush of face in crushMax. Switching it on resets crushMax, energyJ and peakForceN.
  • :settle(face?): stores the current crush in crushResidual and returns it.
  • :setExclude(ids): bodies the lanes look past, for example a dummy's bodies or a rig's props.
  • :brake(torque?): clamps every wheel's brake (default 6000 N·m); 0 releases it.
  • :repair(): back to the built shape and forgets the crush. Panels that came off stay off.

Synced fields: crushMax, crushResidual, lanes, energyJ (J), peakForceN (N), detached ({"bumper", "bonnet"}), looseBumper, looseBonnet, ready, and the tunables reboundShare (0.06), bumperOffAt (0.26 m), bonnetOffAt (0.38 m) and shapeZones (true).

Events: onPartDetached { part } and onImpact { face, speed, target } (closing speed in m/s at first contact, and the entity id of what the face met).

car.component.events.onImpact:connect(function(e)
	print(e.face, "hit", e.target, "at", e.speed * 3.6, "km/h")
end)

Catalog

Mass in kg, sizes in metres. Front law is the crush force as deceleration of the whole car, from first touch to 85 % of the crush travel. Past 85 % the structure bottoms out and stiffens sixfold.

idnameclassmasslengthwidthheightwheelbasefront lawfront travelseats
cityCity carA-segment city car9503.601.641.502.4015–42 g1.01 m4
hatchHatchbackC-segment hatchback12504.101.781.462.6215–42 g1.23 m5
saloonFamily saloonD-segment saloon14504.751.821.452.8015–42 g1.39 m5
estateEstateD-segment estate15504.801.821.482.8015–42 g1.40 m5
suvSUVmid-size SUV18504.601.881.702.7517–48 g1.22 m5
pickupPickupfull-size pickup21005.301.901.803.2019–53 g1.23 m5 (2 seat frames)
coupeSports coupe2+2 sports coupe15004.401.851.302.5516–44 g1.50 m4
mpvPeople carrierMPV / minivan17504.801.881.752.9515–42 g0.84 m7 (4 seat frames)
classic60s1960s steel saloon1960s body-on-frame saloon13004.601.751.422.7039–109 g0.92 m5

classic60s has a stiff, short front and a weak cabin (front = 2.6, cabin = 0.45): it stops harder, and its passenger cell deforms more. Rear faces use 12–34 g and sides 8–30 g, the side travel growing with cabin strength. Seat frames are the seat_* children: driver and passenger, plus rear_left and rear_right on every model but the pickup.

Looks

The look changes how a car is drawn, never its physics.

idnamewhat it looks like
realisticRealisticSmooth production body, metallic paint, crash-test target stickers
toyToyRounded glossy plastic, saturated colours, chunky wheels
lowpolyLow-polyFaceted flat-shaded body in a flat palette

Each model has its own paint per look. Paint is baked into the meshes' vertex colours and drawn through white PBR materials (materials/body_<look>, trim, wheel, windscreen).

How the crush works

  • Lanes. Each face (front, rear, left, right) is three lanes. On the simulating peer, every physics step, rays from inside the body find what stands in front of each lane. They see any collider and soft-body surfaces. Where a lane's face meets something, the car is pushed back with that lane's third of Cars.crushForce(m, S, depth, face). If the obstacle is dynamic or soft, it gets the opposite force. A pole meets one lane, an offset barrier one side, a wall all three.
  • Force law. In g of the car's weight, the force rises linearly from the first value of frontG at no crush to the second at 85 % of frontTravel, then stiffens to 3x (1 + Cars.BOTTOM_OUT) as the crumple zone bottoms out and the cabin structure takes over. Hit faster than 70 km/h, every lane resists harder by Cars.DYNAMIC (strain rate, more members folding at once): 1.5x more per 15 m/s above 19.5 m/s, so a 120 km/h car is stopped by its crumple zone (1.39 m, 39 g mean) rather than by its cabin.
  • Never more than stops it. The force is capped so it never more than stops the closing speed in one step. When the face stops against the obstacle, it gives back reboundShare (6 %) of the impact speed, the way crushed metal does. Against a moving body (a parked car, a moving barrier, a loose panel) the cap uses the two masses together, so a light thing is not flung off.
  • Depth. A lane's crush depth only grows: it is how far the obstacle has moved into the face.
  • Energy. energyJ is the work the crush forces did on the closing motion, which is the energy the car's structure absorbed. It is this part's own model: soft bodies don't report absorbed energy (#20539).
  • Shape. The shell's crush zones take the lanes' depths. Physics.setSoftParticles writes their positions and their rest shape, so the dent stays, and it replicates to every peer like any soft-body dent. The folds bow the sides out and the top up where the metal packed.
  • Panels. While attached, the bumper slides back with the mean crush and the bonnet folds up from its hinge. The bumper comes off past bumperOffAt (0.26 m), or when one side is crushed 0.12 m deeper than the other. The bonnet comes off past bonnetOffAt (0.38 m). Both become loose synced bodies thrown off the car.

Measured through crashRig (hatchback, belted 50th-percentile adult, 2026-10-26).

Version 0.3.2, family saloon, belted 50th-percentile adult (classic), bollard, tow, two runs at each speed (head = peak, chest = 3 ms clip):

speedcrushcar pulse (peak / mean)headchestwith front airbags: head / chest
30 km/h0.36 m12 / 9 g28 / 26 g14 / 13 g25 / 14 g
50 km/h0.82 m16 / 11 g40 / 37 g22 / 20 g43 / 20 g
70 km/h1.28 m29–30 / 16 g63 / 58 g38 / 36 g54 / 29 g
90 km/h1.30 m59 / 28 g349–413 g (see below)61–63 g—
120 km/h1.39 m89 / 39 g600+ g (see below)195–360 g—

From 10 to 70 km/h every channel rises with speed and two runs agree within 8 %. Above about 80 km/h the car's own numbers (crush, pulse) stay believable, but the dummy's head reading does not: its neck runs into its joint stop and the head whips into it in one physics step. A stiffer neck made the solver diverge at 70 km/h, so it was left as it is; the head reading above 80 km/h is the dummy model's limit, not a measurement.

Earlier the same day, with seat foam and a padded wheel but no positioning hold, door foam or load limiter (hatchback, bollard):

testcrushcar pulse (peak / mean)headHIC15chest 3 msenergy
bollard 30 km/h0.35–0.36 m12 / 8–9 g26 g40–4612–13 g43 kJ
bollard 50 km/h0.79 m17 / 11 g45–56 g157–25022–30 g120 kJ
bollard 70 km/h1.14–1.15 m46–51 / 19–21 g97–125 g1007–119249–57 g235 kJ

The rows below were measured earlier the same day, before the seat foam and the padded wheel; rear hits and 64–70 km/h frontal hits read higher on the head and chest then (rigid seat backs, rigid wheel).

testcrush (max)car pulse (peak / mean)headchest 3 mspanelsenergy
rigid wall 30 km/h0.21–0.22 m20 / 12 g16–32 g21–22 gstay on43 kJ (= ½mv²)
rigid wall 50 km/h0.50–0.52 m24–29 / 16–19 g23–31 g27–31 gbumper + bonnet off120 kJ
rigid wall 56 km/h0.57–0.61 m27–42 / 15–19 g34–67 g29–40 gbumper + bonnet off145–149 kJ
rigid wall 70 km/h0.70–0.83 m38–69 / 23–27 g33–177 g40–73 gbumper + bonnet off226–234 kJ
offset barrier 64 km/h0.75 m (0.66 on the far side)34 / 21 g86 g38 gbumper + bonnet off186 kJ
small overlap 64 km/h1.21 m on the struck side, 0.19 on the other64 / 20 g114 g61 gbumper + bonnet off193 kJ
side pole 32 km/h (side-impact dummy)0.25 m, the pole's lane only38 / 19 g53 g44 g—47 kJ
rear moving barrier 50 km/h0.29 m13 / 8 g21 g24 g—70 kJ

Crush, car pulse and energy rise steadily with speed and repeat within a few percent. The head reading varies more from run to run, as in real tests without an airbag: it depends on whether the head strikes the steering wheel.

Multiplayer

  • Spawn on one peer (the host or the test rig's authority). Cars.spawn uses entity.spawnSynced for every piece, so other peers receive the car and never spawn their own.
  • The car simulates on the peer that spawned it. Only that peer runs the lanes and may call anything that writes physics: Cars.setVelocity, :brake, :track, :settle, :setExclude, :repair. Physics.* writes only work on the simulating peer.
  • The dent replicates natively as soft-body particles. The chassis and loose panels replicate as poses. The crush numbers replicate through the component's synced fields. measureCrush on a replica reads them, up to 0.1 s behind.
  • Every mesh and material is an authored asset inside the package, so every peer draws the same car. Regenerate the meshes in edit mode after changing specs or shape, with require("crashCars.build").all(); require("crashCars.build").refs().

Known limits

  • Wheels have no volume and can't come off (engine issue #20543). They are WheelColliders, so a wheel hit is a hit on the body.
  • Soft bodies don't report the energy they absorbed (#20539), so energyJ comes from the lane model, not from the shell.
  • A kinematic body covers a frame's motion in its first step (#21187). If a rig drives a car kinematically, its first contact lands a frame early. Tow it as the dynamic body it is, with Cars.setVelocity every step, as the example does.
  • The crush is a lane model, three lanes per face. A narrow pole crushes a whole lane's width (about a third of the car).
  • Two lane-model cars: in a car-to-car side hit, each car's own lanes push, so the two forces add.
  • Rays need a surface: the lanes only see an obstacle that has a collider or a soft-body surface. A mesh with no collider is passed through. Give a pole a pole-sized collider: a convex hull round a pole and its frame is as wide as the frame.
  • Side tests: spawn the car with noTrim = "left" (or "right") for the struck side. The door trim that stops the occupant in other crashes is rigid, and an obstacle that accepts every collision group would stop dead on it.
  • The shell touches nothing. It is skin: light (3 % of the car), held to the cabin, shaped by the lanes. It has no underside and no surface round the wheel arches, because a WheelCollider's ray reads no collision filter and would stand the wheel on its own body.
  • Don't despawn a car's child colliders during play. A collider removed from a synced body that way was seen to stay in the physics world under a dead id until the whole car was despawned.

Seats, foam and the steering wheel

  • Cars.seatLayout(m) lists each seat (driver, passenger, and rear_left/rear_right where the model has them) with its seat back and head restraint, and for the driver the steering wheel. Each pad is { face, n, up, rigid, halfX, halfUp, foam } in the car's frame: face is the foam surface, n points out of it, and rigid is the centre of the rigid frame behind it. The seat back leans back 23°, the torso angle crashDummies seats at; nothing stands behind the rear bulkhead, where the rear crush zone is.
  • Cars.FOAM holds the pad depths (m) and spring-damper rates: seat back 8 cm, head restraint 6 cm, wheel hub on a collapsing column 10 cm.
  • Every pad (foam, wheel column, door, airbag) is an explicit spring-damper applied once a physics step, so its stiffness and damping are capped by the step and the body's mass (k·dt²/m <= 1.6, c·dt/m <= 1.1): at the world default of 30 steps a second the pads stay stable, and at 60 every pad is exactly as tuned.
  • car.component:setOccupants(bodyIds) registers an occupant's rigid bodies. Each step the foam pushes them out along n (k·penetration + c·closing speed) and the car takes the reaction. Owner only.
  • car.component:fitSeats() sets the seat up for the settled occupant, as a test lab does: the back's foam to touch the torso (5 mm preload), the head restraint to a 4 cm backset. Call it after the occupant settles.
  • car.component:padState() reports each body's gap to its pad and the peak foam force (debug).
  • Cars.GROUPS: shell, dummy, carBody (every collider of a car's body) and panel (a loose panel, which leaves carBody out of its filter so it never touches its own car). Collision groups apply per rigid body, not per child collider.
  • Frontal airbags (Cars.spawn{ airbags = true }, CrashCar field airbags): the driver's bag fills out of the wheel hub, the passenger's out of the dash. They fire 15 ms after a frontal hit closing faster than 4.2 m/s (15 km/h), fill in 30 ms, hold 100 ms, then vent over 120 ms; airbagFiredMs says when they fired (-1: not). While a bag stands it pushes on each occupant body that meets it with a near-steady gas pressure over the body's area plus a vent-flow term on its closing speed (Cars.AIRBAG), and gives back little on the way out. The bag is drawn as a white cushion (a synced child airbag_<seat>) and stays draped after it vents.
  • The door's inner trim beside each front occupant is foam too (door pad, sill to window frame), and the steering wheel has no rigid collider: hub, collapsing column and rim are one pad that bottoms out on a stiff spring (kWheelBottom), so nothing the occupant meets is met in a single physics step.
  • A cramped rear bench (city car, coupe 2+2) keeps its foam where the occupant sits and leaves out the rigid seat-back frame, so nothing rigid stands in the rear crush zone (seat.noRigid).

After a test

  • car.component:park(true): the lanes stop, so the dent stays exactly what was measured and nothing the car rests against (the wall, a replay ghost) can push it. The seat foam keeps holding the occupant. park(false) or repair() resumes. crashRig parks the car as soon as it has taken its readouts.
  • The lanes look through a soft body that collides with nothing (collisionFilter or collisionMemberships 0), such as a replay ghost: rays meet every soft surface, whatever its collision groups.
  • A car on WheelColliders doesn't sleep, even standing still, so its shell never "comes to rest" either.