Improve doc-blocks; remove unnecessary params. Relates to #1509

mods/lord/_experimental/lord_damage/src/damage/api.lua

@@ -7,15 +7,27 @@ local function calculate_damage_absorption(player, amount, damage_type)
 	return amount - protection
 end
 
---- @type table<string,fun(player:Player, amount:number, reason:PlayerHPChangeReason, source:string, chunks:number)>
+--- @class DamageReason:PlayerHPChangeReason
+--- @field damage_type string
+--- @field source      string
+
+--- @alias DamageBehavior fun(object:ObjectRef,amount:number,reason:DamageReason,chunks:number|nil,run:function|nil)
+
+--- @type table<string,DamageBehavior>
 local damage_types = {}
 
+--- @param object Player|Entity  object to set the source onto
+--- @param source string         source name
+--- @param value  boolean        whether source is active (true) or not (false)
 local function set_source(object, source, value)
 	local state = base_classes.ObjectState:new(object)
 	state:set_entry(source, value)
 	state:save(object)
 end
 
+--- @param object Player|Entity  object to get the source from
+--- @param source string         source name
+--- @return boolean  whether source is active (true) or not (false)
 local function get_source_status(object, source)
 	local state = base_classes.ObjectState:new(object)
 
@@ -34,33 +46,43 @@ local function get_registered_damage_types()
 	return damage_types
 end
 
-local function deal_damage(player, amount, damage_type, reason, source, chunks)
+
+--- @param object Player|Entity
+--- @param amount amount
+--- @param reason DamageReason
+--- @param chunks number
+--- @param run    function
+local function deal_damage(object, amount, reason, chunks, run)
 	if not amount then
 		return false
 	end
 
-	if not damage_type then
-		damage_type = "direct"
-	end
-
 	chunks = chunks or 1
 
-	local to_return = damage_types[damage_type](player, amount, reason, source, chunks)
+	local to_return = damage_types[reason.damage_type or "direct"](object, amount, reason, chunks, run)
 	return to_return
 end
 
-local function base_behavior(object, amount, damage_type, reason, source)
-	amount = calculate_damage_absorption(object, amount, damage_type)
-	reason = reason or { type = "set_hp", damage_type = damage_type, source = source, }
+--- @param object Player|Entity
+--- @param amount amount
+--- @param reason DamageReason
+local function base_behavior(object, amount, reason)
 	-- THE FOLLOWING LINE IS FOR TESTING PURPOSES ONLY! REMOVE IT WHEN THE DAMAGE SYSTEM IS INTEGRATED INTO THE GAME.
 	minetest.chat_send_player(reason.dealer:get_player_name(), "Hit: "..amount.."!")
-	return object:set_hp(object:get_hp() - amount, reason)
+	object:set_hp(object:get_hp() - amount, reason)
 end
 
-local function periodic_base_behavior(object, amount, damage_type, reason, source, chunks, do_in_cycle)
+--- @param object Player|Entity
+--- @param amount amount
+--- @param reason DamageReason
+--- @param chunks number|nil
+--- @param run    function
+local function periodic_base_behavior(object, amount, reason, chunks, run)
+	dump(chunks)
+	local damage_type = reason.damage_type
+	local source = reason.source
 	amount = calculate_damage_absorption(object, amount, damage_type)
-	reason = reason or { type = "set_hp", damage_type = damage_type, source = source, }
-	do_in_cycle = do_in_cycle or function() end
+	run = run or function() end
 	local caused_by_source = false
 	if source then
 		caused_by_source = true
