minetest.get_perlin

From Minetest Developer Wiki
Jump to: navigation, search

Contents

Syntax

minetest.get_perlin(seeddiff, octaves, persistence, spread)

or

minetest.get_perlin(noiseparams)
  • seeddiff - difference to the world seed which is added to this perlin noise generator to create a unique noise pattern specific to this world.
  • octaves - 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.
  • persistence - 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.
  • spread - 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. `spread` is a vector with values for x, y, z to allow the noise variation to be stretched or compressed in the desired axes. This function applies equal spread in all 3 axes. Value is a positive number.
  • noiseparams - table of noise parameters as found in map_meta.txt. Use minetest.get_mapgen_setting_noiseparams to obtain the table from the settings for your world.
note.png
Note: using the first form of the function returns a perlin object that will not scale or offset the output.


Description

Constructs a PerlinNoise object with seed derived from the world's seed value. This function must not be called until after the world is finished initializing, so it must be called during some kind of callback rather than at the top level mod initialization code. The PerlinNoise constructor, on the other hand, may be called at any time since it does not depend on the world's seed.

note.png
Note: each call to this function allocates a new perlin noise object in the engine. You may want to cache this object if used repeatedly.


noise = offset + scale * (octave1 + octave2 * persistence + octave3 * persistence ^ 2 + octave4 * persistence ^ 3 + ...)

Typical Noise Parameters

mg_biome_np_heat = {fags = defaults, lacunarity = 2, octaves = 3, offset = 50, persistence = 0.5, scale = 50, seed = 5349, spread = {x=1000,y=1000,z=1000}}

  • flags - Leave this field unset for no special handling. Currently supported are `defaults`, `eased` and `absvalue`
    • defaults - Specify this if you would like to keep auto-selection of eased/not-eased while 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 with a slightly gridded appearence. If no flags are specified (or defaults is), 2D noise is eased and 3D noise is not eased.
    • absvalue - 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 = offset + scale * (abs(octave1) + abs(octave2) * persistence + abs(octave3) * persistence ^ 2 + abs(octave4) * persistence ^ 3 + ...)

  • lacunarity - 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 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 particular range of 'wavelengths'.
note.png
Note: Easing a 3D noise significantly increases the noise calculation load, so use with restraint.


Example

local perlin = minetest.get_perlin(354, 3, 0.7, 100)
local np_myNoiseParams = minetest.get_mapgen_setting_noiseparams("mg_biome_np_heat")
local perlin_WithScaleAndOffset = minetest.get_perlin(np_myNoiseParams)

See Also

Personal tools
Namespaces

Variants
Actions
Navigation
API
Toolbox