Adding missing noise descriptions: ValueNoise, ValueNoiseMap, NoiseParams. Close #2
This commit is contained in:
24
classes/ValueNoise.lua
Normal file
24
classes/ValueNoise.lua
Normal file
@@ -0,0 +1,24 @@
|
|||||||
|
--- @diagnostic disable: missing-return
|
||||||
|
|
||||||
|
--- A value noise generator. It can be created via ValueNoise() or core.get_value_noise().
|
||||||
|
--- For core.get_value_noise(), the actual seed used is the noiseparams seed plus the world
|
||||||
|
--- seed, to create world-specific noise.
|
||||||
|
---
|
||||||
|
--- **Important**: These require the mapgen environment to be initalized, do not use at load time.
|
||||||
|
---
|
||||||
|
--- * `ValueNoise(noiseparams)`
|
||||||
|
--- * `ValueNoise(seed, octaves, persistence, spread)` (deprecated)
|
||||||
|
--- * `core.get_value_noise(noiseparams)`
|
||||||
|
--- * `core.get_value_noise(seeddiff, octaves, persistence, spread)` (deprecated)
|
||||||
|
--- @class ValueNoise
|
||||||
|
ValueNoise = {}
|
||||||
|
|
||||||
|
--- Returns 2D noise value at `pos={x=,y=}`
|
||||||
|
--- @param pos vector
|
||||||
|
--- @return number
|
||||||
|
function ValueNoise:get_2d(pos) end
|
||||||
|
|
||||||
|
--- Returns 3D noise value at `pos={x=,y=,z=}`
|
||||||
|
--- @param pos vector
|
||||||
|
--- @return number
|
||||||
|
function ValueNoise:get_3d(pos) end
|
||||||
77
classes/ValueNoiseMap.lua
Normal file
77
classes/ValueNoiseMap.lua
Normal file
@@ -0,0 +1,77 @@
|
|||||||
|
--- @diagnostic disable: missing-return
|
||||||
|
|
||||||
|
--- A fast, bulk noise generator.
|
||||||
|
---
|
||||||
|
--- It can be created via `ValueNoiseMap(noiseparams, size)` or
|
||||||
|
--- `core.get_value_noise_map(noiseparams, size)`.
|
||||||
|
--- For `core.get_value_noise_map()`, the actual seed used is the noiseparams seed
|
||||||
|
--- plus the world seed, to create world-specific noise.
|
||||||
|
---
|
||||||
|
--- Format of `size` is `{x=dimx, y=dimy, z=dimz}`. The `z` component is omitted
|
||||||
|
--- for 2D noise, and it must be larger than 1 for 3D noise (otherwise
|
||||||
|
--- `nil` is returned).
|
||||||
|
---
|
||||||
|
--- For each of the functions with an optional `buffer` parameter:If `buffer` is not nil, this
|
||||||
|
--- table will be used to store the result instead of creating a new table.
|
||||||
|
---
|
||||||
|
--- **Important**: These require the mapgen environment to be initalized, do not use at load time.
|
||||||
|
--- @class ValueNoiseMap
|
||||||
|
ValueNoiseMap = {}
|
||||||
|
|
||||||
|
--- Returns a `<size.x>` times `<size.y>` 2D array of 2D noise
|
||||||
|
--- with values starting at `pos={x=,y=}`
|
||||||
|
--- @param pos vector
|
||||||
|
--- @return table
|
||||||
|
function ValueNoiseMap:get_2d_map(pos) end
|
||||||
|
|
||||||
|
--- Returns a `<size.x>` times `<size.y>` times `<size.z>`
|
||||||
|
--- 3D array of 3D noise with values starting at `pos={x=,y=,z=}`
|
||||||
|
--- @param pos vector
|
||||||
|
--- @return table
|
||||||
|
function ValueNoiseMap:get_3d_map(pos) end
|
||||||
|
|
||||||
|
--- Returns a flat `<size.x * size.y>` element
|
||||||
|
--- array of 2D noise with values starting at `pos={x=,y=}`
|
||||||
|
--- @param pos vector
|
||||||
|
--- @param buffer table If `buffer` is not nil, this table will be used to store the result instead of creating a new table.
|
||||||
|
--- @return table
|
||||||
|
function ValueNoiseMap:get_2d_map_flat(pos, buffer) end
|
||||||
|
|
||||||
|
--- Same as `get2dMap_flat`, but 3D noise
|
||||||
|
--- @param pos vector
|
||||||
|
--- @param buffer table If `buffer` is not nil, this table will be used to store the result instead of creating a new table.
|
||||||
|
--- @return table
|
||||||
|
function ValueNoiseMap:get_3d_map_flat(pos, buffer) end
|
||||||
|
|
||||||
|
--- Calculates the 2d noise map starting at `pos`. The result
|
||||||
|
--- is stored internally.
|
||||||
|
--- @param pos vector
|
||||||
|
function ValueNoiseMap:calc_2d_map(pos) end
|
||||||
|
|
||||||
|
--- Calculates the 3d noise map starting at `pos`. The result
|
||||||
|
--- is stored internally.
|
||||||
|
--- @param pos vector
|
||||||
|
function ValueNoiseMap:calc_3d_map(pos) end
|
||||||
|
|
||||||
|
--- In the form of an array,
|
||||||
|
--- returns a slice of the most recently computed noise results. The result slice
|
||||||
|
--- begins at coordinates `slice_offset` and takes a chunk of `slice_size`.
|
||||||
|
--- E.g., to grab a 2-slice high horizontal 2d plane of noise starting at buffer
|
||||||
|
--- offset `y = 20`:
|
||||||
|
--- ```lua
|
||||||
|
--- noisevals = noise:get_map_slice({y=20}, {y=2})
|
||||||
|
--- ```
|
||||||
|
--- It is important to note that `slice_offset` offset coordinates begin at 1,
|
||||||
|
--- and are relative to the starting position of the most recently calculated
|
||||||
|
--- noise.
|
||||||
|
--- To grab a single vertical column of noise starting at map coordinates
|
||||||
|
--- `x = 1023, y=1000, z = 1000`:
|
||||||
|
--- ```lua
|
||||||
|
--- noise:calc_3d_map({x=1000, y=1000, z=1000})
|
||||||
|
--- noisevals = noise:get_map_slice({x=24, z=1}, {x=1, z=1})
|
||||||
|
--- ```
|
||||||
|
--- @param slice_offset vector
|
||||||
|
--- @param slice_size vector
|
||||||
|
--- @param buffer table If `buffer` is not nil, this table will be used to store the result instead of creating a new table.
|
||||||
|
--- @return table
|
||||||
|
function ValueNoiseMap:get_map_slice(slice_offset, slice_size, buffer) end
|
||||||
127
definitions/NoiseParams.lua
Normal file
127
definitions/NoiseParams.lua
Normal file
@@ -0,0 +1,127 @@
|
|||||||
|
--- For 2D or 3D value noise or value noise maps:
|
||||||
|
---
|
||||||
|
--- ```lua
|
||||||
|
--- np_terrain = {
|
||||||
|
--- offset = 0,
|
||||||
|
--- scale = 1,
|
||||||
|
--- spread = {x = 500, y = 500, z = 500},
|
||||||
|
--- seed = 571347,
|
||||||
|
--- octaves = 5,
|
||||||
|
--- persistence = 0.63,
|
||||||
|
--- lacunarity = 2.0,
|
||||||
|
--- flags = "defaults, absvalue",
|
||||||
|
--- }
|
||||||
|
--- ```
|
||||||
|
---
|
||||||
|
--- 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.
|
||||||
|
--- @class NoiseParams
|
||||||
|
local NoiseParams = {
|
||||||
|
--- 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.
|
||||||
|
--- @type number
|
||||||
|
offset = 0,
|
||||||
|
|
||||||
|
--- Once all octaves have been combined, the result is multiplied by this.
|
||||||
|
--- Can be positive or negative
|
||||||
|
--- @type number
|
||||||
|
scale = 1,
|
||||||
|
|
||||||
|
--- 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.
|
||||||
|
--- Values are positive numbers.
|
||||||
|
--- @type vector
|
||||||
|
spread = vector(1,1,1),
|
||||||
|
|
||||||
|
--- 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.
|
||||||
|
---
|
||||||
|
--- In some noise APIs the world seed is added to the seed specified in noise
|
||||||
|
--- parameters. This is done to make the resulting noise pattern vary in different
|
||||||
|
--- worlds, and be 'world-specific'.
|
||||||
|
--- @type number
|
||||||
|
seed = 0,
|
||||||
|
|
||||||
|
--- 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' appearance.
|
||||||
|
---
|
||||||
|
--- 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.
|
||||||
|
--- Warning: If the 'wavelength' of any octave falls below 1 an error will occur.
|
||||||
|
--- @type number
|
||||||
|
octaves = 1,
|
||||||
|
|
||||||
|
--- 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.
|
||||||
|
---
|
||||||
|
--- Instead of `persistence`, the key `persist` may be used to the same effect.
|
||||||
|
--- @type number
|
||||||
|
persistence = 0.5,
|
||||||
|
|
||||||
|
|
||||||
|
--- 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'.
|
||||||
|
--- @type number
|
||||||
|
lacunarity = 2.0,
|
||||||
|
|
||||||
|
--- 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
|
||||||
|
--- appearance.
|
||||||
|
--- 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`
|
||||||
|
--- The absolute value of each octave's noise variation is used when combining the
|
||||||
|
--- octaves. The final value noise variation is created as follows:
|
||||||
|
--- ```
|
||||||
|
--- noise = offset + scale * (abs(octave1) +
|
||||||
|
--- abs(octave2) * persistence +
|
||||||
|
--- abs(octave3) * persistence ^ 2 +
|
||||||
|
--- abs(octave4) * persistence ^ 3 +
|
||||||
|
--- ...)
|
||||||
|
--- ```
|
||||||
|
--- @type string?
|
||||||
|
flags = nil,
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user