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 namegain
: 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 jumpsdefault_dig_<groupname>
: Default node digging sound (gain = 0.5) (see node sound definition for details)