Sounds Module Reference
Module defined in `lua/vehicle/sounds.lua`. This module interfaces with the game's audio engine to handle impacts, scrapes, wind, tires, and the JBeam soundscape. It also provides a wrapper for manage
Module defined in lua/vehicle/sounds.lua. This module interfaces with the game's audio engine to handle impacts, scrapes, wind, tires, and the JBeam soundscape. It also provides a wrapper for managed sound objects with optimized volume and pitch updates.
See Also
- Props: For visual props that often have associated audio triggers.
- CheatSheet: For common one-shot sound examples.
State Fields
| Variable | Description |
|---|---|
engineNode | CID of the primary node used for engine sound emission. |
refNode | CID of the vehicle's primary reference node. |
objType | Current FMOD spatialization index (0: Player, 1: AI, 2: Traffic). |
usesOldCustomSounds | Boolean flag indicating if the vehicle is using the legacy .sbeam system. |
scrapeLoosenessMap | Table mapping material IDs to surface looseness coefficients (0.0 to 1.0). |
Public API - Managed Sound Objects (soundObj)
Returned by createSoundObj. These objects provide a high-performance interface for looping sounds.
| Function | Signature | Description |
|---|---|---|
sObj:setVolumePitch | (vol, pitch, color, texture) | Updates the sound's parameters. Includes internal delta-checks to prevent redundant C++ calls if values haven't significantly changed. |
sObj:setParameter | (name, value) | Directly sets a named FMOD parameter on the sound source. |
Public API
| Function | Signature | Description |
|---|---|---|
sounds.playSoundOnceAtNode | (name, nodeId, vol, pitch, color, texture) | Triggers a one-shot 3D sound at a fixed world coordinate (the node's position at trigger time). |
sounds.playSoundOnceFollowNode | (name, nodeId, vol, pitch, color, texture) | Triggers a one-shot 3D sound that moves with the specified node. |
sounds.playSoundSkipAI | (handle, volume) | Plays a sound source handle only if the vehicle is being controlled by a player (skips for traffic/background AI). |
sounds.createSoundObj | (file, description, profile, nodeId) | Returns a managed soundObj wrapper around a C++ SFX source. |
sounds.createSoundscapeSound | (name) | Instantiates a sound defined in JBeam metadata. |
sounds.hzToFMODHz | (hz) / FMODHzToHz(fmodHz) | Converts frequency values between standard Hertz and the internal FMOD representation used by the engine. Returns (((fmodHzValue / 100) - (range - 1)) * (fmodtable[range + 1] - fmodtable[range])) + fmodtable[range]. |
sounds.updateCabinFilter | () | Forces an update of the global cabin muffling strength. |
sounds.init | () / reset() | Lifecycle hooks for loading sbeams, identifying nodes, and resetting suspension/tire audio state. |
sounds.updateGFX | (dt) | Primary frame update. Evaluates impacts, wind mapping, suspension stress, and tire surface interactions. |
Public API - Debug & Data
| Function | Signature | Description |
|---|---|---|
sounds.getEngineSoundData | () | Returns detailed configuration tables for all active FMOD engine sound mappings. |
sounds.getBeamSounds | () | Returns the internal table of active per-beam suspension sounds. |
module.setUIDebug | (enabled, data) | todo: save data |
module.bodyCollision | (p) | print((p.slipVel * p.normalForce * 0.001)..','..(p.slipVel * 0.01)..','..(p.normalForce * 0.01)) |
Sensors Module Reference
Module defined in `lua/vehicle/sensors.lua`. Provides real-time physical sensor data (G-forces, angular velocities, orientation) with optional temporal smoothing. Used by AI for driving decisions, by the UI for G-force meters, and by extensions for impact detection and stability monitoring. Reads directly from the C++ physics engine via FFI for maximum performance.
Streams Module Reference
Module defined in `lua/vehicle/guistreams.lua`. Manages the subscription-based data streaming system that feeds real-time vehicle telemetry to UI apps. When a UI app registers interest in a data category (e.g., engine data, wheel thermals), this module evaluates the corresponding handler each frame and sends results via `guihooks`. Prevents wasted computation by only evaluating streams that have active subscribers.