Add sounds mod v1.6...

ContentDB: https://content.minetest.net/packages/AntumDeluge/sounds/
Release: https://github.com/AntumMT/mod-sounds/releases/tag/v1.6

README.md

@@ -15,6 +15,8 @@ The game includes the mods from the default [minetest_game](https://github.com/m
   * [no_fall_damage][] ([MIT][lic.no_fall_damage]) -- version [1.0.0][ver.no_fall_damage] *2020-12-19*
   * [spectator_mode][] ([WTFPL][lic.spectator_mode]) -- version: [3648371 Git][ver.spectator_mode] *2020-07-15*
   * [whitelist][] ([MIT][lic.whitelist]) -- version: [1.1][ver.whitelist] *2021-06-09*
+* audio/
+  * [sounds][] ([MIT][lic.sounds] / [CC BY-SA][lic.ccbysa3.0]) -- version: [1.6][version.sounds] *2021-08-13*
 * buildings/
   * [bridges][] ([GPL][lic.gpl3.0]) -- version: [5b5f475 Git][ver.bridges] *2015-08-23* ([patched][patch.bridges])
   * [christmas][] ([MIT][lic.christmas]) -- version [d3bd872 Git][ver.christmas] *2013-01-11* ([patched][patch.christmas])
@@ -411,6 +413,7 @@ The game includes the mods from the default [minetest_game](https://github.com/m
 [slingshot]: https://github.com/AntumMT/mod-slingshot
 [sneeker]: https://forum.minetest.net/viewtopic.php?t=26685
 [snowdrift]: https://forum.minetest.net/viewtopic.php?t=6854
+[sounds]: https://content.minetest.net/packages/AntumDeluge/sounds/
 [asm_spawneggs]: https://forum.minetest.net/viewtopic.php?t=26676
 [spectator_mode]: https://forum.minetest.net/viewtopic.php?t=13718
 [mobs_monster]: https://content.minetest.net/packages/TenPlus1/mobs_monster/
@@ -511,6 +514,7 @@ The game includes the mods from the default [minetest_game](https://github.com/m
 [lic.snowdrift]: mods/weather/snowdrift/license.txt
 [lic.stone_monster]: mods/mobiles/stone_monster/license.txt
 [lic.asm_spawneggs]: mods/spawning/asm_spawneggs/LICENSE.txt
+[lic.sounds]: mods/audio/sounds/LICENSE.txt
 [lic.spectator_mode]: mods/admin/spectator_mode/LICENSE
 [lic.tools_obsidian]: mods/tools/tools_obsidian/README.md
 [lic.trash_can]: mods/furniture/trash_can/LICENSE.txt
@@ -674,6 +678,7 @@ The game includes the mods from the default [minetest_game](https://github.com/m
 [ver.slingshot]: https://github.com/AntumMT/mod-slingshot/releases/tag/v0.3
 [ver.sneeker]: https://github.com/AntumMT/mod-sneeker/releases/tag/v1.1-1
 [ver.snowdrift]: https://github.com/paramat/snowdrift/tree/3342939
+[ver.sounds]: https://github.com/AntumMT/mod-sounds/releases/tag/v1.6
 [ver.stone_monster]: https://github.com/AntumMT/mod-mob_stone_monster/tree/fa52f6f
 [ver.asm_spawneggs]: https://github.com/AntumMT/mod-asm_spawneggs/releases/tag/v1.2
 [ver.spectator_mode]: https://github.com/minetest-mods/spectator_mode/tree/3648371

mods/audio/sounds/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2021 Jordan Irwin (AntumDeluge)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mods/audio/sounds/README.md

@@ -0,0 +1,132 @@
+## Sound Pack for Minetest
+
+### Description:
+
+A [Minetest][] mod that provides a set of free sounds & methods. It is intended as a more universal method for adding sounds to games rather than depending on [MTG & default][default] for sounds only.
+
+<img src="screenshot.png" alt="icon" width="200" />
+
+### Licensing:
+
+- Code: [MIT](LICENSE.txt)
+- Icon/Screenshot: [CC0](https://openclipart.org/detail/260975)
+- Media: see following table
+
+#### Sound file sources & licensing:<a name="sources" />
+
+See [sources.md](sources.md)
+
+### Usage:
+
+#### Replacement for default:
+
+If your mod depends on *default* for node sounds only, then you can easily switch to *sounds*. Simply add *default* & *sounds* as optional dependencies in your *mod.conf*. *sounds* overrides methods used by *default* to its own. For example *default.node_sound_dirt_defaults*.
+
+Example of overidden method:
+```lua
+function sounds.node_dirt(tbl)
+	tbl = tbl or {}
+
+	tbl.footstep = tbl.footstep or {name="sounds_dirt_step", gain=0.4}
+	tbl.dug = tbl.dug or {name="sounds_dirt_step", gain=1.0}
+	tbl.place = tbl.place or {name="sounds_node_place_soft", gain=1.0}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+default.node_sound_dirt_defaults = sounds.node_dirt
+```
+
+Example of setting node sounds:
+```lua
+minetest.register_node("foo:bar", {
+	description = "Foo Node",
+	sounds = default.node_sound_stone_defaults() -- this is the same as calling `sounds.node_stone()`
+	...
+})
+```
+
+#### Playing Sounds Manually:
+
+`SoundGroup` instances are objects for storing & playing sounds. These objects can be called to play a sound from their group. An index can be specified when called to determine which sound to play. If the index parameter is omitted, a random sound will be picked. A table of arguments can also be passed. This is compatible with [SimpleSoundSpec](https://minetest.gitlab.io/minetest/sounds/#simplesoundspec).
+
+Creating `SoundGroup` objects:
+```lua
+local s_group1 = SoundGroup({"sound1", "sound2"})
+local s_group2 = SoundGroup({"sound3", "sound4", "sound5"})
+
+-- SoundGroup objects can be concatenated with the arithmetic operator
+local s_group3 = s_group1 + s_group2
+
+-- to prevent sound file names from being prefixed with "sounds_" when played, the `no_prepend` field must be set to `true`
+s_group1(2) -- plays "sounds_sound2"
+
+s_group1.no_prepend = true
+s_group1(2) -- plays "sound2"
+```
+
+There are many [pre-defined sound groups](https://antummt.github.io/mod-sounds/reference/latest/topics/groups.html).
+
+Calling a `SoundGroup` object:
+```lua
+-- play random sound from group
+sounds.horse_neigh()
+
+-- play specific sound from group
+sounds.horse_neigh(2)
+
+-- play random sound from group with parameters
+sounds.horse_neigh({gain=1.0})
+
+-- play specific sound from group with parameters
+sounds.horse_neigh(2, {gain=1.0})
+
+-- the `play` method is the same as calling the object directly
+sounds.horse_neigh:play(2, {gain=1.0})
+```
+
+#### Node Sounds:
+
+`SoundGroup` objects can also be used in node registration:
+```lua
+minetest.register_node("foo:bar", {
+	description = "Foo Node",
+	sounds = {
+		dig = sounds.cow_moo, -- a random sound from the `sounds.cow_moo` group will be played when digging this node
+	},
+	...
+```
+
+Currently using `SoundGroup` for node sounds only works for "dig", "dug", & "place".
+
+`SoundGroup` objects are tables & are indexed by integer. But using the `get` method is more reliable as it will return the string name with "sounds_" prefix if `no_prepend` isn't set:
+```lua
+local s_group1 = SoundGroup({"sound1", "sound2"})
+local s1 = s_group1:get(1) -- returns "sounds_sound1"
+local s2 = s_group1[2] -- returns "sound2"
+
+local s_group2 = SoundGroup({"sound3", "sound4", no_prepend=true})
+local s3 = s_group2:get(1) -- returns "sound3"
+local s4 = s_group2[2] -- returns "sound4"
+```
+
+The built-in `type` function can be used to check for a `SoundGroup` instance:
+```lua
+if type(s_group1) == "SoundGroup" then
+	s_group1()
+end
+```
+
+### Links:
+
+- [![ContentDB](https://content.minetest.net/packages/AntumDeluge/sounds/shields/title/)](https://content.minetest.net/packages/AntumDeluge/sounds/)
+- [Forum](https://forum.minetest.net/viewtopic.php?t=26868)
+- [Git repo](https://github.com/AntumMT/mod-sounds)
+- [Reference](https://antummt.github.io/mod-sounds/reference/)
+- [Changelog](changelog.txt)
+- [TODO](TODO.txt)
+
+
+[Minetest]: http://minetest.net/
+[default]: https://github.com/minetest/minetest_game/tree/master/mods/default

mods/audio/sounds/TODO.txt

@@ -0,0 +1,21 @@
+
+TODO:
+- add more methods for playing sounds
+- normalize sound files
+- add ambiance registration for biomes
+- add option to get sound by string name in "SoundGroup:get" using string.match
+- allow SoundGroup arithmetic expression using string
+- create SoundGroup instances for all cached mod sounds
+- fix "node_dug_meta" & "node_place_metal" are the same
+- add more sounds:
+	- hit/damage
+	- tree
+	- airplane
+	- car
+	- motorcycle
+	- train
+	- chalk
+	- generator
+	- horn
+- add sounds from:
+	- cmer

mods/audio/sounds/api.lua

@@ -0,0 +1,253 @@
+
+--- Sounds API
+--
+--  @topic api
+
+
+local failed = {}
+
+
+-- initialize random number generator
+local rand = PcgRandom(os.time())
+
+
+--- Plays a sound.
+--
+--
+--  @function sounds:play
+--  @tparam string name Sound file without .ogg suffix.
+--  @tparam[opt] SoundParams sp Sound parameters.
+--  @treturn int Sound handle or `nil`.
+--  @usage
+--  local handle = sounds:play("sound1", {gain=1.0})
+--  if handle then
+--    print("Sound handle: " .. handle)
+--  end
+sounds.play = function(self, name, sp)
+	local s_type = type(name)
+	if s_type ~= "string" then
+		sounds.log("error", "cannot play non-string type: " .. s_type)
+		return
+	end
+
+	if not sounds.cache[name] then
+		if not failed[name] then
+			failed[name] = true
+			sounds.log("error", "\"" .. name .. "\" not available for playing")
+		end
+
+		return
+	end
+
+	local s_handle = core.sound_play(name, sp)
+
+	-- TODO: register check to see if sound is still playing & remove from "playing" list
+	--playing[s_handle] = name
+
+	return s_handle
+end
+
+
+--- Objects
+--
+--  @section objects
+
+--- Sound Group.
+--
+--  @table SoundGroup
+--  @tfield SoundGroup:count count Retrieves number of available sounds.
+--  @tfield SoundGroup:play play Plays indexed or random sound.
+--  @tfield bool no_prepend If set to `true`, omits prepending "sounds_" to sound filenames when played.
+SoundGroup = {
+	--- Constructor.
+	--
+	--  @function SoundGroup
+	--  @tparam table def Sound definition.
+	--  @treturn SoundGroup Sound group definition table.
+	--  @usage
+	--  -- create new sound groups
+	--  local s_group1 = SoundGroup({"sound1", "sound2"})
+	--  local s_group2 = SoundGroup({"modname_sound1", "modname_sound2", no_prepend=true})
+	--
+	--  -- play sound at index
+	--  s_group1:play(2)
+	--
+	--  -- play random sound from group
+	--  s_group1:play()
+	--
+	--  -- play sound at index with parameters
+	--  s_group1:play(1, {gain=1.0, max_hear_distance=100})
+	--
+	--  -- play random sound with parameters
+	--  s_group1:play({gain=1.0, max_hear_distance=100})
+	--
+	--  -- calling a SoundGroup instance directly is the same as executing the "play" method
+	--  s_group(1, {gain=1.0, max_hear_distance=100})
+	__init = {
+		__call = function(self, def)
+			def = def or {}
+
+			for k, v in pairs(self) do
+				if k ~= "new" and k ~= "__init" and def[k] == nil then
+					def[k] = v
+				end
+			end
+
+			def.__type = "SoundGroup"
+
+			def.__init = {
+				-- execute "play" methode when called directly
+				__call = self.play,
+
+				-- allow arithmetic operation to join groups
+				__add = function(self, g1)
+					local new_group = {}
+					for _, snd in ipairs(self) do
+						table.insert(new_group, snd)
+					end
+					for _, snd in ipairs(g1) do
+						table.insert(new_group, snd)
+					end
+
+					return SoundGroup(new_group)
+				end,
+			}
+			setmetatable(def, def.__init)
+
+			return def
+		end,
+	},
+
+	--- Retrieves number of sounds in group.
+	--
+	--  @function SoundGroup:count
+	--  @treturn int
+	count = function(self)
+		local s_count = 0
+		for _, idx in ipairs(self) do
+			s_count = s_count + 1
+		end
+
+		return s_count
+	end,
+
+	--- Plays a sound from the group.
+	--
+	--  If ***idx*** is not specified, an available sound will be selected
+	--  randomly from the group.
+	--
+	--  @function SoundGroup:play
+	--  @tparam[opt] int idx Sound index.
+	--  @tparam[opt] SoundParams sp Sound parameters.
+	--  @treturn int Sound handle or `nil`.
+	--  @note idx & sp parameters positions can be switched.
+	--  @usage
+	--  local handle = SoundGroup:play(2, {gain=1.0})
+	--  if handle then
+	--    print("Sound handle: " .. handle)
+	--  end
+	play = function(self, idx, sp)
+		local s_count = self:count()
+		if s_count < 1 then
+			sounds.log("error", "no sounds to play")
+			return
+		end
+
+		-- allow second parameter to be sound parameters table
+		if type(idx) == "table" then
+			local sp_old = sp
+			sp = table.copy(idx)
+			idx = sp_old
+			sp_old = nil
+		end
+
+		-- play random
+		if not idx then
+			if s_count == 1 then
+				idx = 1
+			else
+				idx = rand:next(1, s_count)
+			end
+		end
+
+		if type(idx) ~= "number" then
+			print("idx must be a number")
+			return
+		end
+
+		if idx > s_count then
+			sounds.log("error", "sound index " .. idx .. " out of range: max " .. s_count)
+			return
+		end
+
+		local selected = self[idx]
+		if type(selected) == "string" and self.no_prepend ~= true then
+			selected = "sounds_" .. selected
+		end
+
+		return sounds:play(selected, sp)
+	end,
+
+	--- Retrieves random name from group.
+	--
+	--  @function SoundGroup:get_random
+	--  @treturn string
+	get_random = function(self)
+		local name
+		local s_count = self:count()
+		if s_count > 0 then
+			if s_count == 1 then
+				name = self[1]
+			else
+				name = self[rand:next(1, s_count)]
+			end
+
+			if self.no_prepend ~= true then
+				name = "sounds_" .. name
+			end
+		end
+
+		return name
+	end,
+
+	--- Retrieves sounds names in group.
+	--
+	--  If `idx` is supplied, a `string` or `nil` is returned. If
+	--  there is only one sound in the group, the `string` name of
+	--  that sound is returned. Otherwise, a table is returned with
+	--  all sound file names.
+	--
+	--  @function SoundGroup:get
+	--  @tparam[opt] int idx Sound index.
+	--  @return `string` or `table` containing sound file names.
+	get = function(self, idx)
+		local count = self:count()
+		if count == 0 then return end
+
+		local retval
+		if type(idx) == "number" then
+			retval = self[idx]
+		elseif count == 1 then
+			retval = self[1]
+		else
+			retval = {}
+			for _, snd in ipairs(self) do
+				table.insert(retval, snd)
+			end
+		end
+
+		if self.no_prepend ~= true then
+			local rtype = type(retval)
+			if rtype == "string" then
+				retval = "sounds_" .. retval
+			elseif rtype == "table" then
+				for idx, snd in ipairs(retval) do
+					retval[idx] = "sounds_" .. snd
+				end
+			end
+		end
+
+		return retval
+	end,
+}
+setmetatable(SoundGroup, SoundGroup.__init)

mods/audio/sounds/changelog.txt

@@ -0,0 +1,153 @@
+
+v1.6
+----
+- added sounds:
+	- door_close_02
+	- door_close_03
+	- door_knock
+	- door_open
+	- doorbell
+	- fire_crackle
+	- leaves
+	- match_ignite
+	- tool_break
+	- vehicle_motor_idle
+	- vomit
+	- woodpecker_peck
+	- woosh
+
+
+v1.5
+----
+- added sounds:
+	- balloon_inflate
+	- balloon_pop
+	- bicycle_bell
+	- bicycle_horn
+	- bicycle_spokes
+	- cobra
+	- dolphin_chirp
+	- dolphin_click
+	- door_close
+	- door_creak
+	- goose
+	- lamb
+	- laugh_evil
+	- lava_cool
+	- leopard (many)
+	- raccoon_chatter
+	- rain_heavy
+	- rain_light
+	- rain_medium
+	- sea_lion
+	- seagull
+	- seagulls
+	- snake_rattle
+	- squirrel
+	- thunder
+	- whale
+	- wind
+- renamed sounds:
+	- sheep -> sheep_baa
+
+
+v1.4
+----
+- added sounds:
+	- bat
+	- bear
+	- camel
+	- canary
+	- cricket
+	- giraffe_hum
+	- gorilla_grunt
+	- gorilla_roar
+	- gorilla_snarl
+	- monkey
+	- parrot
+	- parrot_chirp
+	- parrot_whistle
+	- peacock_02
+	- penguin
+	- pig_snort
+	- pig_squeal
+	- puppy_bark
+	- toucan
+	- turkey_gobble
+- renamed sounds:
+	- elephant -> elephant_trumpet
+
+
+v1.3
+----
+- pencil sounds split into "pencil_erase" & "pencil_write" groups
+- fixed arithmetic operations on SoundGroup
+- renamed node sound files
+- SoundGroup:play returns handle or nil only
+- using built-in type function on SoundGroup instance will return "SoundGroup"
+- added sounds:
+	- bee
+	- bees
+	- bumble_bee
+	- chicken
+	- clock_tick
+	- coyote_howl
+	- crow_caw
+	- duck_quack
+	- goat_bleat
+	- grasshopper
+	- hyena
+	- jaguar_saw
+	- lion
+	- mouse
+	- owl
+	- peacock
+	- piano
+	- pigeon
+	- tiger_roar
+	- tiger_snarl
+	- undead_moan
+	- vulture
+	- watch_tick
+	- whistle
+	- wolf
+	- yak
+	- zebra
+	- zipper
+
+
+v1.2
+----
+- added API object "SoundGroup" for creating & playing sound groups
+- added sounds:
+	- apple_bite
+	- bird
+	- bounce
+	- cat_meow
+	- coins
+	- cow_moo
+	- dog_bark
+	- elephant
+	- explosion
+	- frog
+	- fuse
+	- gallop
+	- horse_neigh
+	- horse_snort
+	- pencil
+	- quail
+	- rooster
+	- sheep
+	- skeleton_bones
+
+
+v1.1
+----
+- added entity hit sound from default mod
+
+
+v1.0
+----
+- initial release
+- added node sounds from default mod
+- added methods for setting node sounds

mods/audio/sounds/groups.lua

@@ -0,0 +1,430 @@
+
+--- Pre-defined General Sound Groups
+--
+--  @topic groups
+
+
+
+--- Balloon
+--
+--  @section balloon
+
+
+--- @sndgroup sounds.balloon_inflate
+--  @snd balloon_inflate
+sounds.balloon_inflate = SoundGroup({
+	"balloon_inflate",
+})
+
+--- @sndgroup sounds.balloon_pop
+--  @snd balloon_pop
+sounds.balloon_pop = SoundGroup({
+	"balloon_pop",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.balloon_inflate`
+--  - `sounds.balloon_pop`
+--
+--  @sndgroup sounds.balloon
+sounds.balloon = sounds.balloon_inflate + sounds.balloon_pop
+
+
+
+--- Bicycle
+--
+--  @section bicycle
+
+
+--- @sndgroup sounds.bicycle_bell
+--  @snd bicycle_bell
+sounds.bicycle_bell = SoundGroup({
+	"bicycle_bell",
+})
+
+--- @sndgroup sounds.bicycle_horn
+--  @snd bicycle_horn
+sounds.bicycle_horn = SoundGroup({
+	"bicycle_horn",
+})
+
+--- @sndgroup sounds.bicycle_spokes
+--  @snd bicycle_spokes
+sounds.bicycle_spokes = SoundGroup({
+	"bicycle_spokes",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.bicycle_bell`
+--  - `sounds.bicycle_horn`
+--  - `sounds.bicycle_spokes`
+--
+--  @sndgroup sounds.bicycle
+sounds.bicycle = sounds.bicycle_bell + sounds.bicycle_horn + sounds.bicycle_spokes
+
+--- @sndgroup sounds.bite
+--  @snd apple_bite
+sounds.bite = SoundGroup({
+	"apple_bite",
+})
+
+
+
+--- Bounce
+--
+--  @section bounce
+
+
+--- @sndgroup sounds.bounce
+--  @snd boing
+sounds.bounce = SoundGroup({
+	"boing",
+})
+
+
+
+--- Clock
+--
+--  @section clock
+
+
+--- @sndgroup sounds.clock
+--  @snd clock_tick
+sounds.clock = SoundGroup({
+	"clock_tick",
+})
+
+
+
+--- Coin
+--
+--  @section coin
+
+
+--- @sndgroup sounds.coin
+--  @snd coin
+sounds.coin = SoundGroup({
+	"coin",
+})
+
+
+
+--- Door
+--
+--  @section door
+
+
+--- @sndgroup sounds.door_close
+--  @snd door_close_01
+--  @snd door_close_02
+--  @snd door_close_03
+sounds.door_close = SoundGroup({
+	"door_close_01",
+	"door_close_02",
+	"door_close_03",
+})
+
+--- @sndgroup sounds.door_creak
+--  @snd door_creak
+sounds.door_creak = SoundGroup({
+	"door_creak",
+})
+
+--- @sndgroup sounds.door_knock
+--  @snd door_knock_01
+--  @snd door_knock_02
+sounds.door_knock = SoundGroup({
+	"door_knock_01",
+	"door_knock_02",
+})
+
+--- @sndgroup sounds.door_open
+--  @snd door_open
+sounds.door_open = SoundGroup({
+	"door_open",
+})
+
+--- @sndgroup sounds.doorbell
+--  @snd doorbell_01
+--  @snd doorbell_02
+--  @snd doorbell_03
+sounds.doorbell = SoundGroup({
+	"doorbell_01",
+	"doorbell_02",
+	"doorbell_03",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.door_close`
+--  - `sounds.door_creak`
+--  - `sounds.door_knock`
+--  - `sounds.door_open`
+--  - `sounds.doorbell`
+--
+--  @sndgroup sounds.door
+sounds.door = sounds.door_close + sounds.door_creak + sounds.door_knock + sounds.door_open
+	+ sounds.doorbell
+
+
+
+--- Entity
+--
+--  @section entity
+
+
+--- @sndgroup sounds.entity_hit
+--  @snd entity_hit
+sounds.entity_hit = SoundGroup({
+	"entity_hit",
+})
+
+
+
+--- Explosion
+--
+--  @section explosion
+
+
+--- @sndgroup sounds.explosion
+--  @snd explosion
+sounds.explosion = SoundGroup({
+	"explosion",
+})
+
+
+
+--- Fire
+--
+--  @section fire
+
+
+--- @sndgroup sounds.fire
+--  @snd fire_crackle (loopable)
+sounds.fire = SoundGroup({
+	"fire_crackle",
+})
+
+
+
+--- Fuse
+--
+--  @section fuse
+
+
+--- @sndgroup sounds.fuse
+--  @snd fuse
+sounds.fuse = SoundGroup({
+	"fuse",
+})
+
+
+
+--- Gallop
+--
+--  @section gallop
+
+
+--- @sndgroup sounds.gallop
+--  @snd gallop_01 (loopable)
+--  @snd gallop_02 (loopable)
+sounds.gallop = SoundGroup({
+	"gallop_01",
+	"gallop_02",
+})
+
+
+
+--- Lava
+--
+--  @section laval
+
+
+--- @sndgroup sounds.lava_cool
+--  @snd[r3] lava_cool
+sounds.lava_cool = SoundGroup({
+	"lava_cool",
+})
+
+
+
+--- Leaves
+--
+--  @section leaves
+
+
+--- @sndgroup sounds.leaves
+--  @snd leaves_01
+--  @snd leaves_02
+sounds.leaves = SoundGroup({
+	"leaves_01",
+	"leaves_02",
+})
+
+
+
+--- Match
+--
+--  @section match
+
+
+--- @sndgroup sounds.match
+--  @snd match_ignite
+sounds.match = SoundGroup({
+	"match_ignite",
+})
+
+
+
+--- Pencil
+--
+--  @section pencil
+
+
+--- @sndgroup sounds.pencil_erase
+--  @snd pencil_erase
+sounds.pencil_erase = SoundGroup({
+ "pencil_erase",
+})
+
+--- @sndgroup sounds.pencil_write
+--  @snd pencil_write
+sounds.pencil_write = SoundGroup({
+	"pencil_write",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.pencil_erase`
+--  - `sounds.pencil_write`.
+--
+--  @sndgroup sounds.pencil
+sounds.pencil = sounds.pencil_erase + sounds.pencil_write
+
+
+
+--- Piano
+--
+--  @section piano
+
+
+--- @sndgroup sounds.piano
+--  @snd piano
+sounds.piano = SoundGroup({
+	"piano",
+})
+
+
+
+--- Tool
+--
+--  @section tool
+
+
+--- @sndgroup sounds.tool_break
+--  @snd[r3] tool_break
+sounds.tool_break = SoundGroup({
+	"tool_break",
+})
+
+
+
+--- Vehicle
+--
+--  @section vehicle
+
+
+--- @sndgroup sounds.vehicle
+--  @snd vehicle_motor_idle (loopable)
+sounds.vehicle = SoundGroup({
+	"vehicle_motor_idle",
+})
+
+
+
+--- Vomit
+--
+--  @section vomit
+
+
+--- @sndgroup sounds.vomit
+--  @snd vomit_01
+--  @snd vomit_02
+--  @snd vomit_03
+--  @snd vomit_04
+--  @snd vomit_05
+sounds.vomit = SoundGroup({
+	"vomit_01",
+	"vomit_02",
+	"vomit_03",
+	"vomit_04",
+	"vomit_05",
+})
+
+
+
+--- Watch
+--
+--  @section watch
+
+
+--- @sndgroup sounds.watch
+--  @snd watch_tick
+sounds.watch = SoundGroup({
+	"watch_tick",
+})
+
+
+
+--- Whistle
+--
+--  @section whistle
+
+
+--- @sndgroup sounds.whistle
+--  @snd whistle
+sounds.whistle = SoundGroup({
+	"whistle",
+})
+
+
+
+--- Woosh
+--
+--  @section woosh
+
+
+--- @sndgroup sounds.woosh
+--  @snd woosh_01
+--  @snd woosh_02
+--  @snd woosh_03
+--  @snd woosh_04
+sounds.woosh = SoundGroup({
+	"woosh_01",
+	"woosh_02",
+	"woosh_03",
+	"woosh_04",
+})
+
+
+
+--- Zipper
+--
+--  @section zipper
+
+
+--- @sndgroup sounds.zipper
+--  @snd zipper
+sounds.zipper = SoundGroup({
+	"zipper",
+})

mods/audio/sounds/groups_animal.lua

@@ -0,0 +1,881 @@
+
+--- Pre-defined Animal Sound Groups
+--
+--  @topic animal_groups
+
+
+
+--- Amphibian
+--
+--  @section amphibian
+
+
+--- @sndgroup sounds.frog
+--  @snd frog
+sounds.frog = SoundGroup({
+	"frog",
+})
+
+
+
+--- Bat
+--
+--  @section bat
+
+
+--- @sndgroup sounds.bat
+--  @snd bat_01
+--  @snd bat_02
+--  @snd bat_03
+sounds.bat = SoundGroup({
+	"bat_01",
+	"bat_02",
+	"bat_03",
+})
+
+
+
+--- Bear
+--
+--  @section bear
+
+
+--- @sndgroup sounds.bear
+--  @snd bear_01
+--  @snd bear_02
+sounds.bear = SoundGroup({
+	"bear_01",
+	"bear_02",
+})
+
+
+
+--- Bovine
+--
+--  @section bovine
+
+
+--- @sndgroup sounds.cow_moo
+--  @snd cow_moo_01
+--  @snd cow_moo_02
+sounds.cow_moo = SoundGroup({
+	"cow_moo_01",
+	"cow_moo_02",
+})
+
+--- @sndgroup sounds.yak
+--  @snd yak (imitation)
+sounds.yak = SoundGroup({
+	"yak",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.cow_moo`
+--  - `sounds.yak`
+--
+--  @sndgroup sounds.bovine
+sounds.bovine = sounds.cow_moo + sounds.yak
+
+
+
+--- Camelid
+--
+--  @section camelid
+
+
+--- @sndgroup sounds.camel
+--  @snd camel_01
+--  @snd camel_02
+sounds.camel = SoundGroup({
+	"camel_01",
+	"camel_02",
+})
+
+
+
+--- Canine
+--
+--  @section canine
+
+
+--- @sndgroup sounds.coyote_howl
+--  @snd coyote_howl
+sounds.coyote_howl = SoundGroup({
+	"coyote_howl",
+})
+
+--- @sndgroup sounds.dog_bark
+--  @snd dog_bark
+sounds.dog_bark = SoundGroup({
+	"dog_bark",
+})
+
+--- @sndgroup sounds.puppy_bark
+--  @snd puppy_bark
+sounds.puppy_bark = SoundGroup({
+	"puppy_bark",
+})
+
+--- <br>
+--
+-- Includes:
+--
+--  - `sounds.dog_bark`
+--  - `sounds.puppy_bark`
+--
+--  @sndgroup sounds.dog
+sounds.dog = sounds.dog_bark + sounds.puppy_bark
+
+--- @sndgroup sounds.hyena
+--  @snd hyena_01
+--  @snd hyena_02
+--  @snd hyena_03
+sounds.hyena = SoundGroup({
+	"hyena_01",
+	"hyena_02",
+	"hyena_03",
+})
+
+--- @sndgroup sounds.wolf_howl
+--  @snd wolf_howl
+sounds.wolf_howl = SoundGroup({
+	"wolf_howl",
+})
+
+--- @sndgroup sounds.wolf_snarl
+--  @snd wolf_snarl
+sounds.wolf_snarl = SoundGroup({
+	"wolf_snarl",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.wolf_howl`
+--  - `sounds.wolf_snarl`
+--
+--  @sndgroup sounds.wolf
+sounds.wolf = sounds.wolf_howl + sounds.wolf_snarl
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.coyote_howl`
+--  - `sounds.dog`
+--  - `sounds.hyena`
+--  - `sounds.wolf`
+--
+--  @sndgroup sounds.canine
+sounds.canine = sounds.coyote_howl + sounds.dog + sounds.hyena + sounds.wolf
+
+
+
+--- Caprine
+--
+--  @section caprine
+
+
+--- @sndgroup sounds.goat_bleat
+--  @snd goat_bleat_01
+--  @snd goat_bleat_02
+--  @snd goat_bleat_03
+sounds.goat_bleat = SoundGroup({
+	"goat_bleat_01",
+	"goat_bleat_02",
+	"goat_bleat_03",
+})
+
+--- @sndgroup sounds.lamb
+--  @snd lamb
+sounds.lamb = SoundGroup({
+	"lamb",
+})
+
+--- @sndgroup sounds.sheep_baa
+--  @snd sheep_baa
+sounds.sheep_baa = SoundGroup({
+	"sheep_baa",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.lamb`
+--  - `sounds.sheep_baa`
+--
+--  @sndgroup sounds.sheep
+sounds.sheep = sounds.lamb + sounds.sheep_baa
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.goat_bleat`
+--  - `sounds.sheep`
+--
+--  @sndgroup sounds.caprine
+sounds.caprine = sounds.goat_bleat + sounds.sheep
+
+
+
+--- Cetacean
+--
+--  @section cetacean
+
+
+--- @sndgroup sounds.dolphin_chirp
+--  @snd dolphin_chirp
+sounds.dolphin_chirp = SoundGroup({
+	"dolphin_chirp",
+})
+
+--- @sndgroup sounds.dolphin_click
+--  @snd dolphin_click
+sounds.dolphin_click = SoundGroup({
+	"dolphin_click",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.dolphin_chirp`
+--  - `sounds.dolphin_click`
+--
+--  @sndgroup sounds.dolphin
+sounds.dolphin = sounds.dolphin_chirp + sounds.dolphin_click
+
+--- @sndgroup sounds.whale
+--  @snd whale
+sounds.whale = SoundGroup({
+	"whale",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.dolphin`
+--  - `sounds.whale`
+--
+--  @sndgroup sounds.cetacean
+sounds.cetacean = sounds.dolphin + sounds.whale
+
+
+
+--- Elephant
+--
+--  @section elephant
+
+
+--- @sndgroup sounds.elephant_trumpet
+--  @snd elephant_trumpet
+sounds.elephant_trumpet = SoundGroup({
+	"elephant_trumpet",
+})
+
+
+
+--- Equine
+--
+--  @section equine
+
+
+--- @sndgroup sounds.horse_neigh
+--  @snd horse_neigh_01
+--  @snd horse_neigh_02
+sounds.horse_neigh = SoundGroup({
+	"horse_neigh_01",
+	"horse_neigh_02",
+})
+
+--- @sndgroup sounds.horse_snort
+--  @snd horse_snort_01
+--  @snd horse_snort_02
+sounds.horse_snort = SoundGroup({
+	"horse_snort_01",
+	"horse_snort_02",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.horse_neigh`
+--  - `sounds.horse_snort`
+--
+--  @sndgroup sounds.horse
+sounds.horse = sounds.horse_neigh + sounds.horse_snort
+
+--- @sndgroup sounds.zebra
+--  @snd zebra
+sounds.zebra = SoundGroup({
+	"zebra",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.horse`
+--  - `sounds.zebra`
+--
+--  @sndgroup sounds.equine
+sounds.equine = sounds.horse + sounds.zebra
+
+
+
+--- Feline
+--
+--  @section feline
+
+
+--- @sndgroup sounds.cat_meow
+--  @snd cat_meow
+sounds.cat_meow = SoundGroup({
+	"cat_meow",
+})
+
+--- @sndgroup sounds.jaguar
+--  @snd jaguar_saw
+sounds.jaguar = SoundGroup({
+	"jaguar_saw",
+})
+
+--- @sndgroup sounds.leopard_growl
+--  @snd leopard_growl_01
+--  @snd leopard_growl_02
+--  @snd leopard_growl_03
+sounds.leopard_growl = SoundGroup({
+	"leopard_growl_01",
+	"leopard_growl_02",
+	"leopard_growl_03",
+})
+
+--- @sndgroup sounds.leopard_roar
+--  @snd leopard_roar_01
+--  @snd leopard_roar_02
+--  @snd leopard_roar_03
+--  @snd leopard_roar_04
+--  @snd leopard_roar_05
+sounds.leopard_roar = SoundGroup({
+	"leopard_roar_01",
+	"leopard_roar_02",
+	"leopard_roar_03",
+	"leopard_roar_04",
+	"leopard_roar_05",
+})
+
+--- @sndgroup sounds.leopard_saw
+--  @snd leopard_saw_01
+--  @snd leopard_saw_02
+--  @snd leopard_saw_03
+sounds.leopard_saw = SoundGroup({
+	"leopard_saw_01",
+	"leopard_saw_02",
+	"leopard_saw_03",
+})
+
+--- @sndgroup sounds.leopard_snarl
+--  @snd leopard_snarl_01
+--  @snd leopard_snarl_02
+sounds.leopard_snarl = SoundGroup({
+	"leopard_snarl_01",
+	"leopard_snarl_02",
+})
+
+--- @sndgroup sounds.leopard_snort
+--  @snd leopard_snort
+sounds.leopard_snort = SoundGroup({
+	"leopard_snort",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.leopard_growl`
+--  - `sounds.leopard_roar`
+--  - `sounds.leopard_saw`
+--  - `sounds.leopard_snarl`
+--  - `sounds.leopard_snort`
+--
+--  @sndgroup sounds.leopard
+sounds.leopard = sounds.leopard_growl + sounds.leopard_roar + sounds.leopard_saw
+	+ sounds.leopard_snarl + sounds.leopard_snort
+
+--- @sndgroup sounds.lion
+--  @snd lion_bellow
+sounds.lion = SoundGroup({
+	"lion_bellow",
+})
+
+--- @sndgroup sounds.tiger
+--  @snd tiger_roar_01
+--  @snd tiger_snarl_01
+--  @snd tiger_snarl_02
+--  @snd tiger_snarl_03
+--  @snd tiger_snarl_04
+sounds.tiger = SoundGroup({
+	"tiger_roar_01",
+	"tiger_snarl_01",
+	"tiger_snarl_02",
+	"tiger_snarl_03",
+	"tiger_snarl_04",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.cat_meow`
+--  - `sounds.jaguar`
+--  - `sounds.lion`
+--  - `sounds.tiger`
+--
+--  @sndgroup sounds.feline
+sounds.feline = sounds.cat_meow + sounds.jaguar + sounds.leopard + sounds.lion
+	+ sounds.tiger
+
+
+
+--- Fowl
+--
+--  @section fowl
+
+
+--- @sndgroup sounds.canary
+--  @snd canary_01
+--  @snd canary_02
+--  @snd canary_03
+sounds.canary = SoundGroup({
+	"canary_01",
+	"canary_02",
+	"canary_03",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.canary`
+--
+--  @sndgroup sounds.bird
+--  @snd bird_01
+--  @snd bird_02
+--  @snd bird_03
+sounds.bird = SoundGroup({
+	"bird_01",
+	"bird_02",
+	"bird_03",
+}) + sounds.canary
+
+--- @sndgroup sounds.chicken
+--  @snd chicken_01
+--  @snd chicken_02
+sounds.chicken = SoundGroup({
+	"chicken_01",
+	"chicken_02",
+})
+
+--- @sndgroup sounds.crow_caw
+--  @snd crow_caw
+sounds.crow_caw = SoundGroup({
+	"crow_caw",
+})
+
+--- @sndgroup sounds.duck_quack
+--  @snd duck_quack
+sounds.duck_quack = SoundGroup({
+	"duck_quack",
+})
+
+--- @sndgroup sounds.goose
+--  @snd goose
+sounds.goose = SoundGroup({
+	"goose",
+})
+
+--- @sndgroup sounds.owl
+--  @snd owl_hoot
+sounds.owl = SoundGroup({
+	"owl_hoot",
+})
+
+--- @sndgroup sounds.parrot_chirp
+--  @snd parrot_chirp
+sounds.parrot_chirp = SoundGroup({
+	"parrot_chirp",
+})
+
+--- @sndgroup sounds.parrot_whistle
+--  @snd parrot_whistle
+sounds.parrot_whistle = SoundGroup({
+	"parrot_whistle",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.parrot_chirp`
+--  - `sounds.parrot_whistle`
+--
+--  @sndgroup sounds.parrot
+--  @snd parrot_01
+--  @snd parrot_02
+--  @snd parrot_03
+sounds.parrot = SoundGroup({
+	"parrot_01",
+	"parrot_02",
+	"parrot_03",
+}) + sounds.parrot_chirp + sounds.parrot_whistle
+
+--- @sndgroup sounds.peacock
+--  @snd peacock_01
+--  @snd peacock_02
+sounds.peacock = SoundGroup({
+	"peacock_01",
+	"peacock_02",
+})
+
+--- @sndgroup sounds.penguin
+--  @snd penguin_01
+--  @snd penguin_02
+sounds.penguin = SoundGroup({
+	"penguin_01",
+	"penguin_02",
+})
+
+--- @sndgroup sounds.pigeon
+--  @snd pigeon
+sounds.pigeon = SoundGroup({
+	"pigeon",
+})
+
+--- @sndgroup sounds.quail
+--  @snd quail
+sounds.quail = SoundGroup({
+	"quail",
+})
+
+--- @sndgroup sounds.rooster
+--  @snd rooster
+sounds.rooster = SoundGroup({
+	"rooster",
+})
+
+--- @sndgroup sounds.seagull
+--  @snd seagull_01
+--  @snd seagull_02
+--  @snd seagulls
+sounds.seagull = SoundGroup({
+	"seagull_01",
+	"seagull_02",
+	"seagulls",
+})
+
+--- @sndgroup sounds.toucan
+--  @snd toucan_01
+--  @snd toucan_02
+--  @snd toucan_03
+sounds.toucan = SoundGroup({
+	"toucan_01",
+	"toucan_02",
+	"toucan_03",
+})
+
+--- @sndgroup sounds.turkey_gobble
+--  @snd turkey_gobble
+sounds.turkey_gobble = SoundGroup({
+	"turkey_gobble",
+})
+
+--- @sndgroup sounds.vulture
+--  @snd vulture (imitation)
+sounds.vulture = SoundGroup({
+	"vulture",
+})
+
+--- @sndgroup sounds.woodpecker
+--  @snd woodpecker_peck
+sounds.woodpecker = SoundGroup({
+	"woodpecker_peck",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.bird`
+--  - `sounds.chicken`
+--  - `sounds.crow_caw`
+--  - `sounds.duck_quack`
+--  - `sounds.goose`
+--  - `sounds.owl`
+--  - `sounds.parrot`
+--  - `sounds.peacock`
+--  - `sounds.penguin`
+--  - `sounds.pigeon`
+--  - `sounds.quail`
+--  - `sounds.rooster`
+--  - `sounds.seagull`
+--  - `sounds.toucan`
+--  - `sounds.turkey_gobble`
+--  - `sounds.vulture`
+--  - `sounds.woodpecker`
+--
+--  @sndgroup sounds.fowl
+sounds.fowl = sounds.bird + sounds.chicken + sounds.crow_caw + sounds.duck_quack
+	+ sounds.goose + sounds.owl + sounds.parrot + sounds.peacock + sounds.penguin
+	+ sounds.pigeon + sounds.quail + sounds.rooster + sounds.seagull + sounds.toucan
+	+ sounds.turkey_gobble + sounds.vulture + sounds.woodpecker
+
+
+
+--- Giraffe
+--
+--  @section giraffe
+
+
+--- @sndgroup sounds.giraffe_hum
+--  @snd giraffe_hum
+sounds.giraffe_hum = SoundGroup({
+	"giraffe_hum",
+})
+
+
+
+--- Insect
+--
+--  @section insect
+
+
+--- @sndgroup sounds.bee
+--  @snd bee
+--  @snd bumble_bee_01
+--  @snd bumble_bee_02
+--  @snd bees
+sounds.bee = SoundGroup({
+	"bee",
+	"bumble_bee_01",
+	"bumble_bee_02",
+	"bees",
+})
+
+--- @sndgroup sounds.cricket
+--  @snd cricket
+sounds.cricket = SoundGroup({
+	"cricket",
+})
+
+--- @sndgroup sounds.grasshopper
+--  @snd grasshopper
+sounds.grasshopper = SoundGroup({
+	"grasshopper",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.bee`
+--  - `sounds.cricket`
+--  - `sounds.grasshopper`
+--
+--  @sndgroup sounds.insect
+sounds.insect = sounds.bee + sounds.cricket + sounds.grasshopper
+
+
+
+--- Pinniped
+--
+--  @section pinniped
+
+
+--- @sndgroup sounds.sea_lion
+--  @snd sea_lion_01
+--  @snd sea_lion_02
+--  @snd sea_lion_03
+sounds.sea_lion = SoundGroup({
+	"sea_lion_01",
+	"sea_lion_02",
+	"sea_lion_03",
+})
+
+
+
+--- Primate
+--
+--  @section primate
+
+
+--- @sndgroup sounds.gorilla_grunt
+--  @snd gorilla_grunt
+sounds.gorilla_grunt = SoundGroup({
+	"gorilla_grunt",
+})
+
+--- @sndgroup sounds.gorilla_roar
+--  @snd gorilla_roar
+sounds.gorilla_roar = SoundGroup({
+	"gorilla_roar",
+})
+
+--- @sndgroup sounds.gorilla_snarl
+--  @snd gorilla_snarl_01
+--  @snd gorilla_snarl_02
+--  @snd gorilla_snarl_03
+--  @snd gorilla_snarl_04
+sounds.gorilla_snarl = SoundGroup({
+	"gorilla_snarl_01",
+	"gorilla_snarl_02",
+	"gorilla_snarl_03",
+	"gorilla_snarl_04",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.gorilla_grunt`
+--  - `sounds.gorilla_roar`
+--  - `sounds.gorilla_snarl`
+--
+--  @sndgroup sounds.gorilla
+sounds.gorilla = sounds.gorilla_grunt + sounds.gorilla_roar + sounds.gorilla_snarl
+
+--- @sndgroup sounds.monkey
+--  @snd monkey_01 (imitation)
+--  @snd monkey_02 (imitation)
+--  @snd monkey_03 (imitation)
+sounds.monkey = SoundGroup({
+	"monkey_01",
+	"monkey_02",
+	"monkey_03",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.gorilla`
+--  - `sounds.monkey`
+--
+--  @sndgroup sounds.primate
+sounds.primate = sounds.gorilla + sounds.monkey
+
+
+
+--- Raccoon
+--
+--  @section raccoon
+
+
+--- @sndgroup sounds.raccoon
+--  @snd raccoon_chatter
+--  @snd raccoon_chatter_baby_01
+--  @snd raccoon_chatter_baby_02
+sounds.raccoon = SoundGroup({
+	"raccoon_chatter",
+	"raccoon_chatter_baby_01",
+	"raccoon_chatter_baby_02",
+})
+
+
+--- Rodent
+--
+--  @section rodent
+
+
+--- @sndgroup sounds.mouse
+--  @snd mouse (imitation)
+sounds.mouse = SoundGroup({
+	"mouse",
+})
+
+--- @sndgroup sounds.squirrel
+--  @snd squirrel_01
+--  @snd squirrel_02
+--  @snd squirrel_03
+sounds.squirrel = SoundGroup({
+	"squirrel_01",
+	"squirrel_02",
+	"squirrel_03",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.mouse`
+--  - `sounds.squirrel`
+--
+--  @sndgroup sounds.rodent
+sounds.rodent = sounds.mouse + sounds.squirrel
+
+
+
+--- Snake
+--
+--  @section snake
+
+
+--- @sndgroup sounds.cobra
+--  @snd cobra_01
+--  @snd cobra_02
+sounds.cobra = SoundGroup({
+	"cobra_01",
+	"cobra_02",
+})
+
+--- @sndgroup sounds.snake_rattle
+--  @snd snake_rattle
+sounds.snake_rattle = SoundGroup({
+	"snake_rattle",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.cobra`
+--  - `sounds.snake_rattle`
+--
+--  @sndgroup sounds.snake
+sounds.snake = sounds.cobra + sounds.snake_rattle
+
+
+
+--- Swine
+--
+--  @section swine
+
+
+--- @sndgroup sounds.pig_snort
+--  @snd pig_snort
+sounds.pig_snort = SoundGroup({
+	"pig_snort",
+})
+
+--- @sndgroup sounds.pig_squeal
+--  @snd pig_squeal
+sounds.pig_squeal = SoundGroup({
+	"pig_squeal",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.pig_snort`
+--  - `sounds.pig_squeal`
+--
+--  @sndgroup sounds.pig
+sounds.pig = sounds.pig_snort + sounds.pig_squeal

mods/audio/sounds/groups_creature.lua

@@ -0,0 +1,54 @@
+
+--- Pre-defined Creature Sound Groups
+--
+--  @topic creature_groups
+
+
+
+--- Undead
+--
+--  @section undead
+
+
+--- @sndgroup sounds.skeleton
+--  @snd skeleton_bones
+sounds.skeleton = SoundGroup({
+	"skeleton_bones",
+})
+
+--- @sndgroup sounds.undead_moan
+--  @snd undead_moan_01
+--  @snd undead_moan_02
+--  @snd undead_moan_03
+--  @snd undead_moan_04
+sounds.undead_moan = SoundGroup({
+	"undead_moan_01",
+	"undead_moan_02",
+	"undead_moan_03",
+	"undead_moan_04",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.skeleton`
+--  - `sounds.undead_moan`
+--
+--  @sndgroup sounds.undead
+sounds.undead = sounds.skeleton + sounds.undead_moan
+
+
+
+--- Misc.
+--
+--  @section misc
+
+
+--- @sndgroup sounds.laugh_evil
+--  @snd laugh_evil_01
+--  @snd laugh_evil_02
+sounds.laugh_evil = SoundGroup({
+	"laugh_evil_01",
+	"laugh_evil_02",
+})

mods/audio/sounds/groups_node.lua

@@ -0,0 +1,115 @@
+
+--- Pre-defined Node Sound Groups
+--
+--  @topic node_groups
+
+
+sounds.node = {
+	dig = {
+		--- @sndgroup sounds.node.dig.choppy
+		--  @snd[r3] node_dig_choppy
+		--  @see node sounds.node_choppy
+		choppy = SoundGroup({"node_dig_choppy"}),
+		--- @sndgroup sounds.node.dig.cracky
+		--  @snd[r3] node_dig_cracky
+		--  @see node sounds.node_cracky
+		cracky = SoundGroup({"node_dig_cracky"}),
+		--- @sndgroup sounds.node.dig.crumbly
+		--  @snd node_dig_crumbly
+		--  @see node sounds.node_crumbly
+		crumbly = SoundGroup({"node_dig_crumbly"}),
+		--- @sndgroup sounds.node.dig.snappy
+		--  @snd node_dig_snappy
+		--  @see node sounds.node_snappy
+		snappy = SoundGroup({"node_dig_snappy"}),
+		--- @sndgroup sounds.node.dig.gravel
+		--  @snd[r2] node_dig_gravel
+		--  @see node sounds.node_gravel
+		gravel = SoundGroup({"node_dig_gravel"}),
+		--- @sndgroup sounds.node.dig.ice
+		--  @snd[r3] node_dig_ice
+		--  @see node sounds.node_ice
+		ice = SoundGroup({"node_dig_ice"}),
+		--- @sndgroup sounds.node.dig.metal
+		--  @snd node_dig_metal
+		--  @see node sounds.node_metal
+		metal = SoundGroup({"node_dig_metal"}),
+	},
+	--- @sndgroup sounds.node.dug
+	--  @snd[r2] node_dug
+	--  @see node sounds.node
+	dug = SoundGroup({"node_dug",
+		--- @sndgroup sounds.node.dug.glass
+		--  @snd[r3] node_dug_glass
+		--  @see node sounds.node_glass
+		glass = SoundGroup({"node_dug_glass"}),
+		--- @sndgroup sounds.node.dug.gravel
+		--  @snd[r3] node_dug_gravel
+		gravel = SoundGroup({"node_dug_gravel"}),
+		--- @sndgroup sounds.node.dug.ice
+		--  @snd node_dug_ice
+		--  @see node sounds.node_ice
+		ice = SoundGroup({"node_dug_ice"}),
+		--- @sndgroup sounds.node.dug.metal
+		--  @snd[r2] node_dug_metal
+		--  @see node sounds.node_metal
+		metal = SoundGroup({"node_dug_metal"}),
+	}),
+	--- @sndgroup sounds.node.place
+	--  @snd[r2] node_place
+	--  @see node sounds.node
+	place = SoundGroup({"node_place",
+		--- @sndgroup sounds.node.place.metal
+		--  @snd[r2] node_place_metal
+		--  @see node sounds.node_metal
+		metal = SoundGroup({"node_place_metal"}),
+		--- @sndgroup sounds.node.place.soft
+		--  @snd[r3] node_place_soft
+		soft = SoundGroup({"node_place_soft"}),
+	}),
+	step = {
+		--- @sndgroup sounds.node.step.dirt
+		--  @snd[r2] node_step_dirt
+		--  @see node sounds.node_dirt
+		dirt = SoundGroup({"node_step_dirt"}),
+		--- @sndgroup sounds.node.step.glass
+		--  @snd node_step_glass
+		--  @see node sounds.node_glass
+		glass = SoundGroup({"node_step_glass"}),
+		--- @sndgroup sounds.node.step.grass
+		--  @snd[r3] node_step_grass
+		--  @see node sounds.node_grass
+		grass = SoundGroup({"node_step_grass"}),
+		--- @sndgroup sounds.node.step.gravel
+		--  @snd[r4] node_step_gravel
+		--  @see node sounds.node_gravel
+		gravel = SoundGroup({"node_step_gravel"}),
+		--- @sndgroup sounds.node.step.hard
+		--  @snd[r3] node_step_hard
+		hard = SoundGroup({"node_step_hard"}),
+		--- @sndgroup sounds.node.step.ice
+		--  @snd[r3] node_step_ice
+		--  @see node sounds.node_ice
+		ice = SoundGroup({"node_step_ice"}),
+		--- @sndgroup sounds.node.step.metal
+		--  @snd[r3] node_step_metal
+		--  @see node sounds.node_metal
+		metal = SoundGroup({"node_step_metal"}),
+		--- @sndgroup sounds.node.step.sand
+		--  @snd[r3] node_step_sand
+		--  @see node sounds.node_sand
+		sand = SoundGroup({"node_step_sand"}),
+		--- @sndgroup sounds.node.step.snow
+		--  @snd[r5] node_step_snow
+		--  @see node sounds.node_snow
+		snow = SoundGroup({"node_step_snow"}),
+		--- @sndgroup sounds.node.step.water
+		--  @snd[r4] node_step_water (**Note:** node\_step\_water.4 is silent)
+		--  @see node sounds.node_water
+		water = SoundGroup({"node_step_water"}),
+		--- @sndgroup sounds.node.step.wood
+		--  @snd[r2] node_step_wood
+		--  @see node sounds.node_wood
+		wood = SoundGroup({"node_step_wood"}),
+	},
+}

mods/audio/sounds/groups_weather.lua

@@ -0,0 +1,53 @@
+
+--- Pre-defined Weather Sound Groups
+--
+--  @topic weather_groups
+
+
+
+--- Rain
+--
+--  @section rain
+
+
+--- @sndgroup sounds.rain
+--  @snd rain_light (loopable)
+--  @snd rain_medium (loopable)
+--  @snd rain_heavy_01 (loopable)
+--  @snd rain_heavy_02 (loopable)
+sounds.rain = SoundGroup({
+	"rain_light",
+	"rain_medium",
+	"rain_heavy_01",
+	"rain_heavy_02",
+})
+
+
+
+--- Thunder
+--
+--  @section thunder
+
+
+--- @sndgroup sounds.thunder
+--  @snd thunder_01
+--  @snd thunder_02
+--  @snd thunder_03
+sounds.thunder = SoundGroup({
+	"thunder_01",
+	"thunder_02",
+	"thunder_03",
+})
+
+
+
+--- Wind
+--
+--  @section wind
+
+
+--- @sndgroup sounds.wind
+--  @snd wind (loopable)
+sounds.wind = SoundGroup({
+	"wind",
+})

mods/audio/sounds/init.lua

@@ -0,0 +1,57 @@
+
+sounds = {}
+sounds.modname = core.get_current_modname()
+sounds.modpath = core.get_modpath(sounds.modname)
+
+sounds.log = function(lvl, msg)
+	if not msg then
+		msg = lvl
+		lvl = nil
+	end
+
+	msg = "[" .. sounds.modname .. "] " .. msg
+
+	if not lvl then
+		core.log(msg)
+	else
+		core.log(lvl, msg)
+	end
+end
+
+
+local scripts = {
+	"override",
+	"api",
+	"groups",
+	"groups_animal",
+	"groups_creature",
+	"groups_node",
+	"groups_weather",
+	"node",
+}
+
+for _, s in ipairs(scripts) do
+	dofile(sounds.modpath .. "/" .. s .. ".lua")
+end
+
+
+-- cache available sound files
+sounds.cache = {}
+core.register_on_mods_loaded(function()
+	sounds.log("action", "caching sound files ...")
+
+	for _, modname in ipairs(core.get_modnames()) do
+		local s_dir = core.get_modpath(modname) .. "/sounds"
+		for _, ogg in ipairs(core.get_dir_list(s_dir, false)) do
+			if ogg:find("%.ogg$") then
+				local basename = ogg:gsub("%.ogg$", "")
+				-- files for playing randomly by core must have suffix trimmed
+				if basename:find("%.[0-9]$") then
+					basename = basename:gsub("%.[0-9]$", "")
+				end
+
+				sounds.cache[basename] = true
+			end
+		end
+	end
+end)

mods/audio/sounds/mod.conf

@@ -0,0 +1,7 @@
+name = sounds
+version = 1.6
+title = Sounds
+description = A set of free sounds & API.
+license = MIT
+author = Jordan Irwin (AntumDeluge)
+optional_depends = default

mods/audio/sounds/node.lua

@@ -0,0 +1,301 @@
+
+--- Node Sounds
+--
+--  @topic node
+
+
+--- General sounds.
+--
+--  Aliased or overridden methods:
+--
+--  - `default.node_sound_defaults`
+--
+--  @function sounds.node
+--  @tparam[opt] table tbl Sound table to update.
+local node_sounds = {
+	__call = function(self, tbl)
+		tbl = tbl or {}
+
+		tbl.footstep = tbl.footstep or {name="", gain=1.0}
+		tbl.dug = tbl.dug or {name="sounds_node_dug", gain=0.25}
+		tbl.place = tbl.place or {name="sounds_node_place", gain=1.0}
+
+		return tbl
+	end,
+}
+setmetatable(sounds.node, node_sounds)
+
+--- Sounds for "choppy" objects & tools.
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_choppy(tbl)
+	tbl = tbl or {}
+
+	tbl.dig = tbl.dig or {name="sounds_node_dig_choppy", gain=0.5}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for "cracky" objects & tools.
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_cracky(tbl)
+	tbl = tbl or {}
+
+	tbl.dig = tbl.dig or {name="sounds_node_dig_cracky", gain=0.5}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for "crumbly" objects & tools.
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_crumbly(tbl)
+	tbl = tbl or {}
+
+	tbl.dig = tbl.dig or {name="sounds_node_dig_crumbly", gain=0.5}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for "snappy" objects & tools.
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_snappy(tbl)
+	tbl = tbl or {}
+
+	tbl.dig = tbl.dig or {name="sounds_node_dig_snappy", gain=0.5}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for dirt-like nodes.
+--
+--  Aliased or overridden methods:
+--
+--  - `default.node_sound_dirt_defaults`
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_dirt(tbl)
+	tbl = tbl or {}
+
+	tbl.footstep = tbl.footstep or {name="sounds_node_step_dirt", gain=0.4}
+	tbl.dug = tbl.dug or {name="sounds_node_step_dirt", gain=1.0}
+	tbl.place = tbl.place or {name="sounds_node_place_soft", gain=1.0}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for glass-like nodes.
+--
+--  Aliased or overridden methods:
+--
+--  - `default.node_sound_glass_defaults`
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_glass(tbl)
+	tbl = tbl or {}
+
+	tbl.footstep = tbl.footstep or {name="sounds_node_step_glass", gain=0.3}
+	tbl.dig = tbl.dig or {name="sounds_node_step_glass", gain=0.5}
+	tbl.dug = tbl.dug or {name="sounds_node_dug_glass", gain=1.0}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for grass-like nodes.
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_grass(tbl)
+	tbl = tbl or {}
+
+	tbl.footstep = tbl.footstep or {name="sounds_node_step_grass", gain=0.25}
+
+	return sounds.node_dirt(tbl)
+end
+
+--- Sounds for gravel-like nodes.
+--
+--  Aliased or overridden methods:
+--
+--  - `default.node_sound_gravel_defaults`
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_gravel(tbl)
+	tbl = tbl or {}
+
+	tbl.footstep = tbl.footstep or {name="sounds_node_step_gravel", gain=0.1}
+	tbl.dig = tbl.dig or {name="sounds_node_dig_gravel", gain=0.35}
+	tbl.dug = tbl.dug or {name="sounds_node_dug_gravel", gain=1.0}
+	tbl.place = tbl.place or {name="sounds_node_place_soft", gain=1.0}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for ice-like nodes.
+--
+--  Aliased or overridden methods:
+--
+--  - `default.node_sound_ice_defaults`
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_ice(tbl)
+	tbl = tbl or {}
+
+	tbl.footstep = tbl.footstep or {name="sounds_node_step_ice", gain=0.3}
+	tbl.dig = tbl.dig or {name="sounds_node_dig_ice", gain=0.5}
+	tbl.dug = tbl.dug or {name="sounds_node_dug_ice", gain=0.5}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for leaf-like nodes.
+--
+--  Aliased or overridden methods:
+--
+--  - `default.node_sound_leaves_defaults`
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_leaves(tbl)
+	tbl = tbl or {}
+
+	tbl.footstep = tbl.footstep or {name="sounds_node_step_grass", gain=0.45}
+	tbl.dug = tbl.dug or {name="sounds_node_step_grass", gain=0.7}
+	tbl.place = tbl.place or {name="sounds_node_place_soft", gain=1.0}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for metal-like nodes.
+--
+--  Aliased or overridden methods:
+--
+--  - `default.node_sound_metal_defaults`
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_metal(tbl)
+	tbl = tbl or {}
+
+	tbl.footstep = tbl.footstep or {name="sounds_node_step_metal", gain=0.4}
+	tbl.dig = tbl.dig or {name="sounds_node_dig_metal", gain=0.5}
+	tbl.dug = tbl.dug or {name="sounds_node_dug_metal", gain=0.5}
+	tbl.place = tbl.place or {name="sounds_node_place_metal", gain=0.5}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for sand-like nodes.
+--
+--  Aliased or overridden methods:
+--
+--  - `default.node_sound_sand_defaults`
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_sand(tbl)
+	tbl = tbl or {}
+
+	tbl.footstep = tbl.footstep or {name="sounds_node_step_sand", gain=0.05}
+	tbl.dug = tbl.dug or {name="sounds_node_step_sand", gain=0.15}
+	tbl.place = tbl.place or {name="sounds_node_place_soft", gain=1.0}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for snow-like nodes.
+--
+--  Aliased or overridden methods:
+--
+--  - `default.node_sound_snow_defaults`
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_snow(tbl)
+	tbl = tbl or {}
+
+	tbl.footstep = tbl.footstep or {name="sounds_node_step_snow", gain=0.2}
+	tbl.dig = tbl.dig or {name="sounds_node_step_snow", gain=0.3}
+	tbl.dug = tbl.dug or {name="sounds_node_step_snow", gain=0.3}
+	tbl.place = tbl.place or {name="sounds_node_place_soft", gain=1.0}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for stone-like nodes.
+--
+--  Aliased or overridden methods:
+--
+--  - `default.node_sound_stone_defaults`
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_stone(tbl)
+	tbl = tbl or {}
+
+	tbl.footstep = tbl.footstep or {name="sounds_node_step_hard", gain=0.3}
+	tbl.dug = tbl.dug or {name="sounds_node_step_hard", gain=1.0}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for water-like nodes.
+--
+--  Aliased or overridden methods:
+--
+--  - `default.node_sound_water_defaults`
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_water(tbl)
+	tbl = tbl or {}
+
+	tbl.footstep = tbl.footstep or {name="sounds_node_step_water", gain=0.2}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+--- Sounds for wood-like nodes.
+--
+--  Aliased or overridden methods:
+--
+--  - `default.node_sound_wood_defaults`
+--
+--  @tparam[opt] table tbl Sound table to update.
+function sounds.node_wood(tbl)
+	tbl = tbl or {}
+
+	tbl.footstep = tbl.footstep or {name="sounds_node_step_wood", gain=0.3}
+	tbl.dug = tbl.dug or {name="sounds_node_step_wood", gain=1.0}
+
+	sounds.node(tbl)
+	return tbl
+end
+
+
+-- compatibility with default mod function
+if not core.global_exists("default") then
+	default = {}
+end
+
+default.node_sound_defaults        = sounds.node
+default.node_sound_dirt_defaults   = sounds.node_dirt
+default.node_sound_glass_defaults  = sounds.node_glass
+default.node_sound_gravel_defaults = sounds.node_gravel
+default.node_sound_ice_defaults    = sounds.node_ice
+default.node_sound_leaves_defaults = sounds.node_leaves
+default.node_sound_metal_defaults  = sounds.node_metal
+default.node_sound_sand_defaults   = sounds.node_sand
+default.node_sound_snow_defaults   = sounds.node_snow
+default.node_sound_stone_defaults  = sounds.node_stone
+default.node_sound_water_defaults  = sounds.node_water
+default.node_sound_wood_defaults   = sounds.node_wood

mods/audio/sounds/override.lua

@@ -0,0 +1,82 @@
+
+-- override built-in type function
+local otype = type
+type = function(obj)
+	local base_type = otype(obj)
+	if base_type == "table" then
+		local meta_type = otype(obj.__type)
+		if meta_type == "string" then
+			return obj.__type
+		elseif meta_type == "function" then
+			return obj:__type()
+		end
+	end
+
+	return base_type
+end
+
+-- override node registration
+local register_node_orig = core.register_node
+core.register_node = function(name, def)
+	if type(def.sounds) == "table" then
+		if type(def.sounds.dig) == "SoundGroup" then
+			local on_punch_orig = def.on_punch
+			local s_group = SoundGroup(def.sounds.dig)
+			def.sounds.dig = "" -- override default sound
+			def.on_punch = function(...)
+				s_group() -- FIXME: should retrieve built-in sound spec
+
+				if type(on_punch_orig) == "function" then
+					return on_punch_orig(...)
+				end
+			end
+		end
+
+		if type(def.sounds.dug) == "SoundGroup" then
+			local on_dig_orig = def.on_dig
+			local s_group = SoundGroup(def.sounds.dug)
+			def.sounds.dug = nil
+			def.on_dig = function(...)
+				s_group()
+
+				if type(on_dig_orig) == "function" then
+					return on_dig_orig(...)
+				end
+
+				core.node_dig(...)
+			end
+		end
+
+		if type(def.sounds.footstep) == "SoundGroup" then
+
+		end
+
+		-- FIXME: should be overridden in register_craftitem
+		if type(def.sounds.place) == "SoundGroup" then
+			local on_place_orig = def.on_place
+			local s_group = SoundGroup(def.sounds.place)
+			def.sounds.place = nil
+			def.on_place = function(stack, ...)
+				s_group()
+
+				if type(on_place_orig) == "function" then
+					return on_place_orig(stack, ...)
+				end
+
+				return core.item_place(stack, ...)
+			end
+		end
+
+		if type(def.sounds.place_failed) == "SoundGroup" then
+			-- FIXME: which callback to override
+			def.sounds.place_failed = def.sounds.place_failed:get_random()
+		end
+
+		if type(def.sounds.fall) == "SoundGroup" then
+			-- FIXME: which callback to override
+			def.sounds.fall = def.sounds.fall:get_random()
+		end
+	end
+
+	return register_node_orig(name, def)
+end