# driveSurfaces The ground a tyre stands on. Fourteen surfaces in a fixed order, each with what it does to a tyre (grip, slide grip, stiffness, rolling resistance, bogging drag, roughness, dust colour, skid sound, tyre class) and what it looks like; one call that answers which surface a wheel is on; a `Surface` component that paints any entity with a surface; and a `SurfacePatch` component that lays a puddle, an oil spill or a rumble strip over whatever ground is under it. Paved looks are procedural and texture-free (`drivePavement` shader): aged asphalt with aggregate stones, repair patches and hairline cracks; wet asphalt with standing water; sawn concrete slabs; granite setts in running bond; red/white ribbed kerbs; still puddle water with faint ripples; black oil with a thin-film rainbow sheen. They show at real scale on any box, plane or mesh. Natural grounds wear the installed **groundMaterials** (Terra Firma) surfaces. ## First example Paste this into the console (`execute`) of a fresh world that has driveSurfaces and groundMaterials installed. It lays four 8 m pads and an oil spill in front of the spawn, then asks which surface a wheel would read on each: ```luau local Surfaces = require("driveSurfaces.surfaces") local pads = {} for i, kind in { "tarmac", "gravel", "grass", "ice" } do -- an 8 x 8 m pad whose top is at y = 0.05: material, BoxCollider and Surface component pads[kind] = Surfaces.pad(kind, { (i - 2.5) * 9, 0.05, -12 }, { synced = true }) end -- a 3 x 5 m oil spill lying on the tarmac pad (a zone: it wins over the pad under it) Surfaces.patch("oil", { -13.5, 0.05, -12 }, { size = { 3, 5 }, yaw = 30, synced = true }) -- what a wheel resting at a point reads (normally: the WheelCollider's hit entity and point) print(Surfaces.sample(pads.gravel.id, vector.create(-4.5, 0.05, -12)).name) --> gravel print(Surfaces.sample(pads.tarmac.id, vector.create(-13.5, 0.05, -12)).name) --> oil print(Surfaces.sample(nil, nil).name) --> tarmac ``` To remove it: `for _, e in pads do entity.despawn(e.id) end` and despawn `patch_oil`. To see every surface at once, load the gallery: `zero scene load driveSurfaces.surfacesGallery` in the shell (edit mode; it bakes on its first load). ## API (`require("driveSurfaces.surfaces")`) | Call | Answers | |---|---| | `Surfaces.names()` | surface names in their fixed order: the `car.surfaceId` order of the driving contract | | `Surfaces.list()` | every definition, in order | | `Surfaces.get(name)` / `Surfaces.byId(id)` | one definition, or nil | | `Surfaces.default()` | tarmac | | `Surfaces.sample(hitEntityId, position)` | the surface at a wheel contact: a patch zone at `position` first, else the `Surface` on the hit entity or its nearest ancestor that has one, else tarmac. Takes an id string or entity proxy (or nil), and a vector, a position proxy or `{x, y, z}` | | `Surfaces.ofEntity(entity)` | the entity's own / nearest ancestor's surface, else tarmac | | `Surfaces.patchAt(position)` | the patch zone surface at a point, or nil | | `Surfaces.material(name)` | the material a surface wears (an AssetRef for `Model.material`) | | `Surfaces.paint(entity, kind)` | gives an entity the surface's material (adding a cube Model if it has none) and a `Surface` component | | `Surfaces.pad(kind, position, opts?)` | spawns a drivable pad (`opts.size` {x,y,z}, default 8 x 0.2 x 8, top at `position.y`; `parent`, `name`, `synced`, `yaw`) | | `Surfaces.patch(kind, position, opts?)` | spawns a patch zone lying on the ground at `position` (`opts.size` {x, z}, default 4 x 4) | | `Surfaces.gallery(parent?)` | lays out every surface as a labelled pad | | `Surfaces.invalidate()`, `registerPatch`, `unregisterPatch`, `patchCount()` | what the components call; `patchCount` for debugging | A definition is `{ name, label, id, class, grip, slide, stiffness, rolling, drag, bump, dust: vector, skid, material, patchOnly }`: - `class`: `paved` | `wet` | `loose` | `soft` | `snow` | `ice`, the keys of a tyre's `affinity` table in torqueCars. - `grip`: peak grip multiplier (tarmac 1). `slide`: multiplier on the tyre's sliding grip. `stiffness`: multiplier on tyre stiffness. - `rolling`: rolling resistance coefficient. `drag`: extra speed drag in s^-1 (bogging). `bump`: 0..1 roughness felt through the suspension. - `dust`: colour of the dust or spray a sliding tyre throws. `skid`: `tarmac` | `gravel` | `soft` | `none` (which skid sound). | id | name | class | grip | slide | stiff | rolling | drag | bump | skid | look | |---|---|---|---|---|---|---|---|---|---|---| | 1 | tarmac | paved | 1.00 | 1.00 | 1.00 | 0.012 | 0 | 0.03 | tarmac | aged asphalt (drivePavement) | | 2 | wetTarmac | wet | 0.70 | 0.62 | 0.90 | 0.014 | 0 | 0.03 | tarmac | wet asphalt, standing water | | 3 | concrete | paved | 0.95 | 0.95 | 1.00 | 0.013 | 0 | 0.06 | tarmac | 4 m sawn slabs | | 4 | cobbles | paved | 0.80 | 0.80 | 0.95 | 0.018 | 0 | 0.35 | tarmac | granite setts | | 5 | gravel | loose | 0.60 | 0.75 | 0.60 | 0.030 | 0 | 0.30 | gravel | groundMaterials `gravel` | | 6 | dirt | loose | 0.65 | 0.70 | 0.70 | 0.025 | 0 | 0.20 | gravel | groundMaterials `dirt` | | 7 | mud | soft | 0.40 | 0.45 | 0.50 | 0.060 | 0.20 | 0.25 | soft | groundMaterials `mud` | | 8 | grass | soft | 0.50 | 0.55 | 0.60 | 0.035 | 0 | 0.15 | soft | groundMaterials `shortGrass` | | 9 | sand | soft | 0.45 | 0.55 | 0.45 | 0.080 | 0.25 | 0.10 | soft | groundMaterials `drySand` | | 10 | snow | snow | 0.35 | 0.40 | 0.50 | 0.030 | 0.05 | 0.08 | soft | groundMaterials `packedSnow` | | 11 | ice | ice | 0.10 | 0.12 | 0.90 | 0.010 | 0 | 0.01 | none | groundMaterials `ice` | | 12 | rumble | paved | 0.90 | 0.90 | 1.00 | 0.020 | 0 | 0.85 | tarmac | red/white ribbed kerb | | 13 | puddle | wet | 0.45 | 0.40 | 0.80 | 0.020 | 0 | 0.02 | none | still dark water | | 14 | oil | wet | 0.15 | 0.15 | 0.90 | 0.012 | 0 | 0 | none | black film, rainbow sheen | The order is fixed: new surfaces are appended, never inserted, because `car.surfaceId` is an index into it. ## Components - **`Surface`** (`kind`, synced): this entity, and every descendant without a Surface of its own, is that ground. `Surfaces.paint` adds it. - **`SurfacePatch`** (`kind`, `showLook`, synced): a zone of one surface over other ground. The zone is the entity's unit box times its world scale, turned with the entity; the entity's origin sits ON the ground, and the zone reaches half its Y scale up and down plus 0.35 m of slack. It registers itself into the module's flat patch list on awake (and moves with its entity, checked every 0.25 s) and unregisters on destroy. Its look sits flush on the ground at the origin: water (puddle) and oil are 1.5–2 cm films cut to an irregular blob, rumble is a 3 cm red/white slab whose stripes run along local Z, any other kind a 2 cm slab of its material. ## How a car uses it torqueCars calls `Surfaces.sample(hit.entityId, hit.point)` for each wheel's ground contact, multiplies the tyre's own grip fields by `grip` / `slide` / `stiffness` and its `affinity[class]`, adds `rolling` and `drag` to its resistance, shakes the suspension by `bump`, and publishes the result's `id` as `car.surfaceId`. `sample` is two table lookups for an entity it has seen (cached per entity id, invalidated when a Surface appears, changes or goes) plus one oriented-box test per patch zone, about 0.25 µs per call. ## Known limits - **#20569:** the engine's named terrain surfaces exist, but `WheelCollider` wheels do not read them yet. Grip per surface therefore comes from this package's `sample()`, which the car calls per wheel and applies to its WheelCollider grip fields. When the engine reads surfaces itself, the same table can drive it. - **#20610:** the engine's rolling resistance is in progress. `rolling` is a coefficient the car applies itself (as a resisting torque/force) until the WheelCollider takes one. - **Thin films:** puddle and oil looks are planes 1.5–2 cm above the ground they lie on (a decal projector stamps base colour only, so it cannot carry glossy water). They read cleanly in lit frames, and the engine's z-fighting diagnostic flags them from far away by its distance-relative tolerance. - **Patch zones are boxes:** a puddle's look is an irregular blob, but its zone is the whole box. ## Multiplayer `Surface` and `SurfacePatch` fields are synced, so a patch or paint applied to a synced entity reaches every player; every peer registers its own patch zones from its own entities, so `sample()` answers the same everywhere. Script-made pads in edit mode are local unless spawned `synced`. ## Files `surfaces.module` (the table and `sample`), `Surface.component`, `SurfacePatch.component`, `shaders/pavementLib.shaderModule` (procedural asphalt, concrete, setts, kerb, blob, thin-film, bump), `shaders/drivePavement.shader`, `materials/` (tarmac, wetTarmac, concrete, cobbles, rumble, puddle, oil), `surfacesGallery.scene`.

