Skip to content
Permalink
Browse files

Improve Lua API documentation on sounds (#9265)

  • Loading branch information
Wuzzy2 authored and paramat committed Jan 8, 2020
1 parent 7c0e0c3 commit f4f7c7a11b74d8102afa6b78822830aea551408a
Showing with 60 additions and 11 deletions.
  1. +52 −11 doc/lua_api.txt
  2. +8 −0 doc/menu_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 = "",
@@ -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.

0 comments on commit f4f7c7a

Please sign in to comment.
You can’t perform that action at this time.