Sounds.lua

Location

sounds.lua is a file in the Gamedata/ directory of a Spring Game.

Purpose

The file is used to define SoundItems. Beside simply "linking" to an audio file, SoundItems can use various tags to alter the playback of the file.

Source

The engine source code which parses the data from this file is viewable here: rts/System/Sound/SoundItem.cpp

Details

Wherever a sound is played in Spring, be it associated with a UnitDef, WeaponDef or via the lua API, a SoundItem is used. If you access a raw sound file, a SoundItem with the defaults is created for you.

Additionally, multiple SoundItems can use on single file with different settings, this is very efficient, as they only use 1 shared buffer.

Reserved SoundItems

The following SoundItems are reserved for specific engine sounds:

• IncomingChat - Is played when a chat message is received.
• MultiSelect - Is played when multiple units are selected simultaneously.
• MapPoint - Is played when a map point is placed by the player or an ally.
• FailedCommand - Is played when a unit fails to execute a command. e.g. When a unit cannot reach it's destination etc.

SoundItem Properties

• gain - type: float - default: 1.0

This varies the loudness, > 1.0 is louder, < 1.0 is quieter. 0.0 is silent.

• gainmod - type: float - default: 0.0

If > 0.0 then this adds a random amount to gain each time the sound is played. Clamped between 0.0 and 1.0. The result is in the range [(gain * (1 + gainMod)), (gain * (1 - gainMod))].

• pitch - type: float - default: 1.0

Varies the pitch of the sound, > 1.0 is higher pitched, < 1.0 is lower.

• pitchmod - type: float - default: 0.0

If > 0.0 then this adds a random amount to pitch each time the sound is played. Clamped between 0.0 and 1.0. The result is in the range [(pitch * (1 + pitchMod)), (pitch * (1 - pitchMod))].

• dopplerscale - type: float - default: 1.0

How unit and camera speed affects the sound, to exaggerate it, use values > 1.0. Use 0.0 to completely disable the effect.

• priority - type: int - default: 0

When lots of sounds are played, sounds with lower priority are more likely to get cut off. A priority > 0 will never be cut of (priorities can be negative).

• maxconcurrent - type: int - default: 16

How many copies of this sound can be played at once?

• maxdist - type: float - default: FLT_MAX

The cut-off distance (in elmos) at which this sound will no longer be played.

• rolloff - type: float - default: 1.0

How fast the sound becomes quieter with distance. 0.0 means always the same loudness regardless of distance.

• in3d - type: bool - default: true

Non-3d sounds always came out of the front-speakers (or the centre one). 3d sounds are, well, in 3d.

• looptime - type: int - default: 0

The time in milliseconds the sound should loop for.

Example

default sounds

The following is the default sounds.lua supplied in the base content springcontent.sdz archive, with some of the comments removed (As the information is presented here).

local Sounds = {
  SoundItems = {
    IncomingChat = {
      --- always play on the front speaker(s)
      file = "sounds/beep4.wav",
      in3d = "false",
    },
    MultiSelect = {
      --- always play on the front speaker(s)
      file = "sounds/button9.wav",
      in3d = "false",
    },
    MapPoint = {
      --- respect where the point was set, but don't attenuate in distance
      --- also, when moving the camera, don't pitch it
      file = "sounds/beep6.wav",
      rolloff = 0,
      dopplerscale = 0,
    },
    ExampleSound = {
      --- some things you can do with this file
      --- can be either ogg or wav
      file = "somedir/subdir/soundfile.ogg",
      gain = 1,
      pitch = 1,
      dopplerscale = 1,
      priority = 0,
      maxconcurrent = 16,
      maxdist = 20000,
      rolloff = 1,
      in3d = true,
      looptime = 0,
    },
  },
}

return Sounds

External Examples

cont/base/springcontent/gamedata/sounds.lua - The original default sounds.lua

ZeroK sounds.lua

Further Reading

Information about sounds.lua Information about gainMod and pitchMod