Noise API: Perlin, octave, and double-Perlin functions

The noise API provides the low-level noise primitives that power biome generation from MC 1.18 onward, as well as Beta-era terrain. There are three noise layers: single-octave PerlinNoise, multi-octave OctaveNoise, and the paired DoublePerlinNoise. Most callers do not need to use these directly — they are initialized automatically inside BiomeNoise — but they are exposed for custom noise sampling and analysis.

Structs

`PerlinNoise`

A single octave of Perlin (or simplex) noise.

typedef struct PerlinNoise {
    uint8_t d[256+1]; // permutation table
    uint8_t h2;
    double  a, b, c;  // origin offsets
    double  amplitude;
    double  lacunarity;
    double  d2;
    double  t2;
} PerlinNoise;

Field	Type	Description
`d`	`uint8_t[]`	257-element permutation table.
`a, b, c`	`double`	Origin offsets derived from the seed.
`amplitude`	`double`	Per-octave amplitude scaling factor.
`lacunarity`	`double`	Frequency multiplier between octaves.

`OctaveNoise`

A stack of PerlinNoise octaves combined with exponential amplitude weighting.

typedef struct OctaveNoise {
    int          octcnt;   // number of active octaves
    PerlinNoise *octaves;  // pointer to octave array
} OctaveNoise;

Field	Type	Description
`octcnt`	`int`	Number of active octaves in the stack.
`octaves`	`PerlinNoise *`	Array of `octcnt` initialized octaves.

`DoublePerlinNoise`

Two parallel OctaveNoise stacks whose outputs are combined, matching Minecraft’s 1.18+ climate noise implementation.

typedef struct DoublePerlinNoise {
    double      amplitude; // combined amplitude scaling
    OctaveNoise octA;
    OctaveNoise octB;
} DoublePerlinNoise;

Field	Type	Description
`amplitude`	`double`	Combined scaling factor.
`octA`	`OctaveNoise`	First octave stack.
`octB`	`OctaveNoise`	Second octave stack.

Perlin noise functions

`perlinInit`

void perlinInit(PerlinNoise *noise, uint64_t *seed);

Initializes a PerlinNoise instance using a Java Random seed. Advances the seed state by the number of calls required for initialization.

noise

PerlinNoise *

required

Pointer to the PerlinNoise struct to initialize.

seed

uint64_t *

required

Pointer to a 48-bit Java Random seed. The seed is advanced in place.

`xPerlinInit`

void xPerlinInit(PerlinNoise *noise, Xoroshiro *xr);

Initializes a PerlinNoise instance using an Xoroshiro 128 RNG, as used in MC 1.18+.

noise

PerlinNoise *

required

Pointer to the PerlinNoise struct to initialize.

Xoroshiro *

required

Pointer to an initialized Xoroshiro state. Advanced in place.

`samplePerlin`

double samplePerlin(const PerlinNoise *noise, double x, double y, double z,
    double yamp, double ymin);

Samples Perlin noise at position (x, y, z). The yamp and ymin arguments control vertical amplitude clamping used internally by the terrain system; pass 0 for both to get a plain sample.

noise

const PerlinNoise *

required

Initialized PerlinNoise.

double

required

X coordinate.

double

required

Y coordinate.

double

required

Z coordinate.

yamp

double

Vertical amplitude parameter. Pass 0 to ignore.

ymin

double

Vertical minimum parameter. Pass 0 to ignore.

`sampleSimplex2D`

double sampleSimplex2D(const PerlinNoise *noise, double x, double y);

Samples 2D simplex noise at (x, y) using the permutation table of noise.

noise

const PerlinNoise *

required

Initialized PerlinNoise.

double

required

X coordinate.

double

required

Y coordinate.

Octave noise functions

`octaveInit`

void octaveInit(OctaveNoise *noise, uint64_t *seed, PerlinNoise *octaves,
    int omin, int len);

Initializes an OctaveNoise by calling perlinInit on len consecutive octaves. omin is the index of the lowest-frequency octave.

noise

OctaveNoise *

required

Pointer to the OctaveNoise struct to initialize.

seed

uint64_t *

required

Java Random seed, advanced in place.

octaves

PerlinNoise *

required

Pre-allocated array of at least len PerlinNoise elements.

omin

int

required

Minimum octave index (lowest frequency).

len

int

required

Number of octaves to initialize.

`xOctaveInit`

int xOctaveInit(OctaveNoise *noise, Xoroshiro *xr, PerlinNoise *octaves,
    const double *amplitudes, int omin, int len, int nmax);

Initializes an OctaveNoise using an Xoroshiro RNG with per-octave amplitude values from the amplitudes array (length len). Used for MC 1.18+ climate noise. Returns the number of active octaves on success.

noise

OctaveNoise *

required

Pointer to the OctaveNoise struct to initialize.

Xoroshiro *

required

Xoroshiro state, advanced in place.

octaves

PerlinNoise *

required

Pre-allocated array of at least nmax PerlinNoise elements.

amplitudes

const double *

required

Array of len amplitude values, one per octave. Octaves with amplitude 0 are skipped.

omin

int

required

Minimum octave index.

len

int

required

Length of the amplitudes array.

nmax

int

required

Maximum number of octaves in the octaves buffer.

`octaveInitBeta`

void octaveInitBeta(OctaveNoise *noise, uint64_t *seed, PerlinNoise *octaves,
    int octcnt, double lac, double lacMul, double persist, double persistMul);

Initializes an OctaveNoise for Beta-era terrain generation with explicit lacunarity and persistence multipliers.

noise

OctaveNoise *

required

Pointer to the OctaveNoise struct to initialize.

seed

uint64_t *

required

Java Random seed, advanced in place.

octaves

PerlinNoise *

