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 at a location
{
    pos = {x = 1, y = 2, z = 3},
    gain = 1.0,  -- default
    max_hear_distance = 32,  -- default, uses a Euclidean metric
}
-- Play connected to an object, looped
{
    object = <an ObjectRef>,
    gain = 1.0,  -- default
    max_hear_distance = 32,  -- default, uses a Euclidean metric
    loop = true,
}
-- Play at a location, heard by anyone *but* the given player
{
    pos = {x = 32, y = 0, z = 100},
    max_hear_distance = 40,
    exclude_player = name,
}

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.

exclude_player = name can be applied to locationless, positional and object- bound sounds to exclude a single player from hearing them.

SimpleSoundSpec¶

Specifies a sound name, gain (=volume) and pitch. This is either a string or a table.

In string form, you just specify the sound name or the empty string for no sound.

Table form has the following fields:

• name: Sound name
• gain: Volume (1.0 = 100%)
• pitch: Pitch (1.0 = 100%)

gain and pitch are optional and default to 1.0.

Examples:

• "": No sound
• {}: No sound
• "default_place_node": Play e.g. default_place_node.ogg
• {name = "default_place_node"}: Same as above
• {name = "default_place_node", gain = 0.5}: 50% volume
• {name = "default_place_node", gain = 0.9, pitch = 1.1}: 90% volume, 110% pitch

Special sound files¶

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

• 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)
• player_jump: Played when the local player jumps
• default_dig_<groupname>: Default node digging sound (gain = 0.5) (see node sound definition for details)