Node: update settings & callbacks annotations

This commit is contained in:
Van
2025-10-09 21:26:46 +03:00
parent de64694acf
commit 2ef2bb14ba
2 changed files with 44 additions and 85 deletions

View File

@@ -1,8 +1,6 @@
---@type Item.Callbacks ---@type Item.Callbacks
local ItemCallbacks = Core.Item.require('Item.Callbacks') local ItemCallbacks = Core.Item.require('Item.Callbacks')
-- TODO: Разобраться с дубликатами аннотаций полей. Приоритетно брать аннотации из util/ide-helper
---@class Node.Callbacks : Item.Callbacks ---@class Node.Callbacks : Item.Callbacks
local Callbacks = Mod:getClassExtended(ItemCallbacks, {}) local Callbacks = Mod:getClassExtended(ItemCallbacks, {})
@@ -15,20 +13,16 @@ local Callbacks = Mod:getClassExtended(ItemCallbacks, {})
--- ---
---default: nil ---default: nil
---* `pos`: node position ---* `pos`: node position
---@type nil | fun(pos : table) ---@type fun(pos:Position)?
Callbacks.on_construct = function(pos) Callbacks.on_construct = nil
end
---Node destructor; called before removing node. ---Node destructor; called before removing node.
---Not called for bulk node placement. ---Not called for bulk node placement.
--- ---
---default: nil ---default: nil
---* `pos`: node position ---* `pos`: node position
---@type nil | fun(pos : table) ---@type fun(pos:Position)?
Callbacks.on_destruct = function(pos) Callbacks.on_destruct = nil
end
---Node destructor; called after removing node. ---Node destructor; called after removing node.
---Not called for bulk node placement. ---Not called for bulk node placement.
@@ -36,10 +30,8 @@ end
---default: nil ---default: nil
---* `pos`: node position ---* `pos`: node position
---* `oldnode`: node table of node before it was deleted ---* `oldnode`: node table of node before it was deleted
---@type nil | fun(pos : table, oldnode : table) ---@type fun(pos:Position, old_node)?
Callbacks.after_destruct = function(pos, oldnode) Callbacks.after_destruct = nil
end
---Called when a liquid (newnode) is about to flood oldnode, if it has ---Called when a liquid (newnode) is about to flood oldnode, if it has
---`floodable = true` in the nodedef. Not called for bulk node placement ---`floodable = true` in the nodedef. Not called for bulk node placement
@@ -53,10 +45,8 @@ end
---* `pos`: table node position ---* `pos`: table node position
---* `oldnode`: table node table of node before it was deleted ---* `oldnode`: table node table of node before it was deleted
---* `newnode`: TODO: какой тут тип? ---* `newnode`: TODO: какой тут тип?
---@type nil | fun(pos : table, oldnode : table, newnode : any) ---@type fun(pos:Position, old_node, new_node)?
Callbacks.on_flood = function(pos, oldnode, newnode) Callbacks.on_flood = nil
end
---Called when `oldnode` is about be converted to an item, but before the ---Called when `oldnode` is about be converted to an item, but before the
@@ -71,10 +61,8 @@ end
---* `drops`: a table of `ItemStack`s, so any metadata to be preserved can ---* `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 --- be added directly to one or more of the dropped items. See
--- "ItemStackMetaRef". --- "ItemStackMetaRef".
---@type nil | fun(pos : table, oldnode : table, oldmeta : table, drops : any?) ---@type fun(pos:Position, old_node, new_node, old_meta, drops:ItemStack[])?
Callbacks.preserve_metadata = function(pos, oldnode, oldmeta, drops) Callbacks.preserve_metadata = nil
end
---Called after constructing node when node was placed using ---Called after constructing node when node was placed using
---core.item_place_node / core.place_node. ---core.item_place_node / core.place_node.
@@ -85,10 +73,8 @@ end
---* `placer`: may be any valid ObjectRef or nil ---* `placer`: may be any valid ObjectRef or nil
---* `itemstack`: TODO: сделать описание ---* `itemstack`: TODO: сделать описание
---* `pointed_thing`: Vector of the direction of the gaze of the person who placed the block ---* `pointed_thing`: Vector of the direction of the gaze of the person who placed the block
---@type nil | fun(pos : table, placer : table, itemstack : table, pointed_thing : table):boolean ---@type fun(pos:Position, placer:Player|ObjectRef|nil, itemstack:ItemStack, pointed_thing:pointed_thing)?
Callbacks.after_place_node = function(pos, placer, itemstack, pointed_thing) Callbacks.after_place_node = nil
end
---Called after destructing the node when node was dug using ---Called after destructing the node when node was dug using
---`core.node_dig` / `core.dig_node`. ---`core.node_dig` / `core.dig_node`.
@@ -98,20 +84,16 @@ end
---* `oldnode`: node table of node before it was dug ---* `oldnode`: node table of node before it was dug
---* `oldmetadata`: metadata of node before it was dug, as a metadata table ---* `oldmetadata`: metadata of node before it was dug, as a metadata table
---* `digger`: ObjectRef of digger ---* `digger`: ObjectRef of digger
---@type nil | fun(pos : table, oldnode : table, oldmetadata : table, digger : table) ---@type fun(pos:Player, oldnode, oldmetadata, digger:Player|ObjectRef|nil)?
Callbacks.after_dig_node = function(pos, oldnode, oldmetadata, digger) Callbacks.after_dig_node = nil
end
---Returns true if node can be dug, or false if not. ---Returns true if node can be dug, or false if not.
--- ---
---default: nil ---default: nil
---* `pos`: node position ---* `pos`: node position
---* player: ObjectRef of digger TODO: в API было написано [player], это типо необязательный параметр? Я не понял ---* player: ObjectRef of digger TODO: в API было написано [player], это типо необязательный параметр? Я не понял
---@type nil | fun(pos : table, player : table?):boolean ---@type fun(pos:Position, player:Player|ObjectRef|nil)?
Callbacks.can_dig = function(pos, player) Callbacks.can_dig = nil
return true
end
---Called when puncher (an ObjectRef) punches the node at pos. ---Called when puncher (an ObjectRef) punches the node at pos.
---By default calls core.register_on_punchnode callbacks. ---By default calls core.register_on_punchnode callbacks.
@@ -121,10 +103,8 @@ end
---* `node`: node being hit ---* `node`: node being hit
---* `puncher`: ObjectRef of punch ---* `puncher`: ObjectRef of punch
---* `pointed_thing`: Vector of the direction of the gaze of the person who placed the block ---* `pointed_thing`: Vector of the direction of the gaze of the person who placed the block
---@type nil | fun(pos : table, node : table, puncher : table, pointed_thing : table) ---@type fun(pos:Position, node:NodeTable, puncher:Player|ObjectRef|nil, pointed_thing:pointed_thing)?
Callbacks.on_punch = function(pos, node, puncher, pointed_thing) Callbacks.on_punch = nil
core.node_punch(pos, node, puncher, pointed_thing)
end
---Called when clicker (an ObjectRef) used the 'place/build' key ---Called when clicker (an ObjectRef) used the 'place/build' key
---(not necessarily an actual rightclick) ---(not necessarily an actual rightclick)
@@ -135,10 +115,8 @@ end
---Note: pointed_thing can be nil, if a mod calls this function. ---Note: pointed_thing can be nil, if a mod calls this function.
--- ---
---default: nil ---default: nil
---@type nil | fun(pos : table, node : table, clicker : table, itemstack : table, pointing_thing : table?):table? ---@type (fun(pos:Position, node:NodeTable, clicker:Player|ObjectRef, itemstack:ItemStack, pointed_thing:pointed_thing|nil):ItemStack|nil)?
Callbacks.on_rightclick = function(pos, node, clicker, itemstack, pointed_thing) Callbacks.on_rightclick = core.node_punch
end
---By default checks privileges, wears out item (if tool) and removes node. ---By default checks privileges, wears out item (if tool) and removes node.
@@ -146,10 +124,8 @@ end
---Deprecated: returning nil is the same as returning true. ---Deprecated: returning nil is the same as returning true.
--- ---
---default: core.node_dig ---default: core.node_dig
---@type nil | fun(pos : table, node : table, digger : table):boolean ---@type (fun(pos:Position, node:NodeTable, digger:Player): boolean)?
Callbacks.on_dig = function(pos, node, digger) Callbacks.on_dig = minetest.node_dig
core.node_dig(pos, node, digger)
end
---called by NodeTimers, see core.get_node_timer and NodeTimerRef. ---called by NodeTimers, see core.get_node_timer and NodeTimerRef.
---* `elapsed`: total time passed since the timer was started. ---* `elapsed`: total time passed since the timer was started.
@@ -158,10 +134,8 @@ end
---return true to run the timer for another cycle with the same timeout value. ---return true to run the timer for another cycle with the same timeout value.
--- ---
---default: nil ---default: nil
---@type nil | fun(pos : table, elapsed : number, node : table, timeout : any):boolean? ---@type (fun(pos:Position, elapsed:number): boolean)?
Callbacks.on_timer = function(pos, elapsed, node, timeout) Callbacks.on_timer = nil
end
---fields = {name1 = value1, name2 = value2, ...} ---fields = {name1 = value1, name2 = value2, ...}
--- ---
@@ -170,61 +144,47 @@ end
---See `core.register_on_player_receive_fields` for more info. ---See `core.register_on_player_receive_fields` for more info.
--- ---
---default: nil ---default: nil
---@type nil | fun(pos :table, formname : string, fields : table, sender : any) ---@type fun(pos:Position, formname:string, fields:table, sender:Player)?
Callbacks.on_receive_fields = function(pos, formname, fields, sender) Callbacks.on_receive_fields = nil
end
---Called when a player wants to put something into the inventory. ---Called when a player wants to put something into the inventory.
--- ---
---Return value: number of items allowed to put. ---Return value: number of items allowed to put.
--- ---
---Return value -1: Allow and don't modify item count in inventory. ---Return value -1: Allow and don't modify item count in inventory.
---@type nil | fun(pos :table, from_list : string, from_index : number, to_list : string, to_index : number, count : number, player : table):number ---@type (fun(pos:Position, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): number)?
Callbacks.allow_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player) Callbacks.allow_metadata_inventory_move = nil
return -1
end
---Called when a player wants to take something out of the inventory. ---Called when a player wants to take something out of the inventory.
--- ---
---Return value: number of items allowed to take. ---Return value: number of items allowed to take.
--- ---
---Return value -1: Allow and don't modify item count in inventory. ---Return value -1: Allow and don't modify item count in inventory.
---@type nil | fun(pos : table, listname : string, index : number, stack : table, player : table):number ---@type (fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): number)?
Callbacks.allow_metadata_inventory_take = function(pos, listname, index, stack, player) Callbacks.allow_metadata_inventory_take = nil
return -1
end
---Called after the actual action has happened, according to what was allowed. ---Called after the actual action has happened, according to what was allowed.
--- ---
---No return value. ---No return value.
---@type nil | fun(pos : table, from_list : string, from_index : number, to_list : string, to_index : number, count : number, player : table) ---@type (fun(pos:Position, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): void)?
Callbacks.on_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player) Callbacks.on_metadata_inventory_move = nil
end
---Called after the actual action has happened, according to what was allowed. ---Called after the actual action has happened, according to what was allowed.
--- ---
---No return value. ---No return value.
---@type nil | fun(pos : table, listname : string, index : number, stack : table, player : table) ---@type (fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): void)?
Callbacks.on_metadata_inventory_put = function(pos, listname, index, stack, player) Callbacks.on_metadata_inventory_put = nil
end
---Called after the actual action has happened, according to what was allowed. ---Called after the actual action has happened, according to what was allowed.
--- ---
---No return value. ---No return value.
---@type nil | fun(pos : table, listname : string, index : number, stack : table, player : table) ---@type (fun(pos:Position, listname:string, index:number, stack:ItemStack, player:Player): void)?
Callbacks.on_metadata_inventory_take = function(pos, listname, index, stack, player) Callbacks.on_metadata_inventory_take = nil
end
---If defined, called when an explosion touches the node, instead of ---If defined, called when an explosion touches the node, instead of
---removing the node. ---removing the node.
---* `intensity`: 1.0 = mid range of regular TNT. ---* `intensity`: 1.0 = mid range of regular TNT.
---@type nil | fun(pos : table, intensity : number) ---@type (fun(pos:Position, intensity:number): void)?
Callbacks.on_blast = function(pos, intensity) Callbacks.on_blast = nil
end
return Callbacks return Callbacks

View File

@@ -16,7 +16,7 @@ Settings.drawtype = nil
---node. For torchlike, the image will start at the surface to which the ---node. For torchlike, the image will start at the surface to which the
---node "attaches". For the other drawtypes the image will be centered ---node "attaches". For the other drawtypes the image will be centered
---on the node. ---on the node.
---@type table? ---@type number?
Settings.visual_scale = nil Settings.visual_scale = nil
@@ -24,7 +24,7 @@ Settings.visual_scale = nil
---Textures of node: +Y, -Y, +X, -X, +Z, -Z. ---Textures of node: +Y, -Y, +X, -X, +Z, -Z.
--- ---
---List can be shortened to needed length. ---List can be shortened to needed length.
---@type table ---@type (string[]|TileDefinition[])?
Settings.tiles = {} Settings.tiles = {}
---Same as `tiles`, but these textures are drawn on top of the base ---Same as `tiles`, but these textures are drawn on top of the base
@@ -32,13 +32,13 @@ Settings.tiles = {}
---texture. If the texture name is an empty string, that overlay is not ---texture. If the texture name is an empty string, that overlay is not
---drawn. Since such tiles are drawn twice, it is not recommended to use ---drawn. Since such tiles are drawn twice, it is not recommended to use
---overlays on very common nodes. ---overlays on very common nodes.
---@type table? ---@type (string[]|TileDefinition[])?
Settings.overlay_tiles = nil Settings.overlay_tiles = nil
---Special textures of node; used rarely. ---Special textures of node; used rarely.
--- ---
---List can be shortened to needed length. ---List can be shortened to needed length.
---@type table? ---@type (string[]|TileDefinition[])?
Settings.special_tiles = nil Settings.special_tiles = nil
@@ -46,7 +46,7 @@ Settings.special_tiles = nil
---The node's original color will be multiplied with this color. ---The node's original color will be multiplied with this color.
---If the node has a palette, then this setting only has an effect in ---If the node has a palette, then this setting only has an effect in
---the inventory and on the wield item. ---the inventory and on the wield item.
---@type string? ---@type (string|ColorSpec)?
Settings.color = nil Settings.color = nil
---Specifies how the texture's alpha channel will be used for rendering. ---Specifies how the texture's alpha channel will be used for rendering.
@@ -329,8 +329,7 @@ Settings.waving = nil
---Definition of node sounds to be played at various events. ---Definition of node sounds to be played at various events.
---All fields in this table are optional. ---All fields in this table are optional.
--- ---
--- TODO: вписать специализированный тип с аннотациями ---@type nil|table<string,SimpleSoundSpec|string?>
---@type table?
Settings.sounds = nil Settings.sounds = nil
---Name of dropped item when dug. ---Name of dropped item when dug.