From cb8cb067bd416eb7297c272a47432c13c67dfaca Mon Sep 17 00:00:00 2001 From: Vanic Date: Sun, 5 Oct 2025 14:38:22 +0300 Subject: [PATCH] Adding missing noise descriptions: ValueNoise, ValueNoiseMap, NoiseParams. Close #2 --- classes/ValueNoise.lua | 24 +++++++ classes/ValueNoiseMap.lua | 77 ++++++++++++++++++++++ definitions/NoiseParams.lua | 127 ++++++++++++++++++++++++++++++++++++ 3 files changed, 228 insertions(+) create mode 100644 classes/ValueNoise.lua create mode 100644 classes/ValueNoiseMap.lua create mode 100644 definitions/NoiseParams.lua diff --git a/classes/ValueNoise.lua b/classes/ValueNoise.lua new file mode 100644 index 0000000..efb0c4e --- /dev/null +++ b/classes/ValueNoise.lua @@ -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 \ No newline at end of file diff --git a/classes/ValueNoiseMap.lua b/classes/ValueNoiseMap.lua new file mode 100644 index 0000000..48d7253 --- /dev/null +++ b/classes/ValueNoiseMap.lua @@ -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 `` times `` 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 `` times `` times `` +--- 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 `` 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 \ No newline at end of file diff --git a/definitions/NoiseParams.lua b/definitions/NoiseParams.lua new file mode 100644 index 0000000..93d7460 --- /dev/null +++ b/definitions/NoiseParams.lua @@ -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, +} \ No newline at end of file