Add method sounds:play_random

README.md

@@ -7,7 +7,7 @@ A [Minetest][] mod that provides a set of free sounds & methods.
 What is the purpose of this mod? There are three 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`, 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`. 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)*
+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)*
 
 

TODO.txt

@@ -1,13 +1,10 @@
 
 TODO:
-- add more methods for playing sounds
 - add ambiance registration for biomes
 - add option to get sound by string name in "SoundGroup:get" using string.match
-- create SoundGroup instances for all cached mod sounds
 - fix "node_dug_meta" & "node_place_metal" are the same
 - create sounds.glass group
 - shorten length of rain_light, rain_medium, & wind
-- add "sounds.play_random" function
 - fix clock_tick loop
 - 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)

api.lua

@@ -47,6 +47,26 @@ sounds.play = function(self, name, sp)
 	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.no_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
@@ -178,7 +198,7 @@ SoundGroup = {
 			if s_count == 1 then
 				idx = 1
 			else
-				idx = rand:next(1, s_count)
+				return sounds:play_random(self, sp)
 			end
 		end
 

changelog.txt

@@ -1,6 +1,7 @@
 
 next
 ----
+- added method "sounds:play_random"
 - renamed sounds:
 	- some "ar_fire sounds" to "ar_burst"
 - added sounds: