From 5d3804168b0e07d52688c40e54fb2f56d09f80be Mon Sep 17 00:00:00 2001 From: Van <82447582+varttist@users.noreply.github.com> Date: Fri, 13 Feb 2026 12:09:24 +0300 Subject: [PATCH] Position edits (#7) * Moving annotations for vector classes and positions: `core_namespace.lua` -> `classes/vector.lua`. Rethinking position annotations * Replacing float positions with integer positions where required (voxel manipulator, node coordinates, etc.). Adding missing annotations to the position parameters of core methods * Fix position annotations in noises classes * remove alias `MapPosition2d` * Review fixes --- classes/ValueNoise.lua | 4 +- classes/ValueNoiseMap.lua | 16 ++--- classes/VoxelArea.lua | 18 ++--- classes/VoxelManip.lua | 18 ++--- classes/vector.lua | 32 +++++++++ core_namespace.lua | 114 +++++++++++++++++++++----------- definitions/ABMDefinition.lua | 2 +- definitions/BiomeDefinition.lua | 4 +- definitions/LBMDefinition.lua | 4 +- definitions/NodeDefinition.lua | 38 +++++------ definitions/NoiseParams.lua | 2 +- specs/SchematicSpecifier.lua | 2 +- 12 files changed, 160 insertions(+), 94 deletions(-) diff --git a/classes/ValueNoise.lua b/classes/ValueNoise.lua index dfe9289..ebbacde 100644 --- a/classes/ValueNoise.lua +++ b/classes/ValueNoise.lua @@ -15,11 +15,11 @@ ValueNoise = {} --- Returns 2D noise value at `pos={x=,y=}` ---- @param pos Position2d +--- @param pos IntegerPosition2d --- @return number function ValueNoise:get_2d(pos) end --- Returns 3D noise value at `pos={x=,y=,z=}` ---- @param pos Position +--- @param pos IntegerPosition --- @return number function ValueNoise:get_3d(pos) end diff --git a/classes/ValueNoiseMap.lua b/classes/ValueNoiseMap.lua index 442b692..a5ff0f0 100644 --- a/classes/ValueNoiseMap.lua +++ b/classes/ValueNoiseMap.lua @@ -21,37 +21,37 @@ ValueNoiseMap = {} --- Returns a `` times `` 2D array of 2D noise --- with values starting at `pos={x=,y=}` ---- @param pos Position2d +--- @param pos IntegerPosition2d --- @return table function ValueNoiseMap:get_2d_map(pos) end --- Returns a `` times `` times `` --- 3D array of 3D noise with values starting at `pos={x=,y=,z=}` ---- @param pos Position +--- @param pos IntegerPosition --- @return table function ValueNoiseMap:get_3d_map(pos) end --- Returns a flat `` element --- array of 2D noise with values starting at `pos={x=,y=}` ---- @param pos Position2d +--- @param pos IntegerPosition2d --- @param buffer table If `buffer` is not nil, this table will be used to store the result instead of creating a new table. --- @return table function ValueNoiseMap:get_2d_map_flat(pos, buffer) end --- Same as `get2dMap_flat`, but 3D noise ---- @param pos Position +--- @param pos IntegerPosition --- @param buffer table If `buffer` is not nil, this table will be used to store the result instead of creating a new table. --- @return table function ValueNoiseMap:get_3d_map_flat(pos, buffer) end --- Calculates the 2d noise map starting at `pos`. The result --- is stored internally. ---- @param pos Position2d +--- @param pos IntegerPosition2d function ValueNoiseMap:calc_2d_map(pos) end --- Calculates the 3d noise map starting at `pos`. The result --- is stored internally. ---- @param pos Position +--- @param pos IntegerPosition function ValueNoiseMap:calc_3d_map(pos) end --- In the form of an array, @@ -71,8 +71,8 @@ function ValueNoiseMap:calc_3d_map(pos) end --- noise:calc_3d_map({x=1000, y=1000, z=1000}) --- noisevals = noise:get_map_slice({x=24, z=1}, {x=1, z=1}) --- ``` ---- @param slice_offset {x:number?,y:number?,z:number?} ---- @param slice_size {x:number?,y:number?,z:number?} +--- @param slice_offset {x:integer?,y:integer?,z:integer?} +--- @param slice_size {x:integer?,y:integer?,z:integer?} --- @param buffer table If `buffer` is not nil, this table will be used to store the result instead of creating a new table. --- @return table function ValueNoiseMap:get_map_slice(slice_offset, slice_size, buffer) end diff --git a/classes/VoxelArea.lua b/classes/VoxelArea.lua index e799554..5d5fe5b 100644 --- a/classes/VoxelArea.lua +++ b/classes/VoxelArea.lua @@ -7,8 +7,8 @@ --- `VoxelArea:new({MinEdge = pmin, MaxEdge = pmax})`. --- The coordinates are *inclusive*, like most other things in Luanti. --- ---- @field MinEdge Position ---- @field MaxEdge Position +--- @field MinEdge MapPosition +--- @field MaxEdge MapPosition --- @field ystride integer --- @field zstride integer VoxelArea = {} @@ -17,12 +17,12 @@ VoxelArea = {} --- --- Also you can create an instance via `VoxelArea(pmin, pmax)` --- ---- @param cuboid { MinEdge: Position, MaxEdge: Position } +--- @param cuboid { MinEdge: MapPosition, MaxEdge: MapPosition } --- @return VoxelArea function VoxelArea:new(cuboid) end --- returns a 3D vector containing the size of the area formed by `MinEdge` and `MaxEdge`. ---- @return Position +--- @return IntegerPosition function VoxelArea:getExtent() end --- returns the volume of the area formed by `MinEdge` and `MaxEdge`. @@ -44,13 +44,13 @@ 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 +--- @param position MapPosition --- @return integer function VoxelArea:indexp(position) end --- returns the absolute position vector corresponding to index `i`. --- @param i integer ---- @return Position +--- @return MapPosition function VoxelArea:position(i) end --- check if (`x`,`y`,`z`) is inside area formed by `MinEdge` and `MaxEdge`. @@ -61,7 +61,7 @@ function VoxelArea:position(i) end function VoxelArea:contains(x, y, z) end --- check if Position(`x`,`y`,`z`) is inside area formed by `MinEdge` and `MaxEdge`. ---- @param position Position +--- @param position MapPosition --- @return boolean function VoxelArea:containsp(position) end @@ -83,7 +83,7 @@ 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]]]`. ---- @param min_pos Position ---- @param max_pos Position +--- @param min_pos MapPosition +--- @param max_pos MapPosition --- @return fun(tbl: table): integer, integer function VoxelArea:iterp(min_pos, max_pos) end diff --git a/classes/VoxelManip.lua b/classes/VoxelManip.lua index d488c1d..6d9d0c4 100644 --- a/classes/VoxelManip.lua +++ b/classes/VoxelManip.lua @@ -6,9 +6,9 @@ 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` ---- @param position1 Position min position for load part of map ---- @param position2 Position max position for load part of map ---- @return Position, Position +--- @param position1 MapPosition min position for load part of map +--- @param position2 MapPosition max position for load part of map +--- @return MapPosition, MapPosition function VoxelManip:read_from_map(position1, position2) end --- Writes the data loaded from the `VoxelManip` back to the map. @@ -22,12 +22,12 @@ function VoxelManip:read_from_map(position1, position2) end function VoxelManip:write_to_map(light) end --- Returns a `MapNode` table of the node currently loaded in the `VoxelManip` at that position. ---- @param pos Position +--- @param pos MapPosition --- @return MapNode function VoxelManip:get_node_at(pos) end --- Sets a specific `MapNode` in the `VoxelManip` at that position. ---- @param pos Position +--- @param pos MapPosition --- @param node MapNode function VoxelManip:set_node_at(pos, node) end @@ -90,11 +90,11 @@ function VoxelManip:set_param2_data(param2_data) end --- * `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(p1:MapPosition, p2:MapPosition) --- @overload fun(propagate_shadow:boolean) --- @overload fun() ---- @param p1 Position ---- @param p2 Position +--- @param p1 MapPosition +--- @param p2 MapPosition --- @param propagate_shadow boolean function VoxelManip:calc_lighting(p1, p2, propagate_shadow) end @@ -107,5 +107,5 @@ function VoxelManip:update_liquids() end function VoxelManip:was_modified() end --- Returns actual emerged minimum and maximum positions. ---- @return Position, Position +--- @return MapPosition, MapPosition function VoxelManip:get_emerged_area() end diff --git a/classes/vector.lua b/classes/vector.lua index f12855c..c9a7530 100644 --- a/classes/vector.lua +++ b/classes/vector.lua @@ -1,5 +1,22 @@ --- @meta +--- @class Position +--- @field x number +--- @field y number +--- @field z number + +--- @class IntegerPosition: Position +--- @field x integer +--- @field y integer +--- @field z integer + +--- @class Position2d +--- @field x number +--- @field y number + +--- @class IntegerPosition2d: Position2d +--- @field x integer +--- @field y integer --- @class vector: Position --- @operator eq : boolean @@ -13,6 +30,21 @@ --- @field z number vector = {} +--- Same as `vector`, but all fields are integers. +--- @class IntegerVector: vector +--- @operator eq : boolean +--- @operator unm : IntegerVector +--- @operator add(Position): IntegerVector +--- @operator sub(Position): IntegerVector +--- @operator mul(number) : IntegerVector +--- @operator div(number) : IntegerVector +--- @field x integer +--- @field y integer +--- @field z integer + +--- @alias MapPosition IntegerPosition +--- @alias MapVector IntegerVector +--- @alias PositionVector IntegerVector --- Creates a new vector `(a, b, c)`. --- * Deprecated: `vector.new()` does the same as `vector.zero()` and diff --git a/core_namespace.lua b/core_namespace.lua index 54683a2..890bb15 100644 --- a/core_namespace.lua +++ b/core_namespace.lua @@ -36,28 +36,6 @@ PseudoRandom = {} --- See ./classes/InvRef.lua ---- @class Position ---- @field x integer ---- @field y integer ---- @field z integer - ---- Same as `vector`, but all fields are integers. ---- @class IntegerVector: vector ---- @operator unm : IntegerVector ---- @operator add(Position): IntegerVector ---- @operator sub(Position): IntegerVector ---- @operator mul(number) : IntegerVector ---- @operator div(number) : IntegerVector ---- @field x integer ---- @field y integer ---- @field z integer - ---- @alias PositionVector IntegerVector - ---- @class Position2d ---- @field x integer ---- @field y integer - --- @class pointed_thing --- @field public type string one of {"nothing"|"node"|"object"} --- @field public above Position refers to the node position in front of the pointed face (only if type=="node") @@ -376,8 +354,8 @@ function core.register_on_punchnode(callback) end --- on the VoxelManipulator object is not necessary and is disallowed. --- * `blockseed`: 64-bit seed number used for this chunk. --- ---- @overload fun(callback:fun(min_pos:Position, max_pos:Position, blockseed:number)) ---- @param callback fun(vmanip:VoxelManip, min_pos:Position, max_pos:Position, blockseed:number) +--- @overload fun(callback:fun(min_pos:MapPosition, max_pos:MapPosition, blockseed:number)) +--- @param callback fun(vmanip:VoxelManip, min_pos:MapPosition, max_pos:MapPosition, blockseed:number) function core.register_on_generated(callback) end --- * Called when a new player enters the world for the first time --- @@ -421,7 +399,7 @@ function core.register_on_rightclickplayer(callback) end --- @field from string will be `"mod"` or `"engine"` --- @field object ObjectRef|Player|Entity --- @field node string|nil ---- @field node_pos Position|nil +--- @field node_pos MapPosition|nil --- * Called when the player gets damaged or healed --- * `player`: ObjectRef of the player @@ -760,7 +738,7 @@ function core.chat_send_player(name, text) end function core.format_chat_message(name, message) end -- Environment access: ---- @param pos Position +--- @param pos MapPosition --- @param node NodeTable --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4840-L4840) function core.set_node(pos, node) end @@ -771,6 +749,8 @@ function core.set_node(pos, node) end --- * e.g. `core.set_node({x=0, y=10, z=0}, {name="default:wood"})` --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4841-L4845) +--- @param pos MapPosition +--- @param node NodeTable function core.add_node(pos, node) end --- * Set node on all positions set in the first argument. @@ -785,7 +765,7 @@ function core.add_node(pos, node) end --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4846-L4855) --- ---- @param positions Position[] {pos1, pos2, pos3, ...} +--- @param positions MapPosition[] {pos1, pos2, pos3, ...} --- @param node NodeTable function core.bulk_set_node(positions, node) end @@ -794,7 +774,7 @@ function core.bulk_set_node(positions, node) end --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4856-L4857) --- ---- @param pos Position +--- @param pos MapPosition --- @param node NodeTable function core.swap_node(pos, node) end @@ -802,20 +782,20 @@ function core.swap_node(pos, node) end --- (Any existing metadata is deleted.) --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4858-L4859) ---- @param pos Position +--- @param pos MapPosition function core.remove_node(pos) end --- * Returns the node at the given position as table in the format --- `{name="node_name", param1=0, param2=0}`, --- returns `{name="ignore", param1=0, param2=0}` for unloaded areas. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4860-L4863) ----@param pos Position +---@param pos MapPosition ---@return NodeTable function core.get_node(pos) end --- * Same as `get_node` but returns `nil` for unloaded areas. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4864-L4865) ---- @param pos Position +--- @param pos MapPosition --- @return NodeTable|nil function core.get_node_or_nil(pos) end --- * Gets the light value at the given position. Note that the light value @@ -825,7 +805,7 @@ function core.get_node_or_nil(pos) end --- * `nil` is returned e.g. when the map isn't loaded at `pos` --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4866-L4873) ---- @param pos Position The position where to measure the light. +--- @param pos MapPosition The position where to measure the light. --- @param timeofday number|nil `nil` for current time, `0` for night, `0.5` for day --- @return number|nil function core.get_node_light(pos, timeofday) end @@ -838,6 +818,8 @@ function core.get_node_light(pos, timeofday) end --- unlikely --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4874-L4881) +--- @param pos MapPosition The position where to measure the light. +--- @param timeofday number|nil `nil` for current time, `0` for night, `0.5` for day function core.get_natural_light(pos, timeofday) end --- * Calculates the artificial light (light from e.g. torches) value from the --- `param1` value. @@ -851,35 +833,43 @@ function core.get_artificial_light(param1) end --- * Place node with the same effects that a player would cause --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4889-L4890) +--- @param pos MapPosition +--- @param node NodeTable function core.place_node(pos, node) end --- * Dig node with the same effects that a player would cause --- * Returns `true` if successful, `false` on failure (e.g. protected location) --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4891-L4893) +--- @param pos MapPosition function core.dig_node(pos) end --- * Punch node with the same effects that a player would cause --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4894-L4895) +--- @param pos MapPosition function core.punch_node(pos) end --- * Change node into falling node --- * Returns `true` if successful, `false` on failure --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4896-L4898) +--- @param pos MapPosition function core.spawn_falling_node(pos) end --- * Get a table of positions of nodes that have metadata within a region --- {pos1, pos2}. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4900-L4902) +--- @param pos1 MapPosition +--- @param pos2 MapPosition function core.find_nodes_with_meta(pos1, pos2) end --- * Get a `NodeMetaRef` at that position --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4903-L4904) ---- @param pos Position +--- @param pos MapPosition --- @return NodeMetaRef function core.get_meta(pos) end --- * Get `NodeTimerRef` --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4905-L4906) +--- @param pos MapPosition --- @return NodeTimerRef function core.get_node_timer(pos) end --- Spawn Lua-defined entity at @@ -888,13 +878,17 @@ function core.get_node_timer(pos) end --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4908-L4910) --- `staticdata` [Optional] no info +--- @param pos Position +--- @param name string +--- @param staticdata string? --- @return ObjectRef|Entity|nil function core.add_entity(pos, name, staticdata) end --- Spawn item --- * Returns `ObjectRef`, or `nil` if failed ---- @return ObjectRef|nil --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4911-L4912) +--- @param pos Position +--- @return ObjectRef|nil function core.add_item(pos, item) end --- Get an `ObjectRef` to a player --- @@ -943,7 +937,7 @@ function core.get_day_count() end --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4928-L4933) --- ---- @param pos Position +--- @param pos MapPosition --- @param radius number using a maximum metric --- @param node_names table|string e.g. `{"ignore", "group:tree"}` or `"default:dirt"` --- @param search_in_center boolean Optional. If true `pos` is also checked for the nodes. (default: `false`). @@ -959,8 +953,8 @@ function core.find_node_near(pos, radius, node_names, search_in_center) end --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4934-L4943) --- ---- @param pos1 Position min positions of the area to search. ---- @param pos2 Position max positions of the area to search. +--- @param pos1 MapPosition min positions of the area to search. +--- @param pos2 MapPosition max positions of the area to search. --- @param node_names table|string e.g. `{"ignore", "group:tree"}` or `"default:dirt"` --- @param grouped boolean? [optional] If true the return value is a table indexed by node name which contains lists of positions. (default: `false`). --- @@ -973,7 +967,10 @@ function core.find_nodes_in_area(pos1, pos2, node_names, grouped) end --- * Area volume is limited to 4,096,000 nodes --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4944-L4948) -function core.find_nodes_in_area_under_air(pos1, pos2, nodenames) end +--- @param pos1 MapPosition min positions of the area to search. +--- @param pos2 MapPosition max positions of the area to search. +--- @param node_names table|string e.g. `{"ignore", "group:tree"}` or `"default:dirt"` +function core.find_nodes_in_area_under_air(pos1, pos2, node_names) end --- * Deprecated: renamed to `core.get_value_noise` in version 5.12.0. --- @deprecated --- @param noiseparams NoiseParams @@ -998,8 +995,8 @@ function core.get_value_noise(seeddiff, octaves, persistence, spread) end --- * Loads the manipulator from the map if positions are passed. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4955-L4957) ---- @param min_position Position? min position ---- @param max_position Position? max position +--- @param min_position MapPosition? min position +--- @param max_position MapPosition? max position --- @return VoxelManip function core.get_voxel_manip(min_position, max_position) end --- * Set the types of on-generate notifications that should be collected. @@ -1058,10 +1055,12 @@ function core.get_mapgen_object(objectname) end --- * Returns the heat at the position, or `nil` on failure. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4977-L4978) +--- @param pos MapPosition function core.get_heat(pos) end --- * Returns the humidity at the position, or `nil` on failure. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4979-L4980) +--- @param pos MapPosition function core.get_humidity(pos) end --- * Returns a table containing: --- * `biome` the biome id of the biome at that position @@ -1070,6 +1069,7 @@ function core.get_humidity(pos) end --- * Or returns `nil` on failure. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4981-L4986) +--- @param pos MapPosition function core.get_biome_data(pos) end --- * Returns the biome id, as used in the biomemap Mapgen object and returned --- by `core.get_biome_data(pos)`, for a given biome_name string. @@ -1157,12 +1157,18 @@ function core.get_noiseparams(name) end --- * `pos1` and `pos2` are optional and default to mapchunk minp and maxp. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5047-L5050) +--- @param vm VoxelManip +--- @param pos1 MapPosition +--- @param pos2 MapPosition function core.generate_ores(vm, pos1, pos2) end --- * Generate all registered decorations within the VoxelManip `vm` and in the --- area from `pos1` to `pos2`. --- * `pos1` and `pos2` are optional and default to mapchunk minp and maxp. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5051-L5054) +--- @param vm VoxelManip +--- @param pos1 MapPosition +--- @param pos2 MapPosition function core.generate_decorations(vm, pos1, pos2) end --- * Clear all objects in the environment --- * Takes an optional table as an argument with the field `mode`. @@ -1179,6 +1185,8 @@ function core.clear_objects(options) end --- * This function does not trigger map generation. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5063-L5066) +--- @param pos1 MapPosition +--- @param pos2 MapPosition function core.load_area(pos1, pos2) end --- * Queue all blocks in the area from `pos1` to `pos2`, inclusive, to be --- asynchronously fetched from memory, loaded from disk, or if inexistent, @@ -1201,10 +1209,14 @@ function core.load_area(pos1, pos2) end --- nil if the parameter was absent). --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5067-L5086) +--- @param pos1 MapPosition +--- @param pos2 MapPosition function core.emerge_area(pos1, pos2, callback, param) end --- * delete all mapblocks in the area from pos1 to pos2, inclusive --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5087-L5088) +--- @param pos1 MapPosition +--- @param pos2 MapPosition function core.delete_area(pos1, pos2) end --- Returns `boolean, pos` --- * Checks if there is anything other than air between pos1 and pos2. @@ -1214,6 +1226,8 @@ function core.delete_area(pos1, pos2) end --- * `pos2`: Second position --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5089-L5094) +--- @param pos1 MapPosition +--- @param pos2 MapPosition function core.line_of_sight(pos1, pos2) end --- Returns `Raycast` --- * Creates a `Raycast` object. @@ -1223,6 +1237,10 @@ function core.line_of_sight(pos1, pos2) end --- * `liquids`: if false, liquid nodes won't be returned. Default is `false`. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5095-L5100) +--- @param pos1 MapPosition +--- @param pos2 MapPosition +--- @param objects boolean? +--- @param liquids boolean? function core.raycast(pos1, pos2, objects, liquids) end --- * returns table containing path that can be walked on --- * returns a table of 3D points representing a path from `pos1` to `pos2` or @@ -1245,33 +1263,41 @@ function core.raycast(pos1, pos2, objects, liquids) end --- on-the-fly --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5101-L5120) +--- @param pos1 MapPosition +--- @param pos2 MapPosition function core.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm) end --- * spawns L-system tree at given `pos` with definition in `treedef` table --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5121-L5122) +--- @param pos MapPosition function core.spawn_tree (pos, treedef) end --- * add node to liquid update queue --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5123-L5124) +--- @param pos MapPosition function core.transforming_liquid_add(pos) end --- * get max available level for leveled node --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5125-L5126) +--- @param pos MapPosition function core.get_node_max_level(pos) end --- * get level of leveled node (water, snow) --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5127-L5128) +--- @param pos MapPosition function core.get_node_level(pos) end --- * set level of leveled node, default `level` equals `1` --- * if `totallevel > maxlevel`, returns rest (`total-max`). --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5129-L5131) +--- @param pos MapPosition function core.set_node_level(pos, level) end --- * increase level of leveled node by level, default `level` equals `1` --- * if `totallevel > maxlevel`, returns rest (`total-max`) --- * `level` must be between -127 and 127 --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5132-L5135) +--- @param pos MapPosition function core.add_node_level(pos, level) end --- Returns `true`/`false` --- * resets the light in a cuboid-shaped part of @@ -1291,12 +1317,15 @@ function core.add_node_level(pos, level) end --- `true` otherwise --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5136-L5151) +--- @param pos1 MapPosition +--- @param pos2 MapPosition function core.fix_light(pos1, pos2) end --- * causes an unsupported `group:falling_node` node to fall and causes an --- unattached `group:attached_node` node to fall. --- * does not spread these updates to neighbours. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5152-L5155) +--- @param pos MapPosition function core.check_single_for_falling(pos) end --- * causes an unsupported `group:falling_node` node to fall and causes an --- unattached `group:attached_node` node to fall. @@ -1304,6 +1333,7 @@ function core.check_single_for_falling(pos) end --- of nodes to fall. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5156-L5160) +--- @param pos MapPosition function core.check_for_falling(pos) end --- * Returns a player spawn y co-ordinate for the provided (x, z) --- co-ordinates, or `nil` for an unsuitable spawn point. @@ -1658,11 +1688,13 @@ function core.item_eat(hp_change, replace_with_item) end --- * Calls functions registered by `core.register_on_punchnode()` --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5389-L5390) +--- @param pos MapPosition function core.node_punch(pos, node, puncher, pointed_thing) end --- * Checks if node can be dug, puts item into inventory, removes node --- * Calls functions registered by `core.registered_on_dignodes()` --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5391-L5393) +--- @param pos MapPosition function core.node_dig(pos, node, digger) end -- Sounds: @@ -2231,12 +2263,14 @@ function core.calculate_knockback(player, hitter, time_from_last_punch, tool_ca --- (not saved between server runs). --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5800-L5805) +--- @param pos MapPosition function core.forceload_block(pos, transient) end --- * stops forceloading the position `pos` --- * If `transient` is `false` or absent, frees a persistent forceload. --- If `true`, frees a transient forceload. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5807-L5810) +--- @param pos MapPosition function core.forceload_free_block(pos, transient) end --- Returns an environment containing --- insecure functions if the calling mod has been listed as trusted in the diff --git a/definitions/ABMDefinition.lua b/definitions/ABMDefinition.lua index c897074..edf9e32 100644 --- a/definitions/ABMDefinition.lua +++ b/definitions/ABMDefinition.lua @@ -57,6 +57,6 @@ local ABMDefinition = { --- mapblock plus all 26 neighboring mapblocks. If any neighboring --- mapblocks are unloaded an estimate is calculated for them based on --- loaded mapblocks. - --- @type fun(pos:Position, node:NodeTable, active_object_count:number, active_object_count_wider:number) + --- @type fun(pos:MapPosition, node:NodeTable, active_object_count:number, active_object_count_wider:number) action = function(pos, node, active_object_count, active_object_count_wider) end, } diff --git a/definitions/BiomeDefinition.lua b/definitions/BiomeDefinition.lua index c32f3de..508bbd7 100644 --- a/definitions/BiomeDefinition.lua +++ b/definitions/BiomeDefinition.lua @@ -109,13 +109,13 @@ local BiomeDefinition = { --- Biome is limited to a cuboid defined by these positions. --- Any x, y or z field left undefined defaults to -31000 in 'min_pos' or --- 31000 in 'max_pos'. - --- @type Position|{x:integer?,y:integer?,z:integer?}|nil + --- @type MapPosition|{x:integer?,y:integer?,z:integer?}|nil max_pos = { x = 31000, y = 128, z = 31000 }, --- xyz limits for biome, an alternative to using 'y_min' and 'y_max'. --- Biome is limited to a cuboid defined by these positions. --- Any x, y or z field left undefined defaults to -31000 in 'min_pos' or --- 31000 in 'max_pos'. - --- @type Position|{x:integer?,y:integer?,z:integer?}|nil + --- @type MapPosition|{x:integer?,y:integer?,z:integer?}|nil min_pos = { x = -31000, y = 9, z = -31000 }, --- Vertical distance in nodes above 'y_max' over which the biome will diff --git a/definitions/LBMDefinition.lua b/definitions/LBMDefinition.lua index b2339f0..2980fbd 100644 --- a/definitions/LBMDefinition.lua +++ b/definitions/LBMDefinition.lua @@ -29,7 +29,7 @@ local LBMDefinition = { --- Function triggered for each qualifying node. --- `dtime` is the in-game time (in seconds) elapsed since the mapblock --- was last active (available since 5.7.0). - --- @type fun(pos:Position, node:NodeTable, dtime:number)? + --- @type fun(pos:MapPosition, node:NodeTable, dtime:number)? action = function(pos, node, dtime) end, --- Function triggered with a list of all applicable node positions at once. @@ -37,6 +37,6 @@ local LBMDefinition = { --- - Available since `core.features.bulk_lbms` (5.10.0) --- - `dtime` is the in-game time (in seconds) elapsed since the mapblock --- was last active (available since 5.7.0). - --- @type fun(pos_list:Position[], dtime:number)? + --- @type fun(pos_list:MapPosition[], dtime:number)? bulk_action = function(pos_list, dtime) end, } diff --git a/definitions/NodeDefinition.lua b/definitions/NodeDefinition.lua index c88a2fb..9a6079a 100644 --- a/definitions/NodeDefinition.lua +++ b/definitions/NodeDefinition.lua @@ -504,19 +504,19 @@ local NodeDefinition = { --- infinite loop if it invokes the same callback. --- Consider using `core.swap_node()` instead. --- default: nil - --- @type fun(pos:Position)? + --- @type fun(pos:MapPosition)? on_construct = nil, --- Node destructor; called before removing node. --- Not called for bulk node placement. --- default: nil - --- @type fun(pos:Position)? + --- @type fun(pos:MapPosition)? on_destruct = nil, --- Node destructor; called after removing node. --- Not called for bulk node placement. --- default: nil - --- @type fun(pos:Position, old_node)? + --- @type fun(pos:MapPosition, old_node)? after_destruct = nil, --- Called when a liquid (new_node) is about to flood old_node, if it has @@ -526,7 +526,7 @@ local NodeDefinition = { --- over and over again every liquid update interval. --- Default: nil --- Warning: making a liquid node 'floodable' will cause problems. - --- @type fun(pos:Position, old_node, new_node)? + --- @type fun(pos:MapPosition, old_node, new_node)? on_flood = nil, @@ -539,7 +539,7 @@ local NodeDefinition = { --- be added directly to one or more of the dropped items. --- @see ItemStackMetaRef --- default: nil - --- @type fun(pos:Position, old_node, new_node, old_meta, drops:ItemStack[])? + --- @type fun(pos:MapPosition, old_node, new_node, old_meta, drops:ItemStack[])? preserve_metadata = nil, --- Called after constructing node when node was placed using @@ -547,7 +547,7 @@ local NodeDefinition = { --- If return true no item is taken from itemstack. --- `placer` may be any valid ObjectRef or nil. --- default: nil - --- @type fun(pos:Position, placer:Player|ObjectRef|nil, itemstack:ItemStack, pointed_thing:pointed_thing)? + --- @type fun(pos:MapPosition, placer:Player|ObjectRef|nil, itemstack:ItemStack, pointed_thing:pointed_thing)? after_place_node = nil, --- oldmetadata is in table format. @@ -559,13 +559,13 @@ local NodeDefinition = { --- Returns true if node can be dug, or false if not. --- default: nil - --- @type fun(pos:Position, player:Player|ObjectRef|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:Position, node:NodeTable, puncher:Player|ObjectRef|nil, pointed_thing:pointed_thing)? + --- @type fun(pos:MapPosition, node:NodeTable, puncher:Player|ObjectRef|nil, pointed_thing:pointed_thing)? on_punch = nil, --- default: nil @@ -577,14 +577,14 @@ local NodeDefinition = { --- Note: pointed_thing can be nil, if a mod calls this function. --- This function does not get triggered by clients <=0.4.16 if the --- "formspec" node metadata field is set. - --- @type (fun(pos:Position, node:NodeTable, clicker:Player|ObjectRef, itemstack:ItemStack, pointed_thing:pointed_thing|nil):ItemStack|nil)? + --- @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:Position, node:NodeTable, digger:Player): boolean)? + --- @type (fun(pos:MapPosition, node:NodeTable, digger:Player): boolean)? on_dig = nil, --- default: nil @@ -592,53 +592,53 @@ local NodeDefinition = { --- 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:Position, elapsed:number): boolean)? + --- @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:Position, formname:string, fields:table, sender:Player)? + --- @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:Position, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): number)? + --- @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:Position, listname:string, index:number, stack:ItemStack, player:Player): number)? + --- @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:Position, listname:string, index:number, stack:ItemStack, player:Player): number)? + --- @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:Position, from_list:string, from_index:number, to_list:string, to_index:number, count:number, player:Player): void)? + --- @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:Position, listname:string, index:number, stack:ItemStack, player:Player): void)? + --- @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:Position, listname:string, index:number, stack:ItemStack, player:Player): void)? + --- @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:Position, intensity:number): void)? + --- @type (fun(pos:MapPosition, intensity:number): void)? on_blast = nil, --- stores which mod actually registered a node diff --git a/definitions/NoiseParams.lua b/definitions/NoiseParams.lua index c29f359..1405e3d 100644 --- a/definitions/NoiseParams.lua +++ b/definitions/NoiseParams.lua @@ -41,7 +41,7 @@ local NoiseParams = { --- `spread` is a vector with values for x, y, z to allow the noise variation to be --- stretched or compressed in the desired axes. --- Values are positive numbers. - --- @type Position + --- @type IntegerPosition spread = {x=1,y=1,z=1}, --- This is a whole number that determines the entire pattern of the noise diff --git a/specs/SchematicSpecifier.lua b/specs/SchematicSpecifier.lua index 5a63416..430955d 100644 --- a/specs/SchematicSpecifier.lua +++ b/specs/SchematicSpecifier.lua @@ -6,7 +6,7 @@ local SchematicSpecifier = { --- Size of the schematic. --- Vector containing the dimensions of the provided schematic. (required field) - --- @type Position + --- @type IntegerPosition size = { x = 0, y = 0, z = 0 }, --- List of Y-slice probabilities.