Sounds.lua - beyond-all-reason/springrts_engine_wiki_mirror GitHub Wiki

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:

Data Types

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.

: 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

Examples

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

Using PitchMod to prevent loud explosions

= Taken from this thread by jK:

Explosions can sound louder than intended when they are started in the same simFrame and so are played in sync -> resonance. PitchMod now changes the playback time (e.g. with 0.3 the sounds should have a playback time of 100-130%) and so there isn't a resonance anymore even when the sound is started multiple times in the same simframe.

local files = VFS.DirList("sounds/explosions/")
local t = Sounds.SoundItems
for i=1,#files do
   local fileName = files[i]
   t[fileName] = {
      file     = fileName;
      pitchmod = 0.3;
      gainmod  = 0.2;
      maxconcurrent = 8;
   }
end

External Examples

- The original default sounds.lua

ZeroK sounds.lua