# torqueCars Drivable cars that behave like machines, as one family switched by one setting. Twelve kinds in three looks, each with its own engine character, gearing and drive layout, and every part swappable while you drive. Built on the engine's own vehicle physics: `WheelCollider` tyres that spin and slip, a `ShaftNetwork` drivetrain (engine torque curve → clutch → gearbox → differentials → wheels) solved inside the physics step, and a `SoftBody` shell that crumples where it is hit and **stays crumpled** until the car is reset. ## First example Install torqueCars (it brings `driveSurfaces` for ground grip when you install that too). Then, with the world in **play**, run this from the console (`execute`) — or paste it into your scene's `entrypoint.luau` inside `function onLoad() ... end`: ```luau local Assemble = require("torqueCars.assemble") local car = Assemble.spawn({ kind = "rally", position = vector.create(0, 0.2, 6) }) -- W/S throttle and brake (S at a stop reverses), A/D steer, Space brake, -- Ctrl handbrake, E/Q shift, M auto/manual, R reset, Backspace respawn. ``` The car takes the player's driving controls at once (gamepad and touch too). To make a car **each joining player's own body**, build it under the scene's player prototype in `build.luau`: ```luau local Assemble = require("torqueCars.assemble") local body = entity.spawn("body", { parent = prototype }) Assemble.build(body, { kind = "coupe", look = "real" }) body.component.add("Car", { kind = "coupe", look = "real", control = "player" }) prototype.component.add("PlayerPrototype", { body = body, camera = rig }) ``` Add a `Garage` component to any scene entity and **G** opens the parts panel. ## The family: one setting each Every field below is on the `Car` component and can be changed live (from the garage, from code with `car:setPart(slot, name)`, or in the inspector): | field | values | |---|---| | `kind` | `hatchback` `coupe` `muscle` `rally` `drift` `pickup` `van` `suv` `buggy` `kart` `boxtruck` `electric` | | `look` | `lowpoly` `toy` `real` | | `paint` | `white` `red` `orange` `yellow` `green` `blue` `purple` `black` `silver` `teal` `pink` `brown` (empty = the kind's) | | `engine` | `i4` `turbo4` `v6` `v8` `v12` `diesel` `rotary` `electric` `kart` | | `gearbox` | `manual5` `manual6` `auto` `sequential` `direct` | | `diff` | `open` `lsd` `locked` | | `tyres` | `road` `sport` `slick` `drift` `offroad` `snow` `studded` `steel` | | `control` | `player` `script` (AI / code via `setIntent`) `none` | | `autoShift`, `assists` | auto gear changes; ABS + traction control | An empty part name means "the kind's own". All data is in `torqueCars.catalog`. ### Measured 0–100 km/h (stock, flat tarmac, assists on, simulated time) All twelve measured together on a 2 km tarmac strip with `Bench.accelerate`, full-rate controller. | kind | layout · engine · gearbox | 0–100 | real class | |---|---|---|---| | hatchback | FWD · 1.6 four 122 hp · 5-sp manual | 10.9 s | 9–11 s | | coupe | RWD · 3.5 V6 330 hp · 6-sp manual · LSD | 6.9 s | 5–6 s | | muscle | RWD · 6.2 V8 455 hp · 6-sp manual · LSD | 7.0 s | 4.5–5.5 s | | rally | AWD · 2.0 turbo four 300 hp · sequential | 5.2 s | 4–5 s | | drift | RWD · twin-rotor 240 hp · 5-sp · welded diff | 7.2 s | 5.5–6.5 s | | pickup | RWD · 6.2 V8 · 6-sp automatic | 8.6 s | 6.5–8 s | | van | FWD · 2.5 turbo-diesel 180 hp · 5-sp | 14.1 s | 11–14 s | | suv | AWD · 3.5 V6 · automatic | 7.4 s | 7–8.5 s | | buggy | RWD · 1.6 four · sequential · locked | 8.1 s | 6–7 s | | kart | RWD solid axle · 125cc 45 hp two-stroke · sequential | 7.7 s | 4–5 s | | boxtruck | RWD · diesel · automatic, 5.2 t | never: governed at 93 km/h (0–80 in 20.1 s) | 30–45 s | | electric | AWD · 300 kW dual motor · single speed | 4.3 s | 3.5–4.5 s | Measure your own with `torqueCars.bench` (`Bench.accelerate(car, 100)`, `Bench.brake(car, 60)`, `Bench.brakeRolling(car, 60)`); the bench turns the car's `lod` off. The powerful rear-drivers (muscle, coupe) and the kart are traction-limited off the line: traction control holds the driven tyres near their peak slip, and with it off they spin without limit (#20654), so they launch slower than their real twins. ### Measured 60–0 km/h braking (stock hatchback, road tyres, ABS, rolling start) | tarmac | concrete | sand | cobbles | gravel | mud | dirt | wet tarmac | grass | snow | ice | |---|---|---|---|---|---|---|---|---|---|---| | 17.2 m | 18.4 m | 19.0 m | 20.6 m | 22.0 m | 22.6 m | 23.2 m | 26.3 m | 27.3 m | 33.7 m | 113.8 m | Gravel stops 28 % later than tarmac, ice 6.6× later. Sand and mud stop shorter than their grip alone suggests because the wheels sink and plough (the surface's bogging drag), as they do in a real car. Studded tyres multiply ice grip 4.2×, snow tyres snow grip 1.9×, off-road tyres loose ground 1.35×. ### Measured damage A rally car driven into the valley's concrete crash wall at 60 km/h (crash detector closing speed 44–50 km/h, the rest absorbed in the first instants of contact) kept a permanent crush of **9.5 cm** nose-first and **12.7 cm** side-on, unchanged 5 s later. The dent stays until `reset()` or a respawn, which rebuild the shell undamaged. The rigid core spans the cabin (76 % of the length), so the shell's nose and tail are the crumple zones. ### Cost Per car on a desktop (native, in the editor): the driver runs at the physics tick, about 0.3–0.8 ms a step (network inputs are written only when they change; each `ShaftNetwork:set` costs ~0.2 ms), and the soft-body shell ~0.15–0.2 ms a step at resolution 5 (36–40 particles). Script-driven cars more than 60 m from this peer's own car run their controller every other step (`lod`, on by default). ## How it drives - **Engine**: full-throttle torque curve per engine (idle, redline, limiter); idle governor; turbo spool lag (turbo four, diesel); a rev limiter that cuts fuel in 70 ms bursts. Engine braking from friction and pumping losses. - **Clutch**: automatic — slips to launch, opens for every shift, re-engages (manual ≈0.3 s, sequential 80 ms, automatic slurs like a torque converter). - **Gearbox**: auto-shift by rpm and pedal (kickdown included) or manual E/Q; holding brake at a standstill selects reverse. - **Differentials**: open, limited-slip (preload + bias) or locked; AWD cars add a biased centre diff. - **Tyres**: grip curve per tyre set, multiplied by the ground under each wheel (`driveSurfaces`) and the set's affinity for that ground — studded tyres on ice, off-road tyres on gravel. - **Body**: a plastic soft-body shell held to the chassis along the cabin floor, so the nose and tail are crumple zones. A 60 km/h wall hit leaves about 10 cm of permanent crush (9.5 cm measured nose-first, 12.7 cm side-on). `car:reset()` (R) repairs it. `car.damage` counts from the shell's settled shape, so a fresh or respawned car reads 0 %. - **Cockpit**: the body draws its inner faces as dark cabin trim and leaves the glass open from inside, and every car carries a steering wheel in front of its seat, so a camera at `car.mountSeat` sits in a cabin and one at `car.mountHood` looks over the bonnet. - **Respawn**: `respawn()` (Backspace) takes the car back to where it stood once it had settled after spawning (a spawner that moves the car in its first second moves the spawn point with it), or to `setSpawn`'s point, set down on the ground there. - **Drag**: aerodynamic drag, rolling resistance and soft-ground bogging. ## Values a car publishes Gauges, engine sounds, cameras and AI read the car only through named values on the chassis (`car.rpm`, `car.kmh`, `car.gear`, `car.load`, …). The full list and the `Car` API are in `CONTRACT.md` in this package. ## Contents - `Car` component — the driver (input or script), drivetrain control, assists, damage, values. - `Garage` component — the live parts panel (G / d-pad up / touch). - `torqueCars.assemble` — builds a car under a chassis entity (`build`, `spawn`). - `torqueCars.catalog` — kinds, engines, gearboxes, diffs, tyres, paints. - `torqueCars.bodies` — the 36 body meshes, wheels and paints (three looks). - `torqueCars.bench` — 0–100 and braking measurements. - `torqueCars.cars` — registry of live cars (`Cars.all()`, `Cars.localPlayer()`). - `driveControls` input map — throttle, steer, brake, handbrake, boost, recover (keyboard, gamepad, touch); the car's own, so it does not depend on the engine's vehicle map. - `carControls` input map — shift, auto/manual, respawn, garage (keyboard, gamepad, touch). - `carGallery` scene — every kind in every look side by side. ## Multiplayer Each car is simulated by the peer that owns it (a player's car by that player, AI cars by the host); every other peer draws it from the owner's poses. The engine replicates the soft-body dents from the owner, so everyone sees the same crumpled panels, including a player who joins later. The values a voice, a gauge or a brake lamp needs (`car.rpm`, `car.load`, `car.throttle`, `car.gear`, `car.shiftCount`, `car.boost`, `car.skid`, `car.brake`, `car.impactCount`, …) are declared with a replication rate, so remote cars sound and light up as they drive. The part fields (`kind`, `engine`, `tyres`, …) are synced: a swap made in one player's garage reaches every peer. Driving intent and network inputs are local to the owner. Verified on one machine with the engine's replication read-outs; a second real client has not been connected yet. ## Known engine limits - **#20569** — wheels do not read the ground's named surfaces yet, so each car ray-casts under its wheels itself and asks `driveSurfaces` for the grip. - **#20610** — rolling resistance is in progress in the engine; the car applies its own rolling resistance and drag as forces and leaves `rollingResistance` off double-counting. - **#20543** — wheels have no volume and cannot come off: a crash dents the body but never knocks a wheel loose, and a wheel can clip through a wall the body stops at. - **#20654** — held at full throttle a wheel can spin up without limit; the rev limiter and traction control (assists) keep it in check, with assists off a stationary burnout can over-spin. - **#21001** — a drivetrain's cost grows quickly with its parts, so every car uses the smallest network for its layout (7 parts FWD/RWD, 9 AWD) and writes network inputs only when they change. - **#21241 / #21242** — synced entity references and lists with gaps do not reach other players; the car keeps none in synced fields (the shell's attachment is re-made on each peer).

