diff options
| -rw-r--r-- | doc/lua_api.txt | 136 |
1 files changed, 103 insertions, 33 deletions
diff --git a/doc/lua_api.txt b/doc/lua_api.txt index b045f6402..65604a7ee 100644 --- a/doc/lua_api.txt +++ b/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 |