required

Pre-allocated array of at least octcnt elements.

octcnt

int

required

Number of octaves.

lac

double

required

Starting lacunarity (frequency scale).

lacMul

double

required

Lacunarity multiplier applied per octave.

persist

double

required

Starting persistence (amplitude scale).

persistMul

double

required

Persistence multiplier applied per octave.

`sampleOctave`

double sampleOctave(const OctaveNoise *noise, double x, double y, double z);

Returns the combined sample from all octaves at (x, y, z).

noise

const OctaveNoise *

required

Initialized OctaveNoise.

double

required

X coordinate.

double

required

Y coordinate.

double

required

Z coordinate.

`sampleOctaveAmp`

double sampleOctaveAmp(const OctaveNoise *noise, double x, double y, double z,
    double yamp, double ymin, int ydefault);

Samples all octaves with vertical amplitude clamping, as used in Overworld terrain generation.

noise

const OctaveNoise *

required

Initialized OctaveNoise.

double

required

X coordinate.

double

required

Y coordinate.

double

required

Z coordinate.

yamp

double

required

Vertical amplitude clamp value.

ymin

double

required

Vertical minimum clamp value.

ydefault

int

required

Default Y behavior flag.

`sampleOctave2D`

double sampleOctave2D(const OctaveNoise *noise, double x, double z);

Returns the combined 2D octave sample at (x, z).

noise

const OctaveNoise *

required

Initialized OctaveNoise.

double

required

X coordinate.

double

required

Z coordinate.

Double Perlin noise functions

`doublePerlinInit`

void doublePerlinInit(DoublePerlinNoise *noise, uint64_t *seed,
    PerlinNoise *octavesA, PerlinNoise *octavesB, int omin, int len);

Initializes a DoublePerlinNoise using Java Random, allocating two OctaveNoise stacks octA and octB from separate pre-allocated arrays.

noise

DoublePerlinNoise *

required

Pointer to the DoublePerlinNoise struct to initialize.

seed

uint64_t *

required

Java Random seed, advanced in place.

octavesA

PerlinNoise *

required

Pre-allocated array for the first octave stack.

octavesB

PerlinNoise *

required

Pre-allocated array for the second octave stack.

omin

int

required

Minimum octave index for both stacks.

len

int

required

Number of octaves in each stack.

`xDoublePerlinInit`

int xDoublePerlinInit(DoublePerlinNoise *noise, Xoroshiro *xr,
    PerlinNoise *octaves, const double *amplitudes, int omin, int len, int nmax);

Initializes a DoublePerlinNoise using Xoroshiro and per-octave amplitudes. Used for MC 1.18+ climate parameters. Returns the total number of active octaves.

noise

DoublePerlinNoise *

required

Pointer to the DoublePerlinNoise struct to initialize.

Xoroshiro *

required

Xoroshiro state, advanced in place.

octaves

PerlinNoise *

required

Pre-allocated array for both stacks (must hold at least 2 * nmax elements).

amplitudes

const double *

required

Array of len amplitude values.

omin

int

required

Minimum octave index.

len

int

required

Length of the amplitudes array.

nmax

int

required

Maximum octaves per stack.

`sampleDoublePerlin`

double sampleDoublePerlin(const DoublePerlinNoise *noise,
    double x, double y, double z);

Returns the combined sample from both octave stacks at (x, y, z), scaled by the noise amplitude.

noise

const DoublePerlinNoise *

required

Initialized DoublePerlinNoise.

double

required

X coordinate.

double

required

Y coordinate.

double

required

Z coordinate.

Usage example

#include "noise.h"

// Sample a single DoublePerlinNoise using Java Random
void example_sample(void)
{
    uint64_t seed = 12345ULL;
    setSeed(&seed, seed);

    PerlinNoise octA[4], octB[4];
    DoublePerlinNoise dpn;
    doublePerlinInit(&dpn, &seed, octA, octB, -3, 4);

    double val = sampleDoublePerlin(&dpn, 100.0, 64.0, 200.0);
}

Generator API

Finders API

Noise API: Perlin, octave, and double-Perlin functions

Structs

`PerlinNoise`

`OctaveNoise`

`DoublePerlinNoise`

Perlin noise functions

`perlinInit`

`xPerlinInit`

`samplePerlin`

`sampleSimplex2D`

Octave noise functions

`octaveInit`

`xOctaveInit`

`octaveInitBeta`

`sampleOctave`

`sampleOctaveAmp`

`sampleOctave2D`

Double Perlin noise functions

`doublePerlinInit`

`xDoublePerlinInit`

`sampleDoublePerlin`

Usage example

Build docs developers (and LLMs) love

Generator API

Finders API

Documentation Index

​Structs

​PerlinNoise

​OctaveNoise

​DoublePerlinNoise

​Perlin noise functions

​perlinInit

​xPerlinInit

​samplePerlin

​sampleSimplex2D

​Octave noise functions

​octaveInit

​xOctaveInit

​octaveInitBeta

​sampleOctave

​sampleOctaveAmp

​sampleOctave2D

​Double Perlin noise functions

​doublePerlinInit

​xDoublePerlinInit

​sampleDoublePerlin

​Usage example

Build docs developers (and LLMs) love

Structs

`PerlinNoise`

`OctaveNoise`

`DoublePerlinNoise`

Perlin noise functions

`perlinInit`

`xPerlinInit`

`samplePerlin`

`sampleSimplex2D`

Octave noise functions

`octaveInit`

`xOctaveInit`

`octaveInitBeta`

`sampleOctave`

`sampleOctaveAmp`

`sampleOctave2D`

Double Perlin noise functions

`doublePerlinInit`

`xDoublePerlinInit`

`sampleDoublePerlin`

Usage example