diff --git a/doc/client_lua_api.md b/doc/client_lua_api.md index 017f8b89b6..ff4af5cccf 100644 --- a/doc/client_lua_api.md +++ b/doc/client_lua_api.md @@ -5,8 +5,11 @@ Luanti Lua Client Modding API Reference 5.13.0 it's now called `core` due to the renaming of Luanti (formerly Minetest). `minetest` will keep existing as an alias, so that old code won't break. +Note that `core` has already existed since version 0.4.10, so you can use it +safely without breaking backwards compatibility. + * More information at -* Developer Wiki: +* Additional documentation: Introduction ------------ diff --git a/doc/lua_api.md b/doc/lua_api.md index b604b317c4..747c523a4d 100644 --- a/doc/lua_api.md +++ b/doc/lua_api.md @@ -5,8 +5,11 @@ Luanti Lua Modding API Reference it's now called `core` due to the renaming of Luanti (formerly Minetest). `minetest` will keep existing as an alias, so that old code won't break. +Note that `core` has already existed since version 0.4.10, so you can use it +safely without breaking backwards compatibility. + * More information at -* Developer Wiki: +* Additional documentation: * (Unofficial) Minetest Modding Book by rubenwardy: * Modding tools: @@ -4581,11 +4584,13 @@ and offset the noise variation. The final fractal value noise variation is created as follows: +``` noise = offset + scale * (octave1 + octave2 * persistence + octave3 * persistence ^ 2 + octave4 * persistence ^ 3 + ...) +``` Noise Parameters ---------------- @@ -4699,11 +4704,13 @@ with restraint. The absolute value of each octave's noise variation is used when combining the octaves. The final value noise variation is created as follows: +``` noise = offset + scale * (abs(octave1) + abs(octave2) * persistence + abs(octave3) * persistence ^ 2 + abs(octave4) * persistence ^ 3 + ...) +``` ### Format example @@ -6562,13 +6569,10 @@ Environment access * The actual seed used is the noiseparams seed plus the world seed. * `core.get_value_noise(seeddiff, octaves, persistence, spread)` * Deprecated: use `core.get_value_noise(noiseparams)` instead. - * Return world-specific value noise * `core.get_perlin(noiseparams)` - * Deprecated: use `core.get_value_noise(noiseparams)` instead. - * Return world-specific value noise (was not Perlin noise) + * Deprecated: renamed to `core.get_value_noise` in version 5.12.0. * `core.get_perlin(seeddiff, octaves, persistence, spread)` - * Deprecated: use `core.get_value_noise(noiseparams)` instead. - * Return world-specific value noise (was not Perlin noise) + * Deprecated: renamed to `core.get_value_noise` in version 5.12.0. * `core.get_voxel_manip([pos1, pos2])` * Return voxel manipulator object. * Loads the manipulator from the map if positions are passed. @@ -9061,78 +9065,6 @@ offering very strong randomness. * `get_state()`: return generator state encoded in string * `set_state(state_string)`: restore generator state from encoded string -`ValueNoise` -------------- - -A value noise generator. -It can be created via `ValueNoise()` or `core.get_value_noise()`. -For legacy reasons, it can also be created via `PerlinNoise()` or `core.get_perlin()`, -but the implemented noise is not Perlin noise. -For `core.get_value_noise()`, the actual seed used is the noiseparams seed -plus the world seed, to create world-specific noise. - -* `ValueNoise(noiseparams) -* `ValueNoise(seed, octaves, persistence, spread)` (Deprecated) -* `PerlinNoise(noiseparams)` (Deprecated) -* `PerlinNoise(seed, octaves, persistence, spread)` (Deprecated) - -* `core.get_value_noise(noiseparams)` -* `core.get_value_noise(seeddiff, octaves, persistence, spread)` (Deprecated) -* `core.get_perlin(noiseparams)` (Deprecated) -* `core.get_perlin(seeddiff, octaves, persistence, spread)` (Deprecated) - -### Methods - -* `get_2d(pos)`: returns 2D noise value at `pos={x=,y=}` -* `get_3d(pos)`: returns 3D noise value at `pos={x=,y=,z=}` - -`ValueNoiseMap` ----------------- - -A fast, bulk noise generator. - -It can be created via `ValueNoiseMap(noiseparams, size)` or -`core.get_value_noise_map(noiseparams, size)`. -For legacy reasons, it can also be created via `PerlinNoiseMap(noiseparams, size)` -or `core.get_perlin_map(noiseparams, size)`, but it is not Perlin noise. -For `core.get_value_noise_map()`, the actual seed used is the noiseparams seed -plus the world seed, to create world-specific noise. - -Format of `size` is `{x=dimx, y=dimy, z=dimz}`. The `z` component is omitted -for 2D noise, and it must be larger than 1 for 3D noise (otherwise -`nil` is returned). - -For each of the functions with an optional `buffer` parameter: If `buffer` is -not nil, this table will be used to store the result instead of creating a new -table. - -### Methods - -* `get_2d_map(pos)`: returns a `` times `` 2D array of 2D noise - with values starting at `pos={x=,y=}` -* `get_3d_map(pos)`: returns a `` times `` times `` - 3D array of 3D noise with values starting at `pos={x=,y=,z=}`. -* `get_2d_map_flat(pos, buffer)`: returns a flat `` element - array of 2D noise with values starting at `pos={x=,y=}` -* `get_3d_map_flat(pos, buffer)`: Same as `get2dMap_flat`, but 3D noise -* `calc_2d_map(pos)`: Calculates the 2d noise map starting at `pos`. The result - is stored internally. -* `calc_3d_map(pos)`: Calculates the 3d noise map starting at `pos`. The result - is stored internally. -* `get_map_slice(slice_offset, slice_size, buffer)`: In the form of an array, - returns a slice of the most recently computed noise results. The result slice - begins at coordinates `slice_offset` and takes a chunk of `slice_size`. - E.g., to grab a 2-slice high horizontal 2d plane of noise starting at buffer - offset y = 20: - `noisevals = noise:get_map_slice({y=20}, {y=2})` - It is important to note that `slice_offset` offset coordinates begin at 1, - and are relative to the starting position of the most recently calculated - noise. - To grab a single vertical column of noise starting at map coordinates - x = 1023, y=1000, z = 1000: - `noise:calc_3d_map({x=1000, y=1000, z=1000})` - `noisevals = noise:get_map_slice({x=24, z=1}, {x=1, z=1})` - `PlayerMetaRef` --------------- @@ -9184,14 +9116,17 @@ end The map is loaded as the ray advances. If the map is modified after the `Raycast` is created, the changes may or may not have an effect on the object. -It can be created via `Raycast(pos1, pos2, objects, liquids)` or -`core.raycast(pos1, pos2, objects, liquids)` where: +It can be created via `Raycast(pos1, pos2, objects, liquids, pointabilities)` +or `core.raycast(pos1, pos2, objects, liquids, pointabilities)` where: * `pos1`: start of the ray * `pos2`: end of the ray -* `objects`: if false, only nodes will be returned. Default is true. +* `objects`: if false, only nodes will be returned. Default is `true`. * `liquids`: if false, liquid nodes (`liquidtype ~= "none"`) won't be - returned. Default is false. + returned. Default is `false`. +* `pointabilities`: Allows overriding the `pointable` property of + nodes and objects. Uses the same format as the `pointabilities` property + of item definitions. Default is `nil`. ### Limitations @@ -9307,6 +9242,81 @@ to restrictions of JSON. * All methods in MetaDataRef +`ValueNoise` +------------- + +A value noise generator. +It can be created via `ValueNoise()` or `core.get_value_noise()`. +For `core.get_value_noise()`, the actual seed used is the noiseparams seed +plus the world seed, to create world-specific noise. + +* `ValueNoise(noiseparams)` +* `ValueNoise(seed, octaves, persistence, spread)` (deprecated) +* `core.get_value_noise(noiseparams)` +* `core.get_value_noise(seeddiff, octaves, persistence, spread)` (deprecated) + +These were previously called `PerlinNoise()` and `core.get_perlin()`, but the +implemented noise was not Perlin noise. They were renamed in 5.12.0. The old +names still exist as aliases. + +### Methods + +* `get_2d(pos)`: returns 2D noise value at `pos={x=,y=}` +* `get_3d(pos)`: returns 3D noise value at `pos={x=,y=,z=}` + +`ValueNoiseMap` +---------------- + +A fast, bulk noise generator. + +It can be created via `ValueNoiseMap(noiseparams, size)` or +`core.get_value_noise_map(noiseparams, size)`. +For `core.get_value_noise_map()`, the actual seed used is the noiseparams seed +plus the world seed, to create world-specific noise. + +These were previously called `PerlinNoiseMap()` and `core.get_perlin_map()`, +but the implemented noise was not Perlin noise. They were renamed in 5.12.0. +The old names still exist as aliases. + +Format of `size` is `{x=dimx, y=dimy, z=dimz}`. The `z` component is omitted +for 2D noise, and it must be larger than 1 for 3D noise (otherwise +`nil` is returned). + +For each of the functions with an optional `buffer` parameter: If `buffer` is +not nil, this table will be used to store the result instead of creating a new +table. + +### Methods + +* `get_2d_map(pos)`: returns a `` times `` 2D array of 2D noise + with values starting at `pos={x=,y=}` +* `get_3d_map(pos)`: returns a `` times `` times `` + 3D array of 3D noise with values starting at `pos={x=,y=,z=}`. +* `get_2d_map_flat(pos, buffer)`: returns a flat `` element + array of 2D noise with values starting at `pos={x=,y=}` +* `get_3d_map_flat(pos, buffer)`: Same as `get2dMap_flat`, but 3D noise +* `calc_2d_map(pos)`: Calculates the 2d noise map starting at `pos`. The result + is stored internally. +* `calc_3d_map(pos)`: Calculates the 3d noise map starting at `pos`. The result + is stored internally. +* `get_map_slice(slice_offset, slice_size, buffer)`: In the form of an array, + returns a slice of the most recently computed noise results. The result slice + begins at coordinates `slice_offset` and takes a chunk of `slice_size`. + E.g., to grab a 2-slice high horizontal 2d plane of noise starting at buffer + offset `y = 20`: + ```lua + noisevals = noise:get_map_slice({y=20}, {y=2}) + ``` + It is important to note that `slice_offset` offset coordinates begin at 1, + and are relative to the starting position of the most recently calculated + noise. + To grab a single vertical column of noise starting at map coordinates + `x = 1023, y=1000, z = 1000`: + ```lua + noise:calc_3d_map({x=1000, y=1000, z=1000}) + noisevals = noise:get_map_slice({x=24, z=1}, {x=1, z=1}) + ``` +