search

jwagner / simplex-noise.js

A fast simplex noise implementation in Javascript / Typescript.
MIT License
1.61k stars 130 forks source link
demo gfx javascript nodejs noise-functions procedural procedural-art procedural-generation procedural-terrain procedural-textures simplex typescript

readme

Tests TypeScript

simplex-noise.js header API Documentation

simplex-noise.js is a simplex noise implementation in Javascript/TypeScript. It works in the browser and Node.js, using CommonJS and ES Modules. It is self-contained (dependency-free), relatively small (about 2k minified and gzipped) and fairly fast (about 20 nanoseconds for a sample of 2d noise) and tree shakeable.

Demos & Real World Examples

Created something awesome with simplex-noise? Let me know so I can add it to the list.

Installation

npm i -S simplex-noise

Usage Examples

ES Module Import

// import the noise functions you need
import { createNoise2D } from 'simplex-noise';

CommonJS Require

// import the noise functions you need
const { createNoise2D } = require('simplex-noise');

2D

// initialize the noise function
const noise2D = createNoise2D();
// returns a value between -1 and 1
console.log(noise2D(x, y));

3D

const noise3D = createNoise3D();
console.log(noise3D(x, y, z));

4D

const noise4D = createNoise4D();
console.log(noise4D(x, y, z, w));

Using a seed value

By default simplex-noise.js will use Math.random() to seed the noise. You can pass in a PRNG function to use your own seed value.

# install the alea prng
npm install -S alea
import alea from 'alea';
// create a new random function based on the seed
const prng = alea('seed');
// use the seeded random function to initialize the noise function
const noise2D = createNoise2D(prng);
console.log(noise2D(x, y));

The ALEA PRNG used in the example above can be found in the alea npm package.

Benchmarks

simplex-noise.js is reasonably quick. According to perf/index.js I can perform about 70 million noise2D() calls/second on a single thread on my desktop (Ryzen 5950X).

$ node perf/index.js
noise2D: 72,916,215 ops/sec ±1%
noise3D: 47,855,199 ops/sec ±0%
noise4D: 35,564,111 ops/sec ±0%

Migrating from 3.x to 4.x

random initialization

// 3.x
import SimplexNoise from 'simplex-noise';
const simplex = new SimplexNoise();
const value2d = simplex.noise2D(x, y);
// 4.x
// import the functions you need
import { createNoise2D } from 'simplex-noise';
const noise2D = createNoise2D();
const value2d = noise2D(x, y);

Initialization with a seed

// 3.x
import SimplexNoise from 'simplex-noise';
const simplex = new SimplexNoise('seed');
const value2d = simplex.noise2D(x, y);
// 4.x
// npm install -S alea
import { createNoise2D } from 'simplex-noise';
import alea from 'alea';
const noise2D = createNoise2D(alea('seed'));
const value2d = noise2D(x, y);

// IMPORTANT: If you use multiple noise functions (for example 2d and 3d)
// and want compatible output with 3.x you will need to pass a fresh instance
// of alea to each create call. If you reuse the alea instance you will
// get different outputs compared to simplex-noise 3.x.
const seed = 'seed';
const noise2D = createNoise2D(alea(seed));
const noise3D = createNoise3D(alea(seed));

Emulating the 3.x and older API

const simplex = {
  noise2D: createNoise2D(alea(seed)),
  noise3D: createNoise3D(alea(seed)),
  noise4D: createNoise4D(alea(seed)),
};

Changelog

4.0.3

4.0.2

4.0.1

4.0.0

:warning: This release changes the API and the output of the noise functions. :warning:

3.0.1

3.0.0

2.4.0

2.3.0

:warning: This release changes the output of the noise functions. :warning:

In the future such changes will be released as a new major version.

2.2.0

2.1.1

2.1.0

2.0.0

1.0.0

License

Copyright (c) 2022 Jonas Wagner, licensed under the MIT License (enclosed)

Credits

This is mostly a direct javascript port of the Java implementation by Stefan Gustavson and Peter Eastman.

The initial typescript definition has been provided by Neonit.