Initial commit (version 0.1-test)

mods/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/sounds/README.md

@@ -0,0 +1,218 @@
+## Sound Pack for Minetest
+
+### Description:
+
+A [Minetest][] mod that provides a set of free sounds & methods.
+
+What is the purpose of this mod? There are four ideas behind `sounds`:
+
+1. It is intended as a more universal method for adding sounds to games rather than depending on [MTG & default][default] for sounds only. It is completely compatible with default sounds. The same methods called in `default` to set node sounds, like `default.node_sound_stone_defaults`, are implemented & it can be installed in parallel. *Section: [Replacement for default](#replacement-for-default)*
+2. It is simply a well of sounds. Many sound files are provided & can be used with [minetest.sound_play](https://minetest.gitlab.io/minetest/minetest-namespace-reference/#sounds) just as normal. There is also a wrapper function, [sounds:play](https://antummt.github.io/mod-sounds/reference/latest/topics/api.html#sounds:play), that does its best to verify that a sound played successfully. If so, it will return a sound handle ID. Otherwise it will return `nil`. A random sound can be played from a list with [sounds:play_random](https://antummt.github.io/mod-sounds/reference/latest/topics/api.html#sounds:play_random). It also caches all loaded mod sounds after server startup in `sounds.cache` table. So sound files can easily be checked for existence. *Section: [Checking for Existing Sounds](#checking-for-existing-sounds)*
+3. It adds callable sound groups that can be used to play specified individual sounds, or a random sound in the group. The benefit to this is that the file naming convention is irrelivent. The only thing that matters is that the sound file is registered with the group. *Section: [Playing Sounds Manually](#playing-sounds-manually)*
+4. Adds an API for setting biome ambiance sounds.
+
+Note that most included sounds have been set with a peak amplitude of -6.0db.
+
+
+<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",
+	-- this is the same as calling `sounds.node_stone()`
+	sounds = default.node_sound_stone_defaults()
+	...
+})
+```
+
+#### 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
+
+-- strings can also be concatenated to group with arithmetic operator
+s_group3 = s_group3 + "sound6"
+
+-- by setting the `prepend` attribute `true`, sound file names will be prepended
+-- with "sounds_" when played or accessed
+s_group1(2) -- plays "sound2"
+
+s_group1.prepend = true
+s_group1(2) -- plays "sounds_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 = {
+		-- a random sound from the `sounds.cow_moo` group will be played when digging this node
+		dig = sounds.cow_moo,
+	},
+	...
+```
+
+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 `prepend` is set:
+```lua
+local s_group1 = SoundGroup({"sound1", "sound2"})
+local s1 = s_group1:get(1) -- returns "sound1"
+local s2 = s_group1[2] -- returns "sound2"
+
+local s_group2 = SoundGroup({"sound3", "sound4", prepend=true})
+local s3 = s_group2:get(1) -- returns "sounds_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
+```
+
+#### Checking for Existing Sounds:
+
+All mod sound files are stored in the global table `sounds.cache` after server startup. Checking if a file exists for playing is simple:
+
+```lua
+if sounds.cache["default_dig_crumbly"] then
+	core.sound_play("default_dig_crumbly")
+end
+```
+
+#### Testing Sounds:
+
+If setting `sounds.enable_tests` is enabled, the chat command `/sounds_tests` can be used to show a formspec for playing & testing sounds.
+
+To test *any* sound, input the sound name in the "Manual play" field & press the corresponding "Play" button. If the sound file exists, it will play & some info will be filled in the "Last played" field.
+
+To test sounds cached in sound groups, select a group in the left column of the "Group play" field. Then select a sound in the right column & press the corresponding "Play" button.
+
+Sounds can be looped by checking the "Loop" box.
+
+#### Biome Ambiance:
+
+A sound group can be registered for playing sounds randomly in a biome with the `sounds:register_biome_sounds` method (`sounds.enable_biome_sounds` must be enabled):
+
+```
+sounds:register_biome_sounds(biome, snds, params)
+- Registers a sound group to be played in a biome.
+- parameters:
+  - biome:  Biome name.
+  - snds:   string, table, or SoundGroup of sounds registered with biome.
+  - params: SimpleSoundSpec parameters (optional).
+```
+
+Example usage:
+```lua
+sounds:register_biome_sounds("grassland", sounds.bird, {gain=0.25})
+```
+
+#### Settings:
+
+```
+sounds.disabled_groups
+- Disables individual built-in sound groups categories. "all" disables all categories.
+- type:    string (comma-separated list)
+- default: empty
+
+sounds.enable_tests
+- Enables sounds testing with sounds_tests chat command.
+- type:    bool
+- default: false
+
+sounds.enable_biome_sounds
+- Enables/Disables ambiance sounds for biomes.
+- type:    bool
+- default: false
+
+sounds.biome_interval
+- Interval between playing biome sounds.
+- type:    int
+- min:     5
+- default: 30
+
+sounds.biome_chance
+- Chance that sound will be played at interval.
+- type:    int
+- min:     0
+- max:     100
+- default: 20
+```
+
+### 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/sounds/TODO.txt

@@ -0,0 +1,10 @@
+
+TODO:
+- allow setting explicit parameters for individual sounds in SoundGroup instances
+- tests:
+	- fix wrong sound selected when changing groups (example: select #2, switch to group with one sound, switch to group with two sounds, press play)
+- set interval & chance for individual biomes
+- allow individual biomes sound groups to be configured in settings
+- add chat commands for playing sounds:
+	- /sounds me <play/loop> <sound> (individuals)
+	- /sounds all <play/loop> <sound> (server admins/plays for all players)

mods/sounds/api.lua

@@ -0,0 +1,340 @@
+
+--- Sounds API
+--
+--  @topic api
+
+
+local failed = {}
+
+
+-- initialize random number generator
+local rand = PcgRandom(os.time())
+
+
+--- Functions
+--
+--  @section functions
+
+
+--- Plays a sound.
+--
+--
+--  @function sounds:play
+--  @tparam string name Sound file without .ogg suffix.
+--  @tparam[opt] SoundParams sp Sound parameters.
+--  @treturn list (`int`) Sound handle or `nil` and (`string`) sound file name.
+--  @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, name
+end
+
+--- Plays a random sound from a list.
+--
+--  @function sounds:play_random
+--  @tparam table snds List of sound names.
+--  @tparam[opt] SoundParams sp Sound parameters.
+sounds.play_random = function(self, snds, sp)
+	if #snds == 0 then
+		return
+	end
+
+	local play_group = table.copy(snds)
+	if type(snds) == "SoundGroup" and snds.prepend == true then
+		for idx, snd in ipairs(play_group) do
+			play_group[idx] = "sounds_" .. snd
+		end
+	end
+
+	return sounds:play(play_group[rand:next(1, #play_group)], sp)
+end
+
+--- Wrapper for core.sound_stop.
+--
+--  @function sounds:stop
+--  @tparam int handle
+sounds.stop = function(self, handle)
+	core.sound_stop(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 prepend If set to `true`, prepends "sounds_" to sound filenames when played or accessed.
+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", prepend=true})
+	--  local s_group2 = SoundGroup({"modname_sound1", "modname_sound2"})
+	--
+	--  -- 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 {}
+			if type(def) == "string" then
+				def = {def}
+			end
+
+			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" method 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
+					if type(g1) == "string" then
+						table.insert(new_group, g1)
+					else
+						for _, snd in ipairs(g1) do
+							table.insert(new_group, snd)
+						end
+					end
+
+					new_group.prepend = self.prepend
+					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
+				return sounds:play_random(self, sp)
+			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.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.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.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)
+
+
+--- Internal Sound Group.
+--
+--  Same as `SoundGroup` but with "prepend" set to "true" by default. Meant for
+--  use with sound files prefixed with "sounds_" only.
+--
+--  @table iSoundGroup
+iSoundGroup = table.copy(SoundGroup)
+setmetatable(iSoundGroup, SoundGroup.__init)
+iSoundGroup.prepend = true
+
+
+--- Functions
+--
+--  @section functions
+
+local biome_sounds = {}
+
+--- Registers sounds to play randomly in biome.
+--
+--  @function sounds:register_biome_sounds
+--  @tparam string biome Biome name.
+--  @param snds Sounds registered with biome. Can be `string`, `table`, or `SoundGroup`.
+--  @tparam[opt] table params Sound parameter table.
+sounds.register_biome_sounds = function(self, biome, snds, params)
+	if not sounds.enable_biome_sounds then
+		sounds.log("warning", "sounds:register_biome_sounds: biome sounds disabled, sounds will not play")
+	end
+
+	biome_sounds[biome] = {group=SoundGroup(snds), params=params}
+end
+
+--- Retrieves sounds for biome.
+--
+--  @function sounds:get_biome_sounds
+--  @tparam[opt] string biome Biome name.
+--  @return `SoundGroup` or `nil`. If biome parameter is `nil`, then all registered biome
+--  sound groups are returned.
+sounds.get_biome_sounds = function(self, biome)
+	if not biome then
+		return biome_sounds
+	end
+
+	return biome_sounds[biome]
+end

mods/sounds/changelog.txt

@@ -0,0 +1,279 @@
+
+v1.12
+----
+- fixed cache value check
+- added sounds:
+	- duck_quack
+	- loon
+	- mermaid_song
+	- robot
+	- toy_squeak
+	- trumpeter_swan
+
+
+v1.11
+-----
+- added setting to enable/disable built-in sound groups
+- added setting to disable individual sound groups categories
+- fixed caching random sounds count
+- SoundGroup can be constructed with string parameter
+- biome sounds can be registered with sounds.register_biome_sounds
+- shortened sounds rain_light, rain_medium, & wind
+- added sounds:
+	- church_bells
+
+
+v1.10.1
+-------
+- deleted sounds:
+	- melee_hit_04
+	- melee_hit_07
+	- melee_hit_08
+	- melee_hit_09
+	- melee_hit_10
+	- melee_hit_11
+	- melee_hit_12
+	- melee_hit_13
+	- melee_hit_14
+	- melee_hit_16
+- renamed sounds:
+	- melee_hit_05 to melee_hit_04
+	- melee_hit_06 to melee_hit_05
+	- melee_hit_15 to melee_hit_06
+
+
+v1.10
+-----
+- added method "sounds:play_random"
+- added "random" play button to tests
+- changed to require "prepend" to prefix sound files with "sounds_"
+- fixed inheriting "prepend" attribute when concatenating SoundGroup instances with arithmetic operator
+- added iSoundGroup object meant for use with sounds prefixed with "sounds_" only
+- fixed length of clock_tick so loops
+- deleted "node_place_metal" sounds duplicates of "node_dug_metal"
+- deleted some of the less useful compound groups
+- renamed sounds:
+	- some "ar_fire sounds" to "ar_burst"
+- added sounds:
+	- ar_burst
+	- cicada
+	- explosion
+	- explosion_distant
+	- explosion_scifi
+	- fireworks
+	- fireworks_pop
+	- fuse_short
+	- ghost
+	- ghost_damage
+	- ghost_death
+	- helicopter
+	- melee_hit
+	- plasma_shot
+	- scrape
+	- shears
+	- zombie_damage
+	- zombie_growl
+
+
+v1.9
+----
+- "sounds:play" now returns handle & sound file name string
+- added "sounds:stop" wrapper function for "core:sound_stop"
+- added setting "sounds.enable_tests"
+- added sounds testing formspec shown with "/sounds_tests" chat command
+- added localization support for sounds testing formspec
+- added Spanish translation for sounds testing formspec
+- added sounds:
+	- ar_fire
+	- fireball
+	- laser
+	- pistol_cock
+	- pistol_fire
+	- pistol_fire_dry
+	- pistol_reload
+	- ricochet
+	- rifle_cock
+	- rifle_fire
+	- rifle_fire_cock
+	- rifle_fire_dry
+	- rifle_small_fire
+	- shotgun_fire_pump
+	- shotgun_pump
+
+
+v1.8
+----
+- strings can be added to SoundGroup via arithmetic operator
+- added sounds:
+	- chalk_screech
+	- chalk_write
+	- compressor_motor
+	- motorbike_idle
+	- tree_creak
+	- vehicle_horn
+
+
+v1.7
+----
+- added sounds:
+	- airplane_prop
+	- car_motor
+	- jet_ambience
+	- jet_flyby
+	- jet_land
+	- train_whistle
+	- zombie_death
+
+
+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/sounds/groups/animal.lua

@@ -0,0 +1,801 @@
+
+--- Pre-defined Animal Sound Groups
+--
+--  @topic animal_groups
+
+
+
+--- Amphibian
+--
+--  @section amphibian
+
+
+--- @sndgroup sounds.frog
+--  @snd frog
+sounds.frog = iSoundGroup({
+	"frog",
+})
+
+
+
+--- Bat
+--
+--  @section bat
+
+
+--- @sndgroup sounds.bat
+--  @snd bat_01
+--  @snd bat_02
+--  @snd bat_03
+sounds.bat = iSoundGroup({
+	"bat_01",
+	"bat_02",
+	"bat_03",
+})
+
+
+
+--- Bear
+--
+--  @section bear
+
+
+--- @sndgroup sounds.bear
+--  @snd bear_01
+--  @snd bear_02
+sounds.bear = iSoundGroup({
+	"bear_01",
+	"bear_02",
+})
+
+
+
+--- Bovine
+--
+--  @section bovine
+
+
+--- @sndgroup sounds.cow_moo
+--  @snd cow_moo_01
+--  @snd cow_moo_02
+sounds.cow_moo = iSoundGroup({
+	"cow_moo_01",
+	"cow_moo_02",
+})
+
+--- @sndgroup sounds.yak
+--  @snd yak (imitation)
+sounds.yak = iSoundGroup({
+	"yak",
+})
+
+
+
+--- Camelid
+--
+--  @section camelid
+
+
+--- @sndgroup sounds.camel
+--  @snd camel_01
+--  @snd camel_02
+sounds.camel = iSoundGroup({
+	"camel_01",
+	"camel_02",
+})
+
+
+
+--- Canine
+--
+--  @section canine
+
+
+--- @sndgroup sounds.coyote_howl
+--  @snd coyote_howl
+sounds.coyote_howl = iSoundGroup({
+	"coyote_howl",
+})
+
+--- @sndgroup sounds.dog_bark
+--  @snd dog_bark
+sounds.dog_bark = iSoundGroup({
+	"dog_bark",
+})
+
+--- @sndgroup sounds.puppy_bark
+--  @snd puppy_bark
+sounds.puppy_bark = iSoundGroup({
+	"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 = iSoundGroup({
+	"hyena_01",
+	"hyena_02",
+	"hyena_03",
+})
+
+--- @sndgroup sounds.wolf_howl
+--  @snd wolf_howl
+sounds.wolf_howl = iSoundGroup({
+	"wolf_howl",
+})
+
+--- @sndgroup sounds.wolf_snarl
+--  @snd wolf_snarl
+sounds.wolf_snarl = iSoundGroup({
+	"wolf_snarl",
+})
+
+
+
+--- Caprine
+--
+--  @section caprine
+
+
+--- @sndgroup sounds.goat_bleat
+--  @snd goat_bleat_01
+--  @snd goat_bleat_02
+--  @snd goat_bleat_03
+sounds.goat_bleat = iSoundGroup({
+	"goat_bleat_01",
+	"goat_bleat_02",
+	"goat_bleat_03",
+})
+
+--- @sndgroup sounds.lamb
+--  @snd lamb
+sounds.lamb = iSoundGroup({
+	"lamb",
+})
+
+--- @sndgroup sounds.sheep_baa
+--  @snd sheep_baa
+sounds.sheep_baa = iSoundGroup({
+	"sheep_baa",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.lamb`
+--  - `sounds.sheep_baa`
+--
+--  @sndgroup sounds.sheep
+sounds.sheep = sounds.lamb + sounds.sheep_baa
+
+
+
+--- Cetacean
+--
+--  @section cetacean
+
+
+--- @sndgroup sounds.dolphin_chirp
+--  @snd dolphin_chirp
+sounds.dolphin_chirp = iSoundGroup({
+	"dolphin_chirp",
+})
+
+--- @sndgroup sounds.dolphin_click
+--  @snd dolphin_click
+sounds.dolphin_click = iSoundGroup({
+	"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 = iSoundGroup({
+	"whale",
+})
+
+
+
+--- Elephant
+--
+--  @section elephant
+
+
+--- @sndgroup sounds.elephant_trumpet
+--  @snd elephant_trumpet
+sounds.elephant_trumpet = iSoundGroup({
+	"elephant_trumpet",
+})
+
+
+
+--- Equine
+--
+--  @section equine
+
+
+--- @sndgroup sounds.horse_neigh
+--  @snd horse_neigh_01
+--  @snd horse_neigh_02
+sounds.horse_neigh = iSoundGroup({
+	"horse_neigh_01",
+	"horse_neigh_02",
+})
+
+--- @sndgroup sounds.horse_snort
+--  @snd horse_snort_01
+--  @snd horse_snort_02
+sounds.horse_snort = iSoundGroup({
+	"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 = iSoundGroup({
+	"zebra",
+})
+
+
+
+--- Feline
+--
+--  @section feline
+
+
+--- @sndgroup sounds.cat_meow
+--  @snd cat_meow
+sounds.cat_meow = iSoundGroup({
+	"cat_meow",
+})
+
+--- @sndgroup sounds.jaguar
+--  @snd jaguar_saw
+sounds.jaguar = iSoundGroup({
+	"jaguar_saw",
+})
+
+--- @sndgroup sounds.leopard_growl
+--  @snd leopard_growl_01
+--  @snd leopard_growl_02
+--  @snd leopard_growl_03
+sounds.leopard_growl = iSoundGroup({
+	"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 = iSoundGroup({
+	"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 = iSoundGroup({
+	"leopard_saw_01",
+	"leopard_saw_02",
+	"leopard_saw_03",
+})
+
+--- @sndgroup sounds.leopard_snarl
+--  @snd leopard_snarl_01
+--  @snd leopard_snarl_02
+sounds.leopard_snarl = iSoundGroup({
+	"leopard_snarl_01",
+	"leopard_snarl_02",
+})
+
+--- @sndgroup sounds.leopard_snort
+--  @snd leopard_snort
+sounds.leopard_snort = iSoundGroup({
+	"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 = iSoundGroup({
+	"lion_bellow",
+})
+
+--- @sndgroup sounds.tiger_roar
+--  @snd tiger_roar_01
+sounds.tiger_roar = iSoundGroup({
+	"tiger_roar_01",
+})
+
+--- @sndgroup sounds.tiger_snarl
+--  @snd tiger_snarl_01
+--  @snd tiger_snarl_02
+--  @snd tiger_snarl_03
+--  @snd tiger_snarl_04
+sounds.tiger_snarl = iSoundGroup({
+	"tiger_snarl_01",
+	"tiger_snarl_02",
+	"tiger_snarl_03",
+	"tiger_snarl_04",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.tiger_roar`
+--  - `sounds.tiger_snarl`
+--
+--  @sndgroup sounds.tiger
+sounds.tiger = sounds.tiger_roar + sounds.tiger_snarl
+
+
+
+--- Fowl
+--
+--  @section fowl
+
+
+--- @sndgroup sounds.canary
+--  @snd canary_01
+--  @snd canary_02
+--  @snd canary_03
+sounds.canary = iSoundGroup({
+	"canary_01",
+	"canary_02",
+	"canary_03",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.canary`
+--
+--  @sndgroup sounds.bird
+--  @snd bird_01
+--  @snd bird_02
+--  @snd bird_03
+sounds.bird = iSoundGroup({
+	"bird_01",
+	"bird_02",
+	"bird_03",
+}) + sounds.canary
+
+--- @sndgroup sounds.chicken
+--  @snd chicken_01
+--  @snd chicken_02
+sounds.chicken = iSoundGroup({
+	"chicken_01",
+	"chicken_02",
+})
+
+--- @sndgroup sounds.crow_caw
+--  @snd crow_caw
+sounds.crow_caw = iSoundGroup({
+	"crow_caw",
+})
+
+--- @sndgroup sounds.duck_quack
+--  @snd duck_quack_01
+--  @snd duck_quack_02
+--  @snd duck_quack_03
+sounds.duck_quack = iSoundGroup({
+	"duck_quack_01",
+	"duck_quack_02",
+	"duck_quack_03",
+})
+
+--- @sndgroup sounds.goose
+--  @snd goose
+sounds.goose = iSoundGroup({
+	"goose",
+})
+
+--- @sndgroup sounds.loon
+--  @snd loon_01
+--  @snd loon_02
+--  @snd loon_03
+sounds.loon = iSoundGroup({
+	"loon_01",
+	"loon_02",
+	"loon_03",
+})
+
+--- @sndgroup sounds.owl
+--  @snd owl_hoot
+sounds.owl = iSoundGroup({
+	"owl_hoot",
+})
+
+--- @sndgroup sounds.parrot_chirp
+--  @snd parrot_chirp
+sounds.parrot_chirp = iSoundGroup({
+	"parrot_chirp",
+})
+
+--- @sndgroup sounds.parrot_whistle
+--  @snd parrot_whistle
+sounds.parrot_whistle = iSoundGroup({
+	"parrot_whistle",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.parrot_chirp`
+--  - `sounds.parrot_whistle`
+--
+--  @sndgroup sounds.parrot
+--  @snd parrot_01
+--  @snd parrot_02
+--  @snd parrot_03
+sounds.parrot = iSoundGroup({
+	"parrot_01",
+	"parrot_02",
+	"parrot_03",
+}) + sounds.parrot_chirp + sounds.parrot_whistle
+
+--- @sndgroup sounds.peacock
+--  @snd peacock_01
+--  @snd peacock_02
+sounds.peacock = iSoundGroup({
+	"peacock_01",
+	"peacock_02",
+})
+
+--- @sndgroup sounds.penguin
+--  @snd penguin_01
+--  @snd penguin_02
+sounds.penguin = iSoundGroup({
+	"penguin_01",
+	"penguin_02",
+})
+
+--- @sndgroup sounds.pigeon
+--  @snd pigeon
+sounds.pigeon = iSoundGroup({
+	"pigeon",
+})
+
+--- @sndgroup sounds.quail
+--  @snd quail
+sounds.quail = iSoundGroup({
+	"quail",
+})
+
+--- @sndgroup sounds.rooster
+--  @snd rooster
+sounds.rooster = iSoundGroup({
+	"rooster",
+})
+
+--- @sndgroup sounds.seagull
+--  @snd seagull_01
+--  @snd seagull_02
+--  @snd seagulls
+sounds.seagull = iSoundGroup({
+	"seagull_01",
+	"seagull_02",
+	"seagulls",
+})
+
+--- @sndgroup sounds.toucan
+--  @snd toucan_01
+--  @snd toucan_02
+--  @snd toucan_03
+sounds.toucan = iSoundGroup({
+	"toucan_01",
+	"toucan_02",
+	"toucan_03",
+})
+
+--- @sndgroup sounds.trumpeter_swan
+--  @snd trumpeter_swan
+sounds.trumpeter_swan = iSoundGroup({
+	"trumpeter_swan",
+})
+
+--- @sndgroup sounds.turkey_gobble
+--  @snd turkey_gobble
+sounds.turkey_gobble = iSoundGroup({
+	"turkey_gobble",
+})
+
+--- @sndgroup sounds.vulture
+--  @snd vulture (imitation)
+sounds.vulture = iSoundGroup({
+	"vulture",
+})
+
+--- @sndgroup sounds.woodpecker
+--  @snd woodpecker_peck
+sounds.woodpecker = iSoundGroup({
+	"woodpecker_peck",
+})
+
+
+
+--- Giraffe
+--
+--  @section giraffe
+
+
+--- @sndgroup sounds.giraffe_hum
+--  @snd giraffe_hum
+sounds.giraffe_hum = iSoundGroup({
+	"giraffe_hum",
+})
+
+
+
+--- Insect
+--
+--  @section insect
+
+
+--- @sndgroup sounds.bee
+--  @snd bee (loopable)
+--  @snd bumble_bee_01 (loopable)
+--  @snd bumble_bee_02
+--  @snd bees (loopable)
+sounds.bee = iSoundGroup({
+	"bee",
+	"bumble_bee_01",
+	"bumble_bee_02",
+	"bees",
+})
+
+--- @sndgroup sounds.cicada
+--  @snd cicada_01 (loopable)
+--  @snd cicada_02 (loopable)
+--  @snd cicada_03 (loopable)
+--  @snd cicada_04 (loopable)
+--  @snd cicada_05 (loopable)
+--  @snd cicada_06 (loopable)
+--  @snd cicada_07 (loopable)
+--  @snd cicada_08 (loopable)
+sounds.cicada = iSoundGroup({
+	"cicada_01",
+	"cicada_02",
+	"cicada_03",
+	"cicada_04",
+	"cicada_05",
+	"cicada_06",
+	"cicada_07",
+	"cicada_08",
+})
+
+--- @sndgroup sounds.cricket
+--  @snd cricket (loopable)
+sounds.cricket = iSoundGroup({
+	"cricket",
+})
+
+--- @sndgroup sounds.grasshopper
+--  @snd grasshopper
+sounds.grasshopper = iSoundGroup({
+	"grasshopper",
+})
+
+
+
+--- Pinniped
+--
+--  @section pinniped
+
+
+--- @sndgroup sounds.sea_lion
+--  @snd sea_lion_01
+--  @snd sea_lion_02
+--  @snd sea_lion_03
+sounds.sea_lion = iSoundGroup({
+	"sea_lion_01",
+	"sea_lion_02",
+	"sea_lion_03",
+})
+
+
+
+--- Primate
+--
+--  @section primate
+
+
+--- @sndgroup sounds.gorilla_grunt
+--  @snd gorilla_grunt
+sounds.gorilla_grunt = iSoundGroup({
+	"gorilla_grunt",
+})
+
+--- @sndgroup sounds.gorilla_roar
+--  @snd gorilla_roar
+sounds.gorilla_roar = iSoundGroup({
+	"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 = iSoundGroup({
+	"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 = iSoundGroup({
+	"monkey_01",
+	"monkey_02",
+	"monkey_03",
+})
+
+
+
+--- Raccoon
+--
+--  @section raccoon
+
+
+--- @sndgroup sounds.raccoon
+--  @snd raccoon_chatter
+--  @snd raccoon_chatter_baby_01
+--  @snd raccoon_chatter_baby_02
+sounds.raccoon = iSoundGroup({
+	"raccoon_chatter",
+	"raccoon_chatter_baby_01",
+	"raccoon_chatter_baby_02",
+})
+
+
+--- Rodent
+--
+--  @section rodent
+
+
+--- @sndgroup sounds.mouse
+--  @snd mouse (imitation)
+sounds.mouse = iSoundGroup({
+	"mouse",
+})
+
+--- @sndgroup sounds.squirrel
+--  @snd squirrel_01
+--  @snd squirrel_02
+--  @snd squirrel_03
+sounds.squirrel = iSoundGroup({
+	"squirrel_01",
+	"squirrel_02",
+	"squirrel_03",
+})
+
+
+
+--- Snake
+--
+--  @section snake
+
+
+--- @sndgroup sounds.cobra
+--  @snd cobra_01
+--  @snd cobra_02
+sounds.cobra = iSoundGroup({
+	"cobra_01",
+	"cobra_02",
+})
+
+--- @sndgroup sounds.snake_rattle
+--  @snd snake_rattle
+sounds.snake_rattle = iSoundGroup({
+	"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 = iSoundGroup({
+	"pig_snort",
+})
+
+--- @sndgroup sounds.pig_squeal
+--  @snd pig_squeal
+sounds.pig_squeal = iSoundGroup({
+	"pig_squeal",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.pig_snort`
+--  - `sounds.pig_squeal`
+--
+--  @sndgroup sounds.pig
+sounds.pig = sounds.pig_snort + sounds.pig_squeal

mods/sounds/groups/creature.lua

@@ -0,0 +1,129 @@
+
+--- Pre-defined Creature Sound Groups
+--
+--  @topic creature_groups
+
+
+
+--- Ghost
+--
+--  @section ghost
+
+
+--- @sndgroup sounds.ghost
+--  @snd ghost_01
+--  @snd ghost_02
+sounds.ghost = iSoundGroup({
+	"ghost_01",
+	"ghost_02",
+})
+
+--- @sndgroup sounds.ghost_damage
+--  @snd ghost_damage
+sounds.ghost_damage = iSoundGroup({
+	"ghost_damage",
+})
+
+--- @sndgroup sounds.ghost
+--  @snd ghost_death
+sounds.ghost_death = iSoundGroup({
+	"ghost_death",
+})
+
+
+
+--- Mermaid
+--
+--  @section mermaid
+
+
+--- @sndgroup sounds.mermaid_song
+--  @snd mermaid_song_01
+--  @snd mermaid_song_02
+--  @snd mermaid_song_03
+--  @snd mermaid_song_04
+--  @snd mermaid_song_05
+sounds.mermaid_song = iSoundGroup({
+	"mermaid_song_01",
+	"mermaid_song_02",
+	"mermaid_song_03",
+	"mermaid_song_04",
+	"mermaid_song_05",
+})
+
+
+
+--- Robot
+--
+--  @section robot
+
+
+--- @sndgroup sounds.robot
+--  @snd robot_01
+--  @snd robot_02
+sounds.robot = iSoundGroup({
+	"robot_01",
+	"robot_02",
+})
+
+
+
+--- Undead
+--
+--  @section undead
+
+
+--- @sndgroup sounds.skeleton
+--  @snd skeleton_bones
+sounds.skeleton = iSoundGroup({
+	"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 = iSoundGroup({
+	"undead_moan_01",
+	"undead_moan_02",
+	"undead_moan_03",
+	"undead_moan_04",
+})
+
+--- @sndgroup sounds.zombie_damage
+--  @snd zombie_damage
+sounds.zombie_damage = iSoundGroup({
+	"zombie_damage",
+})
+
+--- @sndgroup sounds.zombie_death
+--  @snd zombie_death
+sounds.zombie_death = iSoundGroup({
+	"zombie_death",
+})
+
+--- @sndgroup sounds.zombie_growl
+--  @snd zombie_growl_01
+--  @snd zombie_growl_02
+--  @snd zombie_growl_03
+sounds.zombie_growl = iSoundGroup({
+	"zombie_growl_01",
+	"zombie_growl_02",
+	"zombie_growl_03",
+})
+
+
+
+--- Misc.
+--
+--  @section misc
+
+
+--- @sndgroup sounds.laugh_evil
+--  @snd laugh_evil_01
+--  @snd laugh_evil_02
+sounds.laugh_evil = iSoundGroup({
+	"laugh_evil_01",
+	"laugh_evil_02",
+})

mods/sounds/groups/firearm.lua

@@ -0,0 +1,151 @@
+
+--- Pre-defined Firearm Sound Groups
+--
+--  @topic firearm_groups
+
+
+
+--- Assualt Rifle
+--
+--  @section ar
+
+
+--- @sndgroup sounds.ar_burst
+--  @snd ar_burst_01
+--  @snd ar_burst_02
+--  @snd ar_burst_03
+sounds.ar_burst = iSoundGroup({
+	"ar_burst_01",
+	"ar_burst_02",
+	"ar_burst_03",
+})
+
+--- <br>
+--
+--  Includes:
+--
+--  - `sounds.ar_burst`
+--
+--  @sndgroup sounds.ar_fire
+--  @snd ar_fire_01
+--  @snd ar_fire_02
+sounds.ar_fire = iSoundGroup({
+	"ar_fire_01",
+	"ar_fire_02",
+}) + sounds.ar_burst
+
+
+
+--- Pistol
+--
+--  @section pistol
+
+
+--- @sndgroup sounds.pistol_cock
+--  @snd pistol_cock_01
+--  @snd pistol_cock_02
+--  @snd pistol_cock_03
+sounds.pistol_cock = iSoundGroup({
+	"pistol_cock_01",
+	"pistol_cock_02",
+	"pistol_cock_03",
+})
+
+--- @sndgroup sounds.pistol_fire
+--  @snd pistol_fire_01
+--  @snd pistol_fire_02
+--  @snd pistol_fire_03
+sounds.pistol_fire = iSoundGroup({
+	"pistol_fire_01",
+	"pistol_fire_02",
+	"pistol_fire_03",
+})
+
+--- @sndgroup sounds.pistol_fire_dry
+--  @snd pistol_fire_dry
+sounds.pistol_fire_dry = iSoundGroup({
+	"pistol_fire_dry",
+})
+
+--- @sndgroup sounds.pistol_reload
+--  @snd pistol_reload
+sounds.pistol_reload = iSoundGroup({
+	"pistol_reload",
+})
+
+
+
+--- Ricochet
+--
+--  @section ricochet
+
+
+--- @sndgroup = sounds.ricochet
+--  @snd ricochet
+sounds.ricochet = iSoundGroup({
+	"ricochet",
+})
+
+
+
+--- Rifle
+--
+--  @section rifle
+
+
+--- @sndgroup sounds.rifle_cock
+--  @snd rifle_cock_01
+--  @snd rifle_cock_02
+--  @snd rifle_cock_03
+sounds.rifle_cock = iSoundGroup({
+	"rifle_cock_01",
+	"rifle_cock_02",
+	"rifle_cock_03",
+})
+
+--- @sndgroup sounds.rifle_fire
+--  @snd rifle_fire_01
+--  @snd rifle_fire_02
+--  @snd rifle_fire_03
+--  @snd rifle_fire_04
+--  @snd rifle_fire_cock
+sounds.rifle_fire = iSoundGroup({
+	"rifle_fire_01",
+	"rifle_fire_02",
+	"rifle_fire_03",
+	"rifle_fire_04",
+	"rifle_fire_cock",
+})
+
+--- @sndgroup sounds.rifle_fire_dry
+--  @snd rifle_fire_dry
+sounds.rifle_fire_dry = iSoundGroup({
+	"rifle_fire_dry",
+})
+
+--- @sndgroup sounds.rifle_small_fire
+--  @snd rifle_small_fire_01
+--  @snd rifle_small_fire_02
+sounds.rifle_small_fire = iSoundGroup({
+	"rifle_small_fire_01",
+	"rifle_small_fire_02",
+})
+
+
+
+--- Shotgun
+--
+--  @section shotgun
+
+
+--- @sndgroup sounds.shotgun_fire
+--  @snd shotgun_fire_pump
+sounds.shotgun_fire = iSoundGroup({
+	"shotgun_fire_pump",
+})
+
+--- @sndgroup sounds.shotgun_pump
+--  @snd shotgun_pump
+sounds.shotgun_pump = iSoundGroup({
+	"shotgun_pump",
+})

mods/sounds/groups/main.lua

@@ -0,0 +1,540 @@
+
+--- Pre-defined General Sound Groups
+--
+--  @topic groups
+
+
+
+--- Balloon
+--
+--  @section balloon
+
+
+--- @sndgroup sounds.balloon_inflate
+--  @snd balloon_inflate
+sounds.balloon_inflate = iSoundGroup({
+	"balloon_inflate",
+})
+
+--- @sndgroup sounds.balloon_pop
+--  @snd balloon_pop
+sounds.balloon_pop = iSoundGroup({
+	"balloon_pop",
+})
+
+
+
+--- Bite
+--
+--  @section bite
+
+
+--- @sndgroup sounds.bite
+--  @snd apple_bite
+sounds.bite = iSoundGroup({
+	"apple_bite",
+})
+
+
+
+--- Bounce
+--
+--  @section bounce
+
+
+--- @sndgroup sounds.bounce
+--  @snd boing
+sounds.bounce = iSoundGroup({
+	"boing",
+})
+
+
+
+--- Chalk
+--
+--  @section chalk
+
+
+--- @sndgroup sounds.chalk_screech
+--  @snd chalk_screech_01
+--  @snd chalk_screech_02
+--  @snd chalk_screech_03
+sounds.chalk_screech = iSoundGroup({
+	"chalk_screech_01",
+	"chalk_screech_02",
+	"chalk_screech_03",
+})
+
+--- @sndgroup sounds.chalk_write
+--  @snd chalk_write_01
+--  @snd chalk_write_02
+--  @snd chalk_write_03
+sounds.chalk_write = iSoundGroup({
+	"chalk_write_01",
+	"chalk_write_02",
+	"chalk_write_03",
+})
+
+
+
+--- Church Bells
+--
+--  @section church_bells
+
+
+--- @sndgroup sounds.church_bells
+--  @snd church_bells_01 (loopable)
+--  @snd church_bells_02 (loopable)
+sounds.church_bells = iSoundGroup({
+	"church_bells_01",
+	"church_bells_02",
+})
+
+
+
+--- Clock
+--
+--  @section clock
+
+
+--- @sndgroup sounds.clock
+--  @snd clock_tick (loopable)
+sounds.clock = iSoundGroup({
+	"clock_tick",
+})
+
+
+
+--- Coin
+--
+--  @section coin
+
+
+--- @sndgroup sounds.coin
+--  @snd coin
+sounds.coin = iSoundGroup({
+	"coin",
+})
+
+
+
+--- Combat
+--
+--  @section combat
+
+
+--- @sndgroup sounds.entity_hit
+--  @snd entity_hit
+sounds.entity_hit = iSoundGroup({
+	"entity_hit",
+})
+
+--- @sndgroup sounds.melee_hit
+--  @snd melee_hit_01
+--  @snd melee_hit_02
+--  @snd melee_hit_03
+--  @snd melee_hit_04
+--  @snd melee_hit_05
+--  @snd melee_hit_06
+sounds.melee_hit = iSoundGroup({
+	"melee_hit_01",
+	"melee_hit_02",
+	"melee_hit_03",
+	"melee_hit_04",
+	"melee_hit_05",
+	"melee_hit_06",
+})
+
+
+
+--- Compressor
+--
+--  @section compressor
+
+
+--- @sndgroup sounds.compressor
+--  @snd compressor_motor_01 (loopable)
+--  @snd compressor_motor_02 (loopable)
+sounds.compressor = iSoundGroup({
+	"compressor_motor_01",
+	"compressor_motor_02",
+})
+
+
+
+--- Door
+--
+--  @section door
+
+
+--- @sndgroup sounds.door_close
+--  @snd door_close_01
+--  @snd door_close_02
+--  @snd door_close_03
+sounds.door_close = iSoundGroup({
+	"door_close_01",
+	"door_close_02",
+	"door_close_03",
+})
+
+--- @sndgroup sounds.door_creak
+--  @snd door_creak
+sounds.door_creak = iSoundGroup({
+	"door_creak",
+})
+
+--- @sndgroup sounds.door_knock
+--  @snd door_knock_01
+--  @snd door_knock_02
+sounds.door_knock = iSoundGroup({
+	"door_knock_01",
+	"door_knock_02",
+})
+
+--- @sndgroup sounds.door_open
+--  @snd door_open
+sounds.door_open = iSoundGroup({
+	"door_open",
+})
+
+--- @sndgroup sounds.doorbell
+--  @snd doorbell_01
+--  @snd doorbell_02
+--  @snd doorbell_03
+sounds.doorbell = iSoundGroup({
+	"doorbell_01",
+	"doorbell_02",
+	"doorbell_03",
+})
+
+
+
+--- Explosion
+--
+--  @section explosion
+
+
+--- @sndgroup sounds.explosion
+--  @snd explosion_01
+--  @snd explosion_02
+--  @snd explosion_03
+sounds.explosion = iSoundGroup({
+	"explosion_01",
+	"explosion_02",
+	"explosion_03",
+})
+
+--- @sndgroup sounds.explosion_distant
+--  @snd explosion_distant_01
+--  @snd explosion_distant_02
+--  @snd explosion_distant_03
+--  @snd explosion_distant_04
+sounds.explosion_distant = iSoundGroup({
+	"explosion_distant_01",
+	"explosion_distant_02",
+	"explosion_distant_03",
+	"explosion_distant_04",
+})
+
+
+
+--- Fire
+--
+--  @section fire
+
+
+--- @sndgroup sounds.fire
+--  @snd fire_crackle (loopable)
+sounds.fire = iSoundGroup({
+	"fire_crackle",
+})
+
+
+
+--- Fireworks
+--
+--  @section fireworks
+
+
+--- @sndgroup sounds.fireworks
+--  @snd fireworks_01
+--  @snd fireworks_02
+sounds.fireworks = iSoundGroup({
+	"fireworks_01",
+	"fireworks_02",
+})
+
+--- @sndgroup sounds.fireworks_pop
+--  @snd fireworks_pop_01
+--  @snd fireworks_pop_02
+--  @snd fireworks_pop_03
+sounds.fireworks_pop = iSoundGroup({
+	"fireworks_pop_01",
+	"fireworks_pop_02",
+	"fireworks_pop_03",
+})
+
+
+
+--- Fuse
+--
+--  @section fuse
+
+
+--- @sndgroup sounds.fuse
+--  @snd fuse
+--  @snd fuse_short
+sounds.fuse = iSoundGroup({
+	"fuse",
+	"fuse_short",
+})
+
+
+
+--- Gallop
+--
+--  @section gallop
+
+
+--- @sndgroup sounds.gallop
+--  @snd gallop_01 (loopable)
+--  @snd gallop_02 (loopable)
+sounds.gallop = iSoundGroup({
+	"gallop_01",
+	"gallop_02",
+})
+
+
+
+--- Lava
+--
+--  @section lava
+
+
+--- @sndgroup sounds.lava_cool
+--  @snd[r3] lava_cool
+sounds.lava_cool = iSoundGroup({
+	"lava_cool",
+})
+
+
+
+--- Leaves
+--
+--  @section leaves
+
+
+--- @sndgroup sounds.leaves
+--  @snd leaves_01
+--  @snd leaves_02
+sounds.leaves = iSoundGroup({
+	"leaves_01",
+	"leaves_02",
+})
+
+
+
+--- Match
+--
+--  @section match
+
+
+--- @sndgroup sounds.match
+--  @snd match_ignite
+sounds.match = iSoundGroup({
+	"match_ignite",
+})
+
+
+
+--- Pencil
+--
+--  @section pencil
+
+
+--- @sndgroup sounds.pencil_erase
+--  @snd pencil_erase
+sounds.pencil_erase = iSoundGroup({
+ "pencil_erase",
+})
+
+--- @sndgroup sounds.pencil_write
+--  @snd pencil_write
+sounds.pencil_write = iSoundGroup({
+	"pencil_write",
+})
+
+
+
+--- Piano
+--
+--  @section piano
+
+
+--- @sndgroup sounds.piano
+--  @snd piano
+sounds.piano = iSoundGroup({
+	"piano",
+})
+
+
+
+--- Scrape
+--
+--  @section scrape
+
+
+--- @sndgroup sounds.scrape
+--  @snd scrape_01
+--  @snd scrape_02
+--  @snd scrape_03
+--  @snd scrape_04
+--  @snd scrape_05
+--  @snd scrape_06
+--  @snd scrape_07
+--  @snd scrape_08
+sounds.scrape = iSoundGroup({
+	"scrape_01",
+	"scrape_02",
+	"scrape_03",
+	"scrape_04",
+	"scrape_05",
+	"scrape_06",
+	"scrape_07",
+	"scrape_08",
+})
+
+
+
+--- Shears
+--
+--  @section shears
+
+
+--- @sndgroup sounds.shears
+--  @snd shears_01
+--  @snd shears_02
+sounds.shears = iSoundGroup({
+	"shears_01",
+	"shears_02",
+})
+
+
+
+--- Tool
+--
+--  @section tool
+
+
+--- @sndgroup sounds.tool_break
+--  @snd[r3] tool_break
+sounds.tool_break = iSoundGroup({
+	"tool_break",
+})
+
+
+
+--- Toy
+--
+--  @section toy
+
+
+--- @sndgroup sounds.toy_squeak
+--  @snd toy_squeak_01
+--  @snd toy_squeak_02
+sounds.toy_squeak = iSoundGroup({
+	"toy_squeak_01",
+	"toy_squeak_02",
+})
+
+
+
+--- Tree
+--
+--  @section tree
+
+
+--- @sndgroup sounds.tree
+--  @snd tree_creak
+sounds.tree = iSoundGroup({
+	"tree_creak",
+})
+
+
+
+--- Vomit
+--
+--  @section vomit
+
+
+--- @sndgroup sounds.vomit
+--  @snd vomit_01
+--  @snd vomit_02
+--  @snd vomit_03
+--  @snd vomit_04
+--  @snd vomit_05
+sounds.vomit = iSoundGroup({
+	"vomit_01",
+	"vomit_02",
+	"vomit_03",
+	"vomit_04",
+	"vomit_05",
+})
+
+
+
+--- Watch
+--
+--  @section watch
+
+
+--- @sndgroup sounds.watch
+--  @snd watch_tick (loopable)
+sounds.watch = iSoundGroup({
+	"watch_tick",
+})
+
+
+
+--- Whistle
+--
+--  @section whistle
+
+
+--- @sndgroup sounds.whistle
+--  @snd whistle
+sounds.whistle = iSoundGroup({
+	"whistle",
+})
+
+
+
+--- Woosh
+--
+--  @section woosh
+
+
+--- @sndgroup sounds.woosh
+--  @snd woosh_01
+--  @snd woosh_02
+--  @snd woosh_03
+--  @snd woosh_04
+sounds.woosh = iSoundGroup({
+	"woosh_01",
+	"woosh_02",
+	"woosh_03",
+	"woosh_04",
+})
+
+
+
+--- Zipper
+--
+--  @section zipper
+
+
+--- @sndgroup sounds.zipper
+--  @snd zipper
+sounds.zipper = iSoundGroup({
+	"zipper",
+})

mods/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 = iSoundGroup({"node_dig_choppy"}),
+		--- @sndgroup sounds.node.dig.cracky
+		--  @snd[r3] node_dig_cracky
+		--  @see node sounds.node_cracky
+		cracky = iSoundGroup({"node_dig_cracky"}),
+		--- @sndgroup sounds.node.dig.crumbly
+		--  @snd node_dig_crumbly
+		--  @see node sounds.node_crumbly
+		crumbly = iSoundGroup({"node_dig_crumbly"}),
+		--- @sndgroup sounds.node.dig.snappy
+		--  @snd node_dig_snappy
+		--  @see node sounds.node_snappy
+		snappy = iSoundGroup({"node_dig_snappy"}),
+		--- @sndgroup sounds.node.dig.gravel
+		--  @snd[r2] node_dig_gravel
+		--  @see node sounds.node_gravel
+		gravel = iSoundGroup({"node_dig_gravel"}),
+		--- @sndgroup sounds.node.dig.ice
+		--  @snd[r3] node_dig_ice
+		--  @see node sounds.node_ice
+		ice = iSoundGroup({"node_dig_ice"}),
+		--- @sndgroup sounds.node.dig.metal
+		--  @snd node_dig_metal
+		--  @see node sounds.node_metal
+		metal = iSoundGroup({"node_dig_metal"}),
+	},
+	--- @sndgroup sounds.node.dug
+	--  @snd[r2] node_dug
+	--  @see node sounds.node
+	dug = iSoundGroup({"node_dug",
+		--- @sndgroup sounds.node.dug.glass
+		--  @snd[r3] node_dug_glass
+		--  @see node sounds.node_glass
+		glass = iSoundGroup({"node_dug_glass"}),
+		--- @sndgroup sounds.node.dug.gravel
+		--  @snd[r3] node_dug_gravel
+		gravel = iSoundGroup({"node_dug_gravel"}),
+		--- @sndgroup sounds.node.dug.ice
+		--  @snd node_dug_ice
+		--  @see node sounds.node_ice
+		ice = iSoundGroup({"node_dug_ice"}),
+		--- @sndgroup sounds.node.dug.metal
+		--  @snd[r2] node_dug_metal
+		--  @see node sounds.node_metal
+		metal = iSoundGroup({"node_dug_metal"}),
+	}),
+	--- @sndgroup sounds.node.place
+	--  @snd[r2] node_place
+	--  @see node sounds.node
+	place = iSoundGroup({"node_place",
+		--- @sndgroup sounds.node.place.metal
+		--  @snd[r2] node_dug_metal
+		--  @see node sounds.node_metal
+		metal = iSoundGroup({"node_dug_metal"}),
+		--- @sndgroup sounds.node.place.soft
+		--  @snd[r3] node_place_soft
+		soft = iSoundGroup({"node_place_soft"}),
+	}),
+	step = {
+		--- @sndgroup sounds.node.step.dirt
+		--  @snd[r2] node_step_dirt
+		--  @see node sounds.node_dirt
+		dirt = iSoundGroup({"node_step_dirt"}),
+		--- @sndgroup sounds.node.step.glass
+		--  @snd node_step_glass
+		--  @see node sounds.node_glass
+		glass = iSoundGroup({"node_step_glass"}),
+		--- @sndgroup sounds.node.step.grass
+		--  @snd[r3] node_step_grass
+		--  @see node sounds.node_grass
+		grass = iSoundGroup({"node_step_grass"}),
+		--- @sndgroup sounds.node.step.gravel
+		--  @snd[r4] node_step_gravel
+		--  @see node sounds.node_gravel
+		gravel = iSoundGroup({"node_step_gravel"}),
+		--- @sndgroup sounds.node.step.hard
+		--  @snd[r3] node_step_hard
+		hard = iSoundGroup({"node_step_hard"}),
+		--- @sndgroup sounds.node.step.ice
+		--  @snd[r3] node_step_ice
+		--  @see node sounds.node_ice
+		ice = iSoundGroup({"node_step_ice"}),
+		--- @sndgroup sounds.node.step.metal
+		--  @snd[r3] node_step_metal
+		--  @see node sounds.node_metal
+		metal = iSoundGroup({"node_step_metal"}),
+		--- @sndgroup sounds.node.step.sand
+		--  @snd[r3] node_step_sand
+		--  @see node sounds.node_sand
+		sand = iSoundGroup({"node_step_sand"}),
+		--- @sndgroup sounds.node.step.snow
+		--  @snd[r5] node_step_snow
+		--  @see node sounds.node_snow
+		snow = iSoundGroup({"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 = iSoundGroup({"node_step_water"}),
+		--- @sndgroup sounds.node.step.wood
+		--  @snd[r2] node_step_wood
+		--  @see node sounds.node_wood
+		wood = iSoundGroup({"node_step_wood"}),
+	},
+}

mods/sounds/groups/projectile.lua

@@ -0,0 +1,46 @@
+
+--- Pre-defined Projectile Sound Groups
+--
+--  @topic projectile_groups
+
+
+
+--- Fireball
+--
+--  @section fireball
+
+
+--- @sndgroup sounds.fireball
+--  @snd fireball_01
+--  @snd fireball_02
+--  @snd fireball_03
+sounds.fireball = iSoundGroup({
+	"fireball_01",
+	"fireball_02",
+	"fireball_03",
+})
+
+
+
+--- Laser
+--
+--  @section laser
+
+
+--- @sndgroup sounds.laser
+--  @snd laser_01
+--  @snd laser_02
+--  @snd laser_03
+--  @snd laser_04
+--  @snd laser_05
+--  @snd laser_06
+--  @snd laser_07
+sounds.laser = iSoundGroup({
+	"laser_01",
+	"laser_02",
+	"laser_03",
+	"laser_04",
+	"laser_05",
+	"laser_06",
+	"laser_07",
+})

mods/sounds/groups/scifi.lua

@@ -0,0 +1,18 @@
+
+--- Pre-defined Sci-Fi Sound Groups
+--
+--  @topic scifi_groups
+
+
+
+--- @sndgroup sounds.explosion_scifi
+--  @snd explosion_scifi
+sounds.explosion_scifi = iSoundGroup({
+	"explosion_scifi",
+})
+
+--- @sndgroup sounds.plasma_shot
+--  @snd plasma_shot
+sounds.plasma_shot = iSoundGroup({
+	"plasma_shot",
+})

mods/sounds/groups/vehicle.lua

@@ -0,0 +1,114 @@
+
+--- Pre-defined Vehicle Sound Groups
+--
+--  @topic vehicle_groups
+
+
+
+--- Airplane
+--
+--  @section airplane
+
+
+--- @sndgroup sounds.airplane
+--  @snd airplane_prop (loopable)
+sounds.airplane = iSoundGroup({
+	"airplane_prop",
+})
+
+--- @sndgroup sounds.jet
+--  @snd jet_ambience (loopable)
+--  @snd jet_flyby
+--  @snd jet_land
+sounds.jet = iSoundGroup({
+	"jet_ambience",
+	"jet_flyby",
+	"jet_land",
+})
+
+
+
+--- Bicycle
+--
+--  @section bicycle
+
+
+--- @sndgroup sounds.bicycle_bell
+--  @snd bicycle_bell
+sounds.bicycle_bell = iSoundGroup({
+	"bicycle_bell",
+})
+
+--- @sndgroup sounds.bicycle_horn
+--  @snd bicycle_horn
+sounds.bicycle_horn = iSoundGroup({
+	"bicycle_horn",
+})
+
+--- @sndgroup sounds.bicycle_spokes
+--  @snd bicycle_spokes
+sounds.bicycle_spokes = iSoundGroup({
+	"bicycle_spokes",
+})
+
+
+
+--- Helicopter
+--
+--  @section helicopter
+
+
+--- @sndgroup sounds.helicopter
+--  @snd helicopter (loopable)
+sounds.helicopter = iSoundGroup({
+	"helicopter",
+})
+
+
+
+--- Motorbike
+--
+--  @section motorbike
+
+
+--- @sndgroup sounds.motorbike
+--  @snd motorbike_idle (loopable)
+sounds.motorbike = iSoundGroup({
+	"motorbike_idle",
+})
+
+
+
+--- Train
+--
+--  @section train
+
+
+--- @sndgroup sounds.train_whistle
+--  @snd train_whistle
+sounds.train_whistle = iSoundGroup({
+	"train_whistle",
+})
+
+
+
+--- Vehicle
+--
+--  @section vehicle
+
+
+--- @sndgroup sounds.vehicle_horn
+--  @snd vehicle_horn_01
+--  @snd vehicle_horn_02
+sounds.vehicle_horn = iSoundGroup({
+	"vehicle_horn_01",
+	"vehicle_horn_02",
+})
+
+--- @sndgroup sounds.vehicle_motor
+--  @snd car_motor (loopable)
+--  @snd vehicle_motor_idle (loopable)
+sounds.vehicle_motor = iSoundGroup({
+	"car_motor",
+	"vehicle_motor_idle",
+})

mods/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 = iSoundGroup({
+	"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 = iSoundGroup({
+	"thunder_01",
+	"thunder_02",
+	"thunder_03",
+})
+
+
+
+--- Wind
+--
+--  @section wind
+
+
+--- @sndgroup sounds.wind
+--  @snd wind (loopable)
+sounds.wind = iSoundGroup({
+	"wind",
+})

mods/sounds/init.lua

@@ -0,0 +1,134 @@
+
+sounds = {}
+sounds.modname = core.get_current_modname()
+sounds.modpath = core.get_modpath(sounds.modname)
+
+local debugging = core.settings:get_bool("debug_mods", false)
+
+sounds.log = function(lvl, msg)
+	if not msg then
+		msg = lvl
+		lvl = nil
+	end
+
+	if not debugging and lvl == "debug" then return end
+
+	msg = "[" .. sounds.modname .. "] " .. msg
+
+	if lvl == "debug" then
+		msg = "[DEBUG] " .. msg
+		lvl = "action"
+	end
+
+	if not lvl then
+		core.log(msg)
+	else
+		core.log(lvl, msg)
+	end
+end
+
+
+dofile(sounds.modpath .. "/settings.lua")
+
+local scripts = {
+	"override",
+	"api",
+}
+
+if not sounds.disabled_groups["all"] then
+	local dir_groups = sounds.modpath .. "/groups"
+	for _, lua in ipairs(core.get_dir_list(dir_groups, false)) do
+		if lua:find("%.lua$") then
+			local sg = lua:gsub("%.lua$", "")
+			if not sounds.disabled_groups[sg] then
+				sounds.log("debug", "sounds groups \"" .. sg .. "\" loading")
+				table.insert(scripts, "groups/" .. sg)
+			else
+				sounds.log("debug", "sounds groups \"" .. sg .. "\" disabled")
+			end
+		end
+	end
+else
+	sounds.log("debug", "built-in sounds groups disabled")
+end
+
+-- ensure that node.lua is loaded after groups/node.lua
+table.insert(scripts, "node")
+
+for _, s in ipairs(scripts) do
+	dofile(sounds.modpath .. "/" .. s .. ".lua")
+end
+
+if sounds.enable_tests then
+	dofile(sounds.modpath .. "/tests.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$", "")
+				local cache_value = true
+
+				-- files for playing randomly by core must have suffix trimmed
+				if basename:find("%.[0-9]$") then
+					basename = basename:gsub("%.[0-9]$", "")
+					cache_value = sounds.cache[basename]
+					if type(cache_value) ~= "number" then
+						cache_value = 1
+					else
+						cache_value = cache_value + 1
+					end
+				end
+
+				sounds.cache[basename] = cache_value
+			end
+		end
+	end
+end)
+
+
+if sounds.enable_biome_sounds then
+	local timer = 0
+	local interval = tonumber(core.settings:get("sounds.biome_interval")) or 30
+	local chance = tonumber(core.settings:get("sounds.biome_chance")) or 20
+
+	interval = interval >= 5 and interval or 5
+	chance = chance >= 0 and chance or 0
+	chance = chance <= 100 and chance or 100
+
+	core.register_globalstep(function(dtime)
+		timer = timer + dtime
+		if timer < interval then
+			return
+		end
+		timer = 0
+
+		if math.random(100) <= chance then
+			for _, player in ipairs(core.get_connected_players()) do
+				local p_name = player:get_player_name()
+				local b_id = core.get_biome_data(player:get_pos()).biome
+
+				if b_id then
+					local b_sounds = sounds:get_biome_sounds(core.get_biome_name(b_id))
+
+					if b_sounds and type(b_sounds.group) == "SoundGroup" then
+						local b_params = {}
+						if b_sounds.params then
+							b_params = table.copy(b_sounds.params)
+						end
+						b_params.to_player = p_name
+
+						b_sounds.group(b_params)
+					end
+				end
+			end
+		end
+	end)
+end

mods/sounds/locale/sounds.es.tr

@@ -0,0 +1,18 @@
+# textdomain:sounds
+
+# Translators: Jordan Irwin (AntumDeluge)
+
+
+Displays sounds tests formspec.=Mostrar formspec de pruebas de sonidos.
+Sounds Tests=Pruebas de Sonidos
+Name: @1=Nombre: @1
+Cached: @1=En caché: @1
+Played: @1=Reproducido: @1
+Manual play:=Reproducir manual:
+Group play:=Reproducir grupo:
+Play=Reproducir
+Stop=Parar
+Loop=Bucle
+Random=Al azar
+yes=sí
+no=

mods/sounds/locale/template.txt

@@ -0,0 +1,18 @@
+# textdomain:sounds
+
+# Translators:
+
+
+Displays sounds tests formspec.=
+Sounds Tests=
+Name: @1=
+Cached: @1=
+Played: @1=
+Manual play:=
+Group play:=
+Play=
+Stop=
+Loop=
+Random=
+yes=
+no=

mods/sounds/mod.conf

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

mods/sounds/node.lua

@@ -0,0 +1,303 @@
+
+--- 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,
+}
+
+sounds.node = sounds.node or {} -- in case groups/node.lua was not loaded
+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_dug_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/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

mods/sounds/settings.lua

@@ -0,0 +1,53 @@
+
+--- Sounds Settings
+--
+--  @topic settings
+
+
+--- Disables individual built-in sound groups categories.
+--
+--  Category names that can be disabled are the filenames in the
+--  "groups" directory without the ".lua" suffix. Use "all" to
+--  disable all built-in groups.
+--
+--  @setting sounds.disabled_groups
+--  @settype string (comma-separated list)
+--  @default Empty string.
+--  @usage # disable animal & weather sound groups
+--  sounds.disabled_groups = animal,weather
+sounds.disabled_groups = {}
+for _, d in ipairs(string.split(core.settings:get("sounds.disabled_groups") or "", ",")) do
+	d = d:trim()
+	if d ~= "" then
+		sounds.disabled_groups[d] = true
+	end
+end
+
+--- Enables/Disables ambiance sounds for biomes.
+--
+--  @setting sounds.enable_biome_sounds
+--  @settype bool
+--  @default false
+sounds.enable_biome_sounds = core.settings:get_bool("sounds.enable_biome_sounds", false)
+
+--- Interval between playing biome sounds.
+--
+--  @setting sounds.biome_interval
+--  @settype int
+--  @min 5
+--  @default 30
+
+--- Chance that sound will be played at interval.
+--
+--  @setting sounds.biome_chance
+--  @settype int
+--  @min 0
+--  @max 100
+--  @default 20
+
+--- Enables sounds testing with [sounds_tests](tests.html#sounds_tests) chat command.
+--
+--  @setting sounds.enable_tests
+--  @settype bool
+--  @default false
+sounds.enable_tests = core.settings:get_bool("sounds.enable_tests", false)

mods/sounds/settingtypes.txt

@@ -0,0 +1,20 @@
+
+# Disables individual built-in sound groups categories (comma-
+# separated list).
+#
+# Category names that can be disabled are the filenames in the
+# "groups" directory without the ".lua" suffix. Use "all" to
+# disable all built-in groups.
+sounds.disabled_groups (Disabled sound groups) string
+
+# Enables/Disables ambiance sounds for biomes.
+sounds.enable_biome_sounds (Enable biome sounds) bool false
+
+# Interval between playing biome sounds.
+sounds.biome_interval (Biome sound interval) int 30 5
+
+# Chance that sound will be played at interval.
+sounds.biome_chance (Biome sound chance) int 20 0 100
+
+# Enables sounds testing with /sounds_tests chat command.
+sounds.enable_tests (Sounds tests) bool false