Compare commits

..

21 Commits

Author SHA1 Message Date
d784ca706f ItemStackMetaRef: add metadata keys 2026-11-17 22:05:07 +03:00
6d6173239b Player: minor fix 2026-11-08 20:48:09 +03:00
2ea20a7960 ItemStack & ItemStackMetaRef: 5.18 update annotations 2026-11-08 20:46:47 +03:00
a94b014166 ItemDefinition & NodeDefinition: add luanti & smc groups annotations 2026-11-08 20:05:18 +03:00
195185f1c2 core_namespace: minor fix 2026-11-07 19:27:37 +03:00
02381f5ffd core_namespace: 5.18 update 2026-11-07 19:25:10 +03:00
f43b79c82c core_namespace: 5.18 update 2026-11-07 19:08:57 +03:00
03b97bc546 core_namespace: 5.18 update 2026-11-07 19:01:51 +03:00
c89e3402a2 vector: fix round() annotation 2026-09-20 21:45:36 +03:00
24d5e06910 Add PcgRandom class 2026-09-08 22:31:03 +03:00
0ed55757ce vector: remove eq operator annotations 2026-09-05 21:45:57 +03:00
510ce9f7fa minor fix 2026-08-14 22:15:51 +03:00
1fe7f3d29a NodeDefinition: minor fix 2026-08-14 21:16:11 +03:00
ac5b6ca488 Splitting NodeDefinition into settings and callbacks, updating annotations to 5.16 2026-06-20 22:20:35 +03:00
4f8fe78b0a Splitting ItemDefinition into settings and callbacks, updating annotations to 5.16 2026-06-18 21:51:27 +03:00
5e8b69c136 Update README.md 2026-06-17 20:58:22 +03:00
Van
3aa8f7dc92 Обновить README.md 2026-06-16 22:06:55 +03:00
908db8e3b0 Add issue template 2026-06-16 21:21:02 +03:00
0489e18385 Update MetaDataRef & readme, rename readme and license 2026-06-16 21:08:22 +03:00
24531f8af6 EmmyLua -> LuaLS 2026-06-16 17:50:09 +03:00
5272c8e5a8 rename HudDefinition -> HUDDefinition 2026-06-16 13:44:40 +03:00
30 changed files with 2046 additions and 1686 deletions

View File

@@ -0,0 +1,17 @@
name: Update request
about: Report discrepancies between the annotation and documentation and request an update.
title: "Update request: "
labels:
- update request
body:
- type: textarea
id: report-desc
attributes:
label: Description
description: Describe the discrepancy you found and attach a link to the Luanti API Reference.
validations:
required: true
- type: markdown
attributes:
value: |
Thank you for reporting the discrepancy!

View File

