Math and Space

Noise

Seeded Perlin, Simplex, Value and Worley noise in 1D, 2D and 3D, with fractal layering, domain warping and composable operators.

PackageShared

Getting it

local Noise = Engine:GetPackage("Noise")

Noise produces smooth pseudo-random values that change gradually over space: the basis of terrain, caves, clouds, wind and texture variation. Every generator returns a NoiseField, and every operator takes NoiseFields and returns a new one, so you build complex noise by composing small pieces.

A NoiseField has three methods:

field:Sample1D(x): number
field:Sample2D(x, y): number
field:Sample3D(x, y, z): number

Gradient noises (Perlin, Simplex, Value) return values roughly between -1 and 1. The same seed always gives the same field, unlike math.noise, which has no seed.

Terrain heights

local Noise = Engine:GetPackage("Noise")

local base = Noise.Scale(Noise.FBM(Noise.Simplex(1234), { octaves = 5 }), 1 / 200)
local mountains = Noise.Scale(Noise.Ridged(Noise.Perlin(1234), { octaves = 4 }), 1 / 400)
local height = Noise.Add(base, Noise.Multiply(mountains, Noise.Clamp(base, 0, 1)))

for x = 1, 256 do
	for z = 1, 256 do
		local h = height:Sample2D(x, z) * 60
		-- place terrain at height h
	end
end

For large maps, run sampling inside ComputeService or spread it with SchedulerService so it doesn't stall a frame. GeometryService can turn a height function straight into a mesh.

Generators

Function	Description
`Noise.Perlin(seed)`	Classic gradient noise. Smooth and natural.
`Noise.Simplex(seed)`	Gradient noise with fewer directional artefacts; faster in higher dimensions.
`Noise.Value(seed)`	Interpolated random values per grid point. Blockier, cheap.
`Noise.Worley(seed, config?)`	Cellular noise based on distance to scattered points: cells, stones, cracks.
`Noise.Custom(sampler)`	Wrap your own functions `{ Sample1D?, Sample2D?, Sample3D? }` so they work with the operators. Missing dimensions error when sampled.

Worley options

Field	Values
`distanceFunction`	`"Euclidean"` (round cells), `"Manhattan"` (diamonds), `"Chebyshev"` (squares).
`returnType`	`"F1"` distance to the nearest point, `"F2"` to the second nearest, `"F2MinusF1"` (cell edges), `"CellValue"` (a flat random value per cell).
`jitter`	0 to 1: how far points move from their cell centre. 0 gives a regular grid.

Fractals

Fractals add several layers (octaves) of the same noise at increasing frequency and decreasing strength, which adds detail.

Function	Description
`Noise.FBM(noise, options?)`	Fractal Brownian motion: the standard layered look.
`Noise.Ridged(noise, options?)`	Sharp ridges, good for mountain ranges.
`Noise.Billow(noise, options?)`	Puffy rounded shapes, good for clouds and hills.

Options: octaves (layers), lacunarity (frequency multiplier per layer) and gain (strength multiplier per layer).

Operators

Function	Description
`Noise.Scale(noise, frequency?)`	Multiplies the coordinates. Small frequencies (e.g. `1/200`) give large, slow features.
`Noise.DomainWarp(noise, warpNoise, strength)`	Offsets the coordinates by another noise, giving swirly, organic shapes.
`Noise.Remap(noise, curveFn)`	Runs every value through your function.
`Noise.Add(a, b)`, `Noise.Multiply(a, b)`	Combine two fields.
`Noise.Min(a, b)`, `Noise.Max(a, b)`	Lower or higher of two fields.
`Noise.Blend(a, b, t)`	Blend between two fields by a number or by a third field.
`Noise.Abs(noise)`, `Noise.Invert(noise)`	Absolute value, or negate.
`Noise.Clamp(noise, min?, max?)`	Limit values (default -1 to 1).
`Noise.Terrace(noise, steps?)`	Quantise into flat steps, like terraced hills.

Configuration

Defaults from DefaultConfiguration/Packages/Noise10 settings

Setting	Default	What it does
DefaultOctaves	4	Layers a fractal (FBM/Ridged/Billow) sums when no octaves are passed.
DefaultLacunarity	2	Frequency multiplier per octave when none is passed.
DefaultGain	0.5	Amplitude multiplier per octave when none is passed.
DefaultWorleyDistanceFunction	"Euclidean"	Distance metric Worley noise uses when none is passed.
DefaultWorleyReturnType	"F1"	Which feature-point distance Worley returns when none is passed.
DefaultWorleyJitter	1	How far Worley feature points move from their cell centre (0-1) when none is passed.
DefaultScaleFrequency	1	Frequency :Scale() applies when none is passed.
DefaultClampMin	-1	Lower bound :Clamp() uses when none is passed.
DefaultClampMax	1	Upper bound :Clamp() uses when none is passed.
DefaultTerraceSteps	8	Steps :Terrace() quantises into when none is passed.

Types

export type NoiseField
export type FractalOptions = { octaves: number?, lacunarity: number?, gain: number? }
export type WorleyConfig
export type CustomSampler