Log inGet started
Package

crashObstacles.package

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

README.md

crashObstacles

The things a crash-test car is launched into, built like a real crash lab: a load-cell rigid wall, the Euro NCAP 40 % offset deformable barrier, the IIHS 25 % small-overlap barrier, a security bollard, a lighting column, a tree, a W-beam guardrail, a water-barrel crash cushion, a parked car, the 254 mm side-impact pole and a 1400 kg moving deformable barrier for rear impacts. The crushable ones are real soft bodies with plasticity, so a ~1300 kg car at 50 km/h leaves a dent that stays, and the dent replicates to every player. The rigid ones do not move.

Every obstacle tells you how the car meets it (frontal, side or rear), where the car's centreline should sit for the right overlap (alignX), and, for the rear test, which body the rig launches instead of the car (mover).

Install

Install the package crashObstacles from ZeroMind (it lands at /source/parts/crashObstacles.package or wherever you install it) and require it by its bare name:

local Obstacles = require("crashObstacles.obstacles")

crashCars is an optional dependency: with it installed, the parkedCar obstacle is a crashCars saloon; without it, crashObstacles uses its own compact saloon (rigid chassis + soft denting body shell).

First example

Paste into a host-only spot (a scene's onHostLoad, or an execute while playing). It spawns the offset barrier, lines a 1300 kg test sled up 40 % offset, tows it at 50 km/h, lets go 1 m before the face and prints the dent the honeycomb kept (0.14 to 0.15 m at 50 km/h: two runs read 0.136 and 0.154 m in a fresh world at 30 physics steps a second; the example scene's sled measured 0.138 m at 60). The dent varies a centimetre or two from run to run because the sled meets the honeycomb's particles at a slightly different point of a physics step each time; the physics rate (physics.tick_rate) changes it by about as much:

--!strict
local Obstacles = require("crashObstacles.obstacles")

local o = Obstacles.spawn({ kind = "offset", position = { 0, 0, -20 }, synced = true,
                            vehicle = { width = 1.8, length = 4.2 } })

-- a 1300 kg box sled, its nose 3 m from the barrier face, lined up 40 % offset
local sled = entity.spawnSynced("Sled", { position = { o.alignX, 0.8, -20 + 2.1 + 3 } })
sled.localScale = { 1.8, 1.0, 4.2 }
sled.component.add("Model", { model = asset.resolve("cube", "mesh") })
sled.component.add("BoxCollider", {})
sled.component.add("Physics", { kind = "dynamic", mass = 1300 })

local towing = true
local stop = Physics.onBeforeStep(function()
    if not towing then return end
    if sled.position.z - 2.1 <= -20 + 1 then -- let go 1 m before the face
        towing = false
        return
    end
    Physics.setVelocity(sled.id, 0, 0, -50 / 3.6)
end)

task.wait(3)
stop()
print(("offset barrier kept a %.2f m dent"):format(Obstacles.dent(o)))

The package's example scene examples/obstaclesDemo.scene lays out all eleven obstacles in a lab and runs the same test on play (component ObstaclesDemoSled), printing peak g, mean g and the dent.

Gallery

examples/obstaclesGallery.scene stands every obstacle in catalog order in one static test hall (wall, offset, smallOverlap, bollard, pole, tree in front; guardrail, cushion, parkedCar, sidePole, rear behind), each on its own pad with its impact face toward the camera and a placard giving its name, id and mode. Each is the real Obstacles.spawn build (synced = false) stripped to its drawn parts, so no soft body, rigid body or collider runs; the parked car is crashCars' drawn-only lineup car when crashCars is installed. Its galleryCamera frames both rows. Load it additively (or open it) to browse the obstacles.

API

Obstacles.spawn(opts) -> Handle
optionmeaning
kindone of the catalog ids below (required)
position{x, y, z} on the ground at the centre of the impact face; the face points +Z (the car comes from +Z travelling toward −Z). Default {0,0,0}
syncedtrue (default) spawns with entity.spawnSynced / addSynced so every player has it: call on ONE peer (the rig authority). false for local or scene-build use
vehicle{ width, length, seatZ? } of the car that will hit it, used for alignX (defaults 1.8 × 4.2 m)
name, parentroot entity name / parent
car, builtinCarparkedCar only: { model, look } passed to crashCars, or builtinCar = true to force the built-in car
tuneadvanced: SoftBody field overrides for the crushable part (e.g. { stiffness = 5e4 })

Handle: { root, kind, spec, alignX, mover, soft, parts, car }

  • root — the obstacle's root entity id (attribute crashObstacle = kind).
  • spec — { id, name, mode, test, description, crushable, carYaw, alignX = function(vehicle) } plus extras (rear.moverMass, rear.moverStart, rear.moverFaceOffset, sidePole.poleDiameter, offset.barrier).
  • alignX — metres along +X the car's centreline should take (already computed for vehicle).
  • mover — rear only: the trolley's dynamic body (1400 kg) that the rig launches along −Z.
  • soft — ids of the soft (crushable) parts; parts — named child ids; car — crashCars handle.

Also: Obstacles.despawn(o), Obstacles.catalog() → list of { id, name, mode, description, test, crushable }, Obstacles.kinds(), Obstacles.spec(kind), Obstacles.alignX(kind, vehicle), Obstacles.dent(o) (deepest permanent dent in metres, read on the simulating peer) and Obstacles.repair(o) (back to the built shape, on every peer).

Catalog

