mirror of
https://github.com/luanti-org/luanti.git
synced 2025-06-27 16:36:03 +00:00
Sound refactor and improvements (#12764)
This commit is contained in:
DS
GitHub
parent
8e1af25738
commit
edcbfa31c9
52 changed files with 2802 additions and 1211 deletions
197
doc/lua_api.md
197
doc/lua_api.md
|
|
@ -994,16 +994,21 @@ 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
|
||||
Mods should generally prefix their sound files 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.
|
||||
Sound group
|
||||
-----------
|
||||
|
||||
When playing the sound `foomod_foosound`, the sound is chosen randomly
|
||||
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`
|
||||
|
|
@ -1012,62 +1017,10 @@ from the available ones of the following files:
|
|||
* (...)
|
||||
* `foomod_foosound.9.ogg`
|
||||
|
||||
Examples of sound parameter tables:
|
||||
|
||||
```lua
|
||||
-- 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.
|
||||
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
|
||||
|
|
@ -1075,11 +1028,25 @@ 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%)
|
||||
* `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` and `pitch` are optional and default to `1.0`.
|
||||
`gain`, `pitch` and `fade` are optional and default to `1.0`, `1.0` and `0.0`.
|
||||
|
||||
Examples:
|
||||
|
||||
|
|
@ -1090,10 +1057,105 @@ Examples:
|
|||
* `{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
|
||||
-------------------
|
||||
Sound parameter table
|
||||
---------------------
|
||||
|
||||
These sound files are played back by the engine if provided.
|
||||
Table used to specify how a sound is played:
|
||||
|
||||
```lua
|
||||
{
|
||||
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.
|
||||
|
||||
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`.
|
||||
|
||||
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:
|
||||
|
||||
```lua
|
||||
-- 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
|
||||
|
|
@ -8804,7 +8866,10 @@ Used by `minetest.register_node`.
|
|||
|
||||
footstep = <SimpleSoundSpec>,
|
||||
-- If walkable, played when object walks on it. If node is
|
||||
-- climbable or a liquid, played when object moves through it
|
||||
-- climbable or a liquid, played when object moves through it.
|
||||
-- Sound is played at the base of the object's collision-box.
|
||||
-- Gain is multiplied by `0.6`.
|
||||
-- For local player, it's played position-less, with normal gain.
|
||||
|
||||
dig = <SimpleSoundSpec> or "__group",
|
||||
-- While digging node.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue