Advanced Train Soundset Base Script

Advanced Declarative Soundset Framework for Transport Fever 3

This mod provides a universal, high-performance audio transformator script designed specifically for Transport Fever 3. It empowers modders to craft deeply realistic, physics-driven vehicle soundscapes using 100% static declarative Lua tables, eliminating the need to write custom per-mod audio scripts or compile code.

It is intended to be used as dependency and called by you own soundsets instead of ::/vehicle/shared/sound/default.script@updateFn

1. Why Does This Script Exist?

Creating rolling stock soundsets across Transport Fever games has historically presented significant hurdles for creators:

• The TF2 Imperative Bottleneck: In Transport Fever 2, vehicle audio was driven by imperative Lua update closures (updateFn(input)). Every single frame, the engine had to call Lua code for every active vehicle. Modders constantly had to copy and paste hundreds of lines of identical math for speed calculations, unit conversions, wheel squeal, and brake sounds. This was error-prone, tedious to maintain, and introduced garbage-collection overhead.
• The TF3 Declarative Shift: Transport Fever 3 overhauled vehicle audio into a declarative system where data() returns static tables processed by an ultra-fast C++ audio backend. However, out-of-the-box TF3 requires modders to either settle for bare-bones linear pitch curves or develop and compile dedicated Teal/C++ transformator scripts for every locomotive class.
• The Lack of Rail Physics in Basic Curves: Real trains do not simply increase volume with speed. Dynamic braking fans roar while speed is dropping, transformers ramp up under heavy electrical load, turbochargers whine according to throttle and engine revolutions, and air compressors cycle on and off at irregular intervals. Standard curve sampling alone cannot produce these behaviors without specialized math.
• The Bi-Mode Dilemma: Dual-mode locomotives and multiple units (such as the SNCF AGC B81500, Stadler FLIRT, or Eurodual) switch between diesel power and electric overhead catenary. Previously, modders had to choose between a pure diesel soundset (playing under wire) or a pure electric soundset (running silent on non-electrified branchlines).
• Audio Bloat from Silence Padding: In earlier games, simulating intermittent equipment like air compressors or air dryers required audio files padded with 2 to 5 minutes of dead silence. This wasted disk space, inflated memory usage, and resulted in identical, synchronized loops across all trains in a fleet.

This sound transformator script solves all these challenges in a single, unified framework. It brings complete rail physics, seamless bi-mode switching, and modular audio behaviors to every modder through clean, readable configuration tables.

2. Key Innovations and Capabilities

• Zero Code Required: Sound designers declare their tracks, events, and update functions in pure Lua tables. The engine executes all calculations natively through the script.
• Automatic Speed Conversion (km/h): Speed curves can be authored directly in real-world kilometers per hour (speedKmh), removing the need for manual speed * 3.6 conversions or normalized 0-to-1 speed ranges.
• Live Bi-Mode Detection and Smooth Blending: The script queries real-time track electrification directly via the vehicle API. When transitioning between electrified and non-electrified tracks, it dynamically crossfades electric traction and diesel audio with a smooth 1.5-second ramp.
• Clean Intermittent Sound Events (No Silence Needed): Short, pristine audio samples (such as a 6-second compressor pump or air dryer burst) can be triggered periodically on a timer with customizable random variance (jitter), ensuring no two trains sound alike.
• Multi-Curve and Dual-Parameter Sampling: Allows multiplying speed curves by throttle (power01) or brake force (brakeDecel) to accurately simulate diesel notches, motor torque harmonics, and coasting conditions.

3. Comprehensive Handler Catalog

Every audio track or event in a soundset is mapped to one of the following specialized handlers:

SampleCurve (Extended)

The core building block for vehicle engines, traction motors, and wheel roll. Beyond standard 2D curves, it provides:

