Files
smc-luanti-ide-helper/definitions/ItemDefinition/Callbacks.lua

92 lines
3.3 KiB
Lua

---Version: 5.16
---@meta
---@class ItemDefinition.Callbacks
local Callbacks = {}
---Called when the 'place' key was pressed with the item in hand
---and pointing at a node.
---
---Shall place item and return the leftover itemstack
---or nil to not modify the inventory.
---
---The placer may be any `ObjectRef` or `nil`.
---
---Default: `core.item_place`
---@type (fun(itemstack:ItemStack, placer:Player|ObjectRef|nil, pointed_thing:pointed_thing):ItemStack?)?
Callbacks.on_place = nil
---Same as `on_place` but called when not pointing at a node.
---
---Function must return either `nil` if inventory shall not be modified,
---or an itemstack to replace the original itemstack.
---
---The user may be any `ObjectRef` or `nil`.
---
---Default: `core.item_secondary_use`
---@type (fun(itemstack:ItemStack, user:Player|ObjectRef|nil, pointed_thing:pointed_thing):ItemStack?)?
Callbacks.on_secondary_use = nil
---Called when the player drops this item from an inventory.
---
---Must return the left-over itemstack. Returning `nil` is equivalent to
---the original itemstack (= inventory not modified).
---
---**WARNING**: Only the count of the returned itemstack is significant. It is not
---possible to modify the item, wear or metadata in a drop operation.
---
---The returned itemstack must not have a higher count than the input stack.
---
--- Parameters:
--- * `itemstack`: the `ItemStack` to be dropped.
--- * `dropper`: any `ObjectRef` or `nil`.
--- * `pos`: position to drop the item at.
---
---Default: `core.item_drop`
---@type (fun(itemstack:ItemStack, dropper:Player|ObjectRef|nil, pos:Position):ItemStack)?
Callbacks.on_drop = nil
---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`: the dropped item (a `"__builtin:item"` luaentity) as `type="object"`.
--- * `time_from_last_punch`: other parameters from `luaentity:on_punch`.
--- * `...`: other parameters from `luaentity:on_punch`.
---
---Default: `core.item_pickup`
---@type fun(itemstack:ItemStack, picker:Player|ObjectRef|nil, pointed_thing:pointed_thing?, time_from_last_punch:number?, ...)?
Callbacks.on_pickup = nil
---Called when user presses the 'punch/dig' key with the item in hand.
---
---Function must return either `nil` if inventory shall not be modified,
---or an itemstack to replace the original itemstack.
---
---e.g. `itemstack:take_item()`; return itemstack
---
---The user may be any `ObjectRef` or `nil`.
---
---Note that defining this callback will prevent normal punching/digging
---behavior on the client, as the interaction is instead "forwarded" to the
---server.
---
---Default: `nil`
---@type (fun(itemstack:ItemStack, user:Player|ObjectRef|nil, pointed_thing:pointed_thing):ItemStack?)?
Callbacks.on_use = nil
---Called after a tool is used to dig a node and will replace the default
---tool wear-out handling.
---
---Shall return the leftover itemstack or `nil` to not modify the dropped item.
---
---The user may be any `ObjectRef` or `nil`.
---
---Default: `nil`
---@type (fun(itemstack:ItemStack, user:Player|ObjectRef|nil, node:NodeTable, digparams:table):ItemStack)?
Callbacks.after_use = nil