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
[![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.
@@ -13,12 +13,24 @@ This ide-helper is specifically designed to support the [SMC game](https://git.a
## Supported IDEs & Plugins
- IntelliJ IDEA (or compatible) with [EmmyLua2 Plugin](https://plugins.jetbrains.com/plugin/25076-emmylua2)
- VS Code with [EmmyLua Extension](https://marketplace.visualstudio.com/items?itemName=tangzx.emmylua) (recommended for VS Code)
- VS Code with [Lua Language Server](https://marketplace.visualstudio.com/items?itemName=sumneko.lua)
- Any editor with LSP support.
Install Lua LS: `cargo install emmylua_ls` (or see [instalation guide](https://github.com/EmmyLuaLs/emmylua-analyzer-rust?tab=readme-ov-file#-installation))
We use [Lua Server Language](https://github.com/luals/lua-language-server). You can install it for the following IDEs:
- **Visual Studio Code** with [plugin](https://marketplace.visualstudio.com/items?itemName=sumneko.lua)
- **Neovim** (see [instalation guide](https://luals.github.io/#neovim-install))
- **JetBrains** with [plugin](https://plugins.jetbrains.com/plugin/22315-sumnekolua)
- 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
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,114 +1,166 @@
--- @meta
---Version: 5.18
---@meta
--- @class ItemStack
--- @overload fun(x:ItemStack|ItemStackString|ItemStackTable|nil):ItemStack
---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
---@overload fun(x:ItemStack|ItemStackString|ItemStackTable|nil):ItemStack
ItemStack = {}
--- @class ItemStackTable: table
--- @field name string
--- @field count number
--- @field wear number
--- @field metadata string
---@class ItemStackTable: table
---@field name string
---@field count number
---@field wear number
---@field metadata string
--- @alias ItemStackString string
---@alias ItemStackString string
--- Put some item or stack onto this stack, returns leftover ItemStack
--- @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
function ItemStack:set_count(count) end
--- @return ItemDefinition returns the item definition table
function ItemStack:get_definition() end
--- 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
--- Returns true/false (success), clears item on failure
--- @param item_name string
--- @return boolean
function ItemStack:set_name(item_name) end
--- Returns the maximum size of the stack (depends on the item)
--- @return number
function ItemStack:get_stack_max() end
--- Returns the digging properties of the item, or those of the hand if none are defined for this item type
--- @return table
function ItemStack:get_tool_capabilities() end
--- Returns tool wear (0-65535), 0 for non-tools
--- @return number
function ItemStack:get_wear() end
--- Returns true/false (success), clears item on failure
--- @param wear number wear <= 65535, otherwise clears
--- @return boolean
function ItemStack:set_wear(wear) end
--- Return true if stack is empty
--- @return boolean
---Returns true if stack is empty.
---@return boolean
function ItemStack:is_empty() end
--- Returns true if the item name refers to a defined item type
--- @return boolean
function ItemStack:is_known() end
---Returns item name (e.g. `"default:stone"`).
---@return string
function ItemStack:get_name() end
--- Returns true if item or stack can be fully added to this one
--- @param item ItemStack|ItemStackString|ItemStackTable
--- @return boolean
function ItemStack:item_fits(item) end
---Sets the item name.
---
---Returns `false` if the stack was cleared, `true` otherwise.
---@param item_name string
---@return boolean
function ItemStack:set_name(item_name) end
--- Copy (don't remove) up to n items from this stack; returns copied ItemStack; if n is omitted, n=1 is used
--- @param count number
--- @return ItemStack
function ItemStack:peek_item(count) end
---Returns amount of items on the stack.
---@return integer
function ItemStack:get_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`
---Sets amount of items in the stack.
---
---Returns `false` if the stack was cleared, `true` otherwise.
---@param count integer
---@return boolean
function ItemStack:set_count(count) end
---Returns tool wear (integer in range [0, 65535]), `0` for non-tools.
---@return integer
function ItemStack:get_wear() end
---Set tool wear.
---
---Returns `false` if the stack was cleared, `true` otherwise
---@param wear integer
---@return boolean
function ItemStack:set_wear(wear) end
---@return ItemStackMetaRef
function ItemStack:get_meta() end
---@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
--- 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
function ItemStack:take_item(count) end
--- Returns the stack in itemstring form
--- @return string
---Returns the stack in `itemstring` form.
---@return string
function ItemStack:to_string() end
--- Returns the stack in Lua table form or `nil` if empty.
--- @return table|nil
---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
function ItemStack:is_known() end
---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
---@return boolean
function ItemStack:item_fits(item) end
---Take (and remove) up to `n` items from this stack.
---@param count number? default: `1`
---@return ItemStack
function ItemStack:take_item(count) end
---Copy (don't remove) up to `n` items from this stack.
---@param count number? default: `1`
---@return ItemStack
function ItemStack:peek_item(count) end
---Returns `true` if this stack is identical to other.
---
---**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,70 +1,145 @@
--- @meta
---Version: 5.16
---@meta
--- Base class used by [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`],
--- and [`PlayerMetaRef`].
---Base class used by [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`],
---and [`PlayerMetaRef`].
---
--- Note: If a metadata value is in the format `${k}`, an attempt to get the value
--- will return the value associated with key `k`. There is a low recursion limit.
--- This behavior is **deprecated** and will be removed in a future version. Usage
--- of the `${k}` syntax in formspecs is not deprecated.
---Note: If a metadata value is in the format `${k}`, an attempt to get the value
---will return the value associated with key `k`. There is a low recursion limit.
---This behavior is **deprecated** and will be removed in a future version. Usage
---of the `${k}` syntax in formspecs is not deprecated.
---
--- @class MetaDataRef
---@class MetaDataRef
MetaDataRef = {}
---@param key string
---@return boolean|nil
---Returns `true` if `key` present, otherwise `false`.
---
---Returns `nil` when the MetaData is inexistent.
---@param key string
---@return boolean?
function MetaDataRef:contains(key) end
---@param key string
---@return string|nil
---Returns the value stored at `key` as a string if present.
---
---Returns nil otherwise.
---@param key string
---@return string?
function MetaDataRef:get(key) end
---@param key string
---@param value string value "" will delete the key
---@return string
---Set the string `value` at `key`.
---
---Value of `""` will delete the key.
---@param key string
---@param value string
function MetaDataRef:set_string(key, value) end
---@param key string
---@return string
---Returns a string value at `key` or `""` if not present.
---@param key string
---@return string
function MetaDataRef:get_string(key) end
---@param key string
---@param value number
---@return number
---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 value integer
function MetaDataRef:set_int(key, value) end
---@param key string
---@return number Returns `0` if `key` not present.
---Returns the value stored at `key` as an integer.
---
---Returns `0` if key not present.
---@param key string
---@return integer
function MetaDataRef:get_int(key) end
---@param key string
---@param value number
---@return number
---Store a number (a 64-bit floating-point number) exactly.
---
---The value will be converted into a string when stored.
---@param key string
---@param value number
function MetaDataRef:set_float(key, value) end
---@param key string
---@return number
---Returns a 64-bit floating-point number stored at `key`.
---
---Returns `0` if key not present.
---@param key string
---@return number
function MetaDataRef:get_float(key) end
--- Returns a list of all keys in the metadata.
--- @return table
---Returns a list of all keys in the metadata.
---@return table
function MetaDataRef:get_keys() end
--- returns `nil` or a table with keys:
--- * `fields`: key-value storage
--- * `inventory`: `{list1 = {}, ...}}` (NodeMetaRef only)
--- @return table|nil
---Metadata tables represent MetaDataRef in a Lua table form (see `from_table`/`to_table`).
---
---Example:
---```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
--- * Any non-table value will clear the metadata
--- * See [Node Metadata] for an example
--- * returns `true` on success
--- @param value table|nil
--- @return boolean
function MetaDataRef:from_table(value) end
---Imports metadata from a [metadata table](lua://MetaDataRef.Table).
---
---If `data` is a metadata table,
---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
function MetaDataRef:from_table(data) end
--- * returns `true` if this metadata has the same key-value pairs as `other`
--- @param other any
--- @return boolean
---Returns `true` if this metadata has the same key-value pairs as `other`.
---@param other any
---@return boolean
function MetaDataRef:equals(other) end

View File

@@ -1,15 +1,47 @@
--- @meta
---Version: 5.18
---@meta
--- ItemStack metadata: reference extra data and functionality stored in a stack.
--- Can be obtained via `item:get_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.
---
--- @class ItemStackMetaRef: MetaDataRef
---Can be obtained via `item:get_meta()`.
---@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 = {}
--- * Overrides the item's tool capabilities
--- * A nil value will clear the override data and restore the original behavior.
---Overrides the item's tool capabilities.
---
---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
--- * 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.
---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.
---@param wear_bar_params ItemDefinition.wearbar_color_table
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
--- Add a HUD element described by HUD def, returns ID number on success.
--- @param hud_definition HudDefinition
--- @param hud_definition HUDDefinition
--- @return integer
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.
--- @param id integer
--- @return HudDefinition
--- @return HUDDefinition
function Player:hud_get(id) end
--- @class Player.hud_flags
@@ -308,7 +308,7 @@ function Player:hud_set_hotbar_itemcount(count) end
function Player:hud_get_hotbar_itemcount() end
--- Sets background image for hotbar.
--- @param string
--- @param texturename string
function Player:hud_set_hotbar_image(texturename) end
--- Returns texturename.
@@ -316,7 +316,7 @@ function Player:hud_set_hotbar_image(texturename) end
function Player:hud_get_hotbar_image() end
--- Sets image for selected item of hotbar.
--- @param string
--- @param texturename string
function Player:hud_set_hotbar_selected_image(texturename) end
--- 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(propagate_shadow:boolean)
--- @overload fun()
--- @param p1 MapPosition
--- @param p2 MapPosition
--- @param propagate_shadow boolean
--- @param p1 MapPosition?
--- @param p2 MapPosition?
--- @param propagate_shadow boolean?
function VoxelManip:calc_lighting(p1, p2, propagate_shadow) end
--- Update liquid flow

View File

@@ -19,7 +19,7 @@
--- @field y integer
--- @class vector: Position
--- @operator eq : boolean
-- - @operator eq : boolean
--- @operator unm : vector
--- @operator add(Position): vector
--- @operator sub(Position): vector
@@ -32,7 +32,7 @@ vector = {}
--- Same as `vector`, but all fields are integers.
--- @class IntegerVector: vector, IntegerPosition
--- @operator eq : boolean
-- - @operator eq : boolean
--- @operator unm : IntegerVector
--- @operator add(Position): IntegerVector
--- @operator sub(Position): IntegerVector
@@ -122,7 +122,7 @@ function vector:ceil() end
--- Returns a vector, each dimension rounded to the nearest integer.
--- At a multiple of 0.5, rounds away from zero.
--- @return vector
--- @return IntegerVector
function vector:round() end
--- 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.
---
--- [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
--- * Called by `builtin` and mods when a player violates protection at a
--- 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" }'`
---
--- [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
function core.serialize(table) end
--- Returns a table

View File

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

View File

@@ -1,122 +1,93 @@
--- @meta
---Version: 5.18
---@meta
--- Environment ---
--- * 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.
--- @param name string technical node name ("<mod>:<node>").
--- @param node_definition NodeDefinition table with node definition properties.
---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.
---@param name string technical node name ("<mod>:<node>").
---@param node_definition NodeDefinition table with node definition properties.
function core.register_node(name, node_definition) end
--- * 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.
--- @param name string technical item name ("<mod>:<item>").
--- @param item_definition ItemDefinition table with item definition properties.
---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.
---@param name string technical item name ("<mod>:<item>").
---@param item_definition ItemDefinition table with item definition properties.
function core.register_craftitem(name, item_definition) end
--- * 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
--- @param item_definition ItemDefinition
---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 technical item name ("<mod>:<item>").
---@param item_definition ItemDefinition table with item definition properties.
function core.register_tool(name, item_definition) end
--- 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.
---Overrides fields of an item registered with register_node/tool/craftitem.
---
--- @param name string
--- @param redefinition ItemDefinition|NodeDefinition
function core.override_item(name, redefinition) end
---**Note**: Item must already be defined.
---@param name string
---@param redefinition ItemDefinition|NodeDefinition
---@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
--- `name` from `core.registered_items` and from the associated item table
--- according to its nature (e.g. `core.registered_nodes`)
---
--- @param name string
---Unregisters the item from the engine, and deletes the entry with key name
---from `core.registered_items` and from the associated item table according
---to its nature (e.g. `core.registered_nodes`)
---@param name string
function core.unregister_item(name) end
--- @param name string
--- @param entity_definition EntityDefinition
---@param name string
---@param entity_definition EntityDefinition
function core.register_entity(name, entity_definition) end
--- @param abm_definition ABMDefinition
---@param abm_definition ABMDefinition
function core.register_abm(abm_definition) end
--- @param lbm_definition LBMDefinition
---@param lbm_definition LBMDefinition
function core.register_lbm(lbm_definition) end
--- * Also use this to set the 'mapgen aliases' needed in a game for the core
--- mapgens. See [Mapgen aliases](https://api.luanti.org/aliases/#mapgen-aliases) section.
---Also use this to set the 'mapgen aliases' needed in a game for the core mapgens.
---
--- @param alias string @itemstring (`"<mod>:<node>"`). For renaming: its old name.
--- @param original_name string @itemstring (`"<mod>:<node>"`). For renaming: its new name.
---See [Mapgen aliases](https://api.luanti.org/core-namespace-reference/#mapgen-aliases) section above.
---
---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
--- * Forces an alias to be created, even if an alias with the same name
--- already exists.
--- @param alias string @itemstring (`"<mod>:<node>"`). For renaming: its old name.
--- @param original_name string @itemstring (`"<mod>:<node>"`). For renaming: its new name.
---Same as core.register_alias, but an already registered item named alias is unregistered first.
---@param alias string
---@param original_name string
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
--- @return integer
---@param ore_definition OreDefinition
---@return integer
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
--- @return integer
---@param biome_definition BiomeDefinition
---@return integer
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
--- * 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
--- @return integer
---@param decoration_definition DecorationDefinition
---@return integer
function core.register_decoration(decoration_definition) end
--- * Returns an integer object handle uniquely identifying the registered
--- 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
function core.register_schematic(schematic, replacements) end
---@param schematic_definition SchematicSpecifier|string
---@return integer
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
--- * Clears all decorations currently registered.
function core.clear_registered_decorations() end
--- * Clears all ores currently registered.
function core.clear_registered_ores() end
--- * Clears all schematics currently registered.
function core.clear_registered_schematics() end

View File

@@ -1,72 +1,29 @@
--- @meta
---Version: 5.18
---@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
--- * 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
--- @return boolean
---@param recipe table
---@return boolean
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 chatcommand_definition ChatCommandDefinition
---@param cmd string
---@param chatcommand_definition ChatCommandDefinition
function core.register_chatcommand(cmd, chatcommand_definition) end
--- Overrides fields of a chatcommand registered with `register_chatcommand`.
---
--- @param name string
--- @param redefinition ChatCommandDefinition
---@param name string
---@param redefinition ChatCommandDefinition
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
--- 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 definition string|PrivilegeDefinition
---@param name string
---@param definition string|PrivilegeDefinition
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

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 @@
--- @meta
---Version: 5.18
---@meta
--- Utilities ---
--- Returns the currently loading mod's name, when loading a mod.
--- - Returns nil if not loading a mod.
--- - 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.
---Returns the currently loading mod's name, when loading a mod.
---@return string
function core.get_current_modname() end
--- Returns the directory path for a mod, e.g. "/home/user/.minetest/usermods/modname".
--- - Returns nil if the mod is not enabled or does not exist (not installed).
--- - Works regardless of whether the mod has been loaded yet.
--- - Useful for loading additional `.lua` modules or static data from a mod, or checking if a mod is enabled.
--- @param mod_name string
--- @return string
function core.get_modpath(mod_name) end
---Returns the directory path for a mod, e.g. `"/home/user/.minetest/"`
---@param modname string
---@return string?
function core.get_modpath(modname) end
--- Returns a list of enabled mods, sorted alphabetically.
--- - Does not include disabled mods, even if they are installed.
--- @return table
function core.get_modnames() end
---Returns a list of the mods' names that are loaded or are yet to be loaded during startup.
---@param load_order boolean?
function core.get_modnames(load_order) end
--- @class GameInfo
--- @field id string
--- @field title string
--- @field author string
--- @field path string The root directory of the game.
---@class Core.GameInfo
---@field id string
---@field title string
---@field author string
---@field path string The root directory of the 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.
---Returns a table containing information about the current game.
---
--- @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
--- Returns e.g. "/home/user/.minetest/world"
--- - Useful for storing custom data
--- @return string
---Returns e.g. `"/home/user/.minetest/world"`.
---@return string
function core.get_worldpath() end
--- 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
---Returns e.g. `"/home/user/.minetest/mod_data/mymod"`
---@return string
function core.get_mod_data_path() end
--- @return boolean
---Returns `true` if the server is running in singleplayer mode, `false` otherwise.
---@return boolean
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
--- @type table
core.features = {
--- @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,
}
---Table containing server-side API feature flags.
---@type Core.Features
core.features = nil
--- Returns `boolean, missing_features`
--- * `arg`: string or table in format `{foo=true, bar=true}`
--- * `missing_features`: `{foo=true, bar=true}`
--- @param arg string|table
--- @return boolean,table<string,boolean>
---Checks for server-side feature availability.
---@param arg string|table
---@return boolean
---@return table<string,boolean> missing_features
function core.has_feature(arg) end
--- Table containing information
--- about a player. Example return value:
--- ```lua
--- {
--- address = "127.0.0.1", -- IP address of client
--- ip_version = 4, -- IPv4 / IPv6
--- connection_uptime = 200, -- seconds since client connected
--- protocol_version = 32, -- protocol version used by client
--- formspec_version = 2, -- supported formspec version
--- lang_code = "fr" -- Language code used for translation
--- -- the following keys can be missing if no stats have been collected yet
--- min_rtt = 0.01, -- minimum round trip time
--- max_rtt = 0.2, -- maximum round trip time
--- avg_rtt = 0.02, -- average round trip time
--- min_jitter = 0.01, -- minimum packet time jitter
--- max_jitter = 0.5, -- maximum packet time jitter
--- avg_jitter = 0.03, -- average packet time jitter
--- -- the following information is available in a debug build only!!!
--- -- DO NOT USE IN MODS
--- --ser_vers = 26, -- serialization version used by client
--- --major = 0, -- major version number
--- --minor = 4, -- minor version number
--- --patch = 10, -- patch version number
--- --vers_string = "0.4.9-git", -- full version string
--- --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)
---@class Core.PlayerInformation
---@field address string
---@field ip_version integer
---@field connection_uptime integer
---@field protocol_version integer
---@field formspec_version integer
---@field lang_code string
---@field min_rtt number?
---@field max_rtt number?
---@field avg_rtt number?
---@field min_jitter number?
---@field max_jitter number?
---@field avg_jitter number?
---@field version_string string
--- The following information is available in a debug build only!!!
-- -@field serialization_version integer?
-- -@field major integer?
-- -@field minor integer?
-- -@field patch integer?
-- -@field state string?
---Table containing information about a player.
---@param player_name string
---@return Core.PlayerInformation
function core.get_player_information(player_name) end
---Table mapping Luanti versions to corresponding protocol versions for modder convenience.
---
---For example, to check whether a client has at least the feature set of Luanti 5.8.0
---or newer, you could do:
---```lua
--- core.get_player_information(player_name).protocol_version >= core.protocol_versions["5.8.0"]
---```
---@type table<string, integer>
core.protocol_versions = nil
--- 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
--- connection as the player resizes the window and moves it between monitors
---
--- 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
--- {
--- -- 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,
--- }
--- ```
---@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
--- Returns success.
--- * Creates a directory specified by `path`, creating parent directories
--- if they don't exist.
---Returns `true` if the given path exists else `false`.
---@param path string
---@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
--- 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.
--- @param path string
--- @param recursive boolean
--- @return boolean
---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.
---@param path string
---@param recursive boolean
---@return boolean success
function core.rmdir(path, recursive) end
--- Copies a directory specified by path to destination
--- Any files in destination will be overwritten if they already exist.
--- Returns true on success, false on failure.
--- @param source string
--- @param destination string
--- @return boolean
---Copies a directory specified by source to destination.
---
---Any files in `destination` will be overwritten if they already exist.
---@param source string
---@param destination string
---@return boolean success
function core.cpdir(source, destination) end
--- Moves a directory specified by path to destination.
--- If the destination is a non-empty directory, then the move will fail.
--- Returns true on success, false on failure.
--- @param source string
--- @param destination string
--- @return boolean
---Moves a directory specified by source to destination.
---
---If the `destination` is a non-empty directory, then the move will fail.
--- @param source string
--- @param destination string
--- @return boolean success
function core.mvdir(source, destination) end
--- Returns list of entry names
--- * `is_dir` [Optional] is one of:
--- * nil: return all entries,
--- * true: return only subdirectory names, or
--- * 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)
---Returns list of entry names
---@param path string
---@param is_dir boolean? is one of:
--- * `nil`: return all entries
--- * `true`: return only subdirectory names
--- * `false`: return only file names
---@return string[]
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. Use this instead of below code when writing e.g. database files:
--- `local f = io.open(path, "wb"); f:write(content); f:close()`
---Replaces contents of file at path with new contents in a safe (atomic) way.
---
--- [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
--- Returns a table containing components of the
--- engine version. Components:
--- * `project`: Name of the project, eg, "Minetest"
--- * `string`: Simple version, eg, "1.2.3-dev"
--- * `hash`: Full git version (only set if available),
--- eg, "1.2.3-dev-01234567-dirty".
--- Use this for informational purposes only. The information in the returned
--- table does not represent the capabilities of the engine, nor is it
--- reliable or verifiable. Compatible forks will have a different name and
--- version entirely. To check for the presence of engine features, test
--- 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)
---@class Core.Version
---@field project string
---@field string string
---@field proto_min integer
---@field proto_max integer
---@field hash string
---@field is_dev string
---Returns a table containing components of the engine version.
---@return Core.Version
function core.get_version() end
--- Returns the sha1 hash of data
--- * `data`: string of data to hash
--- * `raw`: [Optional] return raw bytes instead of hex digits, default: false
---
--- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4451-L4453)
---Returns the sha1 hash of data.
---@param data string string of data to hash
---@param raw boolean? return raw bytes instead of hex digits, default: `false`
---@return string
function core.sha1(data, raw) end
--- Returns the sha256 hash of `data`
--- @param data string string of data to hash
--- @param raw boolean optional. return raw bytes instead of hex digits, default: false
---Returns the sha256 hash of data
---@param data string string of data to hash
---@param raw boolean? return raw bytes instead of hex digits, default: `false`
---@return string
function core.sha256(data, raw) end
--- Converts a ColorSpec to a ColorString. If the ColorSpec is invalid, returns `nil`.
--- @param colorspec ColorSpec The ColorSpec to convert.
--- @return ColorString?
---Converts a `ColorSpec` to a `ColorString`.
---
---If the ColorSpec is invalid, returns `nil`.
---@param colorspec ColorSpec
---@return ColorString?
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.
--- @param colorspec ColorSpec The ColorSpec to convert.
--- @return string?
---Converts a `ColorSpec` to a raw string of four bytes in an RGBA layout,
---returned as a string.
---@param colorspec ColorSpec
---@return string?
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.
--- @param colorspec ColorSpec The ColorSpec to convert.
--- @return {r:number, g:number, b:number, a:number}?
---Converts a `ColorSpec` into RGBA table form.
---
---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
---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
--- @class HudDefinition
local HudDefinition = {
--- @class HUDDefinition
local HUDDefinition = {
--- Name of the HUD element.
---
--- 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
--- @class ItemDefinition: table
local ItemDefinition = {
--- Can contain new lines. "\n" has to be used as new line character.
--- See also: `get_description` in [`ItemStack`]
--- @type string?
description = "",
--- Must not contain new lines.
--- Defaults to nil.
--- Use an [`ItemStack`] to get the short description, e.g.:
--- ItemStack(itemname):get_short_description()
--- @type string?
short_description = "",
--- key = name, value = rating; rating = <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 >",
}
---The original `ItemDefinition`, described in the Luanti API Reference,
---was split into `ItemDefinition.Settings` and `ItemDefinition.Callbacks`.
---
---Please look at the fields and methods in the corresponding classes.
---
---This `ItemDefinition` class is a combination of `ItemDefinition.Settings`
---and `ItemDefinition.Callbacks` and to some extent corresponds to the original.
---@class ItemDefinition : ItemDefinition.Settings, ItemDefinition.Callbacks
---@field [string] any
local ItemDefinition = {}

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
--- @class NodeDefinition: ItemDefinition
local NodeDefinition = {
--- For last version see ["Node drawtypes"](https://api.luanti.org/nodes/#node-drawtypes)
---
--- There are a bunch of different looking node types.
--- * `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).
---
--- @type string?
drawtype = "normal",
--- Supported for drawtypes "plantlike", "signlike", "torchlike",
--- "firelike", "mesh", "nodebox", "allfaces".
--- For plantlike and firelike, the image will start at the bottom of the
--- node. For torchlike, the image will start at the surface to which the
--- node "attaches". For the other drawtypes the image will be centered
--- on the node.
--- @type number?
visual_scale = 1.0,
--- {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",
}
---@meta
---The original `NodeDefinition`, described in the Luanti API Reference,
---was split into `NodeDefinition.Settings` and `NodeDefinition.Callbacks`.
---
---Please look at the fields and methods in the corresponding classes.
---
---This `NodeDefinition` class is a combination of `NodeDefinition.Settings`
---and `NodeDefinition.Callbacks` and to some extent corresponds to the original.
---@class NodeDefinition: NodeDefinition.Settings, NodeDefinition.Callbacks
local NodeDefinition = {}

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
--- @class TileAnimationDefinition: table
local TileAnimationDefinition = {
--- @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,
}
---@alias TileAnimationDefinition
---|{type:'vertical_frames', aspect_w:integer, aspect_h:integer, length:integer}
---|{type:'sheet_2d', frames_w:integer, frames_h:integer, frame_length:integer}

View File

@@ -1,39 +1,8 @@
---Version: 5.16
--- @meta
--- @class TileDefinition
local TileDefinition = {
--- @type string
name = "image.png",
--- @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 = ""
}
---@alias TileDefinition
---|string
---|{name:string, animation:TileAnimationDefinition}
---|{name:string, backface_culling:boolean, align_style:'node'|'world'|'user', scale:integer}
---|{name:string, color:ColorSpec}

View File

@@ -2,17 +2,18 @@
--- e.g. `"a,b":split(",")` returns `{"a","b"}`
--- @param s string
--- @param separator? string cannot be empty, default: `","`
--- @param include_empty? boolean default: `false`
--- @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`
--- @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
--- e.g. `"\n \t\tfoo bar\t ":trim()` returns `"foo bar"`
--- @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
---

View File

@@ -1,22 +1,33 @@
--- @meta
---Version: 5.18
---@meta
--- Colors ---
--- A ColorString is a string that represents a color. It can be one of the following:
--- * a named color, e.g. `"red"`, `"blue"`, `"green"`, etc.
--- (see [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/#named-colors) for a full list of named colors)
--- * a named color with alpha, e.g. `"red#08"`, `"blue#FF"`, `"green#F"`, etc.
--- * 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.
--- * 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.
--- @alias ColorString string
--- * `"#RGB"` defines a color in hexadecimal format, fully opaque.
--- * `"#RGBA"` defines a color in hexadecimal format, with an alpha channel.
--- * `"#RRGGBB"` defines a color in hexadecimal format, fully opaque.
--- * `"#RRGGBBAA"` defines a color in hexadecimal format, with an alpha channel.
---
---Named colors are also supported and are equivalent to
---[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
---@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:
--- * table form: Each element ranging from 0..255 (a, if absent, defaults to 255):
--- `colorspec = {a=255, r=0, g=255, b=0}`
--- * numerical form: The raw integer value of an ARGB8 quad:
--- `colorspec = 0xFF00FF00`
--- * string form: A ColorString (defined above):
--- `colorspec = "green"`
--- @alias ColorSpec {r:number, g:number, b:number, a:number}|ColorString|number
---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):
---
--- `colorspec = {a=255, r=0, g=255, b=0}`
--- * numerical form: The raw integer value of an ARGB8 quad:
---
--- `colorspec = 0xFF00FF00`
--- * string form: A ColorString (defined above):
---
--- `colorspec = "green"`
---@alias ColorSpec ColorTable|ColorString|integer