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 sound files with modname_, e.g. given the mod name "foomod", a sound could be called:

foomod_foosound.ogg

Sound group

A sound group is the set of all sound files, whose filenames are of the following format: <sound-group name>[.<single digit>].ogg When a sound-group is played, one the files in the group is chosen at random. Sound files can only be referred to by their sound-group name.

Example: 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

SimpleSoundSpec

Specifies a sound name, gain (=volume), pitch and fade. 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-group name. If == "", no sound is played.
  • gain: Volume (1.0 = 100%), must be non-negative. At the end, OpenAL clamps sound gain to a maximum of 1.0. By setting gain for a positional sound higher than 1.0, one can increase the radius inside which maximal gain is reached. Furthermore, gain of positional sounds doesn't increase inside a 1 node radius. The gain given here describes the gain at a distance of 3 nodes.
  • pitch: Applies a pitch-shift to the sound. Each factor of 2.0 results in a pitch-shift of +12 semitones. Must be positive.
  • fade: If > 0.0, the sound is faded in, with this value in gain per second, until gain is reached.

gain, pitch and fade are optional and default to 1.0, 1.0 and 0.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

Sound parameter table

Table used to specify how a sound is played:

{
    gain = 1.0,
    -- Scales the gain specified in `SimpleSoundSpec`.

    pitch = 1.0,
    -- Overwrites the pitch specified in `SimpleSoundSpec`.

    fade = 0.0,
    -- Overwrites the fade specified in `SimpleSoundSpec`.

    start_time = 0.0,
    -- Start with a time-offset into the sound.
    -- The behavior is as if the sound was already playing for this many seconds.
    -- Negative values are relative to the sound's length, so the sound reaches
    -- its end in `-start_time` seconds.
    -- It is unspecified what happens if `loop` is false and `start_time` is
    -- smaller than minus the sound's length.

    -- Available since feature `sound_params_start_time`.

    loop = false,
    -- If true, sound is played in a loop.

    pos = {x = 1, y = 2, z = 3},
    -- Play sound at a position.
    -- Can't be used together with `object`.

    object = <an ObjectRef>,
    -- Attach the sound to an object.
    -- Can't be used together with `pos`.

    -- For backward compatibility, sounds continue playing at the last location
    -- of the object if an object is removed (for example if an entity dies).
    -- It is not recommended to rely on this.
    -- For death sounds, prefer playing a positional sound instead.

    -- If you want to stop a sound when an entity dies or is deactivated,
    -- store the handle and call `minetest.sound_stop` in `on_die` / `on_deactivate`.

    -- Ephemeral sounds are entirely unaffected by the object being removed
    -- or leaving the active object range.

    -- Non-ephemeral sounds stop playing on clients if objects leave
    -- the active object range; they should start playing again if objects
    --- come back into range (but due to a known bug, they don't yet).

    to_player = name,
    -- Only play for this player.
    -- Can't be used together with `exclude_player`.

    exclude_player = name,
    -- Don't play sound for this player.
    -- Can't be used together with `to_player`.

    max_hear_distance = 32,
    -- Only play for players that are at most this far away when the sound
    -- starts playing.
    -- Needs `pos` or `object` to be set.
    -- `32` is the default.
}

Examples:

-- Play locationless on all clients
{
    gain = 1.0,   -- default
    fade = 0.0,   -- default
    pitch = 1.0,  -- default
}
-- Play locationless to one player
{
    to_player = name,
    gain = 1.0,   -- default
    fade = 0.0,   -- default
    pitch = 1.0,  -- default
}
-- Play locationless to one player, looped
{
    to_player = name,
    gain = 1.0,  -- default
    loop = true,
}
-- Play at a location, start the sound at offset 5 seconds
{
    pos = {x = 1, y = 2, z = 3},
    gain = 1.0,  -- default
    max_hear_distance = 32,  -- default
    start_time = 5.0,
}
-- Play connected to an object, looped
{
    object = <an ObjectRef>,
    gain = 1.0,  -- default
    max_hear_distance = 32,  -- default
    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,
}

Special sound-groups

These sound-groups 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)