From 2ef2bb14bacec7cdd541426365cee57315e91b29 Mon Sep 17 00:00:00 2001 From: Vanic Date: Thu, 9 Oct 2025 21:26:46 +0300 Subject: [PATCH] Node: update settings & callbacks annotations --- mods/CORE/Node/src/Node/Callbacks.lua | 116 +++++++++----------------- mods/CORE/Node/src/Node/Settings.lua | 13 ++- 2 files changed, 44 insertions(+), 85 deletions(-) diff --git a/mods/CORE/Node/src/Node/Callbacks.lua b/mods/CORE/Node/src/Node/Callbacks.lua index 28068b3..2526385 100644 --- a/mods/CORE/Node/src/Node/Callbacks.lua +++ b/mods/CORE/Node/src/Node/Callbacks.lua @@ -1,8 +1,6 @@ ---@type Item.Callbacks local ItemCallbacks = Core.Item.require('Item.Callbacks') --- TODO: Разобраться с дубликатами аннотаций полей. Приоритетно брать аннотации из util/ide-helper - ---@class Node.Callbacks : Item.Callbacks local Callbacks = Mod:getClassExtended(ItemCallbacks, {}) @@ -15,20 +13,16 @@ local Callbacks = Mod:getClassExtended(ItemCallbacks, {}) --- ---default: nil ---* `pos`: node position ----@type nil | fun(pos : table) -Callbacks.on_construct = function(pos) - -end +---@type fun(pos:Position)? +Callbacks.on_construct = nil ---Node destructor; called before removing node. ---Not called for bulk node placement. --- ---default: nil ---* `pos`: node position ----@type nil | fun(pos : table) -Callbacks.on_destruct = function(pos) - -end +---@type fun(pos:Position)? +Callbacks.on_destruct = nil ---Node destructor; called after removing node. ---Not called for bulk node placement. @@ -36,10 +30,8 @@ end ---default: nil ---* `pos`: node position ---* `oldnode`: node table of node before it was deleted ----@type nil | fun(pos : table, oldnode : table) -Callbacks.after_destruct = function(pos, oldnode) - -end +---@type fun(pos:Position, old_node)? +Callbacks.after_destruct = nil ---Called when a liquid (newnode) is about to flood oldnode, if it has ---`floodable = true` in the nodedef. Not called for bulk node placement @@ -53,10 +45,8 @@ end ---* `pos`: table node position ---* `oldnode`: table node table of node before it was deleted ---* `newnode`: TODO: какой тут тип? ----@type nil | fun(pos : table, oldnode : table, newnode : any) -Callbacks.on_flood = function(pos, oldnode, newnode) - -end +---@type fun(pos:Position, old_node, new_node)? +Callbacks.on_flood = nil ---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 --- be added directly to one or more of the dropped items. See --- "ItemStackMetaRef". ----@type nil | fun(pos : table, oldnode : table, oldmeta : table, drops : any?) -Callbacks.preserve_metadata = function(pos, oldnode, oldmeta, drops) - -end +---@type fun(pos:Position, old_node, new_node, old_meta, drops:ItemStack[])? +Callbacks.preserve_metadata = nil ---Called after constructing node when node was placed using ---core.item_place_node / core.place_node. @@ -85,10 +73,8 @@ end ---* `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 nil | fun(pos : table, placer : table, itemstack : table, pointed_thing : table):boolean -Callbacks.after_place_node = function(pos, placer, itemstack, pointed_thing) - -end +---@type fun(pos:Position, 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 ---`core.node_dig` / `core.dig_node`. @@ -98,20 +84,16 @@ end ---* `oldnode`: node table of node before it was dug ---* `oldmetadata`: metadata of node before it was dug, as a metadata table ---* `digger`: ObjectRef of digger ----@type nil | fun(pos : table, oldnode : table, oldmetadata : table, digger : table) -Callbacks.after_dig_node = function(pos, oldnode, oldmetadata, digger) - -end +---@type fun(pos:Player, oldnode, oldmetadata, digger:Player|ObjectRef|nil)? +Callbacks.after_dig_node = nil ---Returns true if node can be dug, or false if not. --- ---default: nil ---* `pos`: node position ---* player: ObjectRef of digger TODO: в API было написано [player], это типо необязательный параметр? Я не понял ----@type nil | fun(pos : table, player : table?):boolean -Callbacks.can_dig = function(pos, player) - return true -end +---@type fun(pos:Position, player:Player|ObjectRef|nil)? +Callbacks.can_dig = nil ---Called when puncher (an ObjectRef) punches the node at pos. ---By default calls core.register_on_punchnode callbacks. @@ -121,10 +103,8 @@ end ---* `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 nil | fun(pos : table, node : table, puncher : table, pointed_thing : table) -Callbacks.on_punch = function(pos, node, puncher, pointed_thing) - core.node_punch(pos, node, puncher, pointed_thing) -end +---@type fun(pos:Position, node:NodeTable, puncher:Player|ObjectRef|nil, pointed_thing:pointed_thing)? +Callbacks.on_punch = nil ---Called when clicker (an ObjectRef) used the 'place/build' key ---(not necessarily an actual rightclick) @@ -135,10 +115,8 @@ end ---Note: pointed_thing can be nil, if a mod calls this function. --- ---default: nil ----@type nil | fun(pos : table, node : table, clicker : table, itemstack : table, pointing_thing : table?):table? -Callbacks.on_rightclick = function(pos, node, clicker, itemstack, pointed_thing) - -end +---@type (fun(pos:Position, node:NodeTable, clicker:Player|ObjectRef, itemstack:ItemStack, pointed_thing:pointed_thing|nil):ItemStack|nil)? +Callbacks.on_rightclick = core.node_punch ---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. --- ---default: core.node_dig ----@type nil | fun(pos : table, node : table, digger : table):boolean -Callbacks.on_dig = function(pos, node, digger) - core.node_dig(pos, node, digger) -end +---@type (fun(pos:Position, node:NodeTable, digger:Player): boolean)? +Callbacks.on_dig = minetest.node_dig ---called by NodeTimers, see core.get_node_timer and NodeTimerRef. ---* `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. --- ---default: nil ----@type nil | fun(pos : table, elapsed : number, node : table, timeout : any):boolean? -Callbacks.on_timer = function(pos, elapsed, node, timeout) - -end +---@type (fun(pos:Position, elapsed:number): boolean)? +Callbacks.on_timer = nil ---fields = {name1 = value1, name2 = value2, ...} --- @@ -170,61 +144,47 @@ end ---See `core.register_on_player_receive_fields` for more info. --- ---default: nil ----@type nil | fun(pos :table, formname : string, fields : table, sender : any) -Callbacks.on_receive_fields = function(pos, formname, fields, sender) - -end +---@type fun(pos:Position, formname:string, fields:table, sender:Player)? +Callbacks.on_receive_fields = nil ---Called when a player wants to put something into the inventory. --- ---Return value: number of items allowed to put. --- ---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 -Callbacks.allow_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player) - return -1 -end +---@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 = nil ---Called when a player wants to take something out of the inventory. --- ---Return value: number of items allowed to take. --- ---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 -Callbacks.allow_metadata_inventory_take = function(pos, listname, index, stack, player) - return -1 -end +---@type (fun(pos:Position, 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 nil | fun(pos : table, from_list : string, from_index : number, to_list : string, to_index : number, count : number, player : table) -Callbacks.on_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player) - -end +---@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 = nil ---Called after the actual action has happened, according to what was allowed. --- ---No return value. ----@type nil | fun(pos : table, listname : string, index : number, stack : table, player : table) -Callbacks.on_metadata_inventory_put = function(pos, listname, index, stack, player) - -end +---@type (fun(pos:Position, 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 nil | fun(pos : table, listname : string, index : number, stack : table, player : table) -Callbacks.on_metadata_inventory_take = function(pos, listname, index, stack, player) - -end +---@type (fun(pos:Position, 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 nil | fun(pos : table, intensity : number) -Callbacks.on_blast = function(pos, intensity) - -end +---@type (fun(pos:Position, intensity:number): void)? +Callbacks.on_blast = nil return Callbacks \ No newline at end of file diff --git a/mods/CORE/Node/src/Node/Settings.lua b/mods/CORE/Node/src/Node/Settings.lua index 6f9f84d..4ba0d09 100644 --- a/mods/CORE/Node/src/Node/Settings.lua +++ b/mods/CORE/Node/src/Node/Settings.lua @@ -16,7 +16,7 @@ Settings.drawtype = nil ---node. For torchlike, the image will start at the surface to which the ---node "attaches". For the other drawtypes the image will be centered ---on the node. ----@type table? +---@type number? Settings.visual_scale = nil @@ -24,7 +24,7 @@ Settings.visual_scale = nil ---Textures of node: +Y, -Y, +X, -X, +Z, -Z. --- ---List can be shortened to needed length. ----@type table +---@type (string[]|TileDefinition[])? Settings.tiles = {} ---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 ---drawn. Since such tiles are drawn twice, it is not recommended to use ---overlays on very common nodes. ----@type table? +---@type (string[]|TileDefinition[])? Settings.overlay_tiles = nil ---Special textures of node; used rarely. --- ---List can be shortened to needed length. ----@type table? +---@type (string[]|TileDefinition[])? Settings.special_tiles = nil @@ -46,7 +46,7 @@ Settings.special_tiles = nil ---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 ---the inventory and on the wield item. ----@type string? +---@type (string|ColorSpec)? Settings.color = nil ---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. ---All fields in this table are optional. --- ---- TODO: вписать специализированный тип с аннотациями ----@type table? +---@type nil|table Settings.sounds = nil ---Name of dropped item when dug.