From 0e1cc45130232658f8b4eaf32193413fd0ed50b4 Mon Sep 17 00:00:00 2001 From: Alexander Chibrikin Date: Mon, 5 Jan 2026 21:33:16 +0300 Subject: [PATCH] Fix annotations for voxel manipulations. --- classes/VoxelArea.lua | 70 ++++++++++++++---------- classes/VoxelManip.lua | 120 +++++++++++++++++++++-------------------- core_namespace.lua | 24 ++++----- 3 files changed, 115 insertions(+), 99 deletions(-) diff --git a/classes/VoxelArea.lua b/classes/VoxelArea.lua index 7bf93c3..90a32de 100644 --- a/classes/VoxelArea.lua +++ b/classes/VoxelArea.lua @@ -5,68 +5,84 @@ --- A helper class for voxel areas. --- It can be created via `VoxelArea(pmin, pmax)` or --- `VoxelArea:new({MinEdge = pmin, MaxEdge = pmax})`. ---- The coordinates are *inclusive*, like most other things in Minetest. +--- The coordinates are *inclusive*, like most other things in Luanti. +--- +--- @field MinEdge Position +--- @field MaxEdge Position +--- @field ystride integer +--- @field zstride integer VoxelArea = {} ---- The coordinates are *inclusive*, like most other things in Minetest. +--- The coordinates are *inclusive*, like most other things in Luanti. --- --- Also you can create an instance via `VoxelArea(pmin, pmax)` --- ---- @param cuboid { MinEdge: any, MaxEdge: any } +--- @param cuboid { MinEdge: Position, MaxEdge: Position } --- @return VoxelArea function VoxelArea:new(cuboid) end --- returns a 3D vector containing the size of the area formed by `MinEdge` and `MaxEdge`. --- @return Position function VoxelArea:getExtent() end + --- returns the volume of the area formed by `MinEdge` and `MaxEdge`. ---- @return number +--- @return integer function VoxelArea:getVolume() end + --- returns the index of an absolute position in a flat array starting at `1`. ---- * `x`, `y` and `z` must be integers to avoid an incorrect index result. ---- * The position (x, y, z) is not checked for being inside the area volume, ---- being outside can cause an incorrect index result. ---- * Useful for things like `VoxelManip`, raw Schematic specifiers, ---- `PerlinNoiseMap:get2d`/`3dMap`, and so on. ---- @param x number ---- @param y number ---- @param z number ---- @return number +--- * `x`, `y` and `z` must be integers to avoid an incorrect index result. +--- * The position (x, y, z) is not checked for being inside the area volume, +--- being outside can cause an incorrect index result. +--- * Useful for things like `VoxelManip`, raw Schematic specifiers, +--- `PerlinNoiseMap:get2d`/`3dMap`, and so on. +--- @param x integer +--- @param y integer +--- @param z integer +--- @return integer function VoxelArea:index(x, y, z) end + --- same functionality as `index(x, y, z)` but takes a vector. --- * As with `index(x, y, z)`, the components of `p` must be integers, and `p` --- is not checked for being inside the area volume. --- @param position Position ---- @return number +--- @return integer function VoxelArea:indexp(position) end + --- returns the absolute position vector corresponding to index `i`. ---- @param i number +--- @param i integer --- @return Position function VoxelArea:position(i) end + --- check if (`x`,`y`,`z`) is inside area formed by `MinEdge` and `MaxEdge`. ---- @param x number ---- @param y number ---- @param z number +--- @param x integer +--- @param y integer +--- @param z integer --- @return boolean function VoxelArea:contains(x, y, z) end + --- check if Position(`x`,`y`,`z`) is inside area formed by `MinEdge` and `MaxEdge`. --- @param position Position --- @return boolean function VoxelArea:containsp(position) end ---- same as above, except takes an index `i` + +--- same as `:containsp()`, except takes an index `i` +--- @param i integer +--- @return boolean function VoxelArea:containsi(i) end + --- returns an iterator that returns indices. ---- * from (`min_x`,`min_y`,`min_z`) to (`max_x`,`max_y`,`max_z`) in the order of `[z [y [x]]]`. ---- @param min_x number ---- @param min_y number ---- @param min_z number ---- @param max_x number ---- @param max_y number ---- @param max_z number +--- * from (`min_x`,`min_y`,`min_z`) to (`max_x`,`max_y`,`max_z`) in the order of `[z [y [x]]]`. +--- @param min_x integer +--- @param min_y integer +--- @param min_z integer +--- @param max_x integer +--- @param max_y integer +--- @param max_z integer --- @return fun(tbl: table): number, number function VoxelArea:iter(min_x, min_y, min_z, max_x, max_y, max_z) end + --- returns an iterator that returns indices. ---- * from (`min_x`,`min_y`,`min_z`) to (`max_x`,`max_y`,`max_z`) in the order of `[z [y [x]]]`. +--- * from (`min_x`,`min_y`,`min_z`) to (`max_x`,`max_y`,`max_z`) in the order of `[z [y [x]]]`. --- @param min_pos Position --- @param max_pos Position --- @return fun(tbl: table): number, number diff --git a/classes/VoxelManip.lua b/classes/VoxelManip.lua index 102ede6..4618921 100644 --- a/classes/VoxelManip.lua +++ b/classes/VoxelManip.lua @@ -2,95 +2,94 @@ --- @class VoxelManip ---- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.7.0/doc/lua_api.txt#L4244) VoxelManip = {} ---- Loads a chunk of map into the VoxelManip object ---- containing the region formed by `p1` and `p2`. ---- * returns actual emerged `pmin`, actual emerged `pmax` +--- Loads a chunk of map into the VoxelManip object containing the region formed by `p1` and `p2`. +--- * returns actual emerged `pmin`, actual emerged `pmax` --- @param position1 Position min position for load part of map --- @param position2 Position max position for load part of map --- @return Position, Position function VoxelManip:read_from_map(position1, position2) end ---- Writes the data loaded from the `VoxelManip` back to ---- the map. ---- * **important**: data must be set using `VoxelManip:set_data()` before ---- calling this. ---- * if `light` is true, then lighting is automatically recalculated. ---- The default value is true. ---- If `light` is false, no light calculations happen, and you should correct ---- all modified blocks with `minetest.fix_light()` as soon as possible. ---- Keep in mind that modifying the map where light is incorrect can cause ---- more lighting bugs. ---- @param light boolean? Default: true + +--- Writes the data loaded from the `VoxelManip` back to the map. +--- * **important**: data must be set using `VoxelManip:set_data()` before calling this. +--- * if `light` is `true`, then lighting is automatically recalculated. +--- The default value is `true`. +--- If `light` is `false`, no light calculations happen, and you should correct +--- all modified blocks with `minetest.fix_light()` as soon as possible. +--- Keep in mind that modifying the map where light is incorrect can cause more lighting bugs. +--- @param light boolean? Default: `true` function VoxelManip:write_to_map(light) end ---- Returns a `MapNode` table of the node currently loaded in ---- the `VoxelManip` at that position + +--- Returns a `MapNode` table of the node currently loaded in the `VoxelManip` at that position. +--- @param pos Position +--- @return MapNode function VoxelManip:get_node_at(pos) end ---- Sets a specific `MapNode` in the `VoxelManip` at ---- that position. + +--- Sets a specific `MapNode` in the `VoxelManip` at that position. +--- @param pos Position +--- @param node MapNode function VoxelManip:set_node_at(pos, node) end + --- Retrieves the node content data loaded into the `VoxelManip` object. ---- * returns raw node data in the form of an array of node content IDs ---- * if the param `buffer` is present, this table will be used to store the ---- result instead. ---- @param buffer number[]|nil ---- @return number[] +--- * returns raw node data in the form of an array of node content IDs +--- * if the param `buffer` is present, this table will be used to store the result instead. +--- @param buffer? integer[] +--- @return integer[] function VoxelManip:get_data(buffer) end + --- Sets the data contents of the `VoxelManip` object --- * expects raw node data in the form of an array of node content IDs --- * the array must be exactly the size of the volume of the `VoxelManip` object --- * the array must be indexed from `1` to `volume` --- * the data can be retrieved using `VoxelManip:get_data()` ---- @param data number[] +--- @param data integer[] function VoxelManip:set_data(data) end ---- Sets the data contents of the `VoxelManip` object ---- function VoxelManip:set_data(data) end + --- Does nothing, kept for compatibility. --- function VoxelManip:update_map() end ---- Set the lighting within the `VoxelManip` to ---- a uniform value. ---- * `light` is a table, `{day=<0...15>, night=<0...15>}` ---- * To be used only by a `VoxelManip` object from ---- `minetest.get_mapgen_object`. ---- * (`p1`, `p2`) is the area in which lighting is set, defaults to the whole ---- area if left out. +--- Set the lighting within the `VoxelManip` to a uniform value. +--- * `light` is a table, `{day=<0...15>, night=<0...15>}` +--- * To be used only by a `VoxelManip` object from `minetest.get_mapgen_object`. +--- * (`p1`, `p2`) is the area in which lighting is set, defaults to the whole area if left out. function VoxelManip:set_lighting(light, p1, p2) end + --- Gets the light data read into the `VoxelManip` object. ---- * Returns an array (indices 1 to volume) of integers ranging from `0` to ---- `255`. ---- * Each value is the bitwise combination of day and night light values ---- (`0` to `15` each). ---- * `light = day + (night * 16)` ---- * If the param `buffer` is present, this table will be used to store the ---- result instead. ---- @param buffer number[]? [optional] ---- @return number[] +--- * Returns an array (indices 1 to volume) of integers ranging from `0` to `255`. +--- * Each value is the bitwise combination of day and night light values +--- (`0` to `15` each). +--- * `light = day + (night * 16)` +--- * If the param `buffer` is present, this table will be used to store the +--- result instead. +--- @param buffer integer[]? [optional] +--- @return integer[] function VoxelManip:get_light_data(buffer) end + --- Sets the `param1` (light) contents of each node in the `VoxelManip`. --- * expects lighting data in the same format that `get_light_data()` returns ---- @param light_data number[] +--- @param light_data integer[] function VoxelManip:set_light_data(light_data) end + --- Gets the raw `param2` data read into the `VoxelManip` object. ---- * Returns an array (indices 1 to volume) of integers ranging from `0` to ---- `255`. ---- * If the param `buffer` is present, this table will be used to store the ---- result instead. ---- @param buffer number[]? [optional] ---- @return number[] +--- * Returns an array (indices 1 to volume) of integers ranging from `0` to `255`. +--- * If the param `buffer` is present, this table will be used to store the result instead. +--- @param buffer integer[]? [optional] +--- @return integer[] function VoxelManip:get_param2_data(buffer) end + --- Sets the `param2` contents of each node in the `VoxelManip`. ---- @param param2_data number[] +--- @param param2_data integer[] function VoxelManip:set_param2_data(param2_data) end + --- Calculate lighting within the `VoxelManip`. ---- * To be used only by a `VoxelManip` object from ---- `minetest.get_mapgen_object`. ---- * (`p1`, `p2`) is the area in which lighting is set, defaults to the whole ---- area if left out or nil. For almost all uses these should be left out ---- or nil to use the default. ---- * `propagate_shadow` is an optional boolean deciding whether shadows in a ---- generated mapchunk above are propagated down into the mapchunk, defaults ---- to `true` if left out. +--- * To be used only by a `VoxelManip` object from +--- `minetest.get_mapgen_object`. +--- * (`p1`, `p2`) is the area in which lighting is set, defaults to the whole +--- area if left out or nil. For almost all uses these should be left out +--- or nil to use the default. +--- * `propagate_shadow` is an optional boolean deciding whether shadows in a +--- generated mapchunk above are propagated down into the mapchunk, defaults +--- to `true` if left out. --- @overload fun(p1:Position, p2:Position) --- @overload fun(propagate_shadow:boolean) --- @overload fun() @@ -98,11 +97,14 @@ function VoxelManip:set_param2_data(param2_data) end --- @param p2 Position --- @param propagate_shadow boolean function VoxelManip:calc_lighting(p1, p2, propagate_shadow) end + --- Update liquid flow function VoxelManip:update_liquids() end --- Returns `true` or `false` if the data in the voxel --- manipulator had been modified since the last read from map, due to a call to --- `minetest.set_data()` on the loaded area elsewhere. +--- @return boolean function VoxelManip:was_modified() end + --- Returns actual emerged minimum and maximum positions. function VoxelManip:get_emerged_area() end diff --git a/core_namespace.lua b/core_namespace.lua index 0389489..6b1a63e 100644 --- a/core_namespace.lua +++ b/core_namespace.lua @@ -13,10 +13,14 @@ --- @class NodeTable --- @field name string ---- @field param1 number? ---- @field param2 number? +--- @field param1 integer? 8-bit integer ranging from 0 to 255 +--- @field param2 integer? 8-bit integer ranging from 0 to 255 NodeTable = {} +--- @class MapNode: NodeTable +--- @field force_place? boolean if the node should forcibly overwrite any previous contents (default: false) + + --- See ./classes/NodeMetaRef.lua --- See ./classes/VoxelArea.lua @@ -33,9 +37,9 @@ PseudoRandom = {} --- See ./classes/InvRef.lua --- @class Position ---- @field x number ---- @field y number ---- @field z number +--- @field x number|integer +--- @field y number|integer +--- @field z number|integer @@ -1258,6 +1262,7 @@ function minetest.set_mapgen_params(MapgenParams) end --- 4) Settings set as the user config default --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5019-L5026) +--- @return string|nil function minetest.get_mapgen_setting(name) end --- * Same as above, but returns the value as a NoiseParams table if the --- setting `name` exists and is a valid NoiseParams. @@ -2161,7 +2166,7 @@ function minetest.raillike_group(name) end --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5662-L5663) --- @param name string ---- @return number +--- @return integer function minetest.get_content_id(name) end --- Returns a string --- * Gets the name of the content with that content ID @@ -2391,14 +2396,7 @@ function minetest.request_insecure_environment() end --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5821-L5822) function minetest.global_exists(name) end --- Objects: ---- Settings object containing all of the settings from the ---- main config file (`minetest.conf`). ---- ---- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4766-L4767) ---- @type table -minetest.settings = {} --- `EnvRef` of the server environment and world. --- * Any function in the minetest namespace can be called using the syntax --- `minetest.env:somefunction(somearguments)`