From f4f7c7a11b74d8102afa6b78822830aea551408a Mon Sep 17 00:00:00 2001
From: Wuzzy <wuzzy2@mail.ru>
Date: Wed, 8 Jan 2020 21:27:54 +0000
Subject: [PATCH] Improve Lua API documentation on sounds (#9265)

---
 doc/lua_api.txt      | 63 ++++++++++++++++++++++++++++++++++++--------
 doc/menu_lua_api.txt |  8 ++++++
 2 files changed, 60 insertions(+), 11 deletions(-)

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 374a774b1..304d913d6 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -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 = "",
diff --git a/doc/menu_lua_api.txt b/doc/menu_lua_api.txt
index cc1e508c3..4861ed0d9 100644
--- a/doc/menu_lua_api.txt
+++ b/doc/menu_lua_api.txt
@@ -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.
-- 
2.25.1