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