summaryrefslogtreecommitdiff
path: root/doc/lua_api.txt
diff options
context:
space:
mode:
authorWuzzy <wuzzy2@mail.ru>2020-01-08 21:27:54 +0000
committerParamat <paramat@users.noreply.github.com>2020-01-08 21:27:54 +0000
commitf4f7c7a11b74d8102afa6b78822830aea551408a (patch)
treeff384aca9e80a2af9431bff26988924d9c8f57f8 /doc/lua_api.txt
parent7c0e0c34ecb66e044f59cbab03a4c12fc7838e97 (diff)
downloadminetest-f4f7c7a11b74d8102afa6b78822830aea551408a.tar.gz
minetest-f4f7c7a11b74d8102afa6b78822830aea551408a.tar.bz2
minetest-f4f7c7a11b74d8102afa6b78822830aea551408a.zip
Improve Lua API documentation on sounds (#9265)
Diffstat (limited to 'doc/lua_api.txt')
-rw-r--r--doc/lua_api.txt63
1 files changed, 52 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 = "",