Merge pull request 'Make `mcl_dripping` API public + fix code style' (#2861) from mcl-dripping-api-public into master

Reviewed-on: MineClone2/MineClone2#2861
Reviewed-by: cora <cora@noreply.git.minetest.land>

mods/ENTITIES/mcl_dripping/README.md

@@ -0,0 +1,36 @@
+# mcl_dripping
+
+Dripping Mod by kddekadenz, modified for MineClone 2 by Wuzzy, NO11 and AFCM
+
+## Manual
+
+- drops are generated rarely under solid nodes
+- they will stay some time at the generated block and than they fall down
+- when they collide with the ground, a sound is played and they are destroyed
+
+Water and Lava have builtin drops registered.
+
+## License
+
+code & sounds: CC0
+
+## API
+
+```lua
+mcl_dripping.register_drop({
+	-- The group the liquid's nodes belong to
+	liquid   = "water",
+	-- The texture used (particles will take a random 2x2 area of it)
+	texture  = "default_water_source_animated.png",
+	-- Define particle glow, ranges from `0` to `minetest.LIGHT_MAX`
+	light    = 1,
+	-- The nodes (or node group) the particles will spawn under
+	nodes    = { "group:opaque", "group:leaves" },
+	-- The sound that will be played then the particle detaches from the roof, see SimpleSoundSpec in lua_api.txt
+	sound    = "drippingwater_drip",
+	-- The interval for the ABM to run
+	interval = 60,
+	-- The chance of the ABM
+	chance   = 10,
+})
+```

mods/ENTITIES/mcl_dripping/init.lua

@@ -3,53 +3,98 @@
 -- License of code, textures & sounds: CC0
 
 local math = math
-local function make_drop(pos,liquid,sound,interval)
+
+mcl_dripping = {}
+
+
+---@param pos Vector
+---@param liquid string
+---@param sound SimpleSoundSpec
+---@param interval integer
+---@param texture string
+local function make_drop(pos, liquid, sound, interval, texture)
 	local pt = {
-		velocity = vector.new(0,0,0),
+		velocity = vector.zero(),
 		collision_removal = false,
 	}
+
 	local t = math.random() + math.random(1, interval)
+
 	minetest.after(t, function()
 		local x, z = math.random(-45, 45) / 100, math.random(-45, 45) / 100
+
 		pt.pos = vector.offset(pos, x, -0.52, z)
-		pt.acceleration = vector.new(0,0,0)
+		pt.acceleration = vector.zero()
 		pt.collisiondetection = false
 		pt.expirationtime = t
 
-		pt.texture="[combine:2x2:" .. -math.random(1, 16) .. "," .. -math.random(1, 16) .. "=default_" .. liquid .. "_source_animated.png"
+		pt.texture = "[combine:2x2:" ..
+			-math.random(1, 16) .. "," .. -math.random(1, 16) .. "=" .. texture
+
 		minetest.add_particle(pt)
+
 		minetest.after(t, function()
 			pt.acceleration = vector.new(0, -5, 0)
 			pt.collisiondetection = true
 			pt.expirationtime = math.random() + math.random(1, interval / 2)
+
 			minetest.add_particle(pt)
-			minetest.sound_play({name = "drippingwater_" .. sound .. "drip"}, {pos = pos, gain = 0.5, max_hear_distance = 8}, true)
+
+			minetest.sound_play(sound, { pos = pos, gain = 0.5, max_hear_distance = 8 },
+				true)
 		end)
 	end)
 end
 
-local function register_drop(liquid, glow, sound, nodes, interval, chance)
+---@class mcl_dripping_drop_definition
+---@field liquid string The group the liquid's nodes belong to
+---@field texture string The texture used (particles will take a random 2x2 area of it)
+---@field light integer Define particle glow, ranges from `0` to `minetest.LIGHT_MAX`
+---@field nodes string[] The nodes (or node group) the particles will spawn under
+---@field interval integer The interval for the ABM to run
+---@field chance integer The chance of the ABM
+---@field sound SimpleSoundSpec The sound that will be played then the particle detaches from the roof
+
+---@param def mcl_dripping_drop_definition
+function mcl_dripping.register_drop(def)
 	minetest.register_abm({
 		label = "Create drops",
-		nodenames = nodes,
-		neighbors = {"group:" .. liquid},
-		interval = interval,
-		chance = chance,
+		nodenames = def.nodes,
+		neighbors = { "group:" .. def.liquid },
+		interval = def.interval,
+		chance = def.chance,
 		action = function(pos)
-			local r = math.ceil(interval / 20)
-			local nn=minetest.find_nodes_in_area(vector.offset(pos,-r,0,-r),vector.offset(pos,r,0,r),nodes)
+			local r = math.ceil(def.interval / 20)
+			local nn = minetest.find_nodes_in_area(vector.offset(pos, -r, 0, -r), vector.offset(pos, r, 0, r), def.nodes)
 			--start a bunch of particle cycles to be able to get away
 			--with longer abm cycles
 			table.shuffle(nn)
 			for i = 1, math.random(#nn) do
-				if minetest.get_item_group(minetest.get_node(vector.offset(nn[i], 0, 1, 0)).name, liquid) ~= 0
+				if minetest.get_item_group(minetest.get_node(vector.offset(nn[i], 0, 1, 0)).name, def.liquid) ~= 0
 					and minetest.get_node(vector.offset(nn[i], 0, -1, 0)).name == "air" then
-					make_drop(nn[i],liquid,sound,interval)
+					make_drop(nn[i], def.liquid, def.sound, def.interval, def.texture)
 				end
 			end
 		end,
 	})
 end
 
-register_drop("water", 1, "", {"group:opaque", "group:leaves"},60,10)
-register_drop("lava", math.max(7, minetest.registered_nodes["mcl_core:lava_source"].light_source - 3), "lava", {"group:opaque"},60,10)
+mcl_dripping.register_drop({
+	liquid   = "water",
+	texture  = "default_water_source_animated.png",
+	light    = 1,
+	nodes    = { "group:opaque", "group:leaves" },
+	sound    = "drippingwater_drip",
+	interval = 60,
+	chance   = 10,
+})
+
+mcl_dripping.register_drop({
+	liquid   = "lava",
+	texture  = "default_lava_source_animated.png",
+	light    = math.max(7, minetest.registered_nodes["mcl_core:lava_source"].light_source - 3),
+	nodes    = { "group:opaque" },
+	sound    = "drippingwater_lavadrip",
+	interval = 60,
+	chance   = 10,
+})

mods/ENTITIES/mcl_dripping/readme.txt

@@ -1,29 +0,0 @@
-Dripping Mod
-by kddekadenz
-
-modified for MineClone 2 by Wuzzy and NO11
-
-
-Installing instructions:
-
-	1. Copy the mcl_dripping mod folder into games/gamemode/mods
-
-	2. Start game and enjoy :)
-
-
-Manual:
-
--> drops are generated rarely under solid nodes
--> they will stay some time at the generated block and than they fall down
--> when they collide with the ground, a sound is played and they are destroyed
-
-
-License:
-
-code & sounds: CC0
-
-
-Changelog:
-
-16.04.2012 - first release
-28.04.2012 - drops are now 3D; added lava drops; fixed generating of drops (not at edges now)