mirror of
https://github.com/minetest/minetest.git
synced 2024-12-24 07:02:23 +01:00
Lua_api.txt: Improve noise documentation
This commit is contained in:
parent
cd6bcef6d9
commit
5e2096e396
134
doc/lua_api.txt
134
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
### `octaves`
|
||||
Number of times the noise gradient is accumulated into the noise.
|
||||
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.
|
||||
|
||||
Increase this number to increase the amount of detail in the resulting noise.
|
||||
|
||||
A value of `6` is common.
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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
|
||||
|
Loading…
Reference in New Issue
Block a user