Node: clarification of callbacks annotations

This commit is contained in:
Van
2026-05-02 20:13:46 +03:00
parent 4d11335470
commit 17a2aabfcc

View File

@@ -13,7 +13,7 @@ local Callbacks = Class.extend(ItemCallbacks, {})
---
---default: nil
---* `pos`: node position
---@type fun(pos:Position)?
---@type fun(pos:MapPosition)?
Callbacks.on_construct = nil
---Node destructor; called before removing node.
@@ -21,7 +21,7 @@ Callbacks.on_construct = nil
---
---default: nil
---* `pos`: node position
---@type fun(pos:Position)?
---@type fun(pos:MapPosition)?
Callbacks.on_destruct = nil
---Node destructor; called after removing node.
@@ -30,7 +30,7 @@ Callbacks.on_destruct = nil
---default: nil
---* `pos`: node position
---* `oldnode`: node table of node before it was deleted
---@type fun(pos:Position, old_node)?
---@type fun(pos:MapPosition, old_node)?
Callbacks.after_destruct = nil
---Called when a liquid (newnode) is about to flood oldnode, if it has
@@ -45,7 +45,7 @@ Callbacks.after_destruct = nil
---* `pos`: table node position
---* `oldnode`: table node table of node before it was deleted
---* `newnode`: TODO: какой тут тип?
---@type fun(pos:Position, old_node, new_node)?
---@type fun(pos:MapPosition, old_node, new_node)?
Callbacks.on_flood = nil
@@ -61,7 +61,7 @@ Callbacks.on_flood = nil
---* `drops`: a table of `ItemStack`s, so any metadata to be preserved can
--- be added directly to one or more of the dropped items. See
--- "ItemStackMetaRef".
---@type fun(pos:Position, old_node, new_node, old_meta, drops:ItemStack[])?
---@type fun(pos:MapPosition, old_node, new_node, old_meta, drops:ItemStack[])?
Callbacks.preserve_metadata = nil
---Called after constructing node when node was placed using
@@ -73,7 +73,7 @@ Callbacks.preserve_metadata = nil
---* `placer`: may be any valid ObjectRef or nil
---* `itemstack`: TODO: сделать описание
---* `pointed_thing`: Vector of the direction of the gaze of the person who placed the block
---@type fun(pos:Position, placer:Player|ObjectRef|nil, itemstack:ItemStack, pointed_thing:pointed_thing)?
---@type fun(pos:MapPosition, placer:Player|ObjectRef|nil, itemstack:ItemStack, pointed_thing:pointed_thing)?
Callbacks.after_place_node = nil
---Called after destructing the node when node was dug using
@@ -92,7 +92,7 @@ Callbacks.after_dig_node = nil
---default: nil
---* `pos`: node position
---* player: ObjectRef of digger
---@type fun(pos:Position, player:Player|ObjectRef|nil)?
---@type fun(pos:MapPosition, player:Player|ObjectRef|nil)?
Callbacks.can_dig = nil
---Called when puncher (an ObjectRef) punches the node at pos.
@@ -103,7 +103,7 @@ Callbacks.can_dig = nil
---* `node`: node being hit
---* `puncher`: ObjectRef of punch
---* `pointed_thing`: Vector of the direction of the gaze of the person who placed the block
---@type fun(pos:Position, node:NodeTable, puncher:Player|ObjectRef|nil, pointed_thing:pointed_thing)?
---@type fun(pos:MapPosition, node:NodeTable, puncher:Player|ObjectRef|nil, pointed_thing:pointed_thing)?
Callbacks.on_punch = nil
---Called when clicker (an ObjectRef) used the 'place/build' key
@@ -115,7 +115,7 @@ Callbacks.on_punch = nil
---Note: pointed_thing can be nil, if a mod calls this function.
---
---default: nil
---@type (fun(pos:Position, node:NodeTable, clicker:Player|ObjectRef, itemstack:ItemStack, pointed_thing:pointed_thing|nil):ItemStack|nil)?
---@type (fun(pos:MapPosition, node:NodeTable, clicker:Player|ObjectRef, itemstack:ItemStack, pointed_thing:pointed_thing|nil):ItemStack|nil)?
Callbacks.on_rightclick = core.node_punch
@@ -124,7 +124,7 @@ Callbacks.on_rightclick = core.node_punch
---Deprecated: returning nil is the same as returning true.
---
---default: core.node_dig
---@type (fun(pos:Position, node:NodeTable, digger:Player): boolean)?
---@type (fun(pos:MapPosition, node:NodeTable, digger:Player): boolean)?
Callbacks.on_dig = minetest.node_dig
---called by NodeTimers, see core.get_node_timer and NodeTimerRef.
@@ -134,7 +134,7 @@ Callbacks.on_dig = minetest.node_dig
---return true to run the timer for another cycle with the same timeout value.
---
---default: nil
---@type (fun(pos:Position, elapsed:number): boolean)?
---@type (fun(pos:MapPosition, elapsed:number, node:NodeTable, timeout:number):boolean?)?
Callbacks.on_timer = nil
---fields = {name1 = value1, name2 = value2, ...}
@@ -144,7 +144,7 @@ Callbacks.on_timer = nil
---See `core.register_on_player_receive_fields` for more info.
---
---default: nil
---@type fun(pos:Position, formname:string, fields:table, sender:Player)?
---@type fun(pos:MapPosition, formname:string, fields:table, sender:Player)?
Callbacks.on_receive_fields = nil
---Called when a player wants to put something into the inventory.
@@ -152,7 +152,7 @@ Callbacks.on_receive_fields = nil
---Return value: number of items allowed to put.
---
---Return value -1: Allow and don't modify item count in inventory.
---@type (fun(pos:Position, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): number)?
---@type (fun(pos:MapPosition, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): number)?
Callbacks.allow_metadata_inventory_move = nil
---Called when a player wants to take something out of the inventory.
@@ -160,31 +160,31 @@ Callbacks.allow_metadata_inventory_move = nil
---Return value: number of items allowed to take.
---
---Return value -1: Allow and don't modify item count in inventory.
---@type (fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): number)?
---@type (fun(pos:MapPosition, listname:string, index:number, stack:ItemStack, player:Player): number)?
Callbacks.allow_metadata_inventory_take = nil
---Called after the actual action has happened, according to what was allowed.
---
---No return value.
---@type (fun(pos:Position, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): void)?
---@type (fun(pos:MapPosition, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): void)?
Callbacks.on_metadata_inventory_move = nil
---Called after the actual action has happened, according to what was allowed.
---
---No return value.
---@type (fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): void)?
---@type (fun(pos:MapPosition, listname:string, index:number, stack:ItemStack, player:Player): void)?
Callbacks.on_metadata_inventory_put = nil
---Called after the actual action has happened, according to what was allowed.
---
---No return value.
---@type (fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): void)?
---@type (fun(pos:MapPosition, listname:string, index:number, stack:ItemStack, player:Player): void)?
Callbacks.on_metadata_inventory_take = nil
---If defined, called when an explosion touches the node, instead of
---removing the node.
---* `intensity`: 1.0 = mid range of regular TNT.
---@type (fun(pos:Position, intensity:number): void)?
---@type (fun(pos:MapPosition, intensity:number): void)?
Callbacks.on_blast = nil
return Callbacks