Is "EntityDefinition.on_punched" a Valid Callback?

[AntumDeluge]

Looking through the API I found a line that calls EntityDefinition.on_punched. But is this actually doing anything? Looking through Minetest's Lua API docs, I don't see any on_punched callback. Only on_punch.

[BuckarooBanzay]

this looks like a typo: i grepped through my known modlist and some other 3d-armor related mods and could not find any references to on_punched
Also: the parameters and order of them are the same as with on_punch 🤷

[mckaygerhard]

well as i know in minetest there's no such derfinition at https://github.com/minetest/minetest/blob/8dfeba02b9f084ddd52090ccd906534200f468b3/src/script/cpp_api/s_entity.cpp#L239 ..

but maybe is a definition of the 3d_armor mod? @BuckarooBanzay ?

[BuckarooBanzay]

I think i get it now: this isn't a callback on an entity, this is on the armor-definition 🤔
This is just a callback that gets executed if the armor-part was punched

The def var comes from the armor inventory-list here:

	local list = armor_inv:get_list("armor") -- <---- HERE
	for i, stack in pairs(list) do
		if stack:get_count() == 1 then
			local itemname = stack:get_name()
			local use = minetest.get_item_group(itemname, "armor_use") or 0
			local damage = use > 0
			local def = stack:get_definition() or {} -- <----- HERE
			if type(def.on_punched) == "function" then
				damage = def.on_punched(player, hitter, time_from_last_punch,
					tool_capabilities) ~= false and damage == true
			end

This might just be an undocumented (and unused) feature after all 🤷

[mckaygerhard]

but i not found a definition documented neither used so that piece may confuse others.. what should be do in this case? erased (with danger to break some misterious not knowed others mods that use it) or let as is and coumented? that is working!?

i changed to punch but seems i nete raised that part of the code..

[BuckarooBanzay]

but i not found a definition documented neither used so that piece may confuse others

I don't think that needs changing: on_punched on a armor piece sounds pretty self-explanatory to me :P

[mckaygerhard]

i searched so much in code and i cannot find any reference to on_punched in 3d_armor neither in minetest namespace..

• https://github.com/minetest-mods/3d_armor/search?q=on_punched
• https://github.com/minetest/minetest/search?q=on_punched&type=commits
• https://github.com/minetest/minetest_game/search?q=on_punched&type=commits

the older repo has https://github.com/stujones11/minetest-3d_armor/search?q=on_punched it has a definition documented in the api but not in code, it describes https://github.com/stujones11/minetest-3d_armor/blob/47ecef46f75c977a3d256ac4bab2874c24b785af/3d_armor/README.txt#L85 as aditional field for register_armor over the tool to pass to minetest core .. but currently there is no such definition in any part of code.. inclusivelly was removed from admin shield

finally due register_armor will always end in register_tool searchiv at the definition of tool item i cannot found anything https://minetest.gitlab.io/minetest/definition-tables/#item-definition neither in 3d_armor code..

so i guess any of us as implementer will define the "on_punched" function so can this be documented in the docs and readme more clear? @BuckarooBanzay

[mckaygerhard]

example of usage: stujones11@8e8c79a

on_punched = function(player, hitter, time_from_last_punch, tool_capabilities)
		if type(hitter) == "userdata" then
			if hitter:is_player() then
				hitter:set_wielded_item("")
			end
			play_sound_effect(player, "default_dig_metal")
		end
		return false
	end

Important must retunr always false if no valid logic code is defined

[BuckarooBanzay]

i searched so much in code and i cannot find any reference to on_punched in 3d_armor neither in minetest namespace..

$ grep on_punched . -Rn
./3d_armor/README.md:176:	on_punched = <function>
./3d_armor/README.md:454:*unsure what this note means may apply to all item callbacks or just on_punched*   
./3d_armor/README.md:473:#### on_punched
./3d_armor/README.md:475:	on_punched = func(player, hitter, time_from_last_punch, tool_capabilities)
./3d_armor/README.md:477:`on_punched` is called every time a player is punched or takes damage, `hitter`, `time_from_last_punch` and `tool_capabilities` can be `nil` and will be in the case of fall damage.  
./3d_armor/api.lua:551:			if type(def.on_punched) == "function" then
./3d_armor/api.lua:552:				damage = def.on_punched(player, hitter, time_from_last_punch,