# tecs.math.noise


Native procedural scalar fields in two and three dimensions.

```teal
local terrain <const> = tecs.math.noise.new({
    algorithm = "perlin",
    fractal = "fbm",
    seed = 1234,
    frequency = 0.01,
    octaves = 4,
})

local height <const> = terrain:sample2(worldX, worldY)
```

A field is immutable after construction. The seed, algorithm, and options
therefore determine every sample, and sampling carries no snapshot state.
`fill2` crosses into native code once for a complete row-major grid and reuses
native scratch storage when the same field fills another grid.

FastNoise Lite supplies the algorithms. Its output is stable within the
version Tecs pins, but upgrading that dependency may change a generated field.
Persist the seed and options rather than generated values only when accepting
that versioned behavior.

## Module contents

### Constructors

| Constructor | Description |
| --- | --- |
| [`new`](/modules/math/noise/#tecs.math.noise.new) | Creates an immutable native procedural field. |

### Types

| Type | Kind | Description |
| --- | --- | --- |
| [`Algorithm`](/modules/math/noise/#tecs.math.noise.Algorithm) | <span class="tealdoc-kind-badge tealdoc-kind-enum">enum</span> | Selects the native scalar-field algorithm. |
| [`Fractal`](/modules/math/noise/#tecs.math.noise.Fractal) | <span class="tealdoc-kind-badge tealdoc-kind-enum">enum</span> | Selects how the field combines frequency octaves. |
| [`Noise`](/modules/math/noise/#tecs.math.noise.Noise) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Represents an immutable native procedural field. |
| [`Options`](/modules/math/noise/#tecs.math.noise.Options) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Configures one immutable native noise field. |

## Constructors

<a id="tecs.math.noise.new"></a>
### tecs.math.noise.new <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Creates an immutable native procedural field.

Invalid enum names, non-finite numeric options, a seed outside the
signed 32-bit range, an octave count outside `1..32`, or a weighted
strength outside `[0, 1]` raise at the call site.



```teal
function tecs.math.noise.new(options: Options): Noise
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `options` | [`Options`](/modules/math/noise/#tecs.math.noise.Options) | The field configuration. Nil takes every documented default. |

#### Returns

| Type | Description |
| --- | --- |
| [`Noise`](/modules/math/noise/#tecs.math.noise.Noise) | A field whose native allocation the Lua collector releases. |

## Types

<a id="tecs.math.noise.Algorithm"></a>
### tecs.math.noise.Algorithm <span class="tealdoc-kind-badge tealdoc-kind-enum">enum</span>

Selects the native scalar-field algorithm.


```teal
enum tecs.math.noise.Algorithm
    "cellular"
    "perlin"
    "simplex"
    "simplexSmooth"
    "value"
    "valueCubic"
end
```

<a id="tecs.math.noise.Fractal"></a>
### tecs.math.noise.Fractal <span class="tealdoc-kind-badge tealdoc-kind-enum">enum</span>

Selects how the field combines frequency octaves.


```teal
enum tecs.math.noise.Fractal
    "fbm"
    "none"
    "pingPong"
    "ridged"
end
```

<a id="tecs.math.noise.Noise"></a>
### tecs.math.noise.Noise <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Represents an immutable native procedural field.


```teal
record tecs.math.noise.Noise
    fill2: function(
        self,
        values: {number},
        width: integer,
        height: integer,
        originX: number,
        originY: number,
        stepX: number,
        stepY: number
    ): {number}
    sample2: function(self, x: number, y: number): number
    sample3: function(self, x: number, y: number, z: number): number
end
```

<a id="tecs.math.noise.Noise.fill2"></a>
#### tecs.math.noise.Noise:fill2 <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Fills a list with a row-major two-dimensional grid.

Rows advance by `stepY`; columns advance by `stepX`. The method
replaces indices `1..width*height`, removes any old trailing
entries, and retains the table and native scratch allocation for
reuse.



```teal
function tecs.math.noise.Noise.fill2(
    self,
    values: {number},
    width: integer,
    height: integer,
    originX: number,
    originY: number,
    stepX: number,
    stepY: number
): {number}
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Noise` |  |
| `values` | `{number}` | The caller-owned list the method fills and returns. |
| `width` | `integer` | The number of columns, as an integer in `[0, 2147483647]`. |
| `height` | `integer` | The number of rows, as an integer in `[0, 2147483647]`. |
| `originX` | `number` | The first column's coordinate. Defaults to zero. |
| `originY` | `number` | The first row's coordinate. Defaults to zero. |
| `stepX` | `number` | The coordinate distance between columns. Defaults to one. |
| `stepY` | `number` | The coordinate distance between rows. Defaults to one. |

##### Returns

| Type | Description |
| --- | --- |
| `{number}` | `values` itself after replacing its contents. |

<a id="tecs.math.noise.Noise.sample2"></a>
#### tecs.math.noise.Noise:sample2 <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Samples the field at a two-dimensional coordinate.



```teal
function tecs.math.noise.Noise.sample2(
    self, x: number, y: number
): number
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Noise` |  |
| `x` | `number` | A finite horizontal coordinate, scaled by the field's frequency. |
| `y` | `number` | A finite vertical coordinate, scaled by the field's frequency. |

##### Returns

| Type | Description |
| --- | --- |
| `number` | A value in `[-1, 1]`. |

<a id="tecs.math.noise.Noise.sample3"></a>
#### tecs.math.noise.Noise:sample3 <span class="tealdoc-kind-badge tealdoc-kind-instance">Instance</span>

Samples the field at a three-dimensional coordinate.



```teal
function tecs.math.noise.Noise.sample3(
    self, x: number, y: number, z: number
): number
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `self` | `Noise` |  |
| `x` | `number` | A finite horizontal coordinate, scaled by the field's frequency. |
| `y` | `number` | A finite vertical coordinate, scaled by the field's frequency. |
| `z` | `number` | A finite depth coordinate, scaled by the field's frequency. |

##### Returns

| Type | Description |
| --- | --- |
| `number` | A value in `[-1, 1]`. |

<a id="tecs.math.noise.Options"></a>
### tecs.math.noise.Options <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Configures one immutable native noise field.


```teal
record tecs.math.noise.Options
    algorithm: Algorithm
    fractal: Fractal
    seed: integer
    frequency: number
    octaves: integer
    lacunarity: number
    gain: number
    weightedStrength: number
    pingPongStrength: number
end
```

<a id="tecs.math.noise.Options.algorithm"></a>
#### tecs.math.noise.Options.algorithm <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Selects the field algorithm. Defaults to `"perlin"`.


```teal
tecs.math.noise.Options.algorithm: Algorithm
```

<a id="tecs.math.noise.Options.fractal"></a>
#### tecs.math.noise.Options.fractal <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Selects octave composition. Defaults to `"none"`.


```teal
tecs.math.noise.Options.fractal: Fractal
```

<a id="tecs.math.noise.Options.seed"></a>
#### tecs.math.noise.Options.seed <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Selects the repeatable field. Defaults to `0x5EED1234`.


```teal
tecs.math.noise.Options.seed: integer
```

<a id="tecs.math.noise.Options.frequency"></a>
#### tecs.math.noise.Options.frequency <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Scales every coordinate before sampling. Defaults to `0.01`.


```teal
tecs.math.noise.Options.frequency: number
```

<a id="tecs.math.noise.Options.octaves"></a>
#### tecs.math.noise.Options.octaves <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the octave count for a fractal field. Defaults to three.


```teal
tecs.math.noise.Options.octaves: integer
```

<a id="tecs.math.noise.Options.lacunarity"></a>
#### tecs.math.noise.Options.lacunarity <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Multiplies frequency between octaves. Defaults to two.


```teal
tecs.math.noise.Options.lacunarity: number
```

<a id="tecs.math.noise.Options.gain"></a>
#### tecs.math.noise.Options.gain <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Multiplies amplitude between octaves. Defaults to `0.5`.


```teal
tecs.math.noise.Options.gain: number
```

<a id="tecs.math.noise.Options.weightedStrength"></a>
#### tecs.math.noise.Options.weightedStrength <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Lets one octave's value influence the next octave's
amplitude. Defaults to zero and accepts values in `[0, 1]`.


```teal
tecs.math.noise.Options.weightedStrength: number
```

<a id="tecs.math.noise.Options.pingPongStrength"></a>
#### tecs.math.noise.Options.pingPongStrength <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the fold strength for `"pingPong"`. Defaults to two.


```teal
tecs.math.noise.Options.pingPongStrength: number
```