Sound Sets

Sound sets are configuration files that group several sounds together to get an appropriate sound background. This is used e.g. for vehicles. The sound set .lua files are located in the res/config/sound_set/ folder. They need to have a data() function that returns a data struct like below:

function data()
  return {
    tracks = { ... },
    events = { ... },
    updateFn = function (input)
      ...
    end,
  }
end

The sound set data struct has three properties:

• tracks is a list of data pairs with two properties each:
  • name is a reference to a sound file relative to res/audio/effects.
  • refDist is the reference distance to adjust the radius within which a sound can be heard.
• events is a list of event blocks. Each block hast two properties:
  • names is a list of references to sound files relative to res/audio/effects.
  • refDist is the reference distance to adjust the radius within which a sound can be heard.
• updateFn is a function that is used to modify pitch and gain depending on the current ingame situation, e.g. the speed of a vehicle.

Tracks usually are looped sounds, whereas events are only played once per trigger.

To facilitate the creation of these functions, there is a sound setutil that is used in most sound sets. Therefore the effective structure of the sound set files is mostly like this:

local soundsetutil = require "soundsetutil"
 
function data()
  local data = soundsetutil.makeSoundSet()
 
  soundsetutil.addTrackParam01(
    data, "vehicle/tram_old/drive.wav", 18.0,                 
    { { .0, .0 }, { .1, .32 }, ... }, { { .0, 1.0 } }, "speed01" 
  )	
  ...
 
  soundsetutil.addEvent( data, "openDoors", { "vehicle/tram_old/bell.wav" }, 5.0 )
  ...
 
return data
end

The soundsetutil.lua provides a couple of functions that can be used:

The soundsetutil.makeSoundSet() function is the basic function that sets up the internal structure of the soundset for the use of other util functions. It is required to be used before the other functions.

The soundsetutil.addTrack(data, name, refDist, updateFn) function is used to add a track to the sound set. The parameters are:

• data is the reference to the result data struct.
• name is the reference to a sound file relative to res/audio/effects/.
• refDist is the reference distance for the sound radius.
• updateFn is the function that should be used as updateFn for this track.

This function is very generic. More specific functions can be found below.

The soundsetutil.addEvent(data, key, names, refDist, updateFn) function is used to add an event to the sound set. The parameters are:

• data is the reference to the result data struct.
• key is the key that is used as event trigger.
• names is the list of references to sound files relative to res/audio/effects/.
• refDist is the reference distance for the sound radius.
• updateFn is the function that should be used as updateFn for this event.

If there is more than one sound file referenced, one is chosen randomly.

The soundsetutil.addTrackParam01(data, name, refDist, gainCurve, pitchCurve, param01) function is used to add a track to the sound set in dependance of an input parameter of the updateFn. The parameters are:

• data is the reference to the result data struct.
• name is the reference to a sound file relative to res/audio/effects/.
• refDist is the reference distance for the sound radius.
• gainCurve is a list of {<input value>, <gain value>} pairs. Values between are interpolated, the lowest value is used for all input values below and the highest value is used for all input values above.
• pitchCurve is a list of {<input value>, <pitch value>} pairs. Values between are interpolated, the lowest value is used for all input values below and the highest value is used for all input values above.
• param01 is the key of the updateFn input parameter that is defined to the range between 0 and 1. See below for a full list of available parameters.

The soundsetutil.addSimpleTrackParam01(data, name, refDist, param01) function is a simplified version of the function above. Pitch is constant at level 1, while gain is equal to the input value. The parameters are:

• data is the reference to the result data struct.
• name is the reference to a sound file relative to res/audio/effects/.
• refDist is the reference distance for the sound radius.
• param01 is the key of the updateFn input parameter that is defined to the range between 0 and 1. See below for a full list of available parameters.

The soundsetutil.addEventParam01(data, key, names, refDist, gainCurve, pitchCurve, param01) function is used to add an event to the sound set in dependance of an input parameter of the updateFn. The parameters are:

• data is the reference to the result data struct.
• key is the key that is used as event trigger.
• names is the list of references to sound files relative to res/audio/effects/.
• refDist is the reference distance for the sound radius.
• gainCurve is a list of {<input value>, <gain value>} pairs. Values between are interpolated, the lowest value is used for all input values below and the highest value is used for all input values above.
• pitchCurve is a list of {<input value>, <pitch value>} pairs. Values between are interpolated, the lowest value is used for all input values below and the highest value is used for all input values above.
• param01 is the key of the updateFn input parameter that is defined to the range between 0 and 1. See below for a full list of available parameters.

The soundsetutil.addTrackSqueal(data, name, refDist) function is a specialised function to add a track in dependance of the speed and side force. It usually can be heared when a train drives over switches. The parameters are:

• data is the reference to the result data struct.
• name is the reference to a sound file relative to res/audio/effects/.
• refDist is the reference distance for the sound radius.

The soundsetutil.addTrackBrake(data, name, refDist, maxGain) function is a specialised function to add a track in dependance of the speed and brake intensity. It usually can be heared when a vehicle decelerates. The parameters are:

• data is the reference to the result data struct.
• name is the reference to a sound file relative to res/audio/effects/.
• refDist is the reference distance for the sound radius.
• maxGain is the upper limit of the gain curve. Vehicles with modern brake systems often have lower gain limits.

The soundsetutil.addEventClacks(data, names, refDist, axleRefWeight) function is a specialised function to add an event in dependance of the speed, weight and number of axles. It usually can be heared as small clack sounds when a train runs along tracks and the wheels run over imperfect welding seams or screwed track ends. The more weight lasts on an axle, the louder the sounds can be heared. The parameters are:

