Minor lua_api.md improvements (#16169)

Author: grorp

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 <http://www.luanti.org/>
-* Developer Wiki: <https://dev.luanti.org/>
+* Additional documentation: <https://docs.luanti.org/>
 
 Introduction
 ------------

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 <http://www.luanti.org/>
-* Developer Wiki: <https://dev.luanti.org/>
+* Additional documentation: <https://docs.luanti.org/>
 * (Unofficial) Minetest Modding Book by rubenwardy: <https://rubenwardy.com/minetest_modding_book/>
 * Modding tools: <https://github.com/luanti-org/modtools>
 
@@ -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 `<size.x>` times `<size.y>` 2D array of 2D noise
-  with values starting at `pos={x=,y=}`
-* `get_3d_map(pos)`: returns a `<size.x>` times `<size.y>` times `<size.z>`
-  3D array of 3D noise with values starting at `pos={x=,y=,z=}`.
-* `get_2d_map_flat(pos, buffer)`: returns a flat `<size.x * size.y>` 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 `<size.x>` times `<size.y>` 2D array of 2D noise
+  with values starting at `pos={x=,y=}`
+* `get_3d_map(pos)`: returns a `<size.x>` times `<size.y>` times `<size.z>`
+  3D array of 3D noise with values starting at `pos={x=,y=,z=}`.
+* `get_2d_map_flat(pos, buffer)`: returns a flat `<size.x * size.y>` 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})
+  ```
+