Crumple Zone: Crash Test Dummy Simulator
README.md
crashLab
The crash-test facility a crash-test game happens in, as one installable part: a 40 m x 100 m x 14 m indoor crash hall, closed and light-tight, lit like a real crash lab (crash labs are brutally lit for high-speed cameras).
- Floor. Polished concrete in 5 m slabs with saw-cut joints. A darker sealed 10 m test track runs down the middle with white edge lines and 1 m / 5 m distance ticks. Numbered distance panels sit every 5 m (0–75 m), with a chequered start line at 60 m and yellow/black safety lines. A tow-cable slot with its cable runs down the centreline.
- Impact zone. A dark epoxy pad with a 1 m camera grid, a red impact line at the face and a hazard-striped border.
- Observation pit. A glass-covered, LED-lit pit under the impact point, with a ladder and a camera tripod, for under-car shots.
- Lighting rigs. Two flood-light gantries with 8 aimed flood heads, an 8 x 8 m overhead LED rig, 57 linear high-bay fixtures, roof trusses and ducts.
- Load-cell wall. A reaction block with a 4 x 8 load-cell plate array and chevron panels.
- Control room. Raised, with sloped glazing, operator consoles, live-looking monitors, racks and stairs.
- Screens and signage. Three big result screens, 2 m high-speed-camera grid boards, wall distance boards, hazard and safety signage, lit "TEST IN PROGRESS" / "FIRE EXIT" boxes and crash-test photo targets.
- Props. Cable trays with cables, tool carts, spare barrier blocks and honeycomb barrier faces on pallets, a two-post lift, a test car on jack stands, a tyre stack, the tow winch, bollards, fire extinguishers and electrical cabinets.
Three lighting moods: modern (white LED hall), classic (warm halogen, green-and-blue 1970s lab),
night (dark hall, hard cold floods). Lab.build returns the impact point, the track start, ready
camera spots and the screens.
Everything is plain static scene entities built from authored .mesh / .material /
.texture assets in this package. Call it from a scene's build (build.luau) or a host-only setup
step, and every peer gets the same hall. It needs no other part.
Install
Install the package crashLab from ZeroMind. It lands at /source/parts/crashLab.package or
wherever you install it. Require it by its bare name:
local Lab = require("crashLab.lab")
First example
Run this in edit mode (an execute, or inside a scene's build.luau content()). It builds the
hall at the origin and puts a camera on the high-speed side spot:
--!strict
local Lab = require("crashLab.lab")
local lab = Lab.build({ origin = { 0, 0, 0 }, style = "modern" })
print("impact point", lab.impact[1], lab.impact[2], lab.impact[3])
local spot = lab.cameraSpots.highSpeedSide
local cam = entity.spawn("HighSpeedCam")
cam.localPosition = spot.pos
cam.component.add("Camera", { fov = 50, priority = 10 })
cam.lookAt(spot.lookAt)
Run it again and the old hall is replaced, not duplicated. Lab.clear(lab.root) removes it.
The example scene examples/labDemo.scene does the same from its build.luau, with a camera
behind the start line looking down the track and no sky. Load it with
zero scene load labDemo (identity parts.crashLab.examples.labDemo in this world).
Gallery
examples/labGallery.scene shows all three styles side by side, 60 m apart along X: modern at
x = −60, classic at 0 and night at +60. Each hall's name is a big in-world label over its track
and on its roof. Its main camera (GalleryCamera) sees the three roofs from outside, and
GalleryCam_modern / _classic / _night look down each hall past its label. The scene's build is
one call you can use in your own scenes:
local Gallery = require("crashLab.gallery")
local g = Gallery.build({ origin = { 0, 0, 0 }, spacing = 60, ambientStyle = "modern" })
-- g.halls[style] is that hall's LabHandle; g.cameraSpots.overview / g.cameraSpots[style]
Only ambientStyle adds an ambient light, because a scene resolves only one. A rebuild replaces the
gallery, and Gallery.clear(g.root) removes it. Three halls are 39 lights, 18 of them shadowed
spots, so the gallery is a showcase rather than a game scene.
Tests
crashLab.testSuite covers the styles, asset resolution, the layout contract (it reads every mesh
triangle back against the clear space), the camera spots, build / clear / rebuild, and the gallery.
Run it with zero tests run crashLab in edit mode.
API
Lab.build(opts?) -> LabHandle
Lab.clear(root) -- despawn a hall (and everything under it)
Lab.STYLES -- { "modern", "classic", "night" }
Lab.LAYOUT -- the layout contract below, in the lab's local frame
Lab.LIGHTS -- per-style light colours / intensities (edit before build to retune)
| option | meaning |
|---|---|
origin | {x, y, z} world position of the impact point (default {0, 0, 0}). Everything is laid out relative to it. |
style | "modern" (default), "classic" or "night" |
parent | entity id or proxy to build under (default: top level) |
name | root entity name (default "CrashLab"). A rebuild replaces an existing root of this name under the same parent; give two halls different names. |
ambient | add an ambient Light for the style (default true). Pass false if your scene already has one: a scene resolves one ambient, and two make the engine warn about the tie. |
colliders | add the floor, pit-glass and wall colliders (default true) |
LabHandle:
{
root = "ent_…", -- the hall's root entity
style = "modern",
impact = { x, y, z }, -- = origin: the obstacle's impact face, floor level
trackStart = { x, y, z + 60 }, -- where cars start (up to)
cameraSpots = { -- world positions, { pos = {x,y,z}, lookAt = {x,y,z} }
highSpeedSide, overhead, barrierFace, chase, underCar, gallery, wide, startLine,
},
screens = { -- the three result screens (8 m x 4 m)
main = { id, center, normal, width, height }, -- back wall, above the load-cell wall, faces +Z
left = { … }, -- left wall beside the impact zone, faces +X
data = { … }, -- left wall halfway down the track, faces +X
},
ids = { meshes = { [meshName] = id }, lights = { id… }, colliders = { id… },
floor = id, glass = id, ambient = id? },
}
The camera spots, relative to origin:
| spot | pos | lookAt | what it shows |
|---|---|---|---|
highSpeedSide | (11, 1.2, 1.5) | (0, 0.8, 1.5) | side-on at the impact face, grid boards behind |
overhead | (0, 9.6, 2.0) | (0, 0, 1.6) | straight down on the impact, under the LED rig |
barrierFace | (3.6, 1.6, -0.8) | (0, 0.7, 6) | from beside the barrier at the oncoming car |
chase | (0, 2.4, 67) | (0, 0.9, 52) | behind the start line, down the track |
underCar | (0, -1.6, 3.5) | (0, 2.0, 3.0) | inside the pit, up through the glass |
gallery | (17.4, 4.65, 14) | (0, 0.8, 1) | from the control room, over the consoles |
wide | (-15, 9, 30) | (0, 1, 5) | establishing shot from high on the left |
startLine | (-6.5, 1.6, 64) | (0, 0.8, 0) | down the whole track to the load-cell wall |
A screen is its own entity carrying a Model with an emissive idle material, so a game can swap its
material or place a UiPanel / readout on it using center, normal, width and height.
Layout contract
In the lab's local frame (add origin):
- Impact point at the origin. The obstacle's impact face stands at z = 0, facing +Z.
- Track. Cars start at up to z = +60 and run toward −Z along a 10 m wide track centred on x = 0 (edge lines at x = ±5).
- Impact zone. Obstacles sit at z ≤ 0 in the 12 m x 10 m impact zone, x −6..6, z −10..0.
- Clear space. x −6..6, y 0..5, z −10..62 holds nothing solid but the floor. Cars, moving barriers and side-impact slides travel there; no prop, post or light stands in it.
- Floor. Its top is at y = 0. Its collider is one static box covering x −21..21, z −21..81 (0.5 m thick), and it stays solid over the pit. The pit glass has its own thin box collider as well.
- Pit. The opening is x −2..2, z 1..6, 2.4 m deep, under glass flush with the floor. The
underCarspot is inside it. - Hall. The inner faces are at x = ±20, z = −20 and z = 80, with the ceiling at y = 14. Walls have box colliders, so a car launched off the track stays in.
- Load-cell reaction wall. Its face is at z = −11 (x −8..8, 4.2 m tall), behind the impact zone.
- Control room. On the right wall: x 15.5..20, z 8..20, floor at y = 3.2.
Styles
| style | hall | light |
|---|---|---|
modern | white panels, grey dado, white steel | neutral 5600 K LED, bright floods, low ambient |
classic | pale green panels, dark green dado, blue-grey painted steel | warm halogen floods and fill |
night | charcoal hall | dim fill, hard cold floods on the impact, glowing pit and screens |
Lab.LIGHTS[style] holds each style's numbers (floodI, trackI, fillI, rigI, ambientI,
pitI, roomI and colours). Change them before Lab.build to retune.
Performance
- One hall is 55 entities. It has 32
Models, merged per material (about 75 k vertices in all), and 13 lights. - Lights. 4 flood spots on the impact and 2 track spots cast shadows (6, within the 8 a browser handles comfortably). The 4 area lights, the pit and control-room point lights and the ambient cast none.
- Shadow casters. Floor, paint, glass and emissive meshes cast no shadows.
- No per-frame cost. No component on the hall runs a script, and every sign and number is baked into one 2048² atlas, not drawn with live text.
- Not measured. The GPU frame cost of the hall on its own: the desktop engine it was built on was shared with other sessions running soft-body crash tests the whole time, and the browser build could not be checked (see Known limits).
Regenerating the assets
The meshes and textures are generated, not hand-modelled.
require("crashLab.labtex").buildAll()re-bakes the textures: the floor maps, the signage atlas (its text is rasterised with the engine's own font), the screens and the roof deck.require("crashLab.labgen").buildAll()re-authors every mesh.buildAll({ "deck" })rewrites only the meshes named.
Both run in edit mode and take a few seconds, during which the frame stalls. The floor is an exact tiling (concrete, paint, the epoxy pad, hazard bands and number panels each own their own patch of the floor), and every sign is the front face of its own plate, so nothing lies on top of anything else.
Known limits
- The scene's sky and haze still reach inside. An agent can't bake a reflection probe here, so
the polished floor reflects the scene's sky and the scene's aerial-perspective haze shows down the
hall.
examples/labDemo.sceneturns the sky off (aSkybox { kind = "none" }entity in itsscene.json). In a scene with a bright blue sky the hall reads slightly cool. Baking aReflectionProbeat the impact point (reflectionProbe.add(0, 3, 0, { radius = 40 })thenreflectionProbe.bakeAll()) fixes the reflections. - The z-fighting diagnostic still marks real 3D detail. It flags wall ribs, truss joints and load-cell plates that stand a few cm proud of their surface when seen edge-on. That is a conservative band, not overlapping surfaces: there are no coplanar overlays left.
- Static by design. Nothing in the hall moves, and the screens show baked idle pictures; put live readouts on them yourself.
- The web build is unchecked. An agent can't start a browser engine to check the web build (#20946).