From f0a6c99e7df1d254af15132515bce7be96091807 Mon Sep 17 00:00:00 2001
From: NetherEran <nethereran@hotmail.com>
Date: Thu, 24 Oct 2019 16:08:16 +0200
Subject: [PATCH] made mobkit.make_sound more powerful and documented it

---
 init.lua       | 71 +++++++++++++++++++++++++++++++++++++++++++++++---
 mobkit_api.txt | 30 ++++++++++++++++++++-
 2 files changed, 97 insertions(+), 4 deletions(-)

diff --git a/init.lua b/init.lua
index df031c5..81dd296 100644
--- a/init.lua
+++ b/init.lua
@@ -408,12 +408,77 @@ function mobkit.animate(self,anim)
 	end
 end
 
-function mobkit.make_sound(self,sound)
-	if self.sounds and self.sounds[sound] then
-		minetest.sound_play(self.sounds[sound], {object=self.object})
+--returns a random number inbetween l and r
+local function random_within_range(l, r)
+	local middle = (l + r) / 2
+	local offset = middle - l
+	
+	return  middle + (random() - 0.5) * 2 * offset
+end
+
+--returns val if val is a number, if it's a table, it treats the fields
+--x and y as an interval and returns a random number within it.
+--otherwise returns nil
+local function get_num_or_random_in_range(val)
+	if type(val) == "number" then
+		return val
+	elseif type(val) == "table" then
+		return random_within_range(val.x, val.y)
 	end
 end
 
+function mobkit.make_sound(self, sound)
+	if not (self.sounds and self.sounds[sound]) then
+		return
+	end
+	
+	local soundtype = type(self.sounds[sound])
+	
+	local name
+	local gain
+	local fade
+	local pitch
+	local max_hear_distance
+	local loop
+	
+	if soundtype == "string" then
+		name = self.sounds[sound]
+	else
+		assert(soundtype == "table",
+			"Invalid sound definition: type was '"
+			.. soundtype ..
+			"', must be 'string' or 'table'")
+		sound = self.sounds[sound]
+		
+		
+		--if multiple sounds are in the table, choose one randomly
+		if #sound > 0 then
+			sound = sound[random(#sound)]
+		end
+		
+		name = sound.name
+		
+		--if they are not set in the sound table, these are nil and
+		--minetest fills in the default values
+		gain = get_num_or_random_in_range(sound.gain)
+		fade = get_num_or_random_in_range(sound.fade)
+		pitch = get_num_or_random_in_range(sound.pitch)
+		max_hear_distance = get_num_or_random_in_range(sound.max_distance)
+		loop = sound.loop
+	end
+	
+	return minetest.sound_play(name,
+		{
+			object = self.object,
+			gain = gain,
+			fade = fade,
+			pitch = pitch,
+			max_hear_distance = max_hear_distance,
+			loop = loop,
+		})
+end
+
+
 function mobkit.is_neighbor_node_reachable(self,neighbor)	-- todo: take either number or pos
 	local offset = neighbors[neighbor]
 	local pos=mobkit.get_stand_pos(self)
diff --git a/mobkit_api.txt b/mobkit_api.txt
index bb12faf..7920318 100644
--- a/mobkit_api.txt
+++ b/mobkit_api.txt
@@ -208,7 +208,35 @@ minetest.register_entity("mod:name",{
 		...
 		}
 	sounds = {
-		[name] = [string filename],
+		[name] = [string filename]					--single, simple,
+		
+		[name] = {									--single, more powerful. All fields but 'name' are optional
+			name = [string filename],
+			gain=[num or range],					--range is a table of the format {x=left_bound,y=right_bound}
+			fade=[num or range],
+			pitch=[num or range],
+			max_distance=[num or range],
+			loop = [bool]
+			}
+			
+		[name] = {
+			{										--variant, sound is chosen randomly
+			name = [string filename],
+			gain=[num or range],					--range is at table of the format {x=left_bound,y=right_bound}
+			fade=[num or range],
+			pitch=[num or range],
+			max_distance=[num or range],
+			loop = [bool]
+			},
+			{
+			name = [string filename],
+			gain=[num or range],
+			fade=[num or range],
+			pitch=[num or range],
+			max_distance=[num or range],
+			loop = [bool]
+			}
+		}
 		...
 		}
 	max_speed = [num],					-- m/s