@@ -1,7 +1,7 @@
# SMC Luanti IDE Helper # SMC Luanti IDE Helper
[![Maintained By: Apancore.Studio](https://img.shields.io/badge/Maintained%20By-Apancore.Studio-543c93?style=for-the-badge)](https://github.com/lord-server/lord?tab=readme-ov-file#contributors--%D1%83%D1%87%D0%B0%D1%81%D1%82%D0%BD%D0%B8%D0%BA%D0%B8) [![Maintained By: Apancore.Studio](https://img.shields.io/badge/Maintained%20By-Apancore.Studio-543c93?style=for-the-badge)](https://github.com/lord-server/lord?tab=readme-ov-file#contributors--%D1%83%D1%87%D0%B0%D1%81%D1%82%D0%BD%D0%B8%D0%BA%D0%B8)
[![License: MIT](https://img.shields.io/badge/License-MIT-444?style=for-the-badge)](./license.md) [![License: MIT](https://img.shields.io/badge/License-MIT-444?style=for-the-badge)](./LICENSE.md)
A helper package for [Luanti](https://www.luanti.org/) (Minetest) mod/game development that provides autocompletion and documentation for IDE integration. A helper package for [Luanti](https://www.luanti.org/) (Minetest) mod/game development that provides autocompletion and documentation for IDE integration.
@@ -13,12 +13,24 @@ This ide-helper is specifically designed to support the [SMC game](https://git.a
## Supported IDEs & Plugins ## Supported IDEs & Plugins
- IntelliJ IDEA (or compatible) with [EmmyLua2 Plugin](https://plugins.jetbrains.com/plugin/25076-emmylua2) We use [Lua Server Language](https://github.com/luals/lua-language-server). You can install it for the following IDEs:
- VS Code with [EmmyLua Extension](https://marketplace.visualstudio.com/items?itemName=tangzx.emmylua) (recommended for VS Code) - **Visual Studio Code** with [plugin](https://marketplace.visualstudio.com/items?itemName=sumneko.lua)
- VS Code with [Lua Language Server](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) - **Neovim** (see [instalation guide](https://luals.github.io/#neovim-install))
- Any editor with LSP support. - **JetBrains** with [plugin](https://plugins.jetbrains.com/plugin/22315-sumnekolua)
Install Lua LS: `cargo install emmylua_ls` (or see [instalation guide](https://github.com/EmmyLuaLs/emmylua-analyzer-rust?tab=readme-ov-file#-installation)) - Any editor with LSP support
(see [instalation guide](https://luals.github.io/#install))
## Annotation up-to-dateness
Some annotations may be outdated for newer versions of Luanti, as the Luanti API Reference gradually changes.
At the beginning of some files, there may be information about relevance in the form of a Luanti version:
```lua
---Version: 5.16 -- This means that the annotations were updated or verified with the documentation for Luanti 5.16.
---@meta
```
If you find a discrepancy between the ide-helper annotations and the Luanti API Reference, you can create an [issue](https://git.apancore.ru/Apancore.Studio/smc-luanti-ide-helper/issues/new?template=.gitea%2fissue_template%2fupdate_request.yaml) to notify the maintainers.
## License ## License
This project is licensed under the MIT License - see [`license.md`](./license.md) file for details. This project is licensed under the MIT License - see [`LICENSE.md`](./LICENSE.md) file for details.

View File

@@ -1,6 +1,15 @@
---Version: 5.18
---@meta ---@meta
---An `ItemStack` is a stack of items.
---
---`ItemStack([x])`: returns an `ItemStack`.
---
---`x`: (optional) Is one of the following:
--- * `nil` value: Empty stack
--- * `string` value: an `"itemstring"`.
--- * `table` value: `ItemStack` Table format.
--- * The `name` field is mandatory.
---@class ItemStack ---@class ItemStack
---@overload fun(x:ItemStack|ItemStackString|ItemStackTable|nil):ItemStack ---@overload fun(x:ItemStack|ItemStackString|ItemStackTable|nil):ItemStack
ItemStack = {} ItemStack = {}
@@ -13,102 +22,145 @@ ItemStack = {}
---@alias ItemStackString string ---@alias ItemStackString string
--- Put some item or stack onto this stack, returns leftover ItemStack ---Returns true if stack is empty.
--- @param item ItemStack|ItemStackString|ItemStackTable
--- @return self
function ItemStack:add_item(item) end
--- Increases wear by amount if the item is a tool, otherwise does nothing.
--- Wear is only added if the item is a tool. Adding wear might destroy the item.
--- @param amount number Valid amount range is [0,65536]
--- @return boolean Returns true if the item is (or was) a tool.
function ItemStack:add_wear(amount) end
--- Removes all items from the stack, making it empty
--- @return boolean it seams that it always return `true`
function ItemStack:clear() end
--- Returns number of items on the stack
--- @return integer
function ItemStack:get_count() end
--- Returns true/false (success), clears item on failure
--- @param count number count > 0 && count <= 65535 -- or clears
---@return boolean ---@return boolean
function ItemStack:set_count(count) end function ItemStack:is_empty() end
--- @return ItemDefinition returns the item definition table ---Returns item name (e.g. `"default:stone"`).
function ItemStack:get_definition() end ---@return string
--- Returns get_stack_max() - get_count()
--- @return number
function ItemStack:get_free_space() end
--- @return ItemStackMetaRef
function ItemStack:get_meta() end
--- Returns a string, for compatibility reasons this is equal to get_meta():get_string("")
--- @deprecated
function ItemStack:get_metadata() end
--- Returns item name (e.g. "default:stone")
--- @return ItemStackString
function ItemStack:get_name() end function ItemStack:get_name() end
--- Returns true/false (success), clears item on failure ---Sets the item name.
---
---Returns `false` if the stack was cleared, `true` otherwise.
---@param item_name string ---@param item_name string
---@return boolean ---@return boolean
function ItemStack:set_name(item_name) end function ItemStack:set_name(item_name) end
--- Returns the maximum size of the stack (depends on the item) ---Returns amount of items on the stack.
--- @return number ---@return integer
function ItemStack:get_stack_max() end function ItemStack:get_count() end
--- Returns the digging properties of the item, or those of the hand if none are defined for this item type ---Sets amount of items in the stack.
--- @return table ---
function ItemStack:get_tool_capabilities() end ---Returns `false` if the stack was cleared, `true` otherwise.
---@param count integer
---@return boolean
function ItemStack:set_count(count) end
--- Returns tool wear (0-65535), 0 for non-tools ---Returns tool wear (integer in range [0, 65535]), `0` for non-tools.
--- @return number ---@return integer
function ItemStack:get_wear() end function ItemStack:get_wear() end
--- Returns true/false (success), clears item on failure ---Set tool wear.
--- @param wear number wear <= 65535, otherwise clears ---
---Returns `false` if the stack was cleared, `true` otherwise
---@param wear integer
---@return boolean ---@return boolean
function ItemStack:set_wear(wear) end function ItemStack:set_wear(wear) end
--- Return true if stack is empty ---@return ItemStackMetaRef
--- @return boolean function ItemStack:get_meta() end
function ItemStack:is_empty() end
--- Returns true if the item name refers to a defined item type ---@deprecated
function ItemStack:get_metadata() end
---@deprecated
function ItemStack:set_metadata() end
---Returns the description shown in inventory list tooltips.
---@return string
function ItemStack:get_description() end
---Returns the short description.
---@return string
function ItemStack:get_short_description() end
---Removes all items from the stack, making it empty.
function ItemStack:clear() end
---Replace the contents of this stack.
---@param item ItemStack|ItemStackString|ItemStackTable
function ItemStack:replace(item) end
---Returns the stack in `itemstring` form.
---@return string
function ItemStack:to_string() end
---Returns the stack in Lua table form.
---
---Returns `nil` if the stack is empty
---@return ItemStackTable?
function ItemStack:to_table() end
---Returns the maximum size of the stack (depends on the item).
---@return integer
function ItemStack:get_stack_max() end
---Returns `get_stack_max() - get_count()`.
---@return integer
function ItemStack:get_free_space() end
---Returns `true` if the item name refers to a defined item type.
---@return boolean ---@return boolean
function ItemStack:is_known() end function ItemStack:is_known() end
--- Returns true if item or stack can be fully added to this one ---Returns the item definition table.
---
---Returns the definition of the `unknown` item if the item is not registered.
---@return ItemDefinition|NodeDefinition
function ItemStack:get_definition() end
---Returns the digging properties of the item,
---or those of the hand if none are defined for this item type.
---@return ItemDefinition.tool_capabilities_table
function ItemStack:get_tool_capabilities() end
---Increases wear by `amount` if the item is a tool, otherwise does nothing.
---@param amount integer
function ItemStack:add_wear(amount) end
---Increases wear in such a way that,
---if only this function is called, the item breaks after `max_uses` times.
---
---Does nothing if item is not a tool or if `max_uses` is `0`.
---@param max_uses integer
function ItemStack:add_wear_by_uses(max_uses) end
---Returns the wear bar parameters of the item,
---or nil if none are defined for this item type or in the stack's meta.
---@return ItemDefinition.wearbar_color_table
function ItemStack:get_wear_bar_params() end
---Put some item or stack onto this stack.
---
---Returns leftover ItemStack.
---@param item ItemStack|ItemStackString|ItemStackTable
---@return self
function ItemStack:add_item(item) end
---Returns `true` if item or stack can be fully added to this one
---@param item ItemStack|ItemStackString|ItemStackTable ---@param item ItemStack|ItemStackString|ItemStackTable
---@return boolean ---@return boolean
function ItemStack:item_fits(item) end function ItemStack:item_fits(item) end
--- Copy (don't remove) up to n items from this stack; returns copied ItemStack; if n is omitted, n=1 is used ---Take (and remove) up to `n` items from this stack.
--- @param count number ---@param count number? default: `1`
--- @return ItemStack
function ItemStack:peek_item(count) end
--- Replace the contents of this stack (item can also be an itemstring or table)
--- @param item ItemStack|ItemStackString|ItemStackTable
--- @return boolean seams always `true`
function ItemStack:replace(item) end
--- Take (and remove) up to n items from this stack; returns taken ItemStack; if n is omitted, n=1 is used
--- @param count? number
---@return ItemStack ---@return ItemStack
function ItemStack:take_item(count) end function ItemStack:take_item(count) end
--- Returns the stack in itemstring form ---Copy (don't remove) up to `n` items from this stack.
--- @return string ---@param count number? default: `1`
function ItemStack:to_string() end ---@return ItemStack
function ItemStack:peek_item(count) end
--- Returns the stack in Lua table form or `nil` if empty. ---Returns `true` if this stack is identical to other.
--- @return table|nil ---
function ItemStack:to_table() end ---**Note**: stack1:to_string() == stack2:to_string() is not reliable,
---as stack metadata can be serialized in arbitrary order.
---
---**Note**: if other is an itemstring or table representation of an ItemStack,
---this will always return false, even if it is "equivalent".
---@param other ItemStack|ItemStackString|ItemStackTable
---@return boolean
function ItemStack:equals(other) end

View File

@@ -1,6 +1,6 @@
---Version: 5.16
---@meta ---@meta
---Base class used by [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`], ---Base class used by [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`],
---and [`PlayerMetaRef`]. ---and [`PlayerMetaRef`].
--- ---
@@ -12,37 +12,61 @@
---@class MetaDataRef ---@class MetaDataRef
MetaDataRef = {} MetaDataRef = {}
---Returns `true` if `key` present, otherwise `false`.
---
---Returns `nil` when the MetaData is inexistent.
---@param key string ---@param key string
---@return boolean|nil ---@return boolean?
function MetaDataRef:contains(key) end function MetaDataRef:contains(key) end
---Returns the value stored at `key` as a string if present.
---
---Returns nil otherwise.
---@param key string ---@param key string
---@return string|nil ---@return string?
function MetaDataRef:get(key) end function MetaDataRef:get(key) end
---Set the string `value` at `key`.
---
---Value of `""` will delete the key.
---@param key string ---@param key string
---@param value string value "" will delete the key ---@param value string
---@return string
function MetaDataRef:set_string(key, value) end function MetaDataRef:set_string(key, value) end
---Returns a string value at `key` or `""` if not present.
---@param key string ---@param key string
---@return string ---@return string
function MetaDataRef:get_string(key) end function MetaDataRef:get_string(key) end
---Set an integer number `value` to `key`.
---
---Range: [s32].
---
---Some systems internally have a larger value range
---but but you should not rely on this behavior to ensure portability of your code.
---
---The value will be converted into a string when stored.
---@param key string ---@param key string
---@param value number ---@param value integer
---@return number
function MetaDataRef:set_int(key, value) end function MetaDataRef:set_int(key, value) end
---Returns the value stored at `key` as an integer.
---
---Returns `0` if key not present.
---@param key string ---@param key string
---@return number Returns `0` if `key` not present. ---@return integer
function MetaDataRef:get_int(key) end function MetaDataRef:get_int(key) end
---Store a number (a 64-bit floating-point number) exactly.
---
---The value will be converted into a string when stored.
---@param key string ---@param key string
---@param value number ---@param value number
---@return number
function MetaDataRef:set_float(key, value) end function MetaDataRef:set_float(key, value) end
---Returns a 64-bit floating-point number stored at `key`.
---
---Returns `0` if key not present.
---@param key string ---@param key string
---@return number ---@return number
function MetaDataRef:get_float(key) end function MetaDataRef:get_float(key) end
@@ -51,20 +75,71 @@ function MetaDataRef:get_float(key) end
---@return table ---@return table
function MetaDataRef:get_keys() end function MetaDataRef:get_keys() end
--- returns `nil` or a table with keys: ---Metadata tables represent MetaDataRef in a Lua table form (see `from_table`/`to_table`).
--- * `fields`: key-value storage ---
--- * `inventory`: `{list1 = {}, ...}}` (NodeMetaRef only) ---Example:
--- @return table|nil ---```lua
---metadata_table = {
--- -- metadata fields (key/value store)
--- fields = {
--- infotext = "Container",
--- another_key = "Another Value",
--- },
--- -- inventory data (for nodes)
--- inventory = {
--- -- inventory list "main" with 4 slots
--- main = {
--- -- list of all item slots
--- [1] = ItemStack("example:dirt"),
--- [2] = ItemStack("example:stone 25"),
--- [3] = ItemStack(""), -- empty slot
--- [4] = ItemStack("example:pickaxe"),
--- },
--- -- inventory list "hidden" with 1 slot
--- hidden = {
--- [1] = ItemStack("example:diamond"),
--- },
--- },
---}
---```
---@class MetaDataRef.Table
---Key-value storage of metadata fields.
---
---All values are stored as strings.
---
---Numbers must be converted to strings first.
---@field fields table
---
---(for NodeMetaRef only): A node inventory in table form
---
---Inventory table keys are inventory list names.
---
---Inventory table values are item tables.
---
---Item table keys are slot IDs (starting with 1).
---
---Item table values are ItemStacks
---@field inventory table
---Returns a [metadata table](lua://MetaDataRef.Table) or `nil` on failure.
---@return MetaDataRef.Table?
function MetaDataRef:to_table() end function MetaDataRef:to_table() end
--- * Any non-table value will clear the metadata ---Imports metadata from a [metadata table](lua://MetaDataRef.Table).
--- * See [Node Metadata] for an example ---
--- * returns `true` on success ---If `data` is a metadata table,
--- @param value table|nil ---the metadata it represents will replace all metadata of this MetaDataRef object.
---
---Any non-table value for `data` will clear all metadata.
---
---Item table values the inventory field may also be itemstrings.
---
---Returns `true` on success.
--- @param data MetaDataRef.Table?
--- @return boolean --- @return boolean
function MetaDataRef:from_table(value) end function MetaDataRef:from_table(data) end
--- * returns `true` if this metadata has the same key-value pairs as `other` ---Returns `true` if this metadata has the same key-value pairs as `other`.
---@param other any ---@param other any
---@return boolean ---@return boolean
function MetaDataRef:equals(other) end function MetaDataRef:equals(other) end

View File

@@ -1,15 +1,47 @@
---Version: 5.18
---@meta ---@meta
---@alias ItemStackMetaRef.IntKey
---|string
---|'palette_index' -- TODO: уточнить, точно ли в int?
---|'count_alignment'
---@alias ItemStackMetaRef.FloatKey
---|string
---|'range'
---@alias ItemStackMetaRef.StringKey
---|string
---|'description'
---|'short_description'
---|'inventory_image'
---|'inventory_overlay'
---|'wield_image'
---|'wield_overlay'
---|'wield_scale'
---|'color'
---|'count_meta'
---ItemStack metadata: reference extra data and functionality stored in a stack. ---ItemStack metadata: reference extra data and functionality stored in a stack.
--- Can be obtained via `item:get_meta()`.
--- ---
---Can be obtained via `item:get_meta()`.
---@class ItemStackMetaRef: MetaDataRef ---@class ItemStackMetaRef: MetaDataRef
---@field get_int fun(self, key:ItemStackMetaRef.IntKey):integer
---@field set_int fun(self, key:ItemStackMetaRef.IntKey, value:integer)
---@field get_float fun(self, key:ItemStackMetaRef.FloatKey):number
---@field set_float fun(self, key:ItemStackMetaRef.FloatKey, value:number)
---@field get_string fun(self, key:ItemStackMetaRef.StringKey):string
---@field set_string fun(self, key:ItemStackMetaRef.StringKey, value:string)
ItemStackMetaRef = {} ItemStackMetaRef = {}
--- * Overrides the item's tool capabilities ---Overrides the item's tool capabilities.
--- * A nil value will clear the override data and restore the original behavior. ---
---A `nil` value will clear the override data and restore the original behavior.
---@param tool_capabilities ItemDefinition.tool_capabilities_table
function ItemStackMetaRef:set_tool_capabilities(tool_capabilities) end function ItemStackMetaRef:set_tool_capabilities(tool_capabilities) end
--- * Overrides the item's wear bar parameters (see "Wear Bar Color" section) ---Overrides the item's wear bar parameters (see "Wear Bar Color" section)
--- * A nil value will clear the override data and restore the original behavior. ---
---A `nil` value will clear the override data and restore the original behavior.
---@param wear_bar_params ItemDefinition.wearbar_color_table
function ItemStackMetaRef:set_wear_bar_params(wear_bar_params) end function ItemStackMetaRef:set_wear_bar_params(wear_bar_params) end

View File

@@ -243,7 +243,7 @@ function Player:set_physics_override(override_table) end
function Player:get_physics_override() end function Player:get_physics_override() end
--- Add a HUD element described by HUD def, returns ID number on success. --- Add a HUD element described by HUD def, returns ID number on success.
--- @param hud_definition HudDefinition --- @param hud_definition HUDDefinition
--- @return integer --- @return integer
function Player:hud_add(hud_definition) end function Player:hud_add(hud_definition) end
@@ -259,7 +259,7 @@ function Player:hud_change(id, stat, value) end
--- Gets the HUD element definition structure of the specified ID. --- Gets the HUD element definition structure of the specified ID.
--- @param id integer --- @param id integer
--- @return HudDefinition --- @return HUDDefinition
function Player:hud_get(id) end function Player:hud_get(id) end
--- @class Player.hud_flags --- @class Player.hud_flags
@@ -308,7 +308,7 @@ function Player:hud_set_hotbar_itemcount(count) end
function Player:hud_get_hotbar_itemcount() end function Player:hud_get_hotbar_itemcount() end
--- Sets background image for hotbar. --- Sets background image for hotbar.
--- @param string --- @param texturename string
function Player:hud_set_hotbar_image(texturename) end function Player:hud_set_hotbar_image(texturename) end
--- Returns texturename. --- Returns texturename.
@@ -316,7 +316,7 @@ function Player:hud_set_hotbar_image(texturename) end
function Player:hud_get_hotbar_image() end function Player:hud_get_hotbar_image() end
--- Sets image for selected item of hotbar. --- Sets image for selected item of hotbar.
--- @param string --- @param texturename string
function Player:hud_set_hotbar_selected_image(texturename) end function Player:hud_set_hotbar_selected_image(texturename) end
--- Returns texturename. --- Returns texturename.

40
classes/PcgRandom.lua Normal file
View File

@@ -0,0 +1,40 @@
---Version: 5.18
---@meta
---A 32-bit pseudorandom number generator.
---
---Uses PCG32, an algorithm of the permuted
---congruential generator family,
---offering very strong randomness.
---@class PcgRandom
---@overload fun(seed:integer, seq:integer?):PcgRandom
PcgRandom = {}
---Return next random integer number `[s32]`.
---@param max integer
---@param min integer
---@return integer
---@overload fun():integer
function PcgRandom:next(max, min) end
---Return normally distributed random number `[min...max]`.
---
---This is only a rough approximation of a normal distribution with:
---
---`mean = (max - min) / 2` and `variance = (((max - min + 1) ^ 2) - 1) / (12 * num_trials)`
---
---Increasing `num_trials` improves accuracy of the approximation
---@param max integer
---@param min integer
---@param num_trials integer
---@return integer
function PcgRandom:rand_normal_dist(max, min, num_trials) end
---Return generator state encoded in string.
---@return string
function PcgRandom:get_state() end
---Restore generator state from encoded string.
---@param state_string string
---@return string
function PcgRandom:set_state(state_string) end

View File

@@ -94,9 +94,9 @@ function VoxelManip:set_param2_data(param2_data) end
--- @overload fun(p1:MapPosition, p2:MapPosition) --- @overload fun(p1:MapPosition, p2:MapPosition)
--- @overload fun(propagate_shadow:boolean) --- @overload fun(propagate_shadow:boolean)
--- @overload fun() --- @overload fun()
--- @param p1 MapPosition --- @param p1 MapPosition?
--- @param p2 MapPosition --- @param p2 MapPosition?
--- @param propagate_shadow boolean --- @param propagate_shadow boolean?
function VoxelManip:calc_lighting(p1, p2, propagate_shadow) end function VoxelManip:calc_lighting(p1, p2, propagate_shadow) end
--- Update liquid flow --- Update liquid flow

View File

@@ -122,7 +122,7 @@ function vector:ceil() end
--- Returns a vector, each dimension rounded to the nearest integer. --- Returns a vector, each dimension rounded to the nearest integer.
--- At a multiple of 0.5, rounds away from zero. --- At a multiple of 0.5, rounds away from zero.
--- @return vector --- @return IntegerVector
function vector:round() end function vector:round() end
--- Returns a vector where `math.sign` was called for each component. --- Returns a vector where `math.sign` was called for each component.

View File

@@ -239,57 +239,6 @@ function core.get_hit_params(groups, tool_capabilities , time_from_last_punch) e
-- Translations
--- is a simple wrapper around
--- `core.translate`, and `core.get_translator(textdomain)(str, ...)` is
--- equivalent to `core.translate(textdomain, str, ...)`.
--- It is intended to be used in the following way, so that it avoids verbose
--- repetitions of `core.translate`:
---
--- local S = core.get_translator(textdomain)
--- S(str, ...)
---
--- As an extra commodity, if `textdomain` is nil, it is assumed to be "" instead.
---
--- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L3329-L3338)
---
--- @param text_domain string
--- @return fun(str: string, ...):string
function core.get_translator(text_domain) end
--- translates the string `str` with
--- the given `textdomain` for disambiguation. The textdomain must match the
--- textdomain specified in the translation file in order to get the string
--- translated. This can be used so that a string is translated differently in
--- different contexts.
--- It is advised to use the name of the mod as textdomain whenever possible, to
--- avoid clashes with other mods.
--- This function must be given a number of arguments equal to the number of
--- arguments the translated string expects.
--- Arguments are literal strings -- they will not be translated, so if you want
--- them to be, they need to come as outputs of `core.translate` as well.
---
--- For instance, suppose we want to translate "@1 Wool" with "@1" being replaced
--- by the translation of "Red". We can do the following:
---
--- local S = core.get_translator()
--- S("@1 Wool", S("Red"))
---
--- This will be displayed as "Red Wool" on old clients and on clients that do
--- not have localization enabled. However, if we have for instance a translation
--- file named `wool.fr.tr` containing the following:
---
--- @1 Wool=Laine @1
--- Red=Rouge
---
--- this will be displayed as "Laine Rouge" on clients with a French locale.
---
--- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L3340-L3365)
---
--- @param textdomain string
--- @param str string
--- @return string
function core.translate(textdomain, str, ...) end
@@ -578,7 +527,7 @@ function core.register_allow_player_inventory_action(callback) end
--- * Does not accept or handle any return value. --- * Does not accept or handle any return value.
--- ---
--- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4732-L4735) --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4732-L4735)
--- @param callback fun(player:ObjectRef|Player, action:"move"|"put"|"take", inventory:InvRef, inventory_info:table):integer? --- @param callback fun(player:Player, action:"move"|"put"|"take", inventory:InvRef, inventory_info:table):integer?
function core.register_on_player_inventory_action(callback) end function core.register_on_player_inventory_action(callback) end
--- * Called by `builtin` and mods when a player violates protection at a --- * Called by `builtin` and mods when a player violates protection at a
--- position (eg, digs a node or punches a protected entity). --- position (eg, digs a node or punches a protected entity).
@@ -2105,7 +2054,7 @@ function core.write_json(data, styled) end
--- * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'` --- * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
--- ---
--- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5686-L5689) --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5686-L5689)
--- @param table --- @param table table
--- @return string --- @return string
function core.serialize(table) end function core.serialize(table) end
--- Returns a table --- Returns a table

View File

@@ -1,9 +1,7 @@
---Version: 5.18
---@meta ---@meta
---Calls `core.log` with all arguments converted to string and separated by tabs (similar to print).
--- Equivalent to `core.log(table.concat({...}, "\t"))`
---
--- Calls `core.log()` with all arguments converted to string and separated by tabs (similar to print).
--- ---
---@param ... any ---@param ... any
function core.debug(...) end function core.debug(...) end
@@ -16,9 +14,7 @@ function core.debug(...) end
---| "info" ---| "info"
---| "verbose" ---| "verbose"
--- Logs a message at the specified log level.
---
---@overload fun(text:string) ---@overload fun(text:string)
--- @param level? LogLevel # [Optional] is one of `"none"`, `"error"`, `"warning"`, `"action"`, `"info"`, or `"verbose"`. Default is `"none"`. ---@param level LogLevel?
---@param text string ---@param text string
function core.log(level, text) end function core.log(level, text) end

View File

@@ -1,39 +1,43 @@
---Version: 5.18
---@meta ---@meta
--- Environment ---
--- * register a node with its definition ---Register a node with its definition.
--- * Note: you must pass a clean table that hasn't already been used for another registration to this function, as it will be modified. ---
---**Note**: you must pass a clean table that hasn't already been used
---for another registration to this function, as it will be modified.
---@param name string technical node name ("<mod>:<node>"). ---@param name string technical node name ("<mod>:<node>").
---@param node_definition NodeDefinition table with node definition properties. ---@param node_definition NodeDefinition table with node definition properties.
function core.register_node(name, node_definition) end function core.register_node(name, node_definition) end
---Register an item with its definition.
--- * register an item with its definition ---
--- * Note: you must pass a clean table that hasn't already been used for another registration to this function, as it will be modified. ---**Note**: you must pass a clean table that hasn't already been used
---for another registration to this function, as it will be modified.
---@param name string technical item name ("<mod>:<item>"). ---@param name string technical item name ("<mod>:<item>").
---@param item_definition ItemDefinition table with item definition properties. ---@param item_definition ItemDefinition table with item definition properties.
function core.register_craftitem(name, item_definition) end function core.register_craftitem(name, item_definition) end
--- * register a tool item with its definition ---Register a tool item with its definition.
--- * Note: you must pass a clean table that hasn't already been used for another registration to this function, as it will be modified. ---
--- @param name string ---**Note**: you must pass a clean table that hasn't already been used
--- @param item_definition ItemDefinition ---for another registration to this function, as it will be modified.
---@param name string technical item name ("<mod>:<item>").
---@param item_definition ItemDefinition table with item definition properties.
function core.register_tool(name, item_definition) end function core.register_tool(name, item_definition) end
---Overrides fields of an item registered with register_node/tool/craftitem. ---Overrides fields of an item registered with register_node/tool/craftitem.
--- * `redefinition` is a table of fields `[name] = new_value`, overwriting fields of or adding fields to the existing definition.
--- * Note: Item must already be defined, (opt)depend on the mod defining it.
--- * Example: `core.override_item("default:mese", { light_source = core.LIGHT_MAX }, { "sounds" })`:
--- Overwrites the `light_source` field, removes the `sounds` from the definition of the mese block.
--- ---
---**Note**: Item must already be defined.
---@param name string ---@param name string
---@param redefinition ItemDefinition|NodeDefinition ---@param redefinition ItemDefinition|NodeDefinition
function core.override_item(name, redefinition) end ---@param del_fields string[]
function core.override_item(name, redefinition, del_fields) end
--- Unregisters the item from the engine, and deletes the entry with key ---Unregisters the item from the engine, and deletes the entry with key name
--- `name` from `core.registered_items` and from the associated item table ---from `core.registered_items` and from the associated item table according
--- according to its nature (e.g. `core.registered_nodes`) ---to its nature (e.g. `core.registered_nodes`)
---
---@param name string ---@param name string
function core.unregister_item(name) end function core.unregister_item(name) end
@@ -47,76 +51,43 @@ function core.register_abm(abm_definition) end
---@param lbm_definition LBMDefinition ---@param lbm_definition LBMDefinition
function core.register_lbm(lbm_definition) end function core.register_lbm(lbm_definition) end
--- * Also use this to set the 'mapgen aliases' needed in a game for the core ---Also use this to set the 'mapgen aliases' needed in a game for the core mapgens.
--- mapgens. See [Mapgen aliases](https://api.luanti.org/aliases/#mapgen-aliases) section.
--- ---
--- @param alias string @itemstring (`"<mod>:<node>"`). For renaming: its old name. ---See [Mapgen aliases](https://api.luanti.org/core-namespace-reference/#mapgen-aliases) section above.
--- @param original_name string @itemstring (`"<mod>:<node>"`). For renaming: its new name. ---
---Does nothing if an item named alias is already registered.
---@param alias string
---@param original_name string
function core.register_alias(alias, original_name) end function core.register_alias(alias, original_name) end
--- * Forces an alias to be created, even if an alias with the same name ---Same as core.register_alias, but an already registered item named alias is unregistered first.
--- already exists. ---@param alias string
--- @param alias string @itemstring (`"<mod>:<node>"`). For renaming: its old name. ---@param original_name string
--- @param original_name string @itemstring (`"<mod>:<node>"`). For renaming: its new name.
function core.register_alias_force(alias, original_name) end function core.register_alias_force(alias, original_name) end
--- * Returns an integer object handle uniquely identifying the registered ore on success.
--- * The order of ore registrations determines the order of ore generation.
---
---@param ore_definition OreDefinition ---@param ore_definition OreDefinition
---@return integer ---@return integer
function core.register_ore(ore_definition) end function core.register_ore(ore_definition) end
--- * Returns an integer object handle uniquely identifying the registered
--- biome on success. To get the biome ID, use `core.get_biome_id`.
---
---@param biome_definition BiomeDefinition ---@param biome_definition BiomeDefinition
---@return integer ---@return integer
function core.register_biome(biome_definition) end function core.register_biome(biome_definition) end
--- * Unregisters the biome from the engine, and deletes the entry with key
--- `name` from `core.registered_biomes`.
--- * Warning: This alters the biome to biome ID correspondences, so any
--- decorations or ores using the 'biomes' field must afterwards be cleared
--- and re-registered.
---
---@param name string ---@param name string
function core.unregister_biome(name) end function core.unregister_biome(name) end
--- * Returns an integer object handle uniquely identifying the registered
--- decoration on success. To get the decoration ID, use
--- `core.get_decoration_id`.
--- * The order of decoration registrations determines the order of decoration
--- generation.
---
---@param decoration_definition DecorationDefinition ---@param decoration_definition DecorationDefinition
---@return integer ---@return integer
function core.register_decoration(decoration_definition) end function core.register_decoration(decoration_definition) end
--- * Returns an integer object handle uniquely identifying the registered ---@param schematic_definition SchematicSpecifier|string
--- schematic on success.
--- * If the schematic is loaded from a file, the `name` field is set to the
--- filename.
--- * If the function is called when loading the mod, and `name` is a relative
--- path, then the current mod path will be prepended to the schematic
--- filename.
---
--- @param schematic SchematicSpecifier|string
--- @param replacements? table?
---@return integer ---@return integer
function core.register_schematic(schematic, replacements) end function core.register_schematic(schematic_definition) end
--- * Clears all biomes currently registered.
--- * Warning: Clearing and re-registering biomes alters the biome to biome ID
--- correspondences, so any decorations or ores using the 'biomes' field must
--- afterwards be cleared and re-registered.
function core.clear_registered_biomes() end function core.clear_registered_biomes() end
--- * Clears all decorations currently registered.
function core.clear_registered_decorations() end function core.clear_registered_decorations() end
--- * Clears all ores currently registered.
function core.clear_registered_ores() end function core.clear_registered_ores() end
--- * Clears all schematics currently registered.
function core.clear_registered_schematics() end function core.clear_registered_schematics() end

View File

@@ -1,72 +1,29 @@
---Version: 5.18
---@meta ---@meta
--- Gameplay ---
--- Registers a crafting recipe.
--- * Check recipe table syntax for different types below.
--- [TODO]: Link to recipe table syntax documentation.
---@param recipe table ---@param recipe table
function core.register_craft(recipe) end function core.register_craft(recipe) end
--- * Will erase existing craft based either on output item or on input recipe.
--- * Specify either output or input only. If you specify both, input will be
--- ignored. For input use the same recipe table syntax as for
--- `core.register_craft(recipe)`. For output specify only the item,
--- without a quantity.
--- * Returns false if no erase candidate could be found, otherwise returns true.
--- * **Warning**! The type field ("shaped", "cooking" or any other) will be
--- ignored if the recipe contains output. Erasing is then done independently
--- from the crafting method.
---
---@param recipe table ---@param recipe table
---@return boolean ---@return boolean
function core.clear_craft(recipe) end function core.clear_craft(recipe) end
--- Registers a chatcommand.
--- * `cmd` is the name of the command without the leading slash.
--- * `chatcommand_definition` is a table containing the following fields:
--- * `description` (string) A short description of the command.
--- * `params` (string) A string describing the parameters of the command.
--- * `privs` (table) A table specifying the privileges required to use the command.
--- * `func` (function) The function to be called when the command is executed. \
--- It receives two parameters:
--- * `name` (string) the name of the player who executed the command, and
--- * `param` (string) the parameters passed to the command.
---
--- It should return two values:
--- * `success` (boolean) and
--- * `message` (string).
---
--- If `success` is false, `message` will be sent to the player as an error message. \
--- If `success` is true, `message` will be sent as a regular chat message.
--- If it returns `false` and no `message`, the help message is shown.
---
---@param cmd string ---@param cmd string
---@param chatcommand_definition ChatCommandDefinition ---@param chatcommand_definition ChatCommandDefinition
function core.register_chatcommand(cmd, chatcommand_definition) end function core.register_chatcommand(cmd, chatcommand_definition) end
--- Overrides fields of a chatcommand registered with `register_chatcommand`.
---
---@param name string ---@param name string
---@param redefinition ChatCommandDefinition ---@param redefinition ChatCommandDefinition
function core.override_chatcommand(name, redefinition) end function core.override_chatcommand(name, redefinition) end
--- Unregisters a chatcommands registered with `register_chatcommand`.
---
---@param name string ---@param name string
function core.unregister_chatcommand(name) end function core.unregister_chatcommand(name) end
--- Registers a privilege.
--- * `definition` can be a description or a definition table
--- * If it is a description, the priv will be granted to singleplayer and admin by default.
--- * To allow players with `basic_privs` to grant, see the `basic_privs` minetest.conf setting.
---
---@param name string ---@param name string
---@param definition string|PrivilegeDefinition ---@param definition string|PrivilegeDefinition
function core.register_privilege(name, definition) end function core.register_privilege(name, definition) end
--- Registers an authentication handler.
--- * Registers an auth handler that overrides the builtin one.
--- * This function can be called by a single mod once only.
---
---@param authentication_handler_definition AuthenticationHandlerDefinition ---@param authentication_handler_definition AuthenticationHandlerDefinition
function core.register_authentication_handler(authentication_handler_definition) end function core.register_authentication_handler(authentication_handler_definition) end

View File

@@ -0,0 +1,60 @@
---Version: 5.18
---@meta
--- Translations ---
---Is a simple wrapper around `core.translate` and `core.translate_n`.
---
---After `local S, PS = core.get_translator(textdomain)`,
---we have `S(str, ...)` equivalent to `core.translate(textdomain, str, ...)`, and
---`PS(str, str_plural, n, ...)` to `core.translate_n(textdomain, str, str_plural, n, ...)`.
---It is intended to be used in the following way,
---so that it avoids verbose repetitions of `core.translate`:
---```lua
--- local S, PS = core.get_translator(textdomain)
--- S(str, ...)
---```
---
---As an extra commodity, if `textdomain` is nil, it is assumed to be `""` instead.
---@param textdomain string?
---@return fun(str:string, ...):string, fun(str:string, ...):string
function core.get_translator(textdomain) end
---Translates the string `str` with the given `textdomain` for disambiguation.
---
---The textdomain must match the textdomain specified in the translation file
---in order to get the string translated. This can be used so that a string
---is translated differently in different contexts. It is advised to use
---the name of the mod as textdomain whenever possible, to avoid clashes with other mods.
---
---This function must be given an amount of arguments equal to the amount of arguments
---the translated string expects. Arguments are literal strings -- they will not be translated.
---@param textdomain string
---@param str string
---@param ... string
---@return string
function core.translate(textdomain, str, ...) end
---Translates the string `str` with the given `textdomain` for disambiguation.
---
---The value of `n`, which must be a nonnegative integer,
---is used to decide whether to use the singular or the plural version of the string.
---
---Depending on the locale of the client, the choice between singular and plural
---might be more complicated, but the choice will be done automatically using the value of `n`.
---@param textdomain string
---@param str string
---@param str_plural string
---@param n string
---@param ... string
---@return string
function core.translate_n(textdomain, str, str_plural, n, ...) end
---Resolves translations in the given string just like the client would,
---using the translation files for `lang_code`. For this to have any effect,
---the string needs to contain translation markup,
---e.g. `core.get_translated_string("fr", S("Hello"))`.
---@param lang_code string
---@param str string
---@return string
function core.get_translated_string(lang_code, str) end

View File

@@ -1,370 +1,288 @@
---Version: 5.18
---@meta ---@meta
--- Utilities ---
---Returns the currently loading mod's name, when loading a mod. ---Returns the currently loading mod's name, when loading a mod.
--- - Returns nil if not loading a mod. ---@return string
--- - Only works during mod loading (i.e. when a mod calls this function from
--- its top-level scope, or from a function called during mod loading).
--- - Useful for libraries to determine which mod is loading them, for
--- example to access that mod's mod storage.
--- @see core.get_modpath
--- @see core.get_modnames
--- @see core.get_worldpath
--- @return string returns the currently loading mod's name, when loading a mod.
function core.get_current_modname() end function core.get_current_modname() end
--- Returns the directory path for a mod, e.g. "/home/user/.minetest/usermods/modname". ---Returns the directory path for a mod, e.g. `"/home/user/.minetest/"`
--- - Returns nil if the mod is not enabled or does not exist (not installed). ---@param modname string
--- - Works regardless of whether the mod has been loaded yet. ---@return string?
--- - Useful for loading additional `.lua` modules or static data from a mod, or checking if a mod is enabled. function core.get_modpath(modname) end
--- @param mod_name string
--- @return string
function core.get_modpath(mod_name) end
--- Returns a list of enabled mods, sorted alphabetically. ---Returns a list of the mods' names that are loaded or are yet to be loaded during startup.
--- - Does not include disabled mods, even if they are installed. ---@param load_order boolean?
--- @return table function core.get_modnames(load_order) end
function core.get_modnames() end
--- @class GameInfo ---@class Core.GameInfo
---@field id string ---@field id string
---@field title string ---@field title string
---@field author string ---@field author string
---@field path string The root directory of the game. ---@field path string The root directory of the game.
---Returns a table containing information about the current game. ---Returns a table containing information about the current game.
--- Note that other meta information (e.g. version/release number)
--- can be manually read from `game.conf` in the game's root directory.
--- ---
--- @return GameInfo ---Note that other meta information (e.g. version/release number)
---can be manually read from game.conf in the game's root directory.
---@return Core.GameInfo
function core.get_game_info() end function core.get_game_info() end
--- Returns e.g. "/home/user/.minetest/world" ---Returns e.g. `"/home/user/.minetest/world"`.
--- - Useful for storing custom data
---@return string ---@return string
function core.get_worldpath() end function core.get_worldpath() end
--- Returns e.g. "/home/user/.minetest/mod_data/mymod" ---Returns e.g. `"/home/user/.minetest/mod_data/mymod"`
--- - Useful for storing custom data independently of worlds.
--- - Must be called during mod load time.
--- - Can read or write to this directory at any time.
--- - It's possible that multiple Minetest instances are running at the same time, which may lead to corruption if you are not careful.
---@return string ---@return string
function core.get_mod_data_path() end function core.get_mod_data_path() end
---Returns `true` if the server is running in singleplayer mode, `false` otherwise.
---@return boolean ---@return boolean
function core.is_singleplayer() end function core.is_singleplayer() end
---@class Core.Features
---@field glasslike_framed boolean
---@field nodebox_as_selectionbox boolean
---@field get_all_craft_recipes_works boolean
---@field use_texture_alpha boolean
---@field no_legacy_abms boolean
---@field texture_names_parens boolean
---@field area_store_custom_ids boolean
---@field add_entity_with_staticdata boolean
---@field no_chat_message_prediction boolean
---@field object_use_texture_alpha boolean
---@field object_independent_selectionbox boolean
---@field httpfetch_binary_data boolean
---@field formspec_version_element boolean
---@field area_store_persistent_ids boolean
---@field pathfinder_works boolean
---@field object_step_has_moveresult boolean
---@field direct_velocity_on_players boolean
---@field use_texture_alpha_string_modes boolean
---@field degrotate_240_steps boolean
---@field abm_min_max_y boolean
---@field dynamic_add_media_table boolean
---@field particlespawner_tweenable boolean
---@field get_sky_as_table boolean
---@field get_light_data_buffer boolean
---@field mod_storage_on_disk boolean
---@field compress_zstd boolean
---@field sound_params_start_time boolean
---@field physics_overrides_v2 boolean
---@field hud_def_type_field boolean
---@field random_state_restore boolean
---@field after_order_expiry_registration boolean
---@field wallmounted_rotate boolean
---@field item_specific_pointabilities boolean
---@field blocking_pointability_type boolean
---@field dynamic_add_media_startup boolean
---@field dynamic_add_media_filepath boolean
---@field lsystem_decoration_type boolean
---@field item_meta_range boolean
---@field node_interaction_actor boolean
---@field moveresult_new_pos boolean
---@field override_item_remove_fields boolean
---@field hotbar_hud_element boolean
---@field bulk_lbms boolean
---@field abm_without_neighbors boolean
---@field biome_weights boolean
---@field particle_blend_clip boolean
---@field remove_item_match_meta boolean
---@field httpfetch_additional_methods boolean
---@field object_guids boolean
---@field on_timer_four_args boolean
---@field particlespawner_exclude_player boolean
---@field generate_decorations_biomes boolean
---@field chunksize_vector boolean
---@field item_image_animation boolean
---@field get_modnames_load_order boolean
---@field set_camera_resettable boolean
---@field hud_hideable_field boolean
---@field compress_raw_deflate boolean
---@field get_all_craft_recipes_fuel boolean
---@field get_all_craft_recipes_replacements boolean
--- Table containing API feature flags ---Table containing server-side API feature flags.
--- @type table ---@type Core.Features
core.features = { core.features = nil
--- @since 0.4.7
glasslike_framed = true,
--- @since 0.4.7
nodebox_as_selectionbox = true,
--- @since 0.4.7
get_all_craft_recipes_works = true,
--- The transparency channel of textures can optionally be used on nodes
--- @since 0.4.7
use_texture_alpha = true,
--- Tree and grass ABMs are no longer done from C++
--- @since 0.4.8
no_legacy_abms = true,
--- Texture grouping is possible using parentheses
--- @since 0.4.11
texture_names_parens = true,
--- Unique Area ID for AreaStore:insert_area
--- @since 0.4.14
area_store_custom_ids = true,
--- add_entity supports passing initial staticdata to on_activate
--- @since 0.4.16
add_entity_with_staticdata = true,
--- Chat messages are no longer predicted
--- @since 0.4.16
no_chat_message_prediction = true,
--- The transparency channel of textures can optionally be used on
--- objects (ie: players and lua entities)
--- @since 5.0.0
object_use_texture_alpha = true,
--- Object selectionbox is settable independently from collisionbox
--- @since 5.0.0
object_independent_selectionbox = true,
--- Specifies whether binary data can be uploaded or downloaded using the HTTP API
--- @since 5.1.0
httpfetch_binary_data = true,
--- Whether formspec_version[<version>] may be used
--- @since 5.1.0
formspec_version_element = true,
--- Whether AreaStore's IDs are kept on save/load
--- @since 5.1.0
area_store_persistent_ids = true,
--- Whether core.find_path is functional
--- @since 5.2.0
pathfinder_works = true,
--- Whether Collision info is available to an objects' on_step
--- @since 5.3.0
object_step_has_moveresult = true,
--- Whether get_velocity() and add_velocity() can be used on players
--- @since 5.4.0
direct_velocity_on_players = true,
--- nodedef's use_texture_alpha accepts new string modes
--- @since 5.4.0
use_texture_alpha_string_modes = true,
--- degrotate param2 rotates in units of 1.5° instead of 2°
--- thus changing the range of values from 0-179 to 0-240
--- @since 5.5.0
degrotate_240_steps = true,
--- ABM supports min_y and max_y fields in definition
--- @since 5.5.0
abm_min_max_y = true,
--- dynamic_add_media supports passing a table with options
--- @since 5.5.0
dynamic_add_media_table = true,
--- particlespawners support texpools and animation of properties,
--- particle textures support smooth fade and scale animations, and
--- sprite-sheet particle animations can by synced to the lifetime
--- of individual particles
--- @since 5.6.0
particlespawner_tweenable = true,
--- allows get_sky to return a table instead of separate values
--- @since 5.6.0
get_sky_as_table = true,
--- VoxelManip:get_light_data accepts an optional buffer argument
--- @since 5.7.0
get_light_data_buffer = true,
--- When using a mod storage backend that is not "files" or "dummy",
--- the amount of data in mod storage is not constrained by
--- the amount of RAM available.
--- @since 5.7.0
mod_storage_on_disk = true,
--- "zstd" method for compress/decompress
--- @since 5.7.0
compress_zstd = true,
--- Sound parameter tables support start_time
--- @since 5.8.0
sound_params_start_time = true,
--- New fields for set_physics_override: speed_climb, speed_crouch,
--- liquid_fluidity, liquid_fluidity_smooth, liquid_sink,
--- acceleration_default, acceleration_air
--- @since 5.8.0
physics_overrides_v2 = true,
--- In HUD definitions the field `type` is used and `hud_elem_type` is deprecated
--- @since 5.9.0
hud_def_type_field = true,
--- PseudoRandom and PcgRandom state is restorable
--- PseudoRandom has get_state method
--- PcgRandom has get_state and set_state methods
--- @since 5.9.0
random_state_restore = true,
--- core.after guarantees that coexisting jobs are executed primarily
--- in order of expiry and secondarily in order of registration
--- @since 5.9.0
after_order_expiry_registration = true,
--- wallmounted nodes mounted at floor or ceiling may additionally
--- be rotated by 90° with special param2 values
--- @since 5.9.0
wallmounted_rotate = true,
--- Availability of the `pointabilities` property in the item definition
--- @since 5.9.0
item_specific_pointabilities = true,
--- Nodes `pointable` property can be `"blocking"`
--- @since 5.9.0
blocking_pointability_type = true,
--- dynamic_add_media can be called at startup when leaving callback as `nil`
--- @since 5.9.0
dynamic_add_media_startup = true,
--- dynamic_add_media supports `filename` and `filedata` parameters
--- @since 5.9.0
dynamic_add_media_filepath = true,
--- L-system decoration type
--- @since 5.9.0
lsystem_decoration_type = true,
--- Overrideable pointing range using the itemstack meta key `"range"`
--- @since 5.9.0
item_meta_range = true,
--- Allow passing an optional "actor" ObjectRef to the following functions:
--- core.place_node, core.dig_node, core.punch_node
--- @since 5.9.0
node_interaction_actor = true,
--- "new_pos" field in entity moveresult
--- @since 5.9.0
moveresult_new_pos = true,
--- Allow removing definition fields in `core.override_item`
override_item_remove_fields = true,
}
--- Returns `boolean, missing_features` ---Checks for server-side feature availability.
--- * `arg`: string or table in format `{foo=true, bar=true}`
--- * `missing_features`: `{foo=true, bar=true}`
---@param arg string|table ---@param arg string|table
--- @return boolean,table<string,boolean> ---@return boolean
---@return table<string,boolean> missing_features
function core.has_feature(arg) end function core.has_feature(arg) end
--- Table containing information ---@class Core.PlayerInformation
--- about a player. Example return value: ---@field address string
--- ```lua ---@field ip_version integer
--- { ---@field connection_uptime integer
--- address = "127.0.0.1", -- IP address of client ---@field protocol_version integer
--- ip_version = 4, -- IPv4 / IPv6 ---@field formspec_version integer
--- connection_uptime = 200, -- seconds since client connected ---@field lang_code string
--- protocol_version = 32, -- protocol version used by client ---@field min_rtt number?
--- formspec_version = 2, -- supported formspec version ---@field max_rtt number?
--- lang_code = "fr" -- Language code used for translation ---@field avg_rtt number?
--- -- the following keys can be missing if no stats have been collected yet ---@field min_jitter number?
--- min_rtt = 0.01, -- minimum round trip time ---@field max_jitter number?
--- max_rtt = 0.2, -- maximum round trip time ---@field avg_jitter number?
--- avg_rtt = 0.02, -- average round trip time ---@field version_string string
--- min_jitter = 0.01, -- minimum packet time jitter --- The following information is available in a debug build only!!!
--- max_jitter = 0.5, -- maximum packet time jitter -- -@field serialization_version integer?
--- avg_jitter = 0.03, -- average packet time jitter -- -@field major integer?
--- -- the following information is available in a debug build only!!! -- -@field minor integer?
--- -- DO NOT USE IN MODS -- -@field patch integer?
--- --ser_vers = 26, -- serialization version used by client -- -@field state string?
--- --major = 0, -- major version number
--- --minor = 4, -- minor version number ---Table containing information about a player.
--- --patch = 10, -- patch version number ---@param player_name string
--- --vers_string = "0.4.9-git", -- full version string ---@return Core.PlayerInformation
--- --state = "Active" -- current client state
--- }
--- ```
--- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4400-L4425)
function core.get_player_information(player_name) end function core.get_player_information(player_name) end
---Table mapping Luanti versions to corresponding protocol versions for modder convenience.
--- Will only be present if the client sent this information (requires v5.7+)
--- ---
--- Note that none of these things are constant, they are likely to change during a client ---For example, to check whether a client has at least the feature set of Luanti 5.8.0
--- connection as the player resizes the window and moves it between monitors ---or newer, you could do:
---
--- real_gui_scaling and real_hud_scaling can be used instead of DPI.
--- OSes don't necessarily give the physical DPI, as they may allow user configuration.
--- real_*_scaling is just OS DPI / 96 but with another level of user configuration.
---```lua ---```lua
--- { --- core.get_player_information(player_name).protocol_version >= core.protocol_versions["5.8.0"]
--- -- Current size of the in-game render target (pixels).
--- --
--- -- This is usually the window size, but may be smaller in certain situations,
--- -- such as side-by-side mode.
--- size = {
--- x = 1308,
--- y = 577,
--- },
---
--- -- Estimated maximum formspec size before Minetest will start shrinking the
--- -- formspec to fit. For a fullscreen formspec, use a size 10-20% larger than
--- -- this and `padding[-0.01,-0.01]`.
--- max_formspec_size = {
--- x = 20,
--- y = 11.25
--- },
---
--- -- GUI Scaling multiplier
--- -- Equal to the setting `gui_scaling` multiplied by `dpi / 96`
--- real_gui_scaling = 1,
---
--- -- HUD Scaling multiplier
--- -- Equal to the setting `hud_scaling` multiplied by `dpi / 96`
--- real_hud_scaling = 1,
---
--- -- Whether the touchscreen controls are enabled.
--- -- Usually (but not always) `true` on Android.
--- -- Requires at least Minetest 5.9.0 on the client. For older clients, it
--- -- is always set to `false`.
--- touch_controls = false,
--- }
---``` ---```
---@type table<string, integer>
core.protocol_versions = nil
---@class Core.PlayerWindowInformation
---@field size {x:integer,y:integer}
---@field max_formspec_size {x:integer,y:integer}
---@field real_gui_scaling number
---@field real_hud_scaling number
---@field touch_controls boolean
---@param player_name string
---@return Core.PlayerWindowInformation
function core.get_player_window_information(player_name) end function core.get_player_window_information(player_name) end
--- Returns success. ---Returns `true` if the given path exists else `false`.
--- * Creates a directory specified by `path`, creating parent directories ---@param path string
--- if they don't exist. ---@return boolean
function core.path_exists(path) end
---Creates a directory specified by path, creating parent directories if they don't exist.
--- ---
--- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4427-L4429) ---Returns success.
---@param path string
---@return boolean success
function core.mkdir(path) end function core.mkdir(path) end
---Removes a directory specified by path. ---Removes a directory specified by path.
--- If recursive is set to true, the directory is recursively removed. Otherwise, the directory will only be removed if it is empty. ---
--- Returns true on success, false on failure. ---If `recursive` is set to `true`, the directory is recursively removed.
---Otherwise, the directory will only be removed if it is empty.
---@param path string ---@param path string
---@param recursive boolean ---@param recursive boolean
--- @return boolean ---@return boolean success
function core.rmdir(path, recursive) end function core.rmdir(path, recursive) end
---Copies a directory specified by source to destination.
--- Copies a directory specified by path to destination ---
--- Any files in destination will be overwritten if they already exist. ---Any files in `destination` will be overwritten if they already exist.
--- Returns true on success, false on failure.
---@param source string ---@param source string
---@param destination string ---@param destination string
--- @return boolean ---@return boolean success
function core.cpdir(source, destination) end function core.cpdir(source, destination) end
---Moves a directory specified by source to destination.
--- Moves a directory specified by path to destination. ---
--- If the destination is a non-empty directory, then the move will fail. ---If the `destination` is a non-empty directory, then the move will fail.
--- Returns true on success, false on failure.
--- @param source string --- @param source string
--- @param destination string --- @param destination string
--- @return boolean --- @return boolean success
function core.mvdir(source, destination) end function core.mvdir(source, destination) end
---Returns list of entry names ---Returns list of entry names
--- * `is_dir` [Optional] is one of: ---@param path string
--- * nil: return all entries, ---@param is_dir boolean? is one of:
--- * true: return only subdirectory names, or --- * `nil`: return all entries
--- * false: return only file names. --- * `true`: return only subdirectory names
--- --- * `false`: return only file names
--- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4430-L4434) ---@return string[]
function core.get_dir_list(path, is_dir) end function core.get_dir_list(path, is_dir) end
--- Returns boolean indicating success ---Replaces contents of file at path with new contents in a safe (atomic) way.
--- * Replaces contents of file at path with new contents in a safe (atomic)
--- way. Use this instead of below code when writing e.g. database files:
--- `local f = io.open(path, "wb"); f:write(content); f:close()`
--- ---
--- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4435-L4438) ---Use this instead of below code when writing e.g. database files:
---```lua
--- local f = io.open(path, "wb"); f:write(content); f:close()
---```
---@param path string
---@param content string
function core.safe_file_write(path, content) end function core.safe_file_write(path, content) end
--- Returns a table containing components of the ---@class Core.Version
--- engine version. Components: ---@field project string
--- * `project`: Name of the project, eg, "Minetest" ---@field string string
--- * `string`: Simple version, eg, "1.2.3-dev" ---@field proto_min integer
--- * `hash`: Full git version (only set if available), ---@field proto_max integer
--- eg, "1.2.3-dev-01234567-dirty". ---@field hash string
--- Use this for informational purposes only. The information in the returned ---@field is_dev string
--- table does not represent the capabilities of the engine, nor is it
--- reliable or verifiable. Compatible forks will have a different name and ---Returns a table containing components of the engine version.
--- version entirely. To check for the presence of engine features, test ---@return Core.Version
--- whether the functions exported by the wanted features exist. For example:
--- `if core.check_for_falling then ... end`.
---
--- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4439-L4450)
function core.get_version() end function core.get_version() end
--- Returns the sha1 hash of data ---Returns the sha1 hash of data.
--- * `data`: string of data to hash ---@param data string string of data to hash
--- * `raw`: [Optional] return raw bytes instead of hex digits, default: false ---@param raw boolean? return raw bytes instead of hex digits, default: `false`
--- ---@return string
--- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4451-L4453)
function core.sha1(data, raw) end function core.sha1(data, raw) end
--- Returns the sha256 hash of `data` ---Returns the sha256 hash of data
---@param data string string of data to hash ---@param data string string of data to hash
--- @param raw boolean optional. return raw bytes instead of hex digits, default: false ---@param raw boolean? return raw bytes instead of hex digits, default: `false`
---@return string
function core.sha256(data, raw) end function core.sha256(data, raw) end
--- Converts a ColorSpec to a ColorString. If the ColorSpec is invalid, returns `nil`. ---Converts a `ColorSpec` to a `ColorString`.
--- @param colorspec ColorSpec The ColorSpec to convert. ---
---If the ColorSpec is invalid, returns `nil`.
---@param colorspec ColorSpec
---@return ColorString? ---@return ColorString?
function core.colorspec_to_colorstring(colorspec) end function core.colorspec_to_colorstring(colorspec) end
--- Converts a ColorSpec to a raw string of four bytes in an RGBA layout, returned as a string. ---Converts a `ColorSpec` to a raw string of four bytes in an RGBA layout,
--- @param colorspec ColorSpec The ColorSpec to convert. ---returned as a string.
---@param colorspec ColorSpec
---@return string? ---@return string?
function core.colorspec_to_bytes(colorspec) end function core.colorspec_to_bytes(colorspec) end
--- Converts a ColorSpec into RGBA table form. If the ColorSpec is invalid, returns nil. You can use this to parse ColorStrings. ---Converts a `ColorSpec` into RGBA table form.
--- @param colorspec ColorSpec The ColorSpec to convert. ---
--- @return {r:number, g:number, b:number, a:number}? ---If the ColorSpec is invalid, returns `nil`. You can use this to parse `ColorStrings`.
---@param colorspec ColorSpec
---@return ColorTable?
function core.colorspec_to_table(colorspec) end function core.colorspec_to_table(colorspec) end
---Returns a `"day-night ratio"` value (as accepted by `ObjectRef:override_day_night_ratio`)
---that is equivalent to the given `"time of day"` value (as returned by `core.get_timeofday`).
---@param time_of_day number?
function core.time_to_day_night_ratio(time_of_day) end
---Encode a PNG image and return it in string form.
---@param width integer Width of the image (integer in range [u32])
---@param height integer Height of the image (integer in range [u32])
---@param data table Image data, one of:
--- * array table of ColorSpec, length must be `width*height`
--- * string with raw RGBA pixels, length must be `width*height*4`
---@param compression integer? Optional zlib compression level, integer in range [0, 9].
--- The data is one-dimensional, starting in the upper left
--- corner of the image and laid out in scanlines going from
--- left to right, then top to bottom.
--- You can use colorspec_to_bytes to generate raw RGBA values.
--- Palettes are not supported at the moment. You may use this
--- to procedurally generate textures during server init.
---@return string
function core.encode_png(width, height, data, compression) end
---Encodes reserved URI characters by a percent sign followed by two hex digits.
---
---See [RFC 3986, section 2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
---@param str string
function core.urlencode(str) end

View File

@@ -1,8 +1,8 @@
--- @meta --- @meta
--- @class HudDefinition --- @class HUDDefinition
local HudDefinition = { local HUDDefinition = {
--- Name of the HUD element. --- Name of the HUD element.
--- ---
--- The `name` field is not yet used, but should contain a description of what the HUD element represents. --- The `name` field is not yet used, but should contain a description of what the HUD element represents.

View File

@@ -1,243 +1,12 @@
---@meta ---@meta
---The original `ItemDefinition`, described in the Luanti API Reference,
--- @class ItemDefinition: table ---was split into `ItemDefinition.Settings` and `ItemDefinition.Callbacks`.
local ItemDefinition = { ---
--- Can contain new lines. "\n" has to be used as new line character. ---Please look at the fields and methods in the corresponding classes.
--- See also: `get_description` in [`ItemStack`] ---
--- @type string? ---This `ItemDefinition` class is a combination of `ItemDefinition.Settings`
description = "", ---and `ItemDefinition.Callbacks` and to some extent corresponds to the original.
---@class ItemDefinition : ItemDefinition.Settings, ItemDefinition.Callbacks
--- Must not contain new lines. ---@field [string] any
--- Defaults to nil. local ItemDefinition = {}
--- Use an [`ItemStack`] to get the short description, e.g.:
--- ItemStack(itemname):get_short_description()
--- @type string?
short_description = "",
--- 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<string,number>?
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<string,any>?
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<string,table<string,any>>
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<string,number>
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<string,SimpleSoundSpec>?
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 >",
}

View File

@@ -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

View File

@@ -0,0 +1,20 @@
---Version: 5.18
---@meta
---@class ItemDefinition.Groups
---@field [string] integer?
local ItemDefinition = {}
--- Luanti groups ---
---Special group for inventory mods to indicate that the item should be hidden in item lists.
---@type integer?
ItemDefinition.not_in_creative_inventory = nil
---If set to 1 for a tool, it cannot be repaired using the `"toolrepair"` crafting recipe.
---@type integer?
ItemDefinition.disable_repair = nil
--- SMC groups ---

View File

@@ -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 ItemDefinition.Groups?
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<string, ItemDefinition.pointabilities_table.value>, objects:table<string, ItemDefinition.pointabilities_table.value>}
---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<string, {times:number[], uses:integer, maxlevel:integer}>
---@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<string, integer>
---
---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<number, ColorSpec>
---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<string,SimpleSoundSpec>?
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

View File

@@ -0,0 +1,5 @@
---Version: 5.16
---@meta
---Basically a tile definition but for items.
---@alias ItemImageDefinition {name:string, animation:TileAnimationDefinition}|string

View File

@@ -1,651 +1,11 @@
---@meta ---@meta
---The original `NodeDefinition`, described in the Luanti API Reference,
--- @class NodeDefinition: ItemDefinition ---was split into `NodeDefinition.Settings` and `NodeDefinition.Callbacks`.
local NodeDefinition = {
--- For last version see ["Node drawtypes"](https://api.luanti.org/nodes/#node-drawtypes)
--- ---
--- There are a bunch of different looking node types. ---Please look at the fields and methods in the corresponding classes.
--- * `normal`
--- * * A node-sized cube.
--- * `airlike`
--- * * Invisible, uses no texture.
--- * `liquid`
--- * * The cubic source node for a liquid.
--- * * Faces bordering to the same node are never rendered.
--- * * Connects to node specified in `liquid_alternative_flowing` if specified.
--- * * Use `backface_culling = false` for the tiles you want to make
--- visible when inside the node.
--- * `flowingliquid`
--- * * The flowing version of a liquid, appears with various heights and slopes.
--- * * Faces bordering to the same node are never rendered.
--- * * Connects to node specified in `liquid_alternative_source`.
--- * * You *must* set `liquid_alternative_flowing` to the node's own name.
--- * * Node textures are defined with `special_tiles` where the first tile
--- is for the top and bottom faces and the second tile is for the side
--- faces.
--- * * `tiles` is used for the item/inventory/wield image rendering.
--- * * Use `backface_culling = false` for the special tiles you want to make
--- visible when inside the node
--- * `glasslike`
--- * * Often used for partially-transparent nodes.
--- * * Only external sides of textures are visible.
--- * `glasslike_framed`
--- * * All face-connected nodes are drawn as one volume within a surrounding
--- frame.
--- * * The frame appearance is generated from the edges of the first texture
--- specified in `tiles`. The width of the edges used are 1/16th of texture
--- size: 1 pixel for 16x16, 2 pixels for 32x32 etc.
--- * * The glass 'shine' (or other desired detail) on each node face is supplied
--- by the second texture specified in `tiles`.
--- * `glasslike_framed_optional`
--- * * This switches between the above 2 drawtypes according to the menu setting
--- 'Connected Glass'.
--- * `allfaces`
--- * * Often used for partially-transparent nodes.
--- * * External sides of textures, and unlike other drawtypes, the external sides
--- of other nodes, are visible from the inside.
--- * `allfaces_optional`
--- * * Often used for leaves nodes.
--- * * This switches between `normal`, `glasslike` and `allfaces` according to
--- the menu setting: Opaque Leaves / Simple Leaves / Fancy Leaves.
--- * * With 'Simple Leaves' selected, the texture specified in `special_tiles`
--- is used instead, if present. This allows a visually thicker texture to be
--- used to compensate for how `glasslike` reduces visual thickness.
--- * `torchlike`
--- * * A single vertical texture.
--- * * If `paramtype2="[color]wallmounted"`:
--- * * * If placed on top of a node, uses the first texture specified in `tiles`.
--- * * * If placed against the underside of a node, uses the second texture
--- specified in `tiles`.
--- * * * If placed on the side of a node, uses the third texture specified in
--- `tiles` and is perpendicular to that node.
--- * * If `paramtype2="none"`:
--- * * * Will be rendered as if placed on top of a node (see
--- above) and only the first texture is used.
--- * `signlike`
--- * * A single texture parallel to, and mounted against, the top, underside or
--- side of a node.
--- * * If `paramtype2="[color]wallmounted"`, it rotates according to `param2`
--- * * If `paramtype2="none"`, it will always be on the floor.
--- * `plantlike`
--- * * Two vertical and diagonal textures at right-angles to each other.
--- * * See `paramtype2 = "meshoptions"` above for other options.
--- * `firelike`
--- * * When above a flat surface, appears as 6 textures, the central 2 as
--- `plantlike` plus 4 more surrounding those.
--- * * If not above a surface the central 2 do not appear, but the texture
--- appears against the faces of surrounding nodes if they are present.
--- * `fencelike`
--- * * A 3D model suitable for a wooden fence.
--- * * One placed node appears as a single vertical post.
--- * * Adjacently-placed nodes cause horizontal bars to appear between them.
--- * `raillike`
--- * * Often used for tracks for mining carts.
--- * * Requires 4 textures to be specified in `tiles`, in order: Straight,
--- curved, t-junction, crossing.
--- * * Each placed node automatically switches to a suitable rotated texture
--- determined by the adjacent `raillike` nodes, in order to create a
--- continuous track network.
--- * * Becomes a sloping node if placed against stepped nodes.
--- * `nodebox`
--- * * Often used for stairs and slabs.
--- * * Allows defining nodes consisting of an arbitrary number of boxes.
--- * * See [Node boxes] below for more information.
--- * `mesh`
--- * * Uses models for nodes.
--- * * Tiles should hold model materials textures.
--- * * Only static meshes are implemented.
--- * * For supported model formats see Irrlicht engine documentation.
--- * `plantlike_rooted`
--- * * Enables underwater `plantlike` without air bubbles around the nodes.
--- * * Consists of a base cube at the coordinates of the node plus a
--- `plantlike` extension above
--- * * If `paramtype2="leveled", the `plantlike` extension has a height
--- of `param2 / 16` nodes, otherwise it's the height of 1 node
--- * * If `paramtype2="wallmounted"`, the `plantlike` extension
--- will be at one of the corresponding 6 sides of the base cube.
--- Also, the base cube rotates like a `normal` cube would
--- * * The `plantlike` extension visually passes through any nodes above the
--- base cube without affecting them.
--- * * The base cube texture tiles are defined as normal, the `plantlike`
--- extension uses the defined special tile, for example:
--- `special_tiles = {{name = "default_papyrus.png"}},`
--- ---
--- `*_optional` drawtypes need less rendering time if deactivated(always client-side). ---This `NodeDefinition` class is a combination of `NodeDefinition.Settings`
--- ---and `NodeDefinition.Callbacks` and to some extent corresponds to the original.
--- @type string? ---@class NodeDefinition: NodeDefinition.Settings, NodeDefinition.Callbacks
drawtype = "normal", local NodeDefinition = {}
--- 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,
--- {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[]|TileDefinition[])?
tiles = nil,
--- {tile definition 1, def2, def3, def4, def5, def6}
---
--- Same as `tiles`, but these textures are drawn on top of the base
--- tiles. You can use this to colorize only specific parts of your
--- 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[]|TileDefinition[])?
overlay_tiles = nil,
--- {tile definition 1, Tile definition 2},
--- Special textures of node; used rarely.
--- List can be shortened to needed length.
--- @type (string[]|TileDefinition[])?
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.
--- @see ColorSpec
--- @type (string|ColorSpec)?
color = '',
--- 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 = "",
--- Screen tint if player is inside node, see "ColorSpec"
--- @type string?
post_effect_color = "#00000000",
--- See "Nodes"
--- @type string?
paramtype = "none",
--- See "Nodes"
--- @type string?
paramtype2 = "none",
--- Value for param2 that is set when player places node
--- @type number?
place_param2 = 0,
--- 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 true, sunlight will go infinitely through this node
--- @type boolean?
sunlight_propagates = false,
--- If true, objects collide with node
--- @type boolean?
walkable = true,
--- If true, can be pointed at
--- @type boolean?
pointable = true,
--- If false, can never be dug
--- @type boolean?
diggable = true,
--- 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,
--- 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,
--- 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 = "",
--- 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,
--- If true, a new liquid source can be created by placing two or more
--- sources nearby
--- @type boolean?
liquid_renewable = true,
--- 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?
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,
--- Maximum value for `leveled` (0-127), enforced in
--- `core.set_node_level` and `core.add_node_level`.
--- Values above 124 might causes collision detection issues.
--- @type number?
leveled_max = 127,
--- 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,
--- Player will take this amount of damage if no bubbles are left
--- @type number?
drowning = 0,
--- If player is inside node, this damage is caused
--- @type number?
damage_per_second = 0,
--- See "Node boxes"
--- @type table?
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 = {},
--- Tells connected nodebox nodes to connect only to these sides of this
--- node. possible: "top", "bottom", "front", "left", "back", "right"
--- @type string[]?
connect_sides = {},
--- File name of mesh when using "mesh" drawtype
--- @type string?
mesh = "",
--- 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
--- @type table?
selection_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.
--- @type table?
collision_box = {},
--- 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,
--- Definition of node sounds to be played at various events.
--- All fields in this table are optional.
--- @type nil|table<string,SimpleSoundSpec|string?>
sounds = {
--- 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,
--- While digging node.
--- If `"__group"`, then the sound will be
--- `{name = "default_dig_<groupname>", gain = 0.5}` , where `<groupname>` 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 nil|SimpleSoundSpec|string
dig = {} or "__group",
--- Node was dug
--- @type SimpleSoundSpec?
dug = nil,
--- Node was placed. Also played after falling
--- @type SimpleSoundSpec?
place = 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.
--- @type SimpleSoundSpec?
place_failed = nil,
--- When node starts to fall or is detached
--- @type SimpleSoundSpec?
fall = nil,
},
--- Name of dropped item when dug.
--- Default dropped item is the node itself.
--- Using a table allows multiple items, drop chances and item filtering:
--- @type (string|table)?
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,
--- 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, core.set_node can cause an
--- infinite loop if it invokes the same callback.
--- Consider using `core.swap_node()` instead.
--- default: nil
--- @type fun(pos:MapPosition)?
on_construct = nil,
--- Node destructor; called before removing node.
--- Not called for bulk node placement.
--- default: nil
--- @type fun(pos:MapPosition)?
on_destruct = nil,
--- Node destructor; called after removing node.
--- Not called for bulk node placement.
--- default: nil
--- @type fun(pos:MapPosition, old_node)?
after_destruct = nil,
--- 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:MapPosition, old_node, new_node)?
on_flood = nil,
--- 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:MapPosition, old_node, new_node, old_meta, drops:ItemStack[])?
preserve_metadata = nil,
--- Called after constructing node when node was placed using
--- core.item_place_node / core.place_node.
--- If return true no item is taken from itemstack.
--- `placer` may be any valid ObjectRef or nil.
--- default: nil
--- @type fun(pos:MapPosition, placer:Player|ObjectRef|nil, itemstack:ItemStack, pointed_thing:pointed_thing)?
after_place_node = nil,
--- oldmetadata is in table format.
--- Called after destructing node when node was dug using
--- core.node_dig / core.dig_node.
--- default: nil
--- @type fun(pos:Player, oldnode, oldmetadata, digger:Player|ObjectRef|nil)?
after_dig_node = nil,
--- Returns true if node can be dug, or false if not.
--- default: nil
--- @type fun(pos:MapPosition, player:Player|ObjectRef|nil)?
can_dig = nil,
--- default: core.node_punch
--- Called when puncher (an ObjectRef) punches the node at pos.
--- By default calls core.register_on_punchnode callbacks.
--- @type fun(pos:MapPosition, node:NodeTable, puncher:Player|ObjectRef|nil, pointed_thing:pointed_thing)?
on_punch = 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.
--- @type (fun(pos:MapPosition, node:NodeTable, clicker:Player|ObjectRef, itemstack:ItemStack, pointed_thing:pointed_thing|nil):ItemStack|nil)?
on_rightclick = core.node_punch,
--- default: core.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:MapPosition, node:NodeTable, digger:Player): boolean)?
on_dig = nil,
--- default: nil
--- called by NodeTimers, see core.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:MapPosition, elapsed:number): boolean)?
on_timer = nil,
--- fields = {name1 = value1, name2 = value2, ...}
--- Called when an UI form (e.g. sign text input) returns data.
--- See core.register_on_player_receive_fields for more info.
--- default: nil
--- @type fun(pos:MapPosition, formname:string, fields:table, sender:Player)?
on_receive_fields = nil,
--- Called when a player wants to move items inside the inventory.
--- Return value: number of items allowed to move.
--- @type (fun(pos:MapPosition, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): number)?
allow_metadata_inventory_move = 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 (fun(pos:MapPosition, listname:string, index:number, stack:ItemStack, player:Player): number)?
allow_metadata_inventory_put = 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 (fun(pos:MapPosition, listname:string, index:number, stack:ItemStack, player:Player): number)?
allow_metadata_inventory_take = nil,
--- Called after the actual action has happened, according to what was
--- allowed.
--- No return value.
--- @type (fun(pos:MapPosition, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): void)?
on_metadata_inventory_move = nil,
--- Called after the actual action has happened, according to what was
--- allowed.
--- No return value.
--- @type (fun(pos:MapPosition, listname:string, index:number, stack:ItemStack, player:Player): void)?
on_metadata_inventory_put = nil,
--- Called after the actual action has happened, according to what was
--- allowed.
--- No return value.
--- @type (fun(pos:MapPosition, listname:string, index:number, stack:ItemStack, player:Player): void)?
on_metadata_inventory_take = nil,
--- 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:MapPosition, intensity:number): void)?
on_blast = nil,
--- 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",
}

View File

@@ -0,0 +1,193 @@
---Version: 5.16
---@meta
---@class NodeDefinition.Callbacks : ItemDefinition.Callbacks
local Callbacks = {}
---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, `core.set_node` can cause an
---infinite loop if it invokes the same callback.
---
---Consider using `core.swap_node` instead.
---
---default: `nil`
---@type fun(pos:MapVector)?
Callbacks.on_construct = nil
---Node destructor; called before removing node.
---
---Not called for bulk node placement.
---
---default: `nil`
---@type fun(pos:MapVector)?
Callbacks.on_destruct = nil
---Node destructor; called after removing node.
---
---Not called for bulk node placement.
---
---default: `nil`
---@type fun(pos:MapVector, oldnode:NodeTable)?
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
---(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:MapVector, oldnode:NodeTable, newnode:NodeTable):boolean?)?
Callbacks.on_flood = 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.
--- * `pos`: node position
--- * `oldnode`: node table of node before it was deleted
--- * `oldmeta`: metadata of node before it was deleted, as a metadata table
--- * `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](lua://ItemStackMetaRef).
---
---Default: `nil`
---@type fun(pos:MapVector, oldnode:NodeTable, newnode:NodeTable, oldmeta:NodeMetaRef, drops:ItemStack[])?
Callbacks.preserve_metadata = nil
---Called after constructing node when node was placed using
---`core.item_place_node` / `core.place_node`.
---
---If return `true` no item is taken from itemstack.
---
---Default: `nil`
---@type (fun(pos:MapVector, placer:Player|ObjectRef|nil, itemstack:ItemStack, pointed_thing:pointed_thing):boolean?)?
Callbacks.after_place_node = nil
---Called after destructing the node when node was dug using
---`core.node_dig` / `core.dig_node`.
---
--- * `pos`: node position
--- * `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
---
---Default: `nil`
---@type fun(pos:Player, oldnode:NodeMetaRef, oldmetadata:NodeMetaRef, digger:Player|ObjectRef|nil)?
Callbacks.after_dig_node = nil
---Returns `true` if node can be dug, or `false` if not.
---
---Default: `nil`
---@type (fun(pos:MapVector, player:Player|ObjectRef|nil):boolean)?
Callbacks.can_dig = nil
---Called when puncher (an ObjectRef) punches the node at pos.
---
---By default calls `core.register_on_punchnode` callbacks.
---
---Default: `core.node_punch`
---@type fun(pos:MapVector, node:NodeTable, puncher:Player|ObjectRef, pointed_thing:pointed_thing)?
Callbacks.on_punch = 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.
---
---Default: `nil`
---@type (fun(pos:MapVector, node:NodeTable, clicker:Player|ObjectRef, itemstack:ItemStack, pointed_thing:pointed_thing?):ItemStack|nil)?
Callbacks.on_rightclick = nil
---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: `core.node_dig`
---@type (fun(pos:MapVector, node:NodeTable, digger:Player):boolean)?
Callbacks.on_dig = nil
---Called by NodeTimers, see `core.get_node_timer` and [NodeTimerRef](lua://NodeTimerRef).
---
--- * `elapsed`: total time passed since the timer was started.
--- * `node`: node table (since 5.14)
--- * `timeout`: timeout value of the just ended timer (since 5.14)
---
---Return `true` to run the timer for another cycle with the same timeout value.
---
---Default: `nil`
---@type (fun(pos:MapVector, elapsed:number, node:NodeTable, timeout:number):boolean?)?
Callbacks.on_timer = nil
---Fields = {name1 = value1, name2 = value2, ...}
---
---Formname should be the empty string; you **must not** use formname.
---
---Called when an UI form (e.g. sign text input) returns data.
---
---See `core.register_on_player_receive_fields` for more info.
---
---Default: `nil`
---@type fun(pos:MapVector, formname:string, fields:table<string, any>, sender:Player)?
Callbacks.on_receive_fields = nil
---Called when a player wants to move items inside the inventory.
---
---Return value: number of items allowed to put.
---@type (fun(pos:MapVector, from_list:string, from_index:integer, to_list:string, to_index:integer, count:integer, player:Player):number)?
Callbacks.allow_metadata_inventory_move = nil
---Called when a player wants to put something into 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:MapVector, listname:string, index:integer, stack:ItemStack, player:Player):number)?
Callbacks.allow_metadata_inventory_put = 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 (fun(pos:MapVector, listname:string, index:integer, stack:ItemStack, player:Player):number)?
Callbacks.allow_metadata_inventory_take = nil
---Called after the actual action has happened, according to what was allowed.
---
---No return value.
---@type fun(pos:MapVector, from_list:string, from_index:integer, to_list:string, to_index:integer, count:integer, player:Player)?
Callbacks.on_metadata_inventory_move = nil
---Called after the actual action has happened, according to what was allowed.
---
---No return value.
---@type fun(pos:MapVector, listname:string, index:number, stack:ItemStack, player:Player)?
Callbacks.on_metadata_inventory_put = nil
---Called after the actual action has happened, according to what was allowed.
---
---No return value.
---@type fun(pos:MapVector, listname:string, index:number, stack:ItemStack, player:Player)?
Callbacks.on_metadata_inventory_take = nil
---If defined, called when an explosion touches the node, instead of
---removing the node.
---
--- * `intensity`: 1.0 = mid range of regular TNT.
---@type fun(pos:MapVector, intensity:number)?
Callbacks.on_blast = nil

View File

@@ -0,0 +1,150 @@
---Version: 5.18
---@meta
---@class NodeDefinition.Groups : ItemDefinition.Groups
---@field [string] integer?
local NodeDefinition = {}
--- Luanti groups ---
---The node is `'attached'` to a neighboring node.
---
---It checks whether the node it is attached to is walkable.
---If it isn't, the node will drop as an item.
---
--- * `1`: if the node is wallmounted, the node is attached in the wallmounted direction.
--- Otherwise, the node is attached to the node below.
--- * `2`: if the node is facedir or 4dir, the facedir or 4dir direction is checked.
--- No effect for other nodes. Note: The "attaching face" of this node is tile № 5 (back face).
--- * `3`: the node is always attached to the node below.
--- * `4`: the node is always attached to the node above.
---@type integer?
NodeDefinition.attached_node = nil
---Value is bounce speed in percent.
---
---If positive, jump/sneak on floor impact will increase/decrease bounce height.
---
---Negative value is the same bounciness, but non-controllable.
---@type integer?
NodeDefinition.bouncy = nil
---Makes nodes of raillike drawtype with same group value connect to each other
---@type integer?
NodeDefinition.connect_to_raillike = nil
---Player can always pick up node without reducing tool wear
--- * `2`: the node always gets the digging time 0.5 seconds (rail, sign)
--- * `3`: the node always gets the digging time 0 seconds (torch)
---@type integer?
NodeDefinition.connect_to_raillike = nil
---Player (and possibly other things) cannot jump from node or
---if their feet are in the node.
---
---**Note**: not supported for `new_move = false`.
---@type integer?
NodeDefinition.disable_jump = nil
---Player (and possibly other things) cannot actively descend in node using `Sneak` or `Aux1`
---key (for liquids and climbable nodes only).
---
---**Note**: not supported for `new_move = false`.
---@type integer?
NodeDefinition.disable_descend = nil
---Modifies the fall damage suffered when hitting the top of this node.
---
---There's also an armor group with the same name.
---
---The final player damage is determined by the following formula:
---```lua
--- damage =
--- collision speed
--- * ((node_fall_damage_add_percent + 100) / 100) -- node group
--- * ((player_fall_damage_add_percent + 100) / 100) -- player armor group
--- - (14)
---```
---
---Negative damage values are discarded as no damage.
---@type integer?
NodeDefinition.fall_damage_add_percent = nil
---If there is no walkable node under the node it will fall.
---
---It also falls if the node below is `buildable_to`.
---@type integer?
NodeDefinition.falling_node = nil
---The node will not fall through liquids (liquidtype ~= "none")
---
---A liquid source with `groups = {falling_node = 1, float = 1}`
---will fall through flowing liquids.
---@type integer?
NodeDefinition.float = nil
---Can be used to give an additional sense of progression in the game.
---@type integer?
NodeDefinition.level = nil
---Players and items will slide on the node.
---
---Slipperiness rises steadily with `slippery` value, starting at `1`.
---@type integer?
NodeDefinition.slippery = nil
---Can be added to nodes that shouldn't logically be breakable by the hand but are.
---
---Somewhat similar to dig_immediate, but times are more like `{[1]=3.50,[2]=2.00,[3]=0.70}`
---and this does not override the digging speed of an item if it can dig at
---a faster speed than this suggests for the hand.
NodeDefinition.oddly_breakable_by_hand = nil
--- SMC groups digging time defining group ---
---Digging time defining group.
---
---Suitable for items that can be cut (режущийся).
---@type integer?
NodeDefinition.cutting = nil
---Digging time defining group.
---
---Suitable for items that can be crash (раскалываемый).
---@type integer?
NodeDefinition.crushing = nil
---Digging time defining group.
---
---Suitable for items that can be chop (рубящийся).
---@type integer?
NodeDefinition.chopping = nil
---Digging time defining group.
---
---Suitable for items that can be dig (вскапывающийся).
---@type integer?
NodeDefinition.digging = nil
--- SMC node types groups ---
---@type integer?
NodeDefinition.slabs = nil
---@type integer?
NodeDefinition.stairs = nil
--- SMC special groups ---
---A group for the automatic registration of node segments (slabs and stairs).
--- * `1`: registration only slabs
--- * `2`: registration only stairs
--- * `3`: registration slabs & stairs
---@type integer?
NodeDefinition.segments = nil

View File

@@ -0,0 +1,500 @@
---Version: 5.16
---@meta
---@class NodeDefinition.Settings : ItemDefinition.Settings
local Settings = {}
---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 NodeDefinition.Groups?
Settings.groups = nil
---@alias Node.Settings.drawtype
---|'normal'
---|'airlike'
---|'liquid'
---|'flowingliquid'
---|'glasslike'
---|'glasslike_framed'
---|'glasslike_framed_optional'
---|'allfaces'
---|'allfaces_optional'
---|'torchlike'
---|'signlike'
---|'plantlike'
---|'firelike'
---|'fencelike'
---|'raillike'
---|'nodebox'
---|'mesh'
---|'plantlike_rooted'
---See [Node drawtypes](https://api.luanti.org/nodes/#node-drawtypes)
---@type Node.Settings.drawtype?
Settings.drawtype = nil
---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?
Settings.visual_scale = nil
---Textures of node: +Y, -Y, +X, -X, +Z, -Z.
---
---List can be shortened to needed length.
---@type TileDefinition[]|nil
Settings.tiles = {}
---Same as `tiles`, but these textures are drawn on top of the base
---tiles. You can use this to colorize only specific parts of your
---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 TileDefinition?
Settings.overlay_tiles = nil
---Special textures of node; used rarely.
---
---List can be shortened to needed length.
---@type TileDefinition?
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 ColorSpec?
Settings.color = nil
---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.
--- Use this for nodes with fully transparent and fully opaque areas.
---* `"blend"`:
--- The alpha channel specifies how transparent a given pixel
--- of the rendered node is. This comes at a performance cost.
--- Only use this when correct rendering
--- among semitransparent nodes is necessary.
---
---The default is `"opaque"` for drawtypes normal, liquid and flowingliquid,
---mesh and nodebox or "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 'opaque'|'clip'|'blend'
Settings.use_texture_alpha = nil
---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?
Settings.palette = nil
---Screen tint if a player is inside this node, see `ColorSpec`.
---
---Color is alpha-blended over the screen.
---@type ColorSpec?
Settings.post_effect_color = nil
---Determines whether `post_effect_color` is affected by lighting.
---@type boolean?
Settings.post_effect_color_shaded = nil
---@alias NodeDefinition.paramtype
---|'light'
---|'none'
---See [Node paramtypes](https://api.luanti.org/nodes/#node-paramtypes)
---@type NodeDefinition.paramtype?
Settings.paramtype = nil
---@alias NodeDefinition.paramtype2
---|'flowingliquid'
---|'wallmounted'
---|'facedir'
---|'4dir'
---|'leveled'
---|'degrotate'
---|'meshoptions'
---|'color'
---|'colorfacedir'
---|'color4dir'
---|'colorwallmounted'
---|'glasslikeliquidlevel'
---|'colordegrotate'
---|'none'
---See [Node paramtypes](https://api.luanti.org/nodes/#node-paramtypes)
---@type NodeDefinition.paramtype2?
Settings.paramtype2 = nil
---Value for param2 that is set when player places node.
---@type integer?
Settings.place_param2 = nil
---If true, place_param2 is nil, and this is a wallmounted node,
---this node might use the special 90° rotation when placed
---on the floor or ceiling, depending on the direction.
---
---See the explanation about wallmounted for details.
---
---Otherwise, the rotation is always the same on vertical placement.
---@type boolean?
Settings.wallmounted_rotate_vertical = nil
---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?
Settings.is_ground_content = nil
---If `true`, sunlight will go infinitely through this node.
---@type boolean?
Settings.sunlight_propagates = nil
---If `true`, objects collide with node.
---@type boolean?
Settings.walkable = nil
---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.
---
---A client may be able to point non-pointable nodes, since it isn't checked server-side.
---@type (boolean|'blocking')?
Settings.pointable = nil
---If `false`, can never be dug.
---@type boolean?
Settings.diggable = nil
---If `true`, can be climbed on like a ladder.
---@type boolean?
Settings.climbable = nil
---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 integer?
Settings.move_resistance = nil
---If `true`, placed nodes can replace this node.
---@type boolean?
Settings.buildable_to = nil
---If `true`, liquids flow into and replace this node.
---
---**Warning**: making a liquid node `'floodable'` will cause problems.
---@type boolean?
Settings.floodable = nil
---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 'nonde'|'source'|'flowing'|nil
Settings.liquidtype = nil
---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 `liquidtype ~= "none"` 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?
Settings.liquid_alternative_flowing = nil
---See `Node.Settings.liquid_alternative_flowing`.
---@type string?
Settings.liquid_alternative_source = nil
---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 integer?
Settings.liquid_viscosity = nil
---If `true`, a new liquid source can be created by placing two or more
---sources nearby.
---@type boolean?
Settings.liquid_renewable = 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.
---@type boolean?
Settings.liquid_move_physics = nil
---Unclear meaning, the engine sets this to true for 'air' and 'ignore' deprecated.
---@type string?
Settings.air_equivalent = nil
---Only valid for "nodebox" drawtype with 'type = "leveled"'.
---
---Allows defining the nodebox height without using param2.
---
---The nodebox height is `leveled` / 64 nodes.
---
---Integer with range [0, `leveled_max`].
---@type integer?
Settings.leveled = nil
---Maximum value for `leveled` (0-127), enforced in
---`core.set_node_level` and `core.add_node_level`.
---
---Values above 124 might causes collision detection issues.
---@type integer?
Settings.leveled_max = nil
---Maximum distance that flowing liquid nodes can spread around
---source on flat land;
---maximum = 8; set to 0 to disable liquid flow.
---@type integer?
Settings.liquid_range = nil
---Player will take this amount of damage if no bubbles are left.
---@type number?
Settings.drowning = nil
---If player is inside node, this damage is caused.
---@type number?
Settings.damage_per_second = nil
---@alias NodeDefinition.node_box.box [number, number, number, number, number, number]
---@alias NodeDefinition.node_box
---|{ type:'regular' }
---|{ type:'fixed', fixed:NodeDefinition.node_box.box|NodeDefinition.node_box.box[] }
---|{ type:'leveled', fixed:NodeDefinition.node_box.box|NodeDefinition.node_box.box[] }
---|{ type:'wallmounted', wall_top:NodeDefinition.node_box.box, wall_bottom:NodeDefinition.node_box.box, wall_side:NodeDefinition.node_box.box }
---|{
--- type:'connected',
--- fixed:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- connect_top:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- connect_bottom:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- connect_front:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- connect_left:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- connect_back:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- connect_right:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- disconnected_top:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- disconnected_bottom:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- disconnected_front:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- disconnected_left:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- disconnected_back:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- disconnected_right:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- disconnected:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
--- disconnected_sides:NodeDefinition.node_box.box|NodeDefinition.node_box.box[],
---}
---See "Node boxes"
---@type NodeDefinition.node_box?
Settings.node_box = nil
---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|string[])?
Settings.connects_to = nil
---Tells connected nodebox nodes to connect only to these sides of this node.
---@type 'top'|'bottom'|'front'|'left'|'back'|'right'|nil
Settings.connect_sides = nil
---File name of mesh when using "mesh" drawtype
---The center of the node is the model origin.
---
---For legacy reasons, this uses a different scale depending on the mesh:
--- 1. For `glTF` models: 10 units = 1 node (consistent with the scale for entities).
--- 2. For `obj` models: 1 unit = 1 node.
--- 3. For `b3d` and `x` models: 1 unit = 1 node if static, otherwise 10 units = 1 node.
---
---Using static glTF or obj models is recommended.
---
---You can use the `visual_scale` multiplier to achieve the expected scale.
---@type string?
Settings.mesh = nil
---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
---@type NodeDefinition.node_box?
Settings.selection_box = nil
---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.
---@type NodeDefinition.node_box?
Settings.collision_box = nil
---Support maps made in and before January 2012
---@type boolean?
Settings.legacy_facedir_simple = nil
---Support maps made in and before January 2012
---@type boolean?
Settings.legacy_wallmounted = nil
---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?
Settings.waving = nil
---Definition of node sounds to be played at various events.
---All fields in this table are optional.
---@class NodeDefinition.sounds_table
---
---If walkable, played when object walks on it. If node is
---climbable or a liquid, played when object moves through it.
---
---Sound is played at the base of the object's collision-box.
---
---Gain is multiplied by `0.6`.
---
---For local player, it's played position-less, with normal gain.
---@field footstep SimpleSoundSpec?
---
---While digging node.
---
---If `"__group"`, then the sound will be
---`{name = "default_dig_<groupname>", gain = 0.5}` , where `<groupname>` 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"`
---@field dig SimpleSoundSpec|'__group?
---
---Node was dug.
---@field dug SimpleSoundSpec?
---
---Node was placed. Also played after falling
---@field place SimpleSoundSpec?
---
---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.
---@field place_failed SimpleSoundSpec?
---
---When node starts to fall or is detached.
---@field fall SimpleSoundSpec?
---Definition of node sounds to be played at various events.
---
---All fields in this table are optional.
---@type NodeDefinition.sounds_table?
Settings.sounds = nil
---@alias NodeDefinition.drop_table.dropitem_table {
--- rarity:integer,
--- items:string[],
--- tools:string[],
--- inherit_color:boolean,
--- tool_groups:table,
---}
---Using a table allows multiple items, drop chances and item filtering.
---@class NodeDefinition.drop_table
---@field max_items integer
---@field items NodeDefinition.drop_table.dropitem_table
---Name of dropped item when dug.
---
---Default dropped item is the node itself.
---
---Using a table allows multiple items, drop chances and item filtering.
---@type (NodeDefinition.drop_table|string)?
Settings.drop = nil
---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
Settings.mod_origin = nil

View File

@@ -1,38 +1,6 @@
---Version: 5.16
--- @meta --- @meta
---@alias TileAnimationDefinition
--- @class TileAnimationDefinition: table ---|{type:'vertical_frames', aspect_w:integer, aspect_h:integer, length:integer}
local TileAnimationDefinition = { ---|{type:'sheet_2d', frames_w:integer, frames_h:integer, frame_length:integer}
--- @type string one of {"vertical_frames"|"sheet_2d"}
type = "",
--- Width of a frame in pixels.
--- Only for `type == "vertical_frames"`
--- @type number
aspect_w = 16,
--- Height of a frame in pixels
--- Only for `type == "vertical_frames"`
--- @type number
aspect_h = 16,
--- Full loop length
--- Only for `type == "vertical_frames"`
--- @type number
length = 3.0,
--- Width in number of frames
--- Only for `type == "sheet_2d"`
--- @type number
frames_w = 5,
--- Height in number of frames
--- Only for `type == "sheet_2d"`
--- @type number
frames_h = 3,
--- Length of a single frame
--- Only for `type == "sheet_2d"`
--- @type number
frame_length = 0.5,
}

View File

@@ -1,39 +1,8 @@
---Version: 5.16
--- @meta --- @meta
---@alias TileDefinition
--- @class TileDefinition ---|string
local TileDefinition = { ---|{name:string, animation:TileAnimationDefinition}
--- @type string ---|{name:string, backface_culling:boolean, align_style:'node'|'world'|'user', scale:integer}
name = "image.png", ---|{name:string, color:ColorSpec}
--- @type TileAnimationDefinition?
animation = nil,
--- Backface culling enabled by default for most nodes.
--- @type boolean?
backface_culling = true,
--- One of `{"node"|"world"|"user"}`.
---
--- `align_style` determines whether the texture will be rotated with the node or kept aligned with its surroundings.
---
--- `"user"` means that client setting will be used, similar to `glasslike_framed_optional`.
---
--- **Note:** supported by solid nodes and nodeboxes only.
--- @type string?
align_style = "none",
--- `scale` is used to make texture span several (exactly scale) nodes, instead of just one, in each direction.
---
--- Works for world-aligned textures only.
---
--- **Note** that as the effect is applied on per-mapblock basis,
--- 16 should be equally divisible by scale or you may get wrong results.
--- @type number?
scale = 1,
--- - the texture's color will be multiplied with this color.
--- - the tile's color overrides the owning node's color in all cases.
--- @type string|ColorSpec|nil
color = ""
}

View File

@@ -2,17 +2,18 @@
--- e.g. `"a,b":split(",")` returns `{"a","b"}` --- e.g. `"a,b":split(",")` returns `{"a","b"}`
--- @param s string
--- @param separator? string cannot be empty, default: `","` --- @param separator? string cannot be empty, default: `","`
--- @param include_empty? boolean default: `false` --- @param include_empty? boolean default: `false`
--- @param max_splits? number if it's negative, splits aren't limited, default: `-1` --- @param max_splits? number if it's negative, splits aren't limited, default: `-1`
--- @param sep_is_pattern? boolean it specifies whether separator is a plain string or a pattern (regex), default: `false` --- @param sep_is_pattern? boolean it specifies whether separator is a plain string or a pattern (regex), default: `false`
--- @return string[] --- @return string[]
function string:split(separator, include_empty, max_splits, sep_is_pattern) end function string.split(s, separator, include_empty, max_splits, sep_is_pattern) end
--- Returns the string without whitespace pre- and suffixes --- Returns the string without whitespace pre- and suffixes
--- e.g. `"\n \t\tfoo bar\t ":trim()` returns `"foo bar"` --- e.g. `"\n \t\tfoo bar\t ":trim()` returns `"foo bar"`
--- @return string --- @return string
function string:trim() end function string.trim() end
--- Backported from Lua 5.4, see https://www.lua.org/manual/5.4/manual.html#6.4.2 --- Backported from Lua 5.4, see https://www.lua.org/manual/5.4/manual.html#6.4.2
--- ---

View File

@@ -1,22 +1,33 @@
---Version: 5.18
---@meta ---@meta
--- Colors ---
--- A ColorString is a string that represents a color. It can be one of the following: --- * `"#RGB"` defines a color in hexadecimal format, fully opaque.
--- * a named color, e.g. `"red"`, `"blue"`, `"green"`, etc. --- * `"#RGBA"` defines a color in hexadecimal format, with an alpha channel.
--- (see [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/#named-colors) for a full list of named colors) --- * `"#RRGGBB"` defines a color in hexadecimal format, fully opaque.
--- * a named color with alpha, e.g. `"red#08"`, `"blue#FF"`, `"green#F"`, etc. --- * `"#RRGGBBAA"` defines a color in hexadecimal format, with an alpha channel.
--- * an RGB or RGBA hex color code, e.g. `"#RRGGBB"` or `"#RRGGBBAA"`, where `RR`, `GG`, `BB`, and `AA` are two-digit hexadecimal numbers representing the red, green, blue, and alpha (opacity) components of the color. ---
--- * e.g. `"#FF0000"` for red, `"#00FF00"` for green, `"#0000FF"` for blue, etc. ---Named colors are also supported and are equivalent to
--- * a shorthand hex color code, e.g. `"#RGB"` or `"#RGBA"`, where `R`, `G`, `B`, and `A` are single-digit hexadecimal numbers representing the red, green, blue, and alpha (opacity) components of the color. ---[CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/#named-color).
---To specify the value of the alpha channel,
---append `#A` or `#AA` to the end of the color name (e.g. `"darkgreen#08"`).
---@alias ColorString string ---@alias ColorString string
---@class ColorTable
---@field r integer
---@field g integer
---@field b integer
---@field a integer
---A ColorSpec specifies a 32-bit color. It can be written in any of the following forms: ---A ColorSpec specifies a 32-bit color. It can be written in any of the following forms:
--- * table form: Each element ranging from 0..255 (a, if absent, defaults to 255): --- * table form: Each element ranging from 0..255 (a, if absent, defaults to 255):
---
--- `colorspec = {a=255, r=0, g=255, b=0}` --- `colorspec = {a=255, r=0, g=255, b=0}`
--- * numerical form: The raw integer value of an ARGB8 quad: --- * numerical form: The raw integer value of an ARGB8 quad:
---
--- `colorspec = 0xFF00FF00` --- `colorspec = 0xFF00FF00`
--- * string form: A ColorString (defined above): --- * string form: A ColorString (defined above):
---
--- `colorspec = "green"` --- `colorspec = "green"`
--- @alias ColorSpec {r:number, g:number, b:number, a:number}|ColorString|number ---@alias ColorSpec ColorTable|ColorString|integer