# engineVoices.voices The eight engine voices, in the order `car.voiceId` uses: `four`, `v8`, `v12`, `diesel`, `rotary`, `turbo`, `electric`, `kart`. The module holds each voice's description and its default idle, redline and limiter rpm, plus the synthesis parameters that `engineVoices.synth` bakes it from. It also holds every clip the runtime plays (static identities, so a publish pins them), the skid sound for each `driveSurfaces` surface, and the calls that put a voice on a car. `EngineVoice` is the component that calls it at runtime. Game code calls `attach`, `set` and `names`. ```lua local Voices = require("engineVoices.voices") Voices.names() --> { "four", "v8", "v12", "diesel", "rotary", "turbo", "electric", "kart" } Voices.attach(car) -- EngineVoice on the chassis, voice from car.voiceId Voices.attach(car, "v12") -- forced voice (or Voices.set(car, "v12") later) Voices.detach(car) Voices.get("v8").blurb -- "Cross-plane V8 rumble and burble: ..." Voices.surface(5).skid --> "gravel" Voices.firingHz("v8", 3000) --> 200 ``` The calls are `names()`, `has(name)`, `get(name)`, `nameOf(id)`, `idOf(name)`, `loopName(voice, band, onLoad)`, `firingHz(voice, rpm)`, `clips()`, `surface(id)`, `attach(car, voice?, volume?)`, `set(car, voice)` and `detach(car)`.