@@ -114,7 +136,7 @@ local function periodic_base_behavior(object, amount, damage_type, reason, sourc
 				return
 			end
 
-			do_in_cycle()
+			run()
 
 			-- THE FOLLOWING LINE IS FOR TESTING PURPOSES ONLY! REMOVE IT WHEN THE DAMAGE SYSTEM IS INTEGRATED INTO THE GAME.
 			minetest.chat_send_player(reason.dealer:get_player_name(), "Hit: "..chunks.."!")
@@ -158,7 +180,7 @@ local function periodic_base_behavior(object, amount, damage_type, reason, sourc
 			return
 		end
 
-		do_in_cycle()
+		run()
 
 		-- THE FOLLOWING LINE IS FOR TESTING PURPOSES ONLY! REMOVE IT WHEN THE DAMAGE SYSTEM IS INTEGRATED INTO THE GAME.
 		minetest.chat_send_player(reason.dealer:get_player_name(), "Hit: "..leftover_damage.."!")

mods/lord/_experimental/lord_damage/src/damage/config.lua

@@ -34,75 +34,92 @@ local spawn_particles = function(player, damage_type)
 	})
 end
 
-local direct_behavior = function(player, amount, reason, source)
-	return lord_damage.base_behavior(player, amount, "direct", reason, source)
+local direct_behavior = function(player, amount, reason)
+	reason.damage_type = "direct"
+	return lord_damage.base_behavior(player, amount, reason)
 end
 
-local direct_periodic_behavior = function(player, amount, reason, source, chunks)
-	return lord_damage.periodic_base_behavior(player, amount, "direct_periodic", reason, source, chunks)
+local direct_periodic_behavior = function(player, amount, reason, chunks, run)
+	reason.damage_type = "direct_periodic"
+	return lord_damage.periodic_base_behavior(player, amount, reason, chunks, run)
 end
 
 
-local simple_physical_behavior = function(player, amount, reason, source)
+local simple_physical_behavior = function(player, amount, reason)
+	reason.damage_type = "physical"
 	spawn_particles(player, "physical")
-	return lord_damage.base_behavior(player, amount, "physical", reason, source)
+	return lord_damage.base_behavior(player, amount, reason)
 end
 
-local simple_physical_periodic_behavior = function(player, amount, reason, source, chunks)
-	return lord_damage.periodic_base_behavior(player, amount, "physical_periodic", reason, source, chunks)
+local simple_physical_periodic_behavior = function(player, amount, reason, chunks, run)
+	reason.damage_type = "physical_periodic"
+	return lord_damage.periodic_base_behavior(player, amount, reason, chunks, run)
 end
 
-local slashing_physical_behavior = function(player, amount, reason, source)
+local slashing_physical_behavior = function(player, amount, reason)
+	reason.damage_type = "slashing_physical"
 	spawn_particles(player, "physical")
-	return lord_damage.base_behavior(player, amount, "slashing_physical", reason, source)
+	return lord_damage.base_behavior(player, amount, reason)
 end
 
-local slashing_physical_periodic_behavior = function(player, amount, reason, source, chunks)
-	return lord_damage.periodic_base_behavior(player, amount, "slashing_physical_periodic", reason, source, chunks)
+local slashing_physical_periodic_behavior = function(player, amount, reason, chunks, run)
+	reason.damage_type = "slashing_physical_periodic"
+	return lord_damage.periodic_base_behavior(player, amount, reason, chunks, run)
 end
 
-local piercing_physical_behavior = function(player, amount, reason, source)
+local piercing_physical_behavior = function(player, amount, reason)
+	reason.damage_type = "piercing_physical"
 	spawn_particles(player, "physical")
-	return lord_damage.base_behavior(player, amount, "piercing_physical", reason, source)
+	return lord_damage.base_behavior(player, amount, reason)
 end
 
-local piercing_physical_periodic_behavior = function(player, amount, reason, source, chunks)
-	return lord_damage.periodic_base_behavior(player, amount, "piercing_physical_periodic", reason, source, chunks)
+local piercing_physical_periodic_behavior = function(player, amount, reason, chunks, run)
+	reason.damage_type = "piercing_physical_periodic"
+	return lord_damage.periodic_base_behavior(player, amount, reason, chunks, run)
 end
 
