diff --git a/classes/VoxelArea.lua b/classes/VoxelArea.lua index 4135225..7bf93c3 100644 --- a/classes/VoxelArea.lua +++ b/classes/VoxelArea.lua @@ -13,6 +13,7 @@ VoxelArea = {} --- Also you can create an instance via `VoxelArea(pmin, pmax)` --- --- @param cuboid { MinEdge: any, MaxEdge: any } +--- @return VoxelArea function VoxelArea:new(cuboid) end --- returns a 3D vector containing the size of the area formed by `MinEdge` and `MaxEdge`. diff --git a/classes/VoxelManip.lua b/classes/VoxelManip.lua index f47a89b..74723e3 100644 --- a/classes/VoxelManip.lua +++ b/classes/VoxelManip.lua @@ -10,6 +10,7 @@ VoxelManip = {} --- * 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. @@ -37,6 +38,13 @@ function VoxelManip:set_node_at(pos, node) end --- @return number[] 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[] +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 @@ -56,7 +64,7 @@ function VoxelManip:set_lighting(light, p1, p2) end --- * `light = day + (night * 16)` --- * If the param `buffer` is present, this table will be used to store the --- result instead. ---- @param buffer number[] +--- @param buffer number[]? [optional] --- @return number[] function VoxelManip:get_light_data(buffer) end --- Sets the `param1` (light) contents of each node in the `VoxelManip`. @@ -68,7 +76,7 @@ function VoxelManip:set_light_data(light_data) end --- `255`. --- * If the param `buffer` is present, this table will be used to store the --- result instead. ---- @param buffer number[] +--- @param buffer number[]? [optional] --- @return number[] function VoxelManip:get_param2_data(buffer) end --- Sets the `param2` contents of each node in the `VoxelManip`. @@ -83,6 +91,9 @@ 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(propagate_shadow:boolean) +--- @overload fun() --- @param p1 Position --- @param p2 Position --- @param propagate_shadow boolean diff --git a/classes/vector.lua b/classes/vector.lua new file mode 100644 index 0000000..a740d32 --- /dev/null +++ b/classes/vector.lua @@ -0,0 +1,214 @@ +--- @diagnostic disable: missing-return + +--- @class vector: Position +--- @operator eq : boolean +--- @operator unm : vector +--- @operator add(vector): vector +--- @operator sub(vector): vector +--- @operator mul(number): vector +--- @operator div(number): vector +local vector = {} + +--- Creates a new vector `(a, b, c)`. +--- * Deprecated: `vector.new()` does the same as `vector.zero()` and +--- `vector.new(v)` does the same as `vector.copy(v)` +--- @param x number +--- @param y? number +--- @param z? number +--- @return vector +function vector.new(x, y, z) end + +--- Returns a new vector (0, 0, 0). +--- @return vector +function vector.zero() end + +--- Returns a new vector of length 1, pointing into a direction chosen uniformly at random. +--- @return vector +function vector.random_direction() end + +--- Returns a copy of the vector. +--- @return vector +function vector:copy() end + +--- Returns `v, np`, where `v` is a vector read from the given string `s` and +--- `np` is the next position in the string after the vector. +--- Returns `nil` on failure. +--- `str`: Has to begin with a substring of the form `"(x, y, z)"`. Additional +--- spaces, leaving away commas and adding an additional comma to the end +--- is allowed. +--- `from_position`: If given starts looking for the vector at this string index. +--- +--- @param str string +--- @param from_position? integer # If given starts looking for the vector at this string index +--- @return vector?, integer +function vector.from_string(str, from_position) end + +--- Returns a string of the form `"(x, y, z)"`. +--- `tostring(v)` does the same. +--- @return string +function vector:to_string() end +--- Returns a string of the form `"(x, y, z)"`. +--- @deprecated Use `vector:to_string()` instead. +--- @return string +function vector:tostring() end + +--- Returns a vector of length 1 with direction `p1` to `p2`. +--- If `p1` and `p2` are identical, returns `(0, 0, 0)`. +--- @param p1 Position +--- @param p2 Position +--- @return vector +function vector.direction(p1, p2) end + +--- Returns the distance between `p1` and `p2`. +--- @param p1 Position +--- @param p2 Position +--- @return number # Returns zero or a positive number, the distance between `p1` and `p2`. +function vector.distance(p1, p2) end + +--- Returns the length of the vector. +--- @return number # Returns zero or a positive number, the length of the vector. +function vector:length() end + +--- - Returns a normalized copy of the vector. +--- *(Returns a vector of length 1 with direction of vector).* +--- - If vector has zero length, returns (0, 0, 0). +--- @return vector +function vector:normalize() end + +--- Returns a vector, each dimension rounded down. +--- @return vector +function vector:floor() end + +--- Returns a vector, each dimension rounded up. +--- @return vector +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 +function vector:round() end + +--- Returns a vector where `math.sign` was called for each component. +--- See [Helper functions](https://api.luanti.org/helper-functions/) for details. +function vector:sign() end + +--- Returns a vector with absolute values for each component. +function vector:abs() end + +--- Applies a function to each component of the vector and returns a new vector. +--- Additional arguments are passed to the function. +--- @param func fun(number, ...): number # Function to apply. First argument is the component value. +--- @param ... any # Additional arguments passed to `func`. +--- @return vector # New vector with modified components. +function vector:apply(func, ...) end + +--- Returns a vector where the function func has combined both components of v and w for each component. +--- @param v2 vector # Second vector to combine with. +--- @param func fun(number, number): number +--- @return vector # New vector with combined components. +function vector:combine(v2, func) end + +--- Returns a boolean, true if the vectors are identical. +--- @param other vector +--- @return boolean +function vector:equals(other) end + +--- Returns in order minp, maxp vectors of the cuboid defined by `v1`, `v2`. +--- @param v1 vector +--- @param v2 vector +--- @return vector minp, vector maxp +function vector.sort(v1, v2) end + +--- Returns the angle between vectors in radians. +--- @param other vector +function vector:angle(other) end + +--- Calculates the dot product (скалярное произведение) with another vector. +--- @param other vector +--- @return number +function vector:dot(other) end + +--- Calculates the cross product (векторное произведение) with another vector. +--- @param other vector +--- @return vector +function vector:cross(other) end + +--- Returns a new vector with the offset applied. +--- *(Returns the sum of the vector and v(x, y, z).)* +--- @param x number +--- @param y number +--- @param z number +--- @return vector +function vector:offset(x, y, z) end + +--- - Returns a boolean value indicating whether the vector is a real vector, eg. created by a `vector.*` function. +--- - Returns `false` for anything else, including tables like `{ x = 3, y = 1, z = 4 }`. +--- @return boolean +function vector:check() end + +--- Returns a boolean value indicating if `pos` is inside area formed by `min` and `max`. +--- - `min` and `max` are inclusive. +--- - If `min` is bigger than `max` on some axis, function always returns `false`. +--- - You can use `vector.sort` if you have two vectors and don't know which are the minimum and the maximum. +--- @param pos Position +--- @param min Position +--- @param max Position +--- @return boolean +function vector.in_area(pos, min, max) end + +--- Returns a random integer position in area formed by `min` and `max`. +--- - `min` and `max` are inclusive. +--- - You can use `vector.sort` if you have two vectors and don't know which are the minimum and the maximum. +--- @param min Position +--- @param max Position +--- @return vector +function vector.random_in_area(min, max) end + +--- Returns a vector. +--- - If `x` is a vector: Returns the sum of the vector and `x`. +--- - If `x` is a number: Adds `x` to each component of the vector. +--- @param x vector|number +--- @return vector +function vector:add(x) end + +--- Returns a vector. +--- - If `x` is a vector: Returns the difference of the vector and `x`. +--- - If `x` is a number: Subtracts `x` from each component of the vector. +--- @param x vector|number +--- @return vector +function vector:subtract(x) end + +--- Returns a scaled vector. +--- - Deprecated: If `scalar` is a vector: Returns the Schur product. +--- @param scalar number|vector +--- @return vector +function vector:multiply(scalar) end + +--- Returns a scaled vector. +--- - Deprecated: If `scalar` is a vector: Returns the Schur quotient. +--- @param scalar number +--- @return vector +function vector:divide(scalar) end + +--- Applies the rotation `rotation` to the vector and returns the result vector. +--- - Uses (extrinsic) Z-X-Y rotation order and is right-handed, consistent with `ObjectRef:set_rotation`. +--- - `vector.rotate(vector.new(0, 0, 1), rotation)` and `vector.rotate(vector.new(0, 1, 0), rotation)` +--- return vectors pointing forward and up relative to an entity's rotation `rotation`. +--- @param rotation vector +--- @return vector +function vector:rotate(rotation) end + +--- Rotates the vector around `axis` by `angle` radians according to the right hand rule +--- and returns the result vector. +--- @param axis vector +--- @param angle number # Angle in radians +--- @return vector +function vector:rotate_around_axis(axis, angle) end + +--- Returns a rotation vector for `direction` pointing forward using `up` as the up vector. +--- - If `up` is omitted, the roll of the returned vector defaults to zero. +--- - Otherwise `direction` and `up` need to be vectors in a 90 degree angle to each other. +--- @param direction vector +--- @param up? vector +--- @return vector +function vector.dir_to_rotation(direction, up) end diff --git a/minetest_ns.lua b/core_namespace.lua similarity index 98% rename from minetest_ns.lua rename to core_namespace.lua index d40abf2..387948d 100644 --- a/minetest_ns.lua +++ b/core_namespace.lua @@ -37,7 +37,7 @@ PseudoRandom = {} --- @field y number --- @field z number ---- @class vector: Position + --- @class Position2d --- @field x number @@ -1044,7 +1044,7 @@ function minetest.find_node_near(pos, radius, node_names, search_in_center) end --- @param pos1 Position min positions of the area to search. --- @param pos2 Position max positions of the area to search. --- @param node_names table|string e.g. `{"ignore", "group:tree"}` or `"default:dirt"` ---- @param grouped boolean +--- @param grouped boolean? [optional] If true the return value is a table indexed by node name which contains lists of positions. (default: `false`). --- --- @return (table|Position[]), (nil|table) function minetest.find_nodes_in_area(pos1, pos2, node_names, grouped) end @@ -1070,10 +1070,10 @@ function minetest.get_perlin(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 position1 Position min position ---- @param position2 Position max position +--- @param min_position Position? min position +--- @param max_position Position? max position --- @return VoxelManip -function minetest.get_voxel_manip(position1, position2) end +function minetest.get_voxel_manip(min_position, max_position) end --- * Set the types of on-generate notifications that should be collected. --- * `flags` is a flag field with the available flags: --- * dungeon @@ -1083,12 +1083,13 @@ function minetest.get_voxel_manip(position1, position2) end --- * large_cave_begin --- * large_cave_end --- * decoration ---- * The second parameter is a list of IDs of decorations which notification ---- is requested for. --- ---- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4958-L4969) ---- @param deco_ids table -function minetest.set_gen_notify(flags, deco_ids) end +--- @param flags string flagstring with any of the above flags separated by commas. +--- @param deco_ids table? list of decoration IDs which notification is requested for. +--- @param custom_ids table? list of user-defined IDs (strings) which are requested. +--- By convention these should be the mod name with an optional +--- colon and specifier added, e.g. `"default"` or `"default:dungeon_loot"` +function minetest.set_gen_notify(flags, deco_ids, custom_ids) end --- * Returns a flagstring and a table with the `deco_id`s. --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4970-L4971) @@ -1098,10 +1099,33 @@ function minetest.get_gen_notify() end --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4972-L4974) function minetest.get_decoration_id(decoration_name) end ---- * Return requested mapgen object if available (see [Mapgen objects]) + +--- * `voxelmanip` - VoxelManip object +--- * `heightmap` - 2D array of height values (y) +--- * `biomemap` - 2D array of biome IDs +--- * `heatmap` - 2D array of heat values (0-255) +--- * `humiditymap` - 2D array of humidity values (0-255) +--- * `gennotify` - Table of on-generate notifications (see `minetest.set_gen_notify`) +--- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4970-L4971) +--- @alias MapgenObjectName +--- | "voxelmanip" # VoxelManip object +--- | "heightmap" # 2D? array of height values (y) +--- | "biomemap" # 2D? array of biome IDs +--- | "heatmap" # 2D? array of heat values (0-255) +--- | "humiditymap" # 2D? array of humidity values (0-255) +--- | "gennotify" # Table of on-generate notifications (see `minetest.set_gen_notify`) + +--- Returns requested mapgen object if available (see [Mapgen objects]) --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L4975-L4976) ---- @return VoxelManip|number[][]|number[][][], number, number +--- @overload fun(objectname:"voxelmanip") :VoxelManip, Position, Position +--- @overload fun(objectname:"heightmap") :number[][] +--- @overload fun(objectname:"biomemap") :number[][] +--- @overload fun(objectname:"heatmap") :number[][] +--- @overload fun(objectname:"humiditymap"):number[][] +--- @overload fun(objectname:"gennotify") :table +--- @param objectname MapgenObjectName one of: "voxelmanip", "heightmap", "biomemap", "heatmap", "humiditymap", "gennotify" +--- @return VoxelManip|number[][]|number[][][], Position, Position function minetest.get_mapgen_object(objectname) end --- * Returns the heat at the position, or `nil` on failure. --- @@ -1982,9 +2006,9 @@ function minetest.get_mod_storage() end -- Misc.: --- Returns list of `ObjectRefs` ---- @return Player[] --- --- [View in lua_api.txt](https://github.com/minetest/minetest/blob/5.4.1/doc/lua_api.txt#L5637-L5637) +--- @return Player[] function minetest.get_connected_players() end --- Boolean, whether `obj` is a player --- diff --git a/minetest/utilities.lua b/core_namespace/utilities.lua similarity index 100% rename from minetest/utilities.lua rename to core_namespace/utilities.lua