# engineVoices.synth The deterministic generator behind the engine voices, and the analysis that checks them. Re-run it after you change a voice's parameters in `engineVoices.voices`. Nothing at runtime requires it. Each loop is one second of 32 kHz mono PCM. A loop holds a whole number of engine cycles: every band's reference rpm gives a cycle frequency that is a whole number of Hz (rpm/120 for four-strokes, rpm/60 for two-strokes and the rotary). Firing pulses (gamma-shaped pressure pulses plus combustion-noise bursts) are placed modulo the loop length. Every filter (two-pole low-pass, RBJ band-pass pipe resonances, a DC-blocking high-pass) runs over the buffer twice, so its state wraps, and the result loops with no seam. Per-cylinder imbalance, per-firing amplitude and timing jitter, misfires (kart four-stroking, rotary brap), per-bank pipes and delays (V8 cross-plane burble, V12 banks), diesel knock and valvetrain ticks shape the character. A tanh drive stage gives the on-load takes their extra harmonics. Loudness is set per take: on-load at 0.2 RMS and off-load at about 0.085. ```lua local Synth = require("engineVoices.synth") Synth.bakeAll() -- 48 loops + shared clips, about 6 s Synth.bakeVoice("v8") -- one voice's six loops Synth.bakeShared() -- whistle, inverter, shifts, pops, skid loops local x, ref = Synth.render("kart", 1, true) -- samples without baking Synth.analyze("ev_v8_2_on") --> { peakHz = 168, firingHz = 168, peakOverFiring = 1, harmonicShare = .., rms = .. } ``` `bakeShared` builds the tarmac squeal from soundstage's generated `ss_vehicles_skid_3` take when soundstage is installed. It builds the gravel and soft loops by cutting the steady middle of the generated `ev_skid_*_src` takes and crossfading the wrap.