• Dual-Curve Multiplication: Multiply a primary curve (e.g. speed) by a secondary curve (e.g. throttle power01) for multi-notch diesel simulation.
• Operating Conditions: Restrict playback to specific states using condition = "accelOnly", "decelOnly", or "coastOnly".
• Parametric Traction and Braking Floor (minPower): Simulates realistic base power levels during acceleration and dynamic braking, preventing sudden cutoffs when coasting.
• Coasting Dampening (coastingDamp): Smoothly attenuates motor whine or inverter harmonics when throttle is cut and the train is free-wheeling.
• Bi-Mode Selection: Set powerSupply = "electric" or powerSupply = "diesel" to automatically mute or play tracks based on track catenary.

PeriodicTrigger

Periodically triggers one-shot sound events without requiring long audio files padded with silence.

• Configurable repetition interval (interval in seconds).
• Initial startup delay upon train spawn (initialDelay).
• Randomized timing jitter (randomJitter) so parked trains don't cycle in unison.
• Multi-sample support (soundCount): randomly picks from an array of alternate audio variations (e.g. different air release sounds).

ThresholdTrigger

Fires one-shot audio events whenever a telemetry value crosses a specified threshold.

• Monitors speed, throttle, or brake deceleration.
• Configurable trigger direction: rising, falling, or both.
• Perfect for main circuit breaker clacks on startup, air release bursts upon brake release, or warning chimes.

TurboSpeedSqrt

Acoustic model for continuous-load turbochargers (common on modern and classic diesel locomotives like the BB 67400). Modulates compressor whine pitch based on the square root of vehicle speed, dynamically scaled by engine throttle load.

TurboPitchCurve

Acoustic model for stepped-governor diesel turbochargers (such as the CC 72000 series). Uses discrete speed-to-pitch curves matching engine notches, with an automatic idle threshold to mute turbo whine when coasting.

RheostatBlower

Designed for Direct Current (DC) locomotives where rheostat resistor grids are inserted during startup and acceleration to limit motor inrush current, cutting out once full motor coupling is achieved (for instance, the rheostat is totally eliminated around 76–79 km/h on a BB 9200/9300, though this speed threshold will have different values for other engine series). For locomotives equipped with rheostatic dynamic braking (such as the BB 9300), it automatically switches between an acceleration cooling curve and a deceleration braking curve, driving powerful ventilation blowers whenever starting resistors or electrical braking grids are active.

TransfoBlower

Simulates the main cooling blowers of high-voltage transformers and traction converters. Maintains a steady idle ventilation baseline while stationary and automatically ramps up fan volume and pitch under electrical acceleration and regenerative braking load.

Coasting

Models the distinctive mechanical gear whine and transmission hum heard when a train is rolling at speed under zero throttle ("marche sur l'erre"). Automatically attenuates whenever active traction torque or heavy braking is applied.

Squeal

Physics-based wheel flange curve squeal. Uses real-time bogie lateral force (sideForce) and vehicle speed to produce realistic wheel flange shrieks on sharp curves, with customizable sensitivity (sideForceMult) and maximum volume (maxGain).

Brake

Dynamic brake shoe squeal that monitors smoothed deceleration (brakeDecelSmoothed) and fades in during the final meters of stopping before cutting off at a complete standstill.

Clacks

Generates rail joint impacts dynamically based on vehicle gross weight, axle count, travel speed, and game simulation speedup, with configurable reference axle weight.

Chuffs

Specialized steam locomotive exhaust simulation that blends individual slow wheel strokes into continuous high-speed chuffing based on vehicle weight and axle pacing.

Static

Plays continuous ambient loops or one-shot events at fixed gain and pitch, with full support for bi-mode power supply tagging.

Custom

An escape hatch allowing advanced developers to delegate specific track calculations to custom Lua functions while retaining declarative definitions for all other sounds.

None

Simple pass-through handler for standard one-shot events like horns, whistles, and passenger door cycles.

4. Summary of Benefits

• For Players: Unprecedented acoustic fidelity, authentic dual-mode behavior under overhead wires, and organic ambient sounds without repetitive cycles.
• For Modders: Fast workflow, human-readable km/h parameters, no repetitive boilerplate code, and smaller mod file sizes.
• For Performance: Native execution within the C++ audio pipeline with minimal Lua overhead.
• See usage examples inside mod's soundset_usage_examples.md.