From 80f07f26ccdeaae7fb95c17f14bc40073da5cea0 Mon Sep 17 00:00:00 2001 From: alek13 Date: Fri, 4 Oct 2024 20:08:13 +0300 Subject: [PATCH] `ide-helper`: improve `NodeDefinition` & `ObjectProperties` --- definitions/NodeDefinition.lua | 659 +++++++++++++++++-------------- definitions/ObjectProperties.lua | 249 +++++++----- 2 files changed, 511 insertions(+), 397 deletions(-) diff --git a/definitions/NodeDefinition.lua b/definitions/NodeDefinition.lua index 74a086c..66cc4d5 100644 --- a/definitions/NodeDefinition.lua +++ b/definitions/NodeDefinition.lua @@ -1,20 +1,24 @@ --- @class NodeDefinition: ItemDefinition local NodeDefinition = { - drawtype = "normal", -- See "Node drawtypes" + --- See "Node drawtypes" + --- @type string + drawtype = "normal", + --- Supported for drawtypes "plantlike", "signlike", "torchlike", + --- "firelike", "mesh", "nodebox", "allfaces". + --- For plantlike and firelike, the image will start at the bottom of 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 + --- on the node. + --- @type number visual_scale = 1.0, - -- Supported for drawtypes "plantlike", "signlike", "torchlike", - -- "firelike", "mesh", "nodebox", "allfaces". - -- For plantlike and firelike, the image will start at the bottom of 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 - -- on the node. --- {tile definition 1, def2, def3, def4, def5, def6} --- --- Textures of node; +Y, -Y, +X, -X, +Z, -Z --- List can be shortened to needed length. + --- @type string[] tiles = nil, --- {tile definition 1, def2, def3, def4, def5, def6} @@ -24,433 +28,506 @@ local NodeDefinition = { --- 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 string[] overlay_tiles = nil, --- {tile definition 1, Tile definition 2}, --- Special textures of node; used rarely. --- List can be shortened to needed length. + --- @type string[] special_tiles = nil, - color = ColorSpec, - -- 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. + --- 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. + --- @see ColorSpec + --- @type string|ColorSpec + color = '', - use_texture_alpha = ..., - -- Specifies how the texture's alpha channel will be used for rendering. - -- possible values: - -- * "opaque": Node is rendered opaque regardless of alpha channel - -- * "clip": A given pixel is either fully see-through or opaque - -- depending on the alpha channel being below/above 50% in value - -- * "blend": The alpha channel specifies how transparent a given pixel - -- of the rendered node is - -- The default is "opaque" for drawtypes normal, liquid and flowingliquid; - -- "clip" otherwise. - -- If set to a boolean value (deprecated): true either sets it to blend - -- or clip, false sets it to clip or opaque mode depending on the drawtype. + --- Specifies how the texture's alpha channel will be used for rendering. + --- possible values: + --- * "opaque": Node is rendered opaque regardless of alpha channel + --- * "clip": A given pixel is either fully see-through or opaque + --- depending on the alpha channel being below/above 50% in value + --- * "blend": The alpha channel specifies how transparent a given pixel + --- of the rendered node is + --- The default is "opaque" for drawtypes normal, liquid and flowingliquid; + --- "clip" otherwise. + --- If set to a boolean value (deprecated): true either sets it to blend + --- or clip, false sets it to clip or opaque mode depending on the drawtype. + --- @type string + use_texture_alpha = "opaque", + --- The node's `param2` is used to select a pixel from the image. + --- Pixels are arranged from left to right and from top to bottom. + --- The node's color will be multiplied with the selected pixel's color. + --- Tiles can override this behavior. + --- Only when `paramtype2` supports palettes. + --- @type string palette = "", - -- The node's `param2` is used to select a pixel from the image. - -- Pixels are arranged from left to right and from top to bottom. - -- The node's color will be multiplied with the selected pixel's color. - -- Tiles can override this behavior. - -- Only when `paramtype2` supports palettes. + --- Screen tint if player is inside node, see "ColorSpec" + --- @type string post_effect_color = "#00000000", - -- Screen tint if player is inside node, see "ColorSpec" - paramtype = "none", -- See "Nodes" + --- See "Nodes" + --- @type string + paramtype = "none", - paramtype2 = "none", -- See "Nodes" + --- See "Nodes" + --- @type string + paramtype2 = "none", + --- Value for param2 that is set when player places node + --- @type number place_param2 = 0, - -- Value for param2 that is set when player places node + --- If false, the cave generator and dungeon generator will not carve + --- through this node. + --- Specifically, this stops mod-added nodes being removed by caves and + --- dungeons when those generate in a neighbor mapchunk and extend out + --- beyond the edge of that mapchunk. + --- @type boolean is_ground_content = true, - -- If false, the cave generator and dungeon generator will not carve - -- through this node. - -- Specifically, this stops mod-added nodes being removed by caves and - -- dungeons when those generate in a neighbor mapchunk and extend out - -- beyond the edge of that mapchunk. + --- If true, sunlight will go infinitely through this node + --- @type boolean sunlight_propagates = false, - -- If true, sunlight will go infinitely through this node - walkable = true, -- If true, objects collide with node + --- If true, objects collide with node + --- @type boolean + walkable = true, - pointable = true, -- If true, can be pointed at + --- If true, can be pointed at + --- @type boolean + pointable = true, - diggable = true, -- If false, can never be dug + --- If false, can never be dug + --- @type boolean + diggable = true, - climbable = false, -- If true, can be climbed on like a ladder + --- If true, can be climbed on like a ladder + --- @type boolean + climbable = false, + --- Slows down movement of players through this node (max. 7). + --- If this is nil, it will be equal to liquid_viscosity. + --- Note: If liquid movement physics apply to the node + --- (see `liquid_move_physics`), the movement speed will also be + --- affected by the `movement_liquid_*` settings. + --- @type number move_resistance = 0, - -- Slows down movement of players through this node (max. 7). - -- If this is nil, it will be equal to liquid_viscosity. - -- Note: If liquid movement physics apply to the node - -- (see `liquid_move_physics`), the movement speed will also be - -- affected by the `movement_liquid_*` settings. - buildable_to = false, -- If true, placed nodes can replace this node + --- If true, placed nodes can replace this node + --- @type boolean + buildable_to = false, + --- If true, liquids flow into and replace this node. + --- Warning: making a liquid node 'floodable' will cause problems. + --- @type boolean floodable = false, - -- If true, liquids flow into and replace this node. - -- Warning: making a liquid node 'floodable' will cause problems. - liquidtype = "none", -- specifies liquid flowing physics - -- * "none": no liquid flowing physics - -- * "source": spawns flowing liquid nodes at all 4 sides and below; - -- recommended drawtype: "liquid". - -- * "flowing": spawned from source, spawns more flowing liquid nodes - -- around it until `liquid_range` is reached; - -- will drain out without a source; - -- recommended drawtype: "flowingliquid". - -- If it's "source" or "flowing", then the - -- `liquid_alternative_*` fields _must_ be specified + --- specifies liquid flowing physics + --- * "none": no liquid flowing physics + --- * "source": spawns flowing liquid nodes at all 4 sides and below; + --- recommended drawtype: "liquid". + --- * "flowing": spawned from source, spawns more flowing liquid nodes + --- around it until `liquid_range` is reached; + --- will drain out without a source; + --- recommended drawtype: "flowingliquid". + --- If it's "source" or "flowing", then the + --- `liquid_alternative_*` fields _must_ be specified + --- @type string + liquidtype = "none", + --- These fields may contain node names that represent the + --- flowing version (`liquid_alternative_flowing`) and + --- source version (`liquid_alternative_source`) of a liquid. + --- + --- Specifically, these fields are required if any of these is true: + --- * `liquidtype ~= "none" or + --- * `drawtype == "liquid" or + --- * `drawtype == "flowingliquid" + --- + --- Liquids consist of up to two nodes: source and flowing. + --- + --- There are two ways to define a liquid: + --- 1) Source node and flowing node. This requires both fields to be + --- specified for both nodes. + --- 2) Standalone source node (cannot flow). `liquid_alternative_source` + --- must be specified and `liquid_range` must be set to 0. + --- + --- Example: + --- liquid_alternative_flowing = "example:water_flowing", + --- liquid_alternative_source = "example:water_source", + --- @type string liquid_alternative_flowing = "", + + --- These fields may contain node names that represent the + --- flowing version (`liquid_alternative_flowing`) and + --- source version (`liquid_alternative_source`) of a liquid. + --- + --- Specifically, these fields are required if any of these is true: + --- * `liquidtype ~= "none" or + --- * `drawtype == "liquid" or + --- * `drawtype == "flowingliquid" + --- + --- Liquids consist of up to two nodes: source and flowing. + --- + --- There are two ways to define a liquid: + --- 1) Source node and flowing node. This requires both fields to be + --- specified for both nodes. + --- 2) Standalone source node (cannot flow). `liquid_alternative_source` + --- must be specified and `liquid_range` must be set to 0. + --- + --- Example: + --- liquid_alternative_flowing = "example:water_flowing", + --- liquid_alternative_source = "example:water_source", + --- @type string liquid_alternative_source = "", - -- These fields may contain node names that represent the - -- flowing version (`liquid_alternative_flowing`) and - -- source version (`liquid_alternative_source`) of a liquid. - -- - -- Specifically, these fields are required if any of these is true: - -- * `liquidtype ~= "none" or - -- * `drawtype == "liquid" or - -- * `drawtype == "flowingliquid" - -- - -- Liquids consist of up to two nodes: source and flowing. - -- - -- There are two ways to define a liquid: - -- 1) Source node and flowing node. This requires both fields to be - -- specified for both nodes. - -- 2) Standalone source node (cannot flow). `liquid_alternative_source` - -- must be specified and `liquid_range` must be set to 0. - -- - -- Example: - -- liquid_alternative_flowing = "example:water_flowing", - -- liquid_alternative_source = "example:water_source", + --- Controls speed at which the liquid spreads/flows (max. 7). + --- 0 is fastest, 7 is slowest. + --- By default, this also slows down movement of players inside the node + --- (can be overridden using `move_resistance`) + --- @type number liquid_viscosity = 0, - -- Controls speed at which the liquid spreads/flows (max. 7). - -- 0 is fastest, 7 is slowest. - -- By default, this also slows down movement of players inside the node - -- (can be overridden using `move_resistance`) + --- If true, a new liquid source can be created by placing two or more + --- sources nearby + --- @type boolean liquid_renewable = true, - -- If true, a new liquid source can be created by placing two or more - -- sources nearby - liquid_move_physics = nil, -- specifies movement physics if inside node - -- * false: No liquid movement physics apply. - -- * true: Enables liquid movement physics. Enables things like - -- ability to "swim" up/down, sinking slowly if not moving, - -- smoother speed change when falling into, etc. The `movement_liquid_*` - -- settings apply. - -- * nil: Will be treated as true if `liquidtype ~= "none"` - -- and as false otherwise. + --- specifies movement physics if inside node + --- * false: No liquid movement physics apply. + --- * true: Enables liquid movement physics. Enables things like + --- ability to "swim" up/down, sinking slowly if not moving, + --- smoother speed change when falling into, etc. The `movement_liquid_*` + --- settings apply. + --- * nil: Will be treated as true if `liquidtype ~= "none"` + --- and as false otherwise. + --- @type boolean|nil + liquid_move_physics = nil, + --- Only valid for "nodebox" drawtype with 'type = "leveled"'. + --- Allows defining the nodebox height without using param2. + --- The nodebox height is 'leveled' / 64 nodes. + --- The maximum value of 'leveled' is `leveled_max`. + --- @type number leveled = 0, - -- Only valid for "nodebox" drawtype with 'type = "leveled"'. - -- Allows defining the nodebox height without using param2. - -- The nodebox height is 'leveled' / 64 nodes. - -- The maximum value of 'leveled' is `leveled_max`. + --- Maximum value for `leveled` (0-127), enforced in + --- `minetest.set_node_level` and `minetest.add_node_level`. + --- Values above 124 might causes collision detection issues. + --- @type number leveled_max = 127, - -- Maximum value for `leveled` (0-127), enforced in - -- `minetest.set_node_level` and `minetest.add_node_level`. - -- Values above 124 might causes collision detection issues. + --- Maximum distance that flowing liquid nodes can spread around + --- source on flat land; + --- maximum = 8; set to 0 to disable liquid flow + --- @type number liquid_range = 8, - -- Maximum distance that flowing liquid nodes can spread around - -- source on flat land; - -- maximum = 8; set to 0 to disable liquid flow + --- Player will take this amount of damage if no bubbles are left + --- @type number drowning = 0, - -- Player will take this amount of damage if no bubbles are left + --- If player is inside node, this damage is caused + --- @type number damage_per_second = 0, - -- If player is inside node, this damage is caused - node_box = {type = "regular"}, -- See "Node boxes" + --- See "Node boxes" + node_box = {type = "regular"}, + --- Used for nodebox nodes with the type == "connected". + --- Specifies to what neighboring nodes connections will be drawn. + --- e.g. `{"group:fence", "default:wood"}` or `"default:stone"` + --- @type string[] connects_to = {}, - -- Used for nodebox nodes with the type == "connected". - -- Specifies to what neighboring nodes connections will be drawn. - -- e.g. `{"group:fence", "default:wood"}` or `"default:stone"` + --- Tells connected nodebox nodes to connect only to these sides of this + --- node. possible: "top", "bottom", "front", "left", "back", "right" + --- @type string[] connect_sides = {}, - -- Tells connected nodebox nodes to connect only to these sides of this - -- node. possible: "top", "bottom", "front", "left", "back", "right" + --- File name of mesh when using "mesh" drawtype + --- @type string mesh = "", - -- File name of mesh when using "mesh" drawtype - selection_box = { - -- see [Node boxes] for possibilities - }, - -- Custom selection box definition. Multiple boxes can be defined. - -- If "nodebox" drawtype is used and selection_box is nil, then node_box - -- definition is used for the selection box. + --- Custom selection box definition. Multiple boxes can be defined. + --- If "nodebox" drawtype is used and selection_box is nil, then node_box + --- definition is used for the selection box. + --- see [Node boxes] for possibilities + selection_box = {}, - collision_box = { - -- see [Node boxes] for possibilities - }, - -- Custom collision box definition. Multiple boxes can be defined. - -- If "nodebox" drawtype is used and collision_box is nil, then node_box - -- definition is used for the collision box. + --- see [Node boxes] for possibilities + --- Custom collision box definition. Multiple boxes can be defined. + --- If "nodebox" drawtype is used and collision_box is nil, then node_box + --- definition is used for the collision box. + collision_box = {}, - -- Support maps made in and before January 2012 + --- Support maps made in and before January 2012 + --- @type boolean legacy_facedir_simple = false, + --- Support maps made in and before January 2012 + --- @type boolean legacy_wallmounted = false, + --- Valid for drawtypes: + --- mesh, nodebox, plantlike, allfaces_optional, liquid, flowingliquid. + --- 1 - wave node like plants (node top moves side-to-side, bottom is fixed) + --- 2 - wave node like leaves (whole node moves side-to-side) + --- 3 - wave node like liquids (whole node moves up and down) + --- Not all models will properly wave. + --- plantlike drawtype can only wave like plants. + --- allfaces_optional drawtype can only wave like leaves. + --- liquid, flowingliquid drawtypes can only wave like liquids. + --- @type number waving = 0, - -- Valid for drawtypes: - -- mesh, nodebox, plantlike, allfaces_optional, liquid, flowingliquid. - -- 1 - wave node like plants (node top moves side-to-side, bottom is fixed) - -- 2 - wave node like leaves (whole node moves side-to-side) - -- 3 - wave node like liquids (whole node moves up and down) - -- Not all models will properly wave. - -- plantlike drawtype can only wave like plants. - -- allfaces_optional drawtype can only wave like leaves. - -- liquid, flowingliquid drawtypes can only wave like liquids. + --- Definition of node sounds to be played at various events. + --- All fields in this table are optional. sounds = { - -- Definition of node sounds to be played at various events. - -- All fields in this table are optional. + --- If walkable, played when object walks on it. If node is + --- climbable or a liquid, played when object moves through it --- @type SimpleSoundSpec footstep = nil, - -- If walkable, played when object walks on it. If node is - -- climbable or a liquid, played when object moves through it + --- While digging node. + --- If `"__group"`, then the sound will be + --- `{name = "default_dig_", gain = 0.5}` , where `` is the + --- name of the item's digging group with the fastest digging time. + --- In case of a tie, one of the sounds will be played (but we + --- cannot predict which one) + --- Default value: `"__group"` --- @type SimpleSoundSpec|string dig = {} or "__group", - -- While digging node. - -- If `"__group"`, then the sound will be - -- `{name = "default_dig_", gain = 0.5}` , where `` is the - -- name of the item's digging group with the fastest digging time. - -- In case of a tie, one of the sounds will be played (but we - -- cannot predict which one) - -- Default value: `"__group"` + --- Node was dug --- @type SimpleSoundSpec dug = nil, - -- Node was dug + --- Node was placed. Also played after falling --- @type SimpleSoundSpec place = nil, - -- Node was placed. Also played after falling + --- When node placement failed. + --- Note: This happens if the _built-in_ node placement failed. + --- This sound will still be played if the node is placed in the + --- `on_place` callback manually. --- @type SimpleSoundSpec place_failed = nil, - -- When node placement failed. - -- Note: This happens if the _built-in_ node placement failed. - -- This sound will still be played if the node is placed in the - -- `on_place` callback manually. + --- When node starts to fall or is detached --- @type SimpleSoundSpec fall = nil, - -- When node starts to fall or is detached }, - drop = "", - -- Name of dropped item when dug. - -- Default dropped item is the node itself. - - -- Using a table allows multiple items, drop chances and item filtering: + --- Name of dropped item when dug. + --- Default dropped item is the node itself. + --- Using a table allows multiple items, drop chances and item filtering: drop = { + --- Maximum number of item lists to drop. + --- The entries in 'items' are processed in order. For each: + --- Item filtering is applied, chance of drop is applied, if both are + --- successful the entire item list is dropped. + --- Entry processing continues until the number of dropped item lists + --- equals 'max_items'. + --- Therefore, entries should progress from low to high drop chance. + --- @type number max_items = 1, - -- Maximum number of item lists to drop. - -- The entries in 'items' are processed in order. For each: - -- Item filtering is applied, chance of drop is applied, if both are - -- successful the entire item list is dropped. - -- Entry processing continues until the number of dropped item lists - -- equals 'max_items'. - -- Therefore, entries should progress from low to high drop chance. - items = { - -- Examples: - { - -- 1 in 1000 chance of dropping a diamond. - -- Default rarity is '1'. - rarity = 1000, - items = {"default:diamond"}, - }, - { - -- Only drop if using an item whose name is identical to one - -- of these. - tools = {"default:shovel_mese", "default:shovel_diamond"}, - rarity = 5, - items = {"default:dirt"}, - -- Whether all items in the dropped item list inherit the - -- hardware coloring palette color from the dug node. - -- Default is 'false'. - inherit_color = true, - }, - { - -- Only drop if using an item whose name contains - -- "default:shovel_" (this item filtering by string matching - -- is deprecated, use tool_groups instead). - tools = {"~default:shovel_"}, - rarity = 2, - -- The item list dropped. - items = {"default:sand", "default:desert_sand"}, - }, - { - -- Only drop if using an item in the "magicwand" group, or - -- an item that is in both the "pickaxe" and the "lucky" - -- groups. - tool_groups = { - "magicwand", - {"pickaxe", "lucky"} - }, - items = {"default:coal_lump"}, - }, - }, + ---- Examples: + --- ```lua + --- { + --- -- 1 in 1000 chance of dropping a diamond. + --- -- Default rarity is '1'. + --- rarity = 1000, + --- items = {"default:diamond"}, + --- }, + --- { + --- -- Only drop if using an item whose name is identical to one + --- -- of these. + --- tools = {"default:shovel_mese", "default:shovel_diamond"}, + --- rarity = 5, + --- items = {"default:dirt"}, + --- -- Whether all items in the dropped item list inherit the + --- -- hardware coloring palette color from the dug node. + --- -- Default is 'false'. + --- inherit_color = true, + --- }, + --- { + --- -- Only drop if using an item whose name contains + --- -- "default:shovel_" (this item filtering by string matching + --- -- is deprecated, use tool_groups instead). + --- tools = {"~default:shovel_"}, + --- rarity = 2, + --- -- The item list dropped. + --- items = {"default:sand", "default:desert_sand"}, + --- }, + --- { + --- -- Only drop if using an item in the "magicwand" group, or + --- -- an item that is in both the "pickaxe" and the "lucky" + --- -- groups. + --- tool_groups = { + --- "magicwand", + --- {"pickaxe", "lucky"} + --- }, + --- items = {"default:coal_lump"}, + --- }, + --- ``` + items = {}, }, + --- Node constructor; called after adding node. + --- Can set up metadata and stuff like that. + --- Not called for bulk node placement (i.e. schematics and `VoxelManip`). + --- Note: Within an on_construct callback, minetest.set_node can cause an + --- infinite loop if it invokes the same callback. + --- Consider using `minetest.swap_node()` instead. + --- default: nil --- @type fun(pos:Position) on_construct = nil, - -- Node constructor; called after adding node. - -- Can set up metadata and stuff like that. - -- Not called for bulk node placement (i.e. schematics and VoxelManip). - -- Note: Within an on_construct callback, minetest.set_node can cause an - -- infinite loop if it invokes the same callback. - -- Consider using minetest.swap_node instead. - -- default: nil + --- Node destructor; called before removing node. + --- Not called for bulk node placement. + --- default: nil --- @type fun(pos:Position) on_destruct = nil, - -- Node destructor; called before removing node. - -- Not called for bulk node placement. - -- default: nil - --- @type fun(pos:Position, oldnode) + --- Node destructor; called after removing node. + --- Not called for bulk node placement. + --- default: nil + --- @type fun(pos:Position, old_node) after_destruct = nil, - -- Node destructor; called after removing node. - -- Not called for bulk node placement. - -- default: nil - --- @type fun(pos:Position, oldnode, newnode) + --- Called when a liquid (new_node) is about to flood old_node, if it has + --- `floodable = true` in the nodedef. Not called for bulk node placement + --- (i.e. schematics and `VoxelManip`) or air nodes. If return true the + --- node is not flooded, but on_flood callback will most likely be called + --- over and over again every liquid update interval. + --- Default: nil + --- Warning: making a liquid node 'floodable' will cause problems. + --- @type fun(pos:Position, old_node, new_node) on_flood = 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 - -- (i.e. schematics and VoxelManip) or air nodes. If return true the - -- node is not flooded, but on_flood callback will most likely be called - -- over and over again every liquid update interval. - -- Default: nil - -- Warning: making a liquid node 'floodable' will cause problems. - --- @type fun(pos:Position, oldnode, newnode, oldmeta, drops:ItemStack[]) + --- Called when `old_node` is about be converted to an item, but before the + --- node is deleted from the world or the drops are added. This is + --- generally the result of either the node being dug or an attached node + --- becoming detached. + --- `old_meta` are the metadata fields (table) of the node before deletion. + --- drops is a table of `ItemStacks`, so any metadata to be preserved can + --- be added directly to one or more of the dropped items. + --- @see ItemStackMetaRef + --- default: nil + --- @type fun(pos:Position, old_node, new_node, old_meta, drops:ItemStack[]) preserve_metadata = nil, - -- Called when oldnode is about be converted to an item, but before the - -- node is deleted from the world or the drops are added. This is - -- generally the result of either the node being dug or an attached node - -- becoming detached. - -- oldmeta are the metadata fields (table) of the node before deletion. - -- drops is a table of ItemStacks, so any metadata to be preserved can - -- be added directly to one or more of the dropped items. See - -- "ItemStackMetaRef". - -- default: nil + --- Called after constructing node when node was placed using + --- minetest.item_place_node / minetest.place_node. + --- If return true no item is taken from itemstack. + --- `placer` may be any valid ObjectRef or nil. + --- default: nil --- @type fun(pos:Position, placer:Player|ObjectRef|nil, itemstack:ItemStack, pointed_thing:pointed_thing) after_place_node = nil, - -- Called after constructing node when node was placed using - -- minetest.item_place_node / minetest.place_node. - -- If return true no item is taken from itemstack. - -- `placer` may be any valid ObjectRef or nil. - -- default: nil + --- oldmetadata is in table format. + --- Called after destructing node when node was dug using + --- minetest.node_dig / minetest.dig_node. + --- default: nil --- @type fun(pos:Player, oldnode, oldmetadata, digger:Player|ObjectRef|nil) after_dig_node = nil, - -- oldmetadata is in table format. - -- Called after destructing node when node was dug using - -- minetest.node_dig / minetest.dig_node. - -- default: nil + --- Returns true if node can be dug, or false if not. + --- default: nil --- @type fun(pos:Position, player:Player|ObjectRef|nil) can_dig = nil, - -- Returns true if node can be dug, or false if not. - -- default: nil + --- default: minetest.node_punch + --- Called when puncher (an ObjectRef) punches the node at pos. + --- By default calls minetest.register_on_punchnode callbacks. --- @type fun(pos:Position, node, puncher:Player|ObjectRef|nil, pointed_thing:pointed_thing) on_punch = nil, - -- default: minetest.node_punch - -- Called when puncher (an ObjectRef) punches the node at pos. - -- By default calls minetest.register_on_punchnode callbacks. + --- default: nil + --- Called when clicker (an ObjectRef) used the 'place/build' key + --- (not necessarily an actual rightclick) + --- while pointing at the node at pos with 'node' being the node table. + --- itemstack will hold clicker's wielded item. + --- Shall return the leftover itemstack. + --- Note: pointed_thing can be nil, if a mod calls this function. + --- This function does not get triggered by clients <=0.4.16 if the + --- "formspec" node metadata field is set. --- @type fun (pos:Position, node, clicker:Player|ObjectRef|nil, itemstack:ItemStack, pointed_thing:pointed_thing) on_rightclick = nil, - -- default: nil - -- Called when clicker (an ObjectRef) used the 'place/build' key - -- (not necessarily an actual rightclick) - -- while pointing at the node at pos with 'node' being the node table. - -- itemstack will hold clicker's wielded item. - -- Shall return the leftover itemstack. - -- Note: pointed_thing can be nil, if a mod calls this function. - -- This function does not get triggered by clients <=0.4.16 if the - -- "formspec" node metadata field is set. + --- default: minetest.node_dig + --- By default checks privileges, wears out item (if tool) and removes node. + --- return true if the node was dug successfully, false otherwise. + --- Deprecated: returning nil is the same as returning true. --- @type fun(pos, node, digger) on_dig = nil, - -- default: minetest.node_dig - -- By default checks privileges, wears out item (if tool) and removes node. - -- return true if the node was dug successfully, false otherwise. - -- Deprecated: returning nil is the same as returning true. + --- default: nil + --- called by NodeTimers, see minetest.get_node_timer and NodeTimerRef. + --- elapsed is the total time passed since the timer was started. + --- return true to run the timer for another cycle with the same timeout + --- value. --- @type fun(pos, elapsed) on_timer = nil, - -- default: nil - -- called by NodeTimers, see minetest.get_node_timer and NodeTimerRef. - -- elapsed is the total time passed since the timer was started. - -- return true to run the timer for another cycle with the same timeout - -- value. + --- fields = {name1 = value1, name2 = value2, ...} + --- Called when an UI form (e.g. sign text input) returns data. + --- See minetest.register_on_player_receive_fields for more info. + --- default: nil --- @type fun(pos, formname, fields, sender) on_receive_fields = nil, - -- fields = {name1 = value1, name2 = value2, ...} - -- Called when an UI form (e.g. sign text input) returns data. - -- See minetest.register_on_player_receive_fields for more info. - -- default: nil + --- Called when a player wants to move items inside the inventory. + --- Return value: number of items allowed to move. --- @type fun(pos, from_list, from_index, to_list, to_index, count, player) allow_metadata_inventory_move = nil, - -- Called when a player wants to move items inside the inventory. - -- Return value: number of items allowed to move. + --- 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 fun(pos, listname, index, stack, player) allow_metadata_inventory_put = 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. + --- 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 fun(pos, listname, index, stack, player) allow_metadata_inventory_take = 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. + --- Called after the actual action has happened, according to what was + --- allowed. + --- No return value. --- @type fun(pos, from_list, from_index, to_list, to_index, count, player) on_metadata_inventory_move = nil, + --- Called after the actual action has happened, according to what was + --- allowed. + --- No return value. --- @type fun(pos, listname, index, stack, player) on_metadata_inventory_put = nil, + --- Called after the actual action has happened, according to what was + --- allowed. + --- No return value. --- @type fun(pos, listname, index, stack, player) on_metadata_inventory_take = nil, - -- Called after the actual action has happened, according to what was - -- allowed. - -- No return value. + --- intensity: 1.0 = mid range of regular TNT. + --- If defined, called when an explosion touches the node, instead of + --- removing the node. --- @type fun (pos, intensity) on_blast = nil, - -- intensity: 1.0 = mid range of regular TNT. - -- If defined, called when an explosion touches the node, instead of - -- removing the node. + --- stores which mod actually registered a node + --- If the source could not be determined it contains "??" + --- Useful for getting which mod truly registered something + --- example: if a node is registered as ":othermodname:nodename", + --- nodename will show "othermodname", but mod_origin will say "modname" + --- @type string mod_origin = "modname", - -- stores which mod actually registered a node - -- If the source could not be determined it contains "??" - -- Useful for getting which mod truly registered something - -- example: if a node is registered as ":othermodname:nodename", - -- nodename will show "othermodname", but mod_origin will say "modname" } diff --git a/definitions/ObjectProperties.lua b/definitions/ObjectProperties.lua index 920c31b..a80383d 100644 --- a/definitions/ObjectProperties.lua +++ b/definitions/ObjectProperties.lua @@ -1,171 +1,208 @@ --- @class ObjectProperties local ObjectProperties = { + --- Defines the maximum and default HP of the entity + --- For Lua entities the maximum is not enforced. + --- For players this defaults to `minetest.PLAYER_MAX_HP_DEFAULT`. + --- @type number hp_max = 10, - -- Defines the maximum and default HP of the entity - -- For Lua entities the maximum is not enforced. - -- For players this defaults to `minetest.PLAYER_MAX_HP_DEFAULT`. + --- For players only. Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT`. + --- @type number breath_max = 0, - -- For players only. Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT`. + --- For players only. Zoom FOV in degrees. + --- Note that zoom loads and/or generates world beyond the server's + --- maximum send and generate distances, so acts like a telescope. + --- Smaller zoom_fov values increase the distance loaded/generated. + --- Defaults to 15 in creative mode, 0 in survival mode. + --- zoom_fov = 0 disables zooming for the player. + --- @type number zoom_fov = 0.0, - -- For players only. Zoom FOV in degrees. - -- Note that zoom loads and/or generates world beyond the server's - -- maximum send and generate distances, so acts like a telescope. - -- Smaller zoom_fov values increase the distance loaded/generated. - -- Defaults to 15 in creative mode, 0 in survival mode. - -- zoom_fov = 0 disables zooming for the player. + --- For players only. Camera height above feet position in nodes. + --- @type number eye_height = 1.625, - -- For players only. Camera height above feet position in nodes. + --- Collide with `walkable` nodes. + --- @type boolean physical = false, - -- Collide with `walkable` nodes. + --- Collide with other objects if physical = true + --- @type boolean collide_with_objects = true, - -- Collide with other objects if physical = true - collisionbox = { -0.5, -0.5, -0.5, 0.5, 0.5, 0.5 }, -- default + --- { xmin, ymin, zmin, xmax, ymax, zmax } in nodes from object position. + --- Collision boxes cannot rotate, setting `rotate = true` on it has no effect. + --- If not set, the selection box copies the collision box, and will also not rotate. + --- default: `{ -0.5, -0.5, -0.5, 0.5, 0.5, 0.5 }` + --- @type number[] + collisionbox = { -0.5, -0.5, -0.5, 0.5, 0.5, 0.5 }, + --- { xmin, ymin, zmin, xmax, ymax, zmax } in nodes from object position. + --- Collision boxes cannot rotate, setting `rotate = true` on it has no effect. + --- If not set, the selection box copies the collision box, and will also not rotate. + --- If `rotate = false`, the selection box will not rotate with the object itself, remaining fixed to the axes. + --- If `rotate = true`, it will match the object's rotation and any attachment rotations. + --- Raycasts use the selection box and object's rotation, but do *not* obey attachment rotations. + --- For server-side raycasts to work correctly, + --- the selection box should extend at most 5 units in each direction. + --- @type number[]|{rotate:boolean} selectionbox = { -0.5, -0.5, -0.5, 0.5, 0.5, 0.5, rotate = false }, - -- { xmin, ymin, zmin, xmax, ymax, zmax } in nodes from object position. - -- Collision boxes cannot rotate, setting `rotate = true` on it has no effect. - -- If not set, the selection box copies the collision box, and will also not rotate. - -- If `rotate = false`, the selection box will not rotate with the object itself, remaining fixed to the axes. - -- If `rotate = true`, it will match the object's rotation and any attachment rotations. - -- Raycasts use the selection box and object's rotation, but do *not* obey attachment rotations. - -- For server-side raycasts to work correctly, - -- the selection box should extend at most 5 units in each direction. - + --- Can be `true` if it is pointable, `false` if it can be pointed through, + --- or `"blocking"` if it is pointable but not selectable. + --- Clients older than 5.9.0 interpret `pointable = "blocking"` as `pointable = true`. + --- Can be overridden by the `pointabilities` of the held item. + --- @type boolean pointable = true, - -- Can be `true` if it is pointable, `false` if it can be pointed through, - -- or `"blocking"` if it is pointable but not selectable. - -- Clients older than 5.9.0 interpret `pointable = "blocking"` as `pointable = true`. - -- Can be overridden by the `pointabilities` of the held item. - visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem" / "item", - -- "cube" is a node-sized cube. - -- "sprite" is a flat texture always facing the player. - -- "upright_sprite" is a vertical flat texture. - -- "mesh" uses the defined mesh model. - -- "wielditem" is used for dropped items. - -- (see builtin/game/item_entity.lua). - -- For this use 'wield_item = itemname'. - -- Setting 'textures = {itemname}' has the same effect, but is deprecated. - -- If the item has a 'wield_image' the object will be an extrusion of - -- that, otherwise: - -- If 'itemname' is a cubic node or nodebox the object will appear - -- identical to 'itemname'. - -- If 'itemname' is a plantlike node the object will be an extrusion - -- of its texture. - -- Otherwise for non-node items, the object will be an extrusion of - -- 'inventory_image'. - -- If 'itemname' contains a ColorString or palette index (e.g. from - -- `minetest.itemstring_with_palette()`), the entity will inherit the color. - -- Wielditems are scaled a bit. If you want a wielditem to appear - -- to be as large as a node, use `0.667` in `visual_size` - -- "item" is similar to "wielditem" but ignores the 'wield_image' parameter. + --- `"cube"` / `"sprite"` / `"upright_sprite" / `"mesh" / `"wielditem"` / `"item"` + --- "cube" is a node-sized cube. + --- "sprite" is a flat texture always facing the player. + --- "upright_sprite" is a vertical flat texture. + --- "mesh" uses the defined mesh model. + --- "wielditem" is used for dropped items. + --- (see builtin/game/item_entity.lua). + --- For this use 'wield_item = itemname'. + --- Setting 'textures = {itemname}' has the same effect, but is deprecated. + --- If the item has a 'wield_image' the object will be an extrusion of + --- that, otherwise: + --- If 'itemname' is a cubic node or nodebox the object will appear + --- identical to 'itemname'. + --- If 'itemname' is a plantlike node the object will be an extrusion + --- of its texture. + --- Otherwise for non-node items, the object will be an extrusion of + --- 'inventory_image'. + --- If 'itemname' contains a ColorString or palette index (e.g. from + --- `minetest.itemstring_with_palette()`), the entity will inherit the color. + --- Wielditems are scaled a bit. If you want a wielditem to appear + --- to be as large as a node, use `0.667` in `visual_size` + --- "item" is similar to "wielditem" but ignores the 'wield_image' parameter. + --- @type string + visual = '', + --- Multipliers for the visual size. If `z` is not specified, `x` will be used + --- to scale the entity along both horizontal axes. + --- @type Position visual_size = {x = 1, y = 1, z = 1}, - -- Multipliers for the visual size. If `z` is not specified, `x` will be used - -- to scale the entity along both horizontal axes. + --- File name of mesh when using "mesh" visual + --- @type string mesh = "model.obj", - -- File name of mesh when using "mesh" visual + --- Number of required textures depends on visual. + --- "cube" uses 6 textures just like a node, but all 6 must be defined. + --- "sprite" uses 1 texture. + --- "upright_sprite" uses 2 textures: {front, back}. + --- "mesh" requires one texture for each mesh buffer/material (in order) + --- Deprecated usage of "wielditem" expects 'textures = {itemname}' (see 'visual' above). + --- @type string[] textures = {}, - -- Number of required textures depends on visual. - -- "cube" uses 6 textures just like a node, but all 6 must be defined. - -- "sprite" uses 1 texture. - -- "upright_sprite" uses 2 textures: {front, back}. - -- "mesh" requires one texture for each mesh buffer/material (in order) - -- Deprecated usage of "wielditem" expects 'textures = {itemname}' (see 'visual' above). + --- Number of required colors depends on visual + --- @type string[] colors = {}, - -- Number of required colors depends on visual + --- Use texture's alpha channel. + --- Excludes "upright_sprite" and "wielditem". + --- Note: currently causes visual issues when viewed through other + --- semi-transparent materials such as water. + --- @type boolean use_texture_alpha = false, - -- Use texture's alpha channel. - -- Excludes "upright_sprite" and "wielditem". - -- Note: currently causes visual issues when viewed through other - -- semi-transparent materials such as water. + --- Used with spritesheet textures for animation and/or frame selection + --- according to position relative to player. + --- Defines the number of columns and rows in the spritesheet: + --- {columns, rows}. + --- @type {x:number, y:number} spritediv = {x = 1, y = 1}, - -- Used with spritesheet textures for animation and/or frame selection - -- according to position relative to player. - -- Defines the number of columns and rows in the spritesheet: - -- {columns, rows}. + --- Used with spritesheet textures. + --- Defines the {column, row} position of the initially used frame in the + --- spritesheet. + --- @type {x:number, y:number} initial_sprite_basepos = {x = 0, y = 0}, - -- Used with spritesheet textures. - -- Defines the {column, row} position of the initially used frame in the - -- spritesheet. + --- If false, object is invisible and can't be pointed. + --- @type boolean is_visible = true, - -- If false, object is invisible and can't be pointed. + --- If true, is able to make footstep sounds of nodes + --- (see node sound definition for details). + --- @type boolean makes_footstep_sound = false, - -- If true, is able to make footstep sounds of nodes - -- (see node sound definition for details). + --- Set constant rotation in radians per second, positive or negative. + --- Object rotates along the local Y-axis, and works with set_rotation. + --- Set to 0 to disable constant rotation. + --- @type number automatic_rotate = 0, - -- Set constant rotation in radians per second, positive or negative. - -- Object rotates along the local Y-axis, and works with set_rotation. - -- Set to 0 to disable constant rotation. + --- If positive number, object will climb upwards when it moves + --- horizontally against a `walkable` node, if the height difference + --- is within `stepheight`. + --- @type number stepheight = 0, - -- If positive number, object will climb upwards when it moves - -- horizontally against a `walkable` node, if the height difference - -- is within `stepheight`. + --- Automatically set yaw to movement direction, offset in degrees. + --- 'false' to disable. + --- @type number automatic_face_movement_dir = 0.0, - -- Automatically set yaw to movement direction, offset in degrees. - -- 'false' to disable. + --- Limit automatic rotation to this value in degrees per second. + --- No limit if value <= 0. + --- @type number automatic_face_movement_max_rotation_per_sec = -1, - -- Limit automatic rotation to this value in degrees per second. - -- No limit if value <= 0. + --- Set to false to disable backface_culling for model + --- @type boolean backface_culling = true, - -- Set to false to disable backface_culling for model + --- Add this much extra lighting when calculating texture color. + --- Value < 0 disables light's effect on texture color. + --- For faking self-lighting, UI style entities, or programmatic coloring + --- in mods. + --- @type number glow = 0, - -- Add this much extra lighting when calculating texture color. - -- Value < 0 disables light's effect on texture color. - -- For faking self-lighting, UI style entities, or programmatic coloring - -- in mods. + --- The name to display on the head of the object. By default empty. + --- If the object is a player, a nil or empty nametag is replaced by the player's name. + --- For all other objects, a nil or empty string removes the nametag. + --- To hide a nametag, set its color alpha to zero. That will disable it entirely. + --- @type string nametag = "", - -- The name to display on the head of the object. By default empty. - -- If the object is a player, a nil or empty nametag is replaced by the player's name. - -- For all other objects, a nil or empty string removes the nametag. - -- To hide a nametag, set its color alpha to zero. That will disable it entirely. - --- @t ColorSpec + --- Sets text color of nametag. See ColorSpec + --- @type string nametag_color = "", - -- Sets text color of nametag + --- Sets background color of nametag. See ColorSpec + --- `false` will cause the background to be set automatically based on user settings. + --- Default: false + --- @type string|boolean nametag_bgcolor = "", - -- Sets background color of nametag - -- `false` will cause the background to be set automatically based on user settings. - -- Default: false + --- Same as infotext for nodes. Empty by default + --- @type string infotext = "", - -- Same as infotext for nodes. Empty by default + --- If false, never save this object statically. It will simply be + --- deleted when the block gets unloaded. + --- The get_staticdata() callback is never called then. + --- Defaults to 'true'. + --- @type boolean + --- @type string static_save = true, - -- If false, never save this object statically. It will simply be - -- deleted when the block gets unloaded. - -- The get_staticdata() callback is never called then. - -- Defaults to 'true'. + --- Texture modifier to be applied for a short duration when object is hit + --- @type string damage_texture_modifier = "^[brighten", - -- Texture modifier to be applied for a short duration when object is hit + --- Setting this to 'false' disables diffuse lighting of entity + --- @type boolean shaded = true, - -- Setting this to 'false' disables diffuse lighting of entity + --- Defaults to true for players, false for other entities. + --- If set to true the entity will show as a marker on the minimap. + --- @type boolean show_on_minimap = false, - -- Defaults to true for players, false for other entities. - -- If set to true the entity will show as a marker on the minimap. }