Sounds

Only Ogg Vorbis files are supported.

For positional playing of sounds, only single-channel (mono) files are supported. Otherwise OpenAL will play them non-positionally.

Mods should generally prefix their sounds with modname_, e.g. given the mod name "foomod", a sound could be called:

foomod_foosound.ogg

Sounds are referred to by their name with a dot, a single digit and the file extension stripped out. When a sound is played, the actual sound file is chosen randomly from the matching sounds.

When playing the sound foomod_foosound, the sound is chosen randomly from the available ones of the following files:

  • foomod_foosound.ogg
  • foomod_foosound.0.ogg
  • foomod_foosound.1.ogg
  • (...)
  • foomod_foosound.9.ogg

Examples of sound parameter tables:

-- Play locationless on all clients
{
    gain = 1.0,   -- default
    fade = 0.0,   -- default, change to a value > 0 to fade the sound in
    pitch = 1.0,  -- default
}
-- Play locationless to one player
{
    to_player = name,
    gain = 1.0,   -- default
    fade = 0.0,   -- default, change to a value > 0 to fade the sound in
    pitch = 1.0,  -- default
}
-- Play locationless to one player, looped
{
    to_player = name,
    gain = 1.0,  -- default
    loop = true,
}
-- Play in a location
{
    pos = {x = 1, y = 2, z = 3},
    gain = 1.0,  -- default
    max_hear_distance = 32,  -- default, uses an euclidean metric
}
-- Play connected to an object, looped
{
    object = <an ObjectRef>,
    gain = 1.0,  -- default
    max_hear_distance = 32,  -- default, uses an euclidean metric
    loop = true,
}

Looped sounds must either be connected to an object or played locationless to one player using to_player = name,.

A positional sound will only be heard by players that are within max_hear_distance of the sound position, at the start of the sound.

SimpleSoundSpec

  • e.g. ""
  • e.g. "default_place_node"
  • e.g. {}
  • e.g. {name = "default_place_node"}
  • e.g. {name = "default_place_node", gain = 1.0}
  • e.g. {name = "default_place_node", gain = 1.0, pitch = 1.0}

Special sound files

These sound files are played back by the engine if provided.

  • main_menu: Looped sound in the main menu (gain = 1.0)
  • player_damage: Played when the local player takes damage (gain = 0.5)
  • player_falling_damage: Played when the local player takes damage by falling (gain = 0.5)