kindmodereal-world test it representscrushable?measured at 50 km/h, 1300 kg rigid sled
wallfrontalFull-width rigid barrier (FMVSS 208 / Euro NCAP FW) — 3.6 × 1.8 m block, steel face, 32 load-cell platesrigiddoes not move
offsetfrontalEuro NCAP / ECE R94 ODB, 40 % overlap: 1000 × 650 mm honeycomb (+ stiffer bumper element) 200 mm upyes0.39 m dynamic crush, ~0.14 m permanent dent (0.138 m in the example scene), 28 g mean / 66 ms
smallOverlapfrontalIIHS small overlap, 25 %: 1.5 m rigid steel barrier, 150 mm radius edgerigiddoes not move
bollardfrontalNarrow-object hit: 273 mm concrete-filled steel bollardrigiddoes not move
polefrontalLighting column, 8 m octagonal galvanised, 240 mm at the rootrigiddoes not move
treefrontalRun-off-road tree: mature Scots pine, 540 mm trunkrigiddoes not move
guardrailfrontalW-beam guardrail, 3.81 m span between posts on the centrelineyes1.8 m dynamic deflection, rail stays bent (plastic 0.82), 7.4 g mean / 260 ms
cushionfrontalCrash attenuator: 3 × 4 water-filled barrel arrayyes2.8 m dynamic, ~2.0 m permanent crush, 6 g mean / 250 ms
parkedCarfrontalCar-to-car T-bone into a stationary caryes (car shell)built-in car: 0.17 m door dent, car shoved sideways, 17 g mean
sidePolesideEuro NCAP / FMVSS 214 pole, 254 mm rigid; collides as a 254 × 254 mm box, 3.2 m tall, on the pole axisrigiddoes not move
rearrearRear MDB (FMVSS 301 / R34 style), 1400 kg, 1700 × 500 mm faceyes0.13 m permanent face dent into a 1300 kg standing sled

Peak g read on a rigid sled is a single 200–400 g sample at first contact (a rigid box has no crumple zone); a car's own crush spreads it. Filter it (SAE J211) as a rig would.

How the car meets each obstacle

  • Frontal (mode = "frontal"): the car faces −Z (carYaw = 0) and travels −Z into the face at position. Put its centreline at position.x + o.alignX.
  • Offset / small overlap: alignX puts the barrier's inner edge on the 40 % (offset: 0.5 + 0.1·width) or 25 % (smallOverlap: 0.5 + 0.25·width) line measured from the driver's side. The driver sits on the left, i.e. −X when the car faces −Z.
  • Side pole (mode = "side", carYaw = -90): turn the car so its driver's side leads (local −X → world −Z) and launch it along −Z. alignX puts the driver's H-point on the pole axis: it is vehicle.seatZ (the seat's local Z, negative = ahead of centre) or −6 % of the length. The pole's collider is a rigid 254 mm square BoxCollider (3.2 m tall, front face at position) on the pole axis alone: the frame and base plate around it are visual only, so the door meets a pole-width contact rather than a door-wide wall.
  • Rear (mode = "rear"): park the car facing −Z with its rear bumper at position. The rig launches o.mover (the 1400 kg trolley, its face spec.moverFaceOffset ahead of the body's origin and starting spec.moverStart m behind position) along −Z into it, and releases it 1 m before contact like any tow.
  • Parked car: the target car stands broadside, its side at position; the test car hits it frontally (T-bone). It is dynamic and gets pushed.

Multiplayer

Spawn with synced = true on one peer (the rig authority, e.g. behind multiplayer.isHost()). Every mesh is an authored .mesh asset and every material a .material asset inside the package, so every peer draws the same thing. Soft-body dents replicate natively from the simulating peer (a replica never dents on its own, and late joiners get the settled shape). Rigid bodies (the trolley, the parked car) replicate as poses. Push / tow only from the simulating peer. Obstacles.dent reads the local solver, so read it there; Obstacles.repair goes through the SoftBody component and reaches everyone.

Built from

  • Concrete (concreteSmooth) textures: Brick and Mortar masonry collection (MIT, ZeroMind).
  • Aluminium, galvanised and raw steel textures: Forge and Patina metals collection (MIT, ZeroMind).
  • Tree: RAINLINE realistic mature coastal Scots pine bundle from AFTERCURRENT (MIT, ZeroMind).
  • Everything else (meshes, hazard stripes, chevrons, load cells, barrels, rails, trolley, fallback car) is generated by crashObstacles.meshgen — run require("crashObstacles.meshgen").buildAll() in edit mode to re-author the meshes after changing it.

Known limits

  • Soft bodies don't report the energy they absorbed (engine issue #20539). Obstacles.dent gives the permanent dent; an energy figure has to come from the car's speed change.
  • A kinematic body covers a frame's motion in its first step (#21187): a rig that drives the trolley kinematically will deliver its first contact a frame early. Tow it as a dynamic body with Physics.setVelocity each step (as the example does).
  • The crushable faces are tuned soft bodies, not cell-level honeycomb: the crush force is right in order of magnitude (pulses of 6–30 g on a rigid sled) but not certified to the 0.342 / 1.711 MPa ODB spec.
  • The offset honeycomb and the MDB face rest on a 30 mm steel tray (it carries their weight; a soft body this soft would otherwise creep under gravity). On the ODB the tray is set 150 mm back from the face at 170–200 mm height, so only a car part lower than 200 mm that crushes more than 150 mm reaches it.
  • The guardrail's posts are rigid and the rail is bolted (pinned) to them; the car meets the 3.81 m span between the two centre posts. A hit on a post itself is a rigid hit.
  • rear: the trolley slides on a low-friction skid rather than rolling on wheels.
  • parkedCar with crashCars depends on that package's car; its own limits apply (wheels have no volume and can't come off, #20543).