Is "EntityDefinition.on_punched" a Valid Callback?

AntumDeluge commented 3 years ago

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 commented 3 years ago

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 :shrug:

mckaygerhard commented 3 years ago

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 commented 3 years ago

I think i get it now: this isn't a callback on an entity, this is on the armor-definition :thinking: 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 :shrug:

mckaygerhard commented 3 years ago

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 commented 3 years ago

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 commented 2 years ago

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

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 commented 2 years ago

example of usage: https://github.com/stujones11/minetest-3d_armor/commit/8e8c79aca20db49053a3749e7508bad8a0aaa711

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 commented 2 years ago

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,

minetest-mods / 3d_armor

Is "EntityDefinition.on_punched" a Valid Callback? #57