# EngineVoice The sound of a car. Put it on a car's chassis entity, the one that carries the driving contract's `car.*` named values, and it plays the engine, gear changes, rev limiter, turbo, tyre skids and crashes from those values. It needs no sibling component: any entity that writes `car.rpm`, `car.load` and the rest gets a voice, a `torqueCars` car, another car kit, or the `EngineVoiceDemo` stand-in. It spawns local child entities, each with a spatial `Audio` source at `doppler = 1`, so passing cars drop in pitch: - six engine layers, three rpm bands times on-load and off-load. They crossfade by rpm (equal power, in log rpm) and by `car.load`, and each is pitched to `rpm / band reference rpm`; - an aux layer: the turbo whistle that follows `car.boost` (turbo, diesel) or the inverter whine (electric); - a skid loop whose volume follows `car.skid` and whose clip changes with `car.surfaceId`: tarmac squeal, gravel crunch, soft scrub; - a one-shot host for gear changes (`car.shiftCount`), overrun pops, blow-off on lift, limiter stutter pops and crash crunches (`car.impactCount`, scaled by `car.impactSpeed`). The values replicate and the component runs on every peer, so every player hears every car. ## Fields | field | default | meaning | |---|---|---| | `voice` | `auto` | `auto` follows `car.voiceId`. Set a name to force a voice: `four`, `v8`, `v12`, `diesel`, `rotary`, `turbo`, `electric`, `kart`. It can be changed live. | | `volume` | 1 | multiplier for everything this car sounds | | `maxDistance` | 160 | metres to silence | | `shiftStyle` | `auto` | `auto` reads the `Car` component's gearbox mode, falling back to the voice's default; or `manual`, `sequential`, `automatic`, `none` | | `skids`, `crashes` | true | turn those sounds off | | `doppler` | 1 | Doppler scale on every source | `:mix()` returns what the voice is doing this frame: the voice, the smoothed rpm, load and boost, the band weights, the on-load and off-load gains, the level, the skid level and kind, and the ids of its sources. Read those ids with `audio.voice(id)`. ```lua car.component.add("EngineVoice") -- voice from car.voiceId car.component.get("EngineVoice").voice = "rotary" -- switch it live print(car.component.get("EngineVoice"):mix().bands[2]) ```