-local toxical_behavior = function(player, amount, reason, source)
+local toxical_behavior = function(player, amount, reason)
+	reason.damage_type = "toxical"
 	spawn_particles(player, "toxical")
 
-	return lord_damage.base_behavior(player, amount, "toxical", reason, source)
+	return lord_damage.base_behavior(player, amount, reason)
 end
 
-local toxical_periodic_behavior = function(player, amount, reason, source, chunks)
-	return lord_damage.periodic_base_behavior(player, amount, "toxical_periodic", reason, source, chunks)
+local toxical_periodic_behavior = function(player, amount, reason, chunks, run)
+	reason.damage_type = "toxical_periodic"
+	return lord_damage.periodic_base_behavior(player, amount, reason, chunks, run)
 end
 
 
-local fiery_behavior = function(player, amount, reason, source)
+local fiery_behavior = function(player, amount, reason)
+	reason.damage_type = "fiery"
 	minetest.sound_play("default_cool_lava", { object = player, max_hear_distance = 16, gain = 0.2 }, true)
 	spawn_particles(player, "fiery")
 
-	lord_damage.base_behavior(player, amount, "fiery", reason, source)
+	lord_damage.base_behavior(player, amount, reason)
 end
 
-local fiery_periodic_behavior = function(player, amount, reason, source, chunks)
+local fiery_periodic_behavior = function(player, amount, reason, chunks, run)
+	reason.damage_type = "fiery_periodic"
 	local do_in_cycle = function()
+		if type(run) == "function" then
+			run()
+		end
 		minetest.sound_play("default_cool_lava", { object = player, max_hear_distance = 16, gain = 0.2 }, true)
 		spawn_particles(player, "fiery")
 	end
-	return lord_damage.periodic_base_behavior(player, amount, "fiery_periodic", reason, source, chunks, do_in_cycle)
+	return lord_damage.periodic_base_behavior(player, amount, reason, chunks, do_in_cycle)
 end
 
 
-local mental_behavior = function(player, amount, reason, source)
-	lord_damage.base_behavior(player, amount, "mental", reason, source)
+local mental_behavior = function(player, amount, reason)
+	reason.damage_type = "mental"
+	lord_damage.base_behavior(player, amount, reason)
 end
 
-local mental_periodic_behavior = function(player, amount, reason, source, chunks)
-	return lord_damage.periodic_base_behavior(player, amount, "mental_periodic", reason, source, chunks)
+local mental_periodic_behavior = function(player, amount, reason, chunks, run)
+	reason.damage_type = "mental_periodic"
+	return lord_damage.periodic_base_behavior(player, amount, reason, chunks, run)
 end
 
 return {

mods/lord/_experimental/lord_damage/src/for_testing.lua

@@ -78,8 +78,12 @@ for name, _ in pairs(damage_types) do
 				return
 			end
 
-			lord_damage.deal_damage(object, 13, name, { type = "set_hp",
-					dealer = user, damage_type = name, tool = "lord_damage:target_"..name.."_dealer" }, nil, 3)
+			lord_damage.deal_damage(object, 13, {
+				type = "set_hp",
+				dealer = user,
+				damage_type = name,
+				tool = "lord_damage:target_"..name.."_dealer",
+			}, 3, function() minetest.chat_send_all("In cycle") end)
 		end
 	})
 end
@@ -105,9 +109,12 @@ minetest.register_tool("lord_damage:target_source_burning_dealer",{
 		print(minetest.serialize(object:get_properties()))
 
 
-		lord_damage.deal_damage(object, 13, "fiery_periodic", { type = "set_hp",
-				dealer = user, damage_type = "fiery_periodic",
-				tool = "lord_damage:target_source_burning_dealer", source = source }, source, 3)
+		lord_damage.deal_damage(object, 13, {
+			type = "set_hp",
+			dealer = user,
+			damage_type = "fiery_periodic", tool = "lord_damage:target_source_burning_dealer",
+			source = source,
+		}, 3, function() minetest.chat_send_all("In cycle") end)
 	end
 })