Skip to content

Latest commit

 

History

History
220 lines (167 loc) · 6.7 KB

README.md

File metadata and controls

220 lines (167 loc) · 6.7 KB
Raw

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

  • Additional tweaks to PURE annotations to avoid warnings in rollup.js. Contributed by Damien Seguin.

4.0.2

  • Tweaked PURE annotations to avoid warnings in rollup.js. Contributed by Damien Seguin.

4.0.1

  • Explicitly defined the return type of createNoise4D to be NoiseFunction4D. Contributed by satelllte.

4.0.0

⚠️ This release changes the API and the output of the noise functions. ⚠️

  • Reworked the API so that the noise functions can be imported individually. When combined with tree shaking this helps with build sizes.
  • Removed the built in version of the ALEA PRNG to focus the library to do only one thing. If you want to continue to use it you'll have to install and import it separately.
  • Noise functions are a bit faster (~ 20 - 30%).
  • Noise values can be different from previous versions
  • Input coordinates bigger than 2^31 may not result in a noisy output anymore. If you have a use case that is affected by this change, please file an issue.
  • Test coverage is now at 100%.
  • A big thank you to @mreinstein, @redblobgames and everyone else involved for their comments and PRs which motivated me to create this new version.

3.0.1

  • Include simplex-noise.ts as source file, fixes sourcemap warnings.

3.0.0

  • Changed module structure. When using bundlers that import the es module even using require() the import might need to be updated.
  • Dependency update
  • Setting sideEffects: false in package.json
  • Added snapshot tests
  • Code converted to typescript, the package can of course still be used from regular JS
  • Dropped bower
  • Added support for es modules

2.4.0

  • Included a PRNG based on ALEA to directly allow seeding
  • Included typescript definitions

2.3.0

⚠️ This release changes the output of the noise functions. ⚠️

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

  • Corrected generation of permutation table
  • Moved tests to mocha/chai
  • Cleanup

2.2.0

  • Small performance improvement for 2D noise

2.1.1

  • Increased entropy by fixing a little initialization issue.

2.1.0

  • AMD support

2.0.0

  • Changed node.js api, SimplexNoise is now exported directly.
  • Added unit tests

1.0.0

  • Initial Release

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.