# 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 **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.