{-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
#### `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
---------
seed = 5390,
octaves = 4,
persist = 0.5,
+ lacunarity = 2.0,
flags = "eased",
},
noise_threshold = 1.6
projects / oweals / minetest.git / commitdiff