From 4f8fe78b0a786d475a36b92a509fdb081e842220 Mon Sep 17 00:00:00 2001 From: varttist Date: Thu, 18 Jun 2026 21:51:27 +0300 Subject: [PATCH] Splitting `ItemDefinition` into settings and callbacks, updating annotations to 5.16 --- definitions/ItemDefinition.lua | 252 +---------------------- definitions/ItemDefinition/Callbacks.lua | 91 ++++++++ definitions/ItemDefinition/Settings.lua | 244 ++++++++++++++++++++++ definitions/ItemImageDefinition.lua | 5 + 4 files changed, 350 insertions(+), 242 deletions(-) create mode 100644 definitions/ItemDefinition/Callbacks.lua create mode 100644 definitions/ItemDefinition/Settings.lua create mode 100644 definitions/ItemImageDefinition.lua diff --git a/definitions/ItemDefinition.lua b/definitions/ItemDefinition.lua index 8c69112..9a5d834 100644 --- a/definitions/ItemDefinition.lua +++ b/definitions/ItemDefinition.lua @@ -1,243 +1,11 @@ ---- @meta +---@meta - ---- @class ItemDefinition: table -local ItemDefinition = { - --- Can contain new lines. "\n" has to be used as new line character. - --- See also: `get_description` in [`ItemStack`] - --- @type string? - description = "", - - --- Must not contain new lines. - --- Defaults to nil. - --- Use an [`ItemStack`] to get the short description, e.g.: - --- ItemStack(itemname):get_short_description() - --- @type string? - short_description = "", - - --- key = name, value = rating; rating = . - --- If rating not applicable, use 1. - --- e.g. {wool = 1, fluffy = 3} - --- {soil = 2, outerspace = 1, crumbly = 1} - --- {bendy = 2, snappy = 1}, - --- {hard = 1, metal = 1, spikes = 1} - --- @type table? - groups = {}, - - --- Texture shown in the inventory GUI - --- Defaults to a 3D rendering of the node if left empty. - --- @type string? - inventory_image = "", - - --- An overlay texture which is not affected by colorization - --- @type string? - inventory_overlay = "", - - --- Texture shown when item is held in hand - --- Defaults to a 3D rendering of the node if left empty. - --- @type string? - wield_image = "", - - --- Like inventory_overlay but only used in the same situation as wield_image - --- @type string? - wield_overlay = "", - - --- Scale for the item when held in hand - --- @type Position? scale vector - wield_scale = {x = 1, y = 1, z = 1}, - - --- An image file containing the palette of a node. - --- You can set the currently used color as the "palette_index" field of - --- the item stack metadata. - --- The palette is always stretched to fit indices between 0 and 255, to - --- ensure compatibility with "colorfacedir" (and similar) nodes. - --- @type string? - palette = "", - - --- Color the item is colorized with. The palette overrides this. - --- @type string|ColorSpec|nil - --- Examples: "#ff0000", "#ff0000ff", {r=255,g=0,b=0,a=255} - color = "#ffffffff", - - --- Maximum amount of items that can be in a single stack. - --- The default can be changed by the setting `default_stack_max` - --- @type number? - stack_max = 99, - - --- Range of node and object pointing that is possible with this item held - --- @type number? - range = 4.0, - - --- If true, item can point to all liquid nodes (`liquidtype ~= "none"`), - --- even those for which `pointable = false` - --- @type boolean? - liquids_pointable = false, - - --- When used for nodes: Defines amount of light emitted by node. - --- Otherwise: Defines texture glow when viewed as a dropped item - --- To set the maximum (14), use the value 'core.LIGHT_MAX'. - --- A value outside the range 0 to core.LIGHT_MAX causes undefined - --- behavior. - --- @type number? - light_source = 0, - - --- See "Tool Capabilities" section for an example including explanation - --- @type table? - tool_capabilities = { - --- Time between two uses of the tool (in seconds). - --- For example, a value of 0.5 means the tool can be used twice per second. - --- @type number? - full_punch_interval = 1.0, - --- Maximum level of items that can be dropped using this tool. - --- For example, if max_drop_level = 1, items with level 2 or 3 - --- will not be dropped when the node is dug with this tool. - --- @type number? - max_drop_level = 0, - --- Capabilities of the tool against each group of nodes. - --- Each group has the following fields: - --- - `times`: table of times it takes to dig nodes of the group - --- for each level. The index is the level, the value is the time - --- in seconds. Level 1 is the lowest level. - --- - `uses`: number of uses the tool has against nodes of the group. - --- When this number is exhausted, the tool breaks. 0 means infinite - --- uses. - --- - `maxlevel`: maximum level of nodes in the group that this tool - --- can dig. For example, if maxlevel = 2, nodes of level 3 in - --- this group cannot be dug with this tool. - --- For example: - --- `choppy = {times = {2.50, 1.40, 1.00}, uses = 20, maxlevel = 2}`, - --- @type table> - groupcaps = { - --- For example: - choppy = {times = {2.50, 1.40, 1.00}, uses = 20, maxlevel = 2}, - }, - --- Damage dealt to players and entities when using the tool to punch - --- them. The damage is specified in the same way as for entities, - --- i.e. a table with damage groups as keys and damage values as values. - --- Damage values must be between -32768 and 32767 (2^15) - --- Negative values heal the entity instead of damaging it. - --- If a damage group is not specified, the tool does no damage to that - --- group. - --- For example, to deal 7 damage to the "fleshy" group: - --- `damage_groups = {fleshy = 7}`, or for 3 damage to "fleshy" - --- and 1 damage to "crumbly": - --- `damage_groups = {fleshy = 3, crumbly = 1}` - --- If the tool should do no damage, use an empty table: - --- `damage_groups = {}` - --- @type table - damage_groups = {groupname = 7}, - - --- Amount of uses this tool has for attacking players and entities - --- by punching them (0 = infinite uses). - --- For compatibility, this is automatically set from the first - --- suitable groupcap using the formula "uses * 3^(maxlevel - 1)". - --- It is recommend to set this explicitly instead of relying on the - --- fallback behavior. - --- @type number? - punch_attack_uses = nil, - }, - - --- If nil and item is node, prediction is made automatically. - --- If nil and item is not a node, no prediction is made. - --- If "" and item is anything, no prediction is made. - --- Otherwise should be name of node which the client immediately places - --- on ground when the player places the item. Server will always update - --- with actual result shortly. - --- @type string? - node_placement_prediction = nil, - - --- if "", no prediction is made. - --- if "air", node is removed. - --- Otherwise should be name of node which the client immediately places - --- upon digging. Server will always update with actual result shortly. - --- @type string? - node_dig_prediction = "air", - - --- Definition of item sounds to be played at various events. - --- All fields in this table are optional. - --- See also `core.registered_items[itemname].sound` - --- @type table? - sound = { - - --- When tool breaks due to wear. Ignored for non-tools - --- @type SimpleSoundSpec - breaks = nil, - - --- When item is eaten with `core.do_item_eat` - --- @type SimpleSoundSpec - eat = nil, - - --- When item is used with the 'punch/mine' key pointing at a node or entity - --- @type SimpleSoundSpec - punch_use = nil, - - --- When item is used with the 'punch/mine' key pointing at nothing (air) - --- @type SimpleSoundSpec - punch_use_air = nil, - }, - - --- When the 'place' key was pressed with the item in hand and a node was pointed at. - --- Shall place item and return the leftover itemstack or nil to not modify the inventory. - --- Second return value: position of placed item/node. - --- 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|nil, Position|vector|nil)? - on_place = core.item_place, - - --- 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: nil - --- @type fun(itemstack:ItemStack, user:Player|ObjectRef|nil, pointed_thing:pointed_thing)? - on_secondary_use = nil, - - --- Shall drop item and return the leftover itemstack. - --- The dropper may be any ObjectRef or nil. - --- default: core.item_drop - --- @type (fun(itemstack:ItemStack|ItemStackString, dropper:Player|ObjectRef|nil, pos:Position):ItemStack)? - on_drop = core.item_drop, - - --- 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` (optional): The dropped item (a `"__builtin:item"` - --- luaentity) as `type="object"` `pointed_thing`. - --- * `time_from_last_punch, ...` (optional): 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, ...)? - on_pickup = core.item_pickup, - - --- default: nil - --- When user pressed the 'punch/mine' 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 - --- Otherwise, the function is free to do what it wants. - --- The user may be any ObjectRef or nil. - --- The default functions handle regular use cases. - --- @type (fun(itemstack:ItemStack, user:Player|ObjectRef|nil, pointed_thing:pointed_thing):ItemStack|nil)? - on_use = nil, - - --- default: nil - --- If defined, should return an itemstack and will be called instead of - --- wearing out the item (if tool). If returns nil, does nothing. - --- If after_use doesn't exist, it is the same as: - --- function(itemstack, user, node, digparams) - --- itemstack:add_wear(digparams.wear) - --- return itemstack - --- end - --- The user may be any ObjectRef or nil. - --- @type fun(itemstack:ItemStack, user:Player|ObjectRef|nil, node, digparams)? - after_use = nil, - - --- Add your own custom fields. By convention, all custom field names - --- should start with `_` to avoid naming collisions with future engine - --- usage. - --- @type any? - _custom_field = "< whatever >", -} +---The original `ItemDefinition`, described in the Luanti API Reference, +---was split into `ItemDefinition.Settings` and `ItemDefinition.Callbacks`. +--- +---Please look at the fields and methods in the corresponding classes. +--- +---This `ItemDefinition` class is a combination of `ItemDefinition.Settings` +---and `ItemDefinition.Callbacks` and to some extent corresponds to the original. +---@class ItemDefinition : ItemDefinition.Settings, ItemDefinition.Callbacks +local ItemDefinition = {} diff --git a/definitions/ItemDefinition/Callbacks.lua b/definitions/ItemDefinition/Callbacks.lua new file mode 100644 index 0000000..b857259 --- /dev/null +++ b/definitions/ItemDefinition/Callbacks.lua @@ -0,0 +1,91 @@ +---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 diff --git a/definitions/ItemDefinition/Settings.lua b/definitions/ItemDefinition/Settings.lua new file mode 100644 index 0000000..90071b0 --- /dev/null +++ b/definitions/ItemDefinition/Settings.lua @@ -0,0 +1,244 @@ +---Version: 5.16 +---@meta + +---@class ItemDefinition.Settings +local Settings = {} + +---Can contain new lines. `"\n"` has to be used as new line character. +--- +---See also: `get_description` in [ItemStack](lua://ItemStack). +---@type string? +Settings.description = nil + +---Must not contain new lines. +--- +---Defaults to `nil`. +--- +---Use an [ItemStack](lua://ItemStack) to get the short description, e.g.: +---``` +--- ItemStack(itemname):get_short_description() +---``` +---@type string? +Settings.short_description = nil + +---Table of groups-characteristics of Item. +---``` +--- key = name, value = rating; rating = number. +---``` +---If rating not applicable, use 1. +--- +---e.g.: +---``` +--- {wool = 1, fluffy = 3} +--- {soil = 2, outerspace = 1, crumbly = 1} +--- {bendy = 2, snappy = 1}, +--- {hard = 1, metal = 1, spikes = 1} +---``` +---@type table? +Settings.groups = nil + +---Texture shown in the inventory GUI. +--- +---Defaults to a 3D rendering of the node if left empty. +---@type ItemImageDefinition? +Settings.inventory_image = nil + +---An overlay texture which is not affected by colorization. +---@type ItemImageDefinition? +Settings.inventory_overlay = nil + +---Image shown when item is held in hand. +--- +---Defaults to a 3D rendering of the node if left empty. +---@type ItemImageDefinition? +Settings.wield_image = nil + +---Like `inventory_overlay` but only used in the same situation as `wield_image`. +---@type ItemImageDefinition? +Settings.wield_overlay = nil + +---Scale for the item when held in hand. +---@type Position? +Settings.wield_scale = nil + +---An image file containing the palette of a node. +--- +---You can set the currently used color as the "palette_index" field of +---the item stack metadata. +--- +---The palette is always stretched to fit indices between 0 and 255, to +---ensure compatibility with "colorfacedir" (and similar) nodes. +---@type string? +Settings.palette = nil + +---Color the item is colorized with. The palette overrides this. +--- +---It is a colorspec. +---@type ColorSpec? +Settings.color = nil + +---Maximum amount of items that can be in a single stack. +--- +---The default can be changed by the setting `default_stack_max`. +--- +---Range: [1, 65535] +---@type integer? +Settings.stack_max = nil + +---Range of node and object pointing that is possible with this item held. +--- +---Can be overridden with itemstack meta. +---@type number? +Settings.range = nil + +---If true, item can point to all liquid nodes (`liquidtype ~= "none"`), +---even those for which `pointable = false`. +---@type boolean? +Settings.liquids_pointable = nil + +---@alias ItemDefinition.pointabilities_table.value true|false|"blocking" +---@alias ItemDefinition.pointabilities_table {nodes:table, objects:table} + +---Contains lists to override the `pointable` property of nodes and objects. +--- +---The index can be a node/entity name or a group with the prefix `"group:"`. +--- +---For objects `armor_groups` are used and for players the entity name is irrelevant.) +--- +---If multiple fields fit, the following priority order is applied: +--- 1. value of matching node/entity name +--- 2. `true` for any group +--- 3. `false` for any group +--- 4. `"blocking"` for any group +--- 5. `liquids_pointable` if it is a liquid node +--- 6. `pointable` property of the node or object +---@type ItemDefinition.pointabilities_table? +Settings.pointabilities = nil + +---When used for nodes: Defines amount of light emitted by node. +--- +---Otherwise: Defines texture glow when viewed as a dropped item. +--- +---To set the maximum (14), use the value `core.LIGHT_MAX`. +--- +---A value outside the range 0 to `core.LIGHT_MAX` causes undefined +---behavior. +---@type number? +Settings.light_source = nil + +---@alias ItemDefinition.tool_capabilities_table.groupcaps_table table + +---@class ItemDefinition.tool_capabilities_table +---@field full_punch_interval number +---@field max_drop_level integer +--- +---For example: +---``` +---{ +--- choppy = {times = {2.50, 1.40, 1.00}, uses = 20, maxlevel = 2}, +---}, +---``` +---@field groupcaps ItemDefinition.tool_capabilities_table.groupcaps_table +--- +---Damage values are integers [s16] +---@field damage_groups table +--- +---Amount of uses this tool has for attacking players and entities +---by punching them (0 = infinite uses). +--- +---For compatibility, this is automatically set from the first +---suitable groupcap using the formula "uses * 3^(maxlevel - 1)". +--- +---It is recommend to set this explicitly instead of relying on the +---fallback behavior. +---@field punch_attack_uses integer + +---See "Tool Capabilities" section for an example including explanation. +---@type ItemDefinition.tool_capabilities_table? +Settings.tool_capabilities = nil + +---`Wear Bar` is a property of items that defines the coloring of the bar +---that appears under damaged tools. If it is absent, the default behavior +---of green-yellow-red is used. +---@class ItemDefinition.wearbar_color_table +--- +--- * `linear`: blends smoothly between each defined color point. +--- * `constant`: each color starts at its defined point, +--- and continues up to the next point +---@field blend 'constant'|'linear' +--- +---Specified as ColorSpec color values assigned to float durability keys. +--- +---"Durability" is defined as `1 - (wear / 65535)`. +---@field color_stops table + +---Set wear bar color of the tool by setting color stops and blend mode. +--- +---See "Wear Bar Color" section for further explanation including an example. +---@type ItemDefinition.wearbar_color_table|ColorSpec|nil +Settings.wear_color = nil + +---If `nil` and item is node, prediction is made automatically. +--- +---If `nil` and item is not a node, no prediction is made. +--- +---If `""` and item is anything, no prediction is made. +--- +---Otherwise should be name of node which the client immediately places +---on ground when the player places the item. Server will always update +---with actual result shortly. +---@type string? +Settings.node_placement_prediction = nil + +---If `""`, no prediction is made. +--- +---If `"air"`, node is removed. +--- +---Otherwise should be name of node which the client immediately places +---upon digging. Server will always update with actual result shortly. +--- +---Default: `"air"` +---@type string? +Settings.node_dig_prediction = nil + +---Only affects touchscreen clients. +---Defines the meaning of short and long taps with the item in hand. +---If specified as a table, the field to be used is selected according to +---the current `pointed_thing`. +---There are three possible TouchInteractionMode values: +---* "long_dig_short_place" (long tap = dig, short tap = place) +---* "short_dig_long_place" (short tap = dig, long tap = place) +---* "user": +---* * For `pointed_object`: Equivalent to "short_dig_long_place" if the +--- client-side setting "touch_punch_gesture" is "short_tap" (the +--- default value) and the item is able to punch (i.e. has no on_use +--- callback defined). +--- Equivalent to "long_dig_short_place" otherwise. +---* * For `pointed_node` and `pointed_nothing`: +--- Equivalent to "long_dig_short_place". +---* * The behavior of "user" may change in the future. +---The default value is "user". +--- +---@type table? +Settings.touch_interaction = nil + +---@class ItemDefinition.sound_table +--- +---When tool breaks due to wear. Ignored for non-tools. +---@field breaks SimpleSoundSpec? +--- +---When item is eaten with `core.do_item_eat`. +---@field eat SimpleSoundSpec? +--- +---When item is used with the 'punch/dig' key pointing at a node or entity. +---@field punch_use SimpleSoundSpec? +--- +---When item is used with the 'punch/dig' key pointing at nothing (air) +---@field punch_use_air SimpleSoundSpec? + +---Definition of item sounds to be played at various events. +--- +---All fields in this table are optional. +--- +---@type ItemDefinition.sound_table? +Settings.sound = nil diff --git a/definitions/ItemImageDefinition.lua b/definitions/ItemImageDefinition.lua new file mode 100644 index 0000000..3f0859e --- /dev/null +++ b/definitions/ItemImageDefinition.lua @@ -0,0 +1,5 @@ +---Version: 5.16 +---@meta + +---Basically a tile definition but for items. +---@alias ItemImageDefinition {name:string, animation:TileAnimationDefinition}|string