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 one single file with different settings, this is very efficient, as they only use 1 shared buffer.

New in version 89.0: All item names are treated in lowercase.

Tips

You can update & reload your sounddefs at runtime via Spring.LoadSoundDef("gamedata/sounds.lua").

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.
• default - Used for all sounds that aren't listed in sounds.lua.

SoundItem Properties

float gain Default: 1.0  

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

float gainmod 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 = ))].

float pitch Default: 1.0  

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

float pitchmod 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 = ))].

float dopplerscale Default: 1.0  

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

int priority 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).

int maxconcurrent Default: 16  

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

float maxdist Default: MAX_FLOAT  

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

float rolloff Default: 1.0  

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

bool in3d Default: true  

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

int looptime 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,
    },

    -- new since 89.0
    default = {
      gainmod = 0.35,
      pitchmod = 0.3,
      pitch = 0.7,
      in3d = true,
    },
  },
}

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