• data is the reference to the result data struct.
• names is the list of references to sound files relative to res/audio/effects/.
• refDist is the reference distance for the sound radius.
• axleRefWeight is the reference weight that lasts on one axle when the vehicle is fully loaded.

The soundsetutil.makeRoadVehicle2(data, speeds, idle, idleSpeed, idleGain0, drive, driveSpeed, refDist, param01) function is a specialised function to add sounds for a road vehicle. The parameters are:

• data is the reference to the result data struct.
• speeds is a list of three relative speed values in the range between 0 and 1 where the first and second values limit the interval in which the idle sound should be heard loudest and the third one marks the point where the drive sound can be heard and the idle sound is gone.
• idle is the reference to an idle sound file relative to res/audio/effects/.
• idleSpeed is a coefficient for the pitching curve of the idle sound. It usually is 0.075.
• idleGain0is the gain value for the idle sound when the input parameter (most times speed) is zero.
• drive is the reference to a drive sound file relative to res/audio/effects/.
• driveSpeed is a coefficient for the pitching curve of the drive sound. It usually is 0.4.
• refDist is the reference distance for the sound radius.
• param01 is the key of the updateFn input parameter that is defined to the range between 0 and 1. See below for a full list of available parameters.

The soundsetutil.makeSteamTrain(data, idle, fast, tracksRefDist, chuffNames, chuffsRefDist, chuffsFastFreq, refWeight) function is a specialised function to add sounds for a steam engine. The parameters are:

• data is the reference to the result data struct.
• idle is the reference to an idle running sound file relative to res/audio/effects/.
• fast is the reference to a fast running sound file relative to res/audio/effects/.
• tracksRefDist is the reference distance for the looping track sound radius.
• chuffNames is the list of references to chuffing sound files relative to res/audio/effects/.
• chuffRefDist is the reference distance for the chuffing sound radius.
• chuffsFastFreq is a coefficient for the calculation of the gain and pitching curve of the fast running sound.
• refWeight is the reference weight that is used to influence the gain in dependance of the vehicle wait.

Depending on the type of object, there are different parameters available for the updateFn function.

Town Buildings only have the underConstruction parameter that is used to determine if the building currently is under construction. It returns 0 if not under construction, otherwise some values between 0 and 1 depending on the progress.

Stations have some parameters in relation to their size and the waiting cargo items and passengers:

• cargo is the absolute amount of cargo items waiting at the station.
• cargo01 is the relative amount of cargo items waiting at the station between 0 and 1. It is the result of cargo divided by the station capacity.
• crowd is the absolute amount of passengers waiting at the station.
• crowd01 is the relative amount of passengers waiting at the station between 0 and 1. It is the result of crowd divided by the station capacity.
• terminals is the absolute number of terminals in this station.

Industries have two parameters that can be used for the sound configuration:

• level is the current industry level
• production01 is the current relative production in the range between 0 and 1. It is the result of the production amount divided by the production maximum.

Road vehicles have different speed related parameters that can be used for the configuration:

• speed is the absolute speed in meter per second.
• speed01 is the relative speed in the range between 0 and 1. It is the result of speed divided by topSpeed.
• topSpeed is the possible topSpeed of this vehicle in meter per second.

Rail vehicles have a lot of parameters that can be used for more complicated configurations:

• axleRefWeight is the weight that lasts on a single axis when the vehicle is empty.
• brakeDecel is the current deceleration intensity between 0 and 1.
• chuffStep is the distance between two chuff events.
• curveRadius is the radius of the current track section. Negative values are curves turned the other way.
• curveSpeedLimit is the maximum speed limit in the current curve in kilometer per hour.
• gameSpeedUp is the current simulation speed. This is either 1, 2 or 4.
• maxSideForce is the maximum possible side force, usually 2.
• numAxlesis the number of axles of this vehicle.
• power is the maximum power output of the vehicle engines.
• power01 is the relative power output in the range between 0 and 1. It is the result of powerOutput divided by power.
• powerOutput is the current absolute power output.
• sideForce is the current side force between 0 and maxSideForce.
• speed is the absolute speed in meter per second.
• speed01 is the relative speed in the range between 0 and 1. It is the result of speed divided by topSpeed.
• topSpeed is the possible topSpeed of this vehicle in meter per second.
• weight is the current weight of the vehicle.

Ships have some power and speed related parameters that can be used for the configuration of sounds:

• power is the maximum power output of the ship engines.
• power01 is the relative power output in the range between 0 and 1. It is the result of powerOutput divided by power.
• powerOutput is the current absolute power output.
• speed is the absolute speed in meter per second.
• speed01 is the relative speed in the range between 0 and 1. It is the result of speed divided by topSpeed.
• topSpeed is the possible topSpeed of this vehicle in meter per second.

Planes have some power and speed related parameters that can be used for the configuration of sounds:

• power is the maximum power output of the plane engines.
• power01 is the relative power output in the range between 0 and 1. It is the result of powerOutput divided by power.
• powerIdle is the power output when in idle mode.
• powerOutput is the current absolute power output.
• speed is the absolute speed in meter per second.
• speed01 is the relative speed in the range between 0 and 1. It is the result of speed divided by topSpeed.
• topSpeed is the possible topSpeed of this vehicle in meter per second.

Depending on the type of object, there are several keys available for the sound events defined in sound sets: