Adding missing noise descriptions: ValueNoise, ValueNoiseMap, NoiseParams. Close #2

This commit is contained in:
Van
2025-10-05 14:38:22 +03:00
parent d0df13bfb4
commit cb8cb067bd
3 changed files with 228 additions and 0 deletions

24
classes/ValueNoise.lua Normal file
View 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
View 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
View 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,
}