Add an item pick up callback (2) (#7712)

Co-authored-by: SmallJoker <mk939@ymail.com>
Co-authored-by: Jude Melton-Houghton <jwmhjwmh@gmail.com>

1 files changed, 25 insertions, 0 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 201f4d123..390bf8b2f 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -5318,6 +5318,13 @@ Call these functions only at load time!
 * `minetest.register_on_item_eat(function(hp_change, replace_with_item, itemstack, user, pointed_thing))`
     * Called when an item is eaten, by `minetest.item_eat`
     * Return `itemstack` to cancel the default item eat response (i.e.: hp increase).
+* `minetest.register_on_item_pickup(function(itemstack, picker, pointed_thing, time_from_last_punch,  ...))`
+    * Called by `minetest.item_pickup` before an item is picked up.
+    * Function is added to `minetest.registered_on_item_pickups`.
+    * Oldest functions are called first.
+    * Parameters are the same as in the `on_pickup` callback.
+    * Return an itemstack to cancel the default item pick-up response (i.e.: adding
+      the item into inventory).
 * `minetest.register_on_priv_grant(function(name, granter, priv))`
     * Called when `granter` grants the priv `priv` to `name`.
     * Note that the callback will be called twice if it's done by a player,
@@ -5964,6 +5971,11 @@ Defaults for the `on_place` and `on_drop` item definition functions
     * `param2` overrides facedir and wallmounted `param2`
     * returns `itemstack, position`
       * `position`: the location the node was placed to. `nil` if nothing was placed.
+* `minetest.item_pickup(itemstack, picker, pointed_thing, time_from_last_punch, ...)`
+    * Runs callbacks registered by `minetest.register_on_item_pickup` and adds
+      the item to the picker's `"main"` inventory list.
+    * Parameters are the same as in `on_pickup`.
+    * Returns the leftover itemstack.
 * `minetest.item_drop(itemstack, dropper, pos)`
     * Drop the item
     * returns the leftover itemstack
@@ -8074,6 +8086,19 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and
         -- The dropper may be any ObjectRef or nil.
         -- default: minetest.item_drop
 
+        on_pickup = function(itemstack, picker, pointed_thing, time_from_last_punch, ...),
+        -- Called when a dropped item is punched by a player.
+        -- Shall pick-up the item and return the leftover itemstack or nil to not
+        -- modify the dropped item.
+        -- Parameters:
+        -- * `itemstack`: The `ItemStack` to be picked up.
+        -- * `picker`: Any `ObjectRef` or `nil`.
+        -- * `pointed_thing` (optional): The dropped item (a `"__builtin:item"`
+        --   luaentity) as `type="object"` `pointed_thing`.
+        -- * `time_from_last_punch, ...` (optional): Other parameters from
+        --   `luaentity:on_punch`.
+        -- default: `minetest.item_pickup`
+
         on_use = function(itemstack, user, pointed_thing),
         -- default: nil
         -- When user pressed the 'punch/mine' key with the item in hand.