Improve Lua API documentation on sounds (#9265)

This commit is contained in:
Wuzzy 2020-01-08 21:27:54 +00:00 committed by Paramat
parent 7c0e0c34ec
commit f4f7c7a11b
2 changed files with 60 additions and 11 deletions

@ -849,24 +849,39 @@ A positional sound will only be heard by players that are within
`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}`
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.
* `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)
* `default_dig_<groupname>`: Default node digging sound
(see node sound definition for details)
Registered definitions
======================
@ -6468,9 +6483,14 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and
-- upon digging. Server will always update actual result shortly.
sound = {
breaks = "default_tool_break", -- tools only
place = <SimpleSoundSpec>,
-- Definition of items sounds to be played at various events.
-- All fields in this table are optional.
breaks = <SimpleSoundSpec>,
-- When tool breaks due to wear. Ignored for non-tools
eat = <SimpleSoundSpec>,
-- When item is eaten with `minetest.do_item_eat`
},
on_place = function(itemstack, placer, pointed_thing),
@ -6679,12 +6699,33 @@ Used by `minetest.register_node`.
-- liquid, flowingliquid drawtypes can only wave like liquids.
sounds = {
-- Definition of node sounds to be played at various events.
-- All fields in this table are optional.
footstep = <SimpleSoundSpec>,
dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
-- If walkable, played when object walks on it. If node is
-- climbable or a liquid, played when object moves through it
dig = <SimpleSoundSpec> or "__group",
-- While digging node.
-- If `"__group"`, then the sound will be
-- `default_dig_<groupname>`, where `<groupname>` is the
-- name of the tool's digging group with the fastest digging time.
-- In case of a tie, one of the sounds will be played (but we
-- cannot predict which one)
-- Default value: `"__group"`
dug = <SimpleSoundSpec>,
-- Node was dug
place = <SimpleSoundSpec>,
-- Node was placed. Also played after falling
place_failed = <SimpleSoundSpec>,
-- When node placement failed
fall = <SimpleSoundSpec>,
-- When node starts to fall
},
drop = "",

@ -244,3 +244,11 @@ Limitations of Async operations
-Limited set of available functions
e.g. No access to functions modifying menu like core.start,core.close,
core.show_path_select_dialog
Background music
----------------
The main menu supports background music.
It looks for a `main_menu` sound in `$USER_PATH/sounds`. The same naming
conventions as for normal sounds apply.
This means the player can add a custom sound.
It will be played in the main menu (gain = 1.0), looped.