# surfaces (driveSurfaces.surfaces) The table of driving surfaces and the per-wheel lookup. Fourteen surfaces in a fixed order (tarmac, wetTarmac, concrete, cobbles, gravel, dirt, mud, grass, sand, snow, ice, rumble, puddle, oil; the index is the driving contract's `car.surfaceId`), each with grip, slide grip, stiffness, rolling resistance, bogging drag, roughness, dust colour, skid sound, tyre class and the material it wears. `sample(hitEntityId, position)` answers the surface under a wheel contact: a SurfacePatch zone there first, else the Surface component on the hit entity or its nearest ancestor, else tarmac, cached per entity id so it costs about 0.25 µs. Also `names`, `list`, `get`, `byId`, `ofEntity`, `patchAt`, `material`, and authoring helpers `paint(entity, kind)`, `pad(kind, position, opts)`, `patch(kind, position, opts)` and `gallery(parent)`. Called by torqueCars' cars per wheel per physics tick, and by anything that wants to know the ground (skid sounds, dust, AI caution).

# torqueCars.catalog Every car kind and swappable part as data: `kinds` (12, with dimensions, mass, suspension, drive layout, final drive, brakes, drag area, default parts and camera mounts), `engines` (9 torque curves with idle/redline/limiter, turbo share and lag, voice), `gearboxes` (5), `diffs` (3), `tyres` (8 grip curves with per-surface affinity), `paints` (12). Helpers: `part(slot, name, kind)`, `kind(name)`, `torqueAt(engine, rpm)`, `peakHp(engine)`. Read by `assemble`, `Car` and `Garage`; add an entry to add a car or part. ```luau local Catalog = require("torqueCars.catalog") print(Catalog.kinds.muscle.label, math.floor(Catalog.peakHp(Catalog.engines.v8)), "hp") ```

# engineVoices **engineVoices** gives cars their sound: eight engine voices that follow the revs from idle to limiter and how hard the engine is working, plus gear changes you can hear, a rev-limiter stutter, turbo spool and blow-off, overrun pops, tyre skids that change with the surface, and crash crunches. Every sound is spatial and Doppler-shifted, so a car passing you drops in pitch. The values that drive it replicate, so every player hears every car. It reads only the shared driving contract: the `car.*` named values on a car's chassis entity (`torqueCars` writes them, and so can any other car). Install it, put an `EngineVoice` on the chassis, and the car has a voice. ## Quick start Paste this into any script that runs in play, such as a scene's `entrypoint.luau`. It needs no car: a stand-in entity writes fake `car.*` values, running through idle, a full-throttle pull through the gears, the rev limiter, a lift with pops and blow-off, a slide and a crash, then moves on to the next voice. ```lua local started = false function update(dt) if started then return end local cam = layers.active.camera if not (cam and cam.ready and cam.entity) then return end -- wait for the play camera if audio.listener().count == 0 then cam.entity.component.add("AudioListener") -- the ears end local demo = entity.spawn("demoCar") demo.position = { 0, 1, -12 } demo.component.add("EngineVoiceDemo", { voice = "cycle" }) -- writes car.rpm, car.load, ... demo.component.add("EngineVoice") -- plays them started = true end ``` To hear all eight voices plus a fly-by in one line, use `require("engineVoices.showcase").start()`, or load the `EngineVoicesShowcase` scene in this package. On a real car, put the component on the chassis entity (the one with the car component, which writes the `car.*` values): ```lua local Voices = require("engineVoices.voices") Voices.attach(carChassis) -- voice from the car's car.voiceId Voices.attach(carChassis, "v12") -- or force one Voices.set(carChassis, "rotary") -- switch it live; "auto" goes back to car.voiceId ``` Or set it in the Inspector: `EngineVoice.voice` is one setting. ## The voices | id | name | what it is | |---|---|---| | 1 | `four` | Inline-four buzz: even 180° firing, raspy pipe | | 2 | `v8` | Cross-plane V8: uneven per-bank firing into two different pipes gives the burble, with a lumpy cam at idle and overrun pops | | 3 | `v12` | V12 scream: twelve overlapping pulses, smooth and high-order | | 4 | `diesel` | Turbo-diesel four: low thrum, combustion-knock clatter, turbo whistle | | 5 | `rotary` | Twin-rotor Wankel: needle-sharp pulses, brap-brap at idle, pops | | 6 | `turbo` | Turbo four: exhaust muffled by the turbine, intake whoosh, spool whistle, blow-off on lift, pops | | 7 | `electric` | Motor and gear-mesh whine rising with speed, inverter tone on load, no shift sound | | 8 | `kart` | Two-stroke single: nasal expansion-chamber ring, ring-ding four-stroking at low revs and on overrun | ## How it sounds the way it does - **Engine loops.** Each voice has six seamless one-second loops: three rpm bands, each with an on-load and an off-load take. All 48 were synthesized by `engineVoices.synth` from the engine's own firing pattern, using pressure pulses and combustion noise per cylinder firing, per-cylinder imbalance and jitter, exhaust-pipe resonances per bank, diesel knock, valvetrain ticks and misfires. A loop holds a whole number of engine cycles, so it has no seam. The spectral peak of every loop sits on the engine's firing frequency at the band's rpm, which `Synth.analyze` measures. - **Following the revs.** Each band loop is pitched to `rpm / band rpm` and the bands crossfade at equal power in log-rpm, so the note rises smoothly from idle to limiter without any loop being stretched far from where it was made. - **Following the load.** `car.load` crossfades the on-load take (louder, harsher, more low harmonics) with the off-load take (quieter overrun). Lifting at high rpm on a v8, rotary or turbo fires random exhaust pops. Lifting at boost on the turbo blows off. - **Gear changes.** When `car.shiftCount` changes it plays a manual clunk, a sequential cut-and-bang (with a short ignition cut on the engine layers), or a soft automatic nudge. The style is read from the `Car`'s gearbox, or set with `shiftStyle`. Electric makes no shift sound. The rpm drop itself is heard through the loops. - **Limiter.** While `car.limiter` is true, the on-load layer is chopped at about 16 Hz (the fuel cut), with crackle on the popping voices. - **Turbo.** The whistle's volume and pitch follow `car.boost`. - **Skids.** The skid loop's volume follows `car.skid`, and the loop follows `car.surfaceId`: squeal on tarmac, concrete, cobbles, rumble strips and oil (quieter on wet tarmac and ice), crunch on gravel and dirt, scrub on mud, grass, sand, snow and puddles. - **Crashes.** When `car.impactCount` changes it plays a light tap, a medium crunch or a heavy smash, chosen and scaled by `car.impactSpeed`. ## API - `EngineVoice` component, on the chassis. Fields: `voice` (`auto` or a name), `volume`, `maxDistance`, `shiftStyle`, `skids`, `crashes`, `doppler`. `:mix()` reports the voice, smoothed rpm, load and boost, band weights, on/off-load gains and its source ids. - `engineVoices.voices`: `names()`, `has`, `get`, `nameOf(id)`, `idOf(name)`, `attach(car, voice?, volume?)`, `set(car, voice)`, `detach(car)`, `clips()`, `surface(id)`, `firingHz(voice, rpm)`, `loopName`. - `EngineVoiceDemo` component: a stand-in car that writes the `car.*` values (`voice = "cycle"` or a name, `flyby`, `center`, `distance`, `speed`). - `engineVoices.showcase`: `start(opts?)`, `stop()`. - `engineVoices.synth`: `bakeAll()`, `bakeVoice(name)`, `bakeShared()`, `render(voice, band, onLoad)`, `analyze(clip)`. It re-bakes every clip deterministically after a parameter change. ## Cost Per car: six engine sources, a skid source, a one-shot host, and a whistle or inverter source for the turbo, diesel and electric voices. That is 7 to 8 spatial voices, so 8 cars use about 60 of the mixer's 128. The per-frame script is about 0.04 ms per car, around 0.3 ms for eight. The clips are 32 kHz mono PCM loops, 256 KB resident each. ## Clips The engine loops, turbo whistle, inverter, shift sounds and pops are synthesized. The crash crunches, blow-off and the gravel and soft skid takes were made with the engine's audio generation, and the skid takes were cut into seamless loops. The tarmac squeal comes from soundstage's generated skid take, copied in so this package stands alone. They are all in `clips/`. ## Known limits - **#20654** — a car held at full throttle with assists off can spin its wheels without limit; the voice follows the engine's rpm, so that burnout sits on the limiter chop. - **#20569** — the skid sound follows `car.surfaceId`, which torqueCars works out by ray-casting under its wheels because the wheels do not read the ground's named surfaces yet; a car that writes no `car.surfaceId` gets the tarmac squeal everywhere. - **Doppler and distance** — the pass-by pitch drop is the Doppler shift on the voice's spatial sources (`doppler`, 1 = physical, 0 = off); voices beyond `maxDistance` are silent, and with 8 cars about 60 of the mixer's 128 voices are used, so very large fields will steal voices. - **#21241 / #21242** — nothing of the voice is synced: each peer builds the voice from the car's replicated `car.*` values, so a remote car sounds as its owner drives it. - **#20946** — heard and measured on the native desktop engine only; the web build has not been run.