Lua_api.txt: Improve noise documentation

doc/lua_api.txt

@@ -1118,54 +1118,112 @@ A box of a regular node would look like:
 
     {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
 
+Perlin noise
+------------
+Perlin noise creates a continuously-varying value depending on the input values.
+Usually in Minetest the input values are either 2D or 3D co-ordinates in nodes.
+The result is used during map generation to create the terrain shape, vary heat
+and humidity to distribute biomes, vary the density of decorations or vary the
+structure of ores.
+
+### Structure of perlin noise
+An 'octave' is a simple noise generator that outputs a value between -1 and 1.
+The smooth wavy noise it generates has a single characteristic scale, almost
+like a 'wavelength', so on its own does not create fine detail.
+Due to this perlin noise combines several octaves to create variation on
+multiple scales. Each additional octave has a smaller 'wavelength' than the
+previous.
+
+This combination results in noise varying very roughly between -2.0 and 2.0 and
+with an average value of 0.0, so `scale` and `offset` are then used to multiply
+and offset the noise variation. 
+
+The final perlin noise variation is created as follows:
+
+noise = offset + scale * (octave1 +
+                          octave2 * persistence +
+                          octave3 * persistence ^ 2 +
+                          octave4 * persistence ^ 3 +
+                          ...)
+
 Noise Parameters
 ----------------
-Noise Parameters, or commonly called "`NoiseParams`", define the properties of
-perlin noise.
+Noise Parameters are commonly called `NoiseParams`.
 
 ### `offset`
-Offset that the noise is translated by (i.e. added) after calculation.
+After the multiplication by `scale` this is added to the result and is the final
+step in creating the noise value.
+Can be positive or negative.
 
 ### `scale`
-Factor that the noise is scaled by (i.e. multiplied) after calculation.
+Once all octaves have been combined, the result is multiplied by this.
+Can be positive or negative.
 
 ### `spread`
-Vector containing values by which each coordinate is divided by before
-calculation.
-Higher spread values result in larger noise features.
+For octave1, this is roughly the change of input value needed for a very large
+variation in the noise value generated by octave1. It is almost like a
+'wavelength' for the wavy noise variation.
+Each additional octave has a 'wavelength' that is smaller than the previous
+octave, to create finer detail. `spread` will therefore roughly be the typical
+size of the largest structures in the final noise variation.
 
-A value of `{x=250, y=250, z=250}` is common.
+`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.
 
 ### `seed`
-Random seed for the noise. Add the world seed to a seed offset for world-unique
-noise. In the case of `minetest.get_perlin()`, this value has the world seed
-automatically added.
+This is a whole number that determines the entire pattern of the noise
+variation. Altering it enables different noise patterns to be created.
+With other parameters equal, different seeds produce different noise patterns
+and identical seeds produce identical noise patterns.
 
-### `octaves`
-Number of times the noise gradient is accumulated into the noise.
+For this parameter you can randomly choose any whole number. Usually it is
+preferable for this to be different from other seeds, but sometimes it is useful
+to be able to create identical noise patterns.
 
-Increase this number to increase the amount of detail in the resulting noise.
+When used in mapgen this is actually a 'seed offset', it is added to the
+'world seed' to create the seed used by the noise, to ensure the noise has a
+different pattern in different worlds.
 
-A value of `6` is common.
+### `octaves`
+The number of simple noise generators that are combined.
+A whole number, 1 or more.
+Each additional octave adds finer detail to the noise but also increases the
+noise calculation load.
+3 is a typical minimum for a high quality, complex and natural-looking noise
+variation. 1 octave has a slight 'gridlike' appearence.
+
+Choose the number of octaves according to the `spread` and `lacunarity`, and the
+size of the finest detail you require. For example:
+if `spread` is 512 nodes, `lacunarity` is 2.0 and finest detail required is 16
+nodes, octaves will be 6 because the 'wavelengths' of the octaves will be
+512, 256, 128, 64, 32, 16 nodes.
 
 ### `persistence`
-Factor by which the effect of the noise gradient function changes with each
-successive octave.
-
-Values less than `1` make the details of successive octaves' noise diminish,
-while values greater than `1` make successive octaves stronger.
-
-A value of `0.6` is common.
+Each additional octave has an amplitude that is the amplitude of the previous
+octave multiplied by `persistence`, to reduce the amplitude of finer details,
+as is often helpful and natural to do so.
+Since this controls the balance of fine detail to large-scale detail
+`persistence` can be thought of as the 'roughness' of the noise.
+
+A positive or negative non-zero number, often between 0.3 and 1.0.
+A common medium value is 0.5, such that each octave has half the amplitude of
+the previous octave.
+This may need to be tuned when altering `lacunarity`; when doing so consider
+that a common medium value is 1 / lacunarity.
 
 ### `lacunarity`
-Factor by which the noise feature sizes change with each successive octave.
+Each additional octave has a 'wavelength' that is the 'wavelength' of the
+previous octave multiplied by 1 / lacunarity, to create finer detail.
+'lacunarity' is often 2.0 so 'wavelength' often halves per octave.
 
-A value of `2.0` is common.
+A positive number no smaller than 1.0.
+Values below 2.0 create higher quality noise at the expense of requiring more
+octaves to cover a paticular range of 'wavelengths'.
 
 ### `flags`
 Leave this field unset for no special handling.
-
-Currently supported are `defaults`, `eased` and `absvalue`.
+Currently supported are `defaults`, `eased` and `absvalue`:
 
 #### `defaults`
 Specify this if you would like to keep auto-selection of eased/not-eased while
@@ -1174,28 +1232,39 @@ specifying some other flags.
 #### `eased`
 Maps noise gradient values onto a quintic S-curve before performing
 interpolation. This results in smooth, rolling noise.
-Disable this (`noeased`) for sharp-looking noise.
+Disable this (`noeased`) for sharp-looking noise with a slightly gridded
+appearence.
 If no flags are specified (or defaults is), 2D noise is eased and 3D noise is
 not eased.
+Easing a 3D noise significantly increases the noise calculation load, so use
+with restraint.
 
 #### `absvalue`
-Accumulates the absolute value of each noise gradient result.
+The absolute value of each octave's noise variation is used when combining the
+octaves. The final perlin noise variation is created as follows:
 
-Noise parameters format example for 2D or 3D perlin noise or perlin noise maps:
+noise = offset + scale * (abs(octave1) +
+                          abs(octave2) * persistence +
+                          abs(octave3) * persistence ^ 2 +
+                          abs(octave4) * persistence ^ 3 +
+                          ...)
+
+###Format example
+For 2D or 3D perlin noise or perlin noise maps:
 
     np_terrain = {
         offset = 0,
         scale = 1,
-        spread = {x=500, y=500, z=500},
+        spread = {x = 500, y = 500, z = 500},
         seed = 571347,
         octaves = 5,
         persist = 0.63,
         lacunarity = 2.0,
-        flags = "defaults, absvalue"
+        flags = "defaults, absvalue",
     }
-    ^ A single noise parameter table can be used to get 2D or 3D noise,
-      when getting 2D noise spread.z is ignored.
 
+For 2D noise the Z component of `spread` is still defined but is ignored.
+A single noise parameter table can be used for 2D or 3D noise.
 
 Ore types
 ---------
@@ -1268,6 +1337,7 @@ The following is a decent set of parameters to work from:
         seed    = 5390,
         octaves = 4,
         persist = 0.5,
+        lacunarity = 2.0,
         flags = "eased",
     },
     noise_threshold = 1.6