Skip to content

Commit 6ccfd79

Browse files
simon-parissimon-paris
authored
JavaScript: Add typescript annotations (#157)
1 parent 2530bc5 commit 6ccfd79

11 files changed

Lines changed: 2983 additions & 833 deletions

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,5 +40,7 @@ msbuild.wrn
4040

4141
# JS stuff
4242
node_modules
43+
yarn.lock
44+
package-lock.json
4345

4446
emsdk

‎JavaScript/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
test-output.png

‎JavaScript/README.md‎

Lines changed: 53 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -21,27 +21,32 @@ FastNoise Lite is an extremely portable open source noise generation library wit
2121

2222
### Using FastNoise Lite with npm
2323

24-
To begin install the npm package **fastnoise-lite** with
24+
To begin install the npm package **fastnoise-lite**.
2525

26+
```sh
27+
npm install fastnoise-lite
28+
```
2629

27-
Note FastNoise Lite does **not** support the node.js require(''); function.
28-
Instead, enable ES6 modules and **import**.
30+
And import as follows:
2931

30-
```javascript
32+
```typescript
33+
// using ESM
3134
import FastNoiseLite from "fastnoise-lite";
35+
// using CJS
36+
const FastNoiseLite = require("fastnoise-lite").default;
3237

3338
let noise = new FastNoiseLite();
3439
```
3540

3641
### Creating a 128x128 Array of OpenSimplex2 Noise
3742

38-
```javascript
43+
```typescript
3944
// Create and configure FastNoiseLite object
4045
let noise = new FastNoiseLite();
4146
noise.SetNoiseType(FastNoiseLite.NoiseType.OpenSimplex2);
4247

4348
// Gather noise data
44-
let noiseData = [];
49+
let noiseData: number[][] = [];
4550

4651
for (let x = 0; x < 128; x++) {
4752
noiseData[x] = [];
@@ -54,6 +59,24 @@ for (let x = 0; x < 128; x++) {
5459
// Do something with this data...
5560
```
5661

62+
### BYO Vector2 / Vector3 classes
63+
64+
The DomainWarp method takes in a `Vector2 | Vector3` object, which is any object with x, y or x, y, z properties.
65+
66+
Use your own Vector class from any math library (e.g. three.js), or a plain object. Anything with x, y, and optionally z properties will work. Vectors are treated as 3D if their `z` property is defined.
67+
```typescript
68+
let noise = new FastNoiseLite();
69+
noise.SetDomainWarpType(FastNoiseLite.DomainWarpType.OpenSimplex2);
70+
noise.SetDomainWarpAmp(1.5);
71+
72+
let vec1 = new THREE.Vector2(1, 2);
73+
noise.DomainWarp(vec1);
74+
75+
let vec2 = {x: 1, y: 2};
76+
noise.DomainWarp(vec2);
77+
```
78+
79+
5780
### Internal Method Overloading
5881

5982
Since JavaScript does not support method overloading it has been simulated to make the user experience more continuous
@@ -64,30 +87,43 @@ frequently used places eg the _Hash methods.
6487

6588
Here is a template for the method overloading:
6689

67-
```javascript
90+
```typescript
6891
class FastNoiseLite {
6992
/**
7093
* JSdoc
7194
*/
72-
Method() {
73-
let R2 = (Param1, Param2) => {
95+
Method(coord: Vector2 | Vector3) {
96+
let R2 = (coord: Vector2) => {
7497
// do something 2D
7598
}
7699

77-
let R3 = (Param1, Param2, Param3) => {
100+
let R3 = (coord: Vector3) => {
78101
// do something 3D
79102
}
80103

81-
if (arguments.lenght === 2) {
82-
return R2(arguments[0], arguments[1]);
83-
}
84-
85-
if (arguments.length === 3) {
86-
return R3(arguments[0], arguments[1], arguments[2])
104+
if ((coord as any).z === undefined) {
105+
return R2(coord as Vector2);
106+
} else {
107+
return R3(coord as Vector3);
87108
}
88109
}
89110

90111
}
91112
```
92113

93-
### DM dev_storm on discord or email w/ any questions or need any support or ask someone in our discord :D
114+
## Testing
115+
116+
A test suite is included. It also generates a collection of noise images. Compare the test image on your branch with one generated on master.
117+
118+
(Requires node version 22.6+)
119+
120+
```sh
121+
npm install
122+
npm run test # runs tests and also outputs test-output.png
123+
```
124+
125+
## Build
126+
127+
Run `npm run build` to build .js and .d.ts files.
128+
129+
Build output should be committed.

‎JavaScript/dist/FastNoiseLite.d.ts‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
export declare enum NoiseType {
2+
OpenSimplex2 = 1,
3+
OpenSimplex2S = 2,
4+
Cellular = 3,
5+
Perlin = 4,
6+
ValueCubic = 5,
7+
Value = 6
8+
}
9+
export declare enum RotationType3D {
10+
None = 0,
11+
ImproveXYPlanes = 1,
12+
ImproveXZPlanes = 2
13+
}
14+
export declare enum FractalType {
15+
None = 0,
16+
FBm = 1,
17+
Ridged = 2,
18+
PingPong = 3,
19+
DomainWarpProgressive = 4,
20+
DomainWarpIndependent = 5
21+
}
22+
export declare enum CellularDistanceFunction {
23+
Euclidean = 1,
24+
EuclideanSq = 2,
25+
Manhattan = 3,
26+
Hybrid = 4
27+
}
28+
export declare enum CellularReturnType {
29+
CellValue = 1,
30+
Distance = 2,
31+
Distance2 = 3,
32+
Distance2Add = 4,
33+
Distance2Sub = 5,
34+
Distance2Mul = 6,
35+
Distance2Div = 7
36+
}
37+
export declare enum DomainWarpType {
38+
OpenSimplex2 = 1,
39+
OpenSimplex2Reduced = 2,
40+
BasicGrid = 3
41+
}
42+
export declare enum TransformType3D {
43+
None = 0,
44+
ImproveXYPlanes = 1,
45+
ImproveXZPlanes = 2,
46+
DefaultOpenSimplex2 = 3
47+
}
48+
export interface Vector2 {
49+
x: number;
50+
y: number;
51+
}
52+
export interface Vector3 {
53+
x: number;
54+
y: number;
55+
z: number;
56+
}
57+
/**
58+
* @description FastNoise Lite is an extremely portable open source noise generation library with a large selection of noise algorithms
59+
* @author Jordan Peck, snowfoxsh
60+
* @version 1.1.1
61+
* @copyright Copyright(c) 2023 Jordan Peck, Contributors
62+
* @license MIT
63+
* @git https://github.com/Auburn/FastNoiseLite
64+
* @npm https://www.npmjs.com/package/fastnoise-lite
65+
* @example
66+
// Import from npm (if you used npm)
67+
68+
import FastNoiseLite from "fastnoise-lite";
69+
70+
// Create and configure FastNoiseLite object
71+
72+
let noise = new FastNoiseLite();
73+
noise.SetNoiseType(FastNoiseLite.NoiseType.OpenSimplex2);
74+
75+
// Gather noise data
76+
let noiseData = [];
77+
78+
for (let x = 0; x < 128; x++) {
79+
noiseData[x] = [];
80+
81+
for (let y = 0; y < 128; y++) {
82+
noiseData[x][y] = noise.GetNoise(x,y);
83+
}
84+
}
85+
86+
// Do something with this data...
87+
*/
88+
export default class FastNoiseLite {
89+
static NoiseType: typeof NoiseType;
90+
static RotationType3D: typeof RotationType3D;
91+
static FractalType: typeof FractalType;
92+
static CellularDistanceFunction: typeof CellularDistanceFunction;
93+
static CellularReturnType: typeof CellularReturnType;
94+
static DomainWarpType: typeof DomainWarpType;
95+
static TransformType3D: typeof TransformType3D;
96+
private _Seed;
97+
private _Frequency;
98+
private _NoiseType;
99+
private _RotationType3D;
100+
private _TransformType3D;
101+
private _DomainWarpAmp;
102+
private _FractalType;
103+
private _Octaves;
104+
private _Lacunarity;
105+
private _Gain;
106+
private _WeightedStrength;
107+
private _PingPongStrength;
108+
private _FractalBounding;
109+
private _CellularDistanceFunction;
110+
private _CellularReturnType;
111+
private _CellularJitterModifier;
112+
private _DomainWarpType;
113+
private _WarpTransformType3D;
114+
/**
115+
* @description Create new FastNoiseLite object with optional seed
116+
*/
117+
constructor(seed?: number);
118+
/**
119+
* @description Sets seed used for all noise types
120+
* @remarks Default: 1337
121+
*/
122+
SetSeed(seed: number): void;
123+
/**
124+
* @description Sets frequency for all noise types
125+
* @remarks Default: 0.01
126+
*/
127+
SetFrequency(frequency: number): void;
128+
/**
129+
* @description Sets noise algorithm used for GetNoise(...)
130+
* @remarks Default: OpenSimplex2
131+
*/
132+
SetNoiseType(noiseType: NoiseType): void;
133+
/**
134+
* @description Sets domain rotation type for 3D Noise and 3D DomainWarp.
135+
* @description Can aid in reducing directional artifacts when sampling a 2D plane in 3D
136+
* @remarks Default: None
137+
*/
138+
SetRotationType3D(rotationType3D: RotationType3D): void;
139+
/**
140+
* @description Sets method for combining octaves in all fractal noise types
141+
* @remarks Default: None
142+
*/
143+
SetFractalType(fractalType: FractalType): void;
144+
/**
145+
* @description Sets octave count for all fractal noise types
146+
* @remarks Default: 3
147+
*/
148+
SetFractalOctaves(octaves: number): void;
149+
/**
150+
* @description Sets octave lacunarity for all fractal noise types
151+
* @remarks Default: 2.0
152+
*/
153+
SetFractalLacunarity(lacunarity: number): void;
154+
/**
155+
* @description Sets octave gain for all fractal noise types
156+
* @remarks Default: 0.5
157+
*/
158+
SetFractalGain(gain: number): void;
159+
/**
160+
* @description Sets octave weighting for all none DomainWarp fratal types
161+
* @remarks Default: 0.0 | Keep between 0...1 to maintain -1...1 output bounding
162+
*/
163+
SetFractalWeightedStrength(weightedStrength: number): void;
164+
/**
165+
* @description Sets strength of the fractal ping pong effect
166+
* @remarks Default: 2.0
167+
*/
168+
SetFractalPingPongStrength(pingPongStrength: number): void;
169+
/**
170+
* @description Sets distance function used in cellular noise calculations
171+
* @remarks Default: EuclideanSq
172+
*/
173+
SetCellularDistanceFunction(cellularDistanceFunction: CellularDistanceFunction): void;
174+
/**
175+
* @description Sets return type from cellular noise calculations
176+
* @remarks Default: Distance
177+
*/
178+
SetCellularReturnType(cellularReturnType: CellularReturnType): void;
179+
/**
180+
* @description Sets the maximum distance a cellular point can move from it's grid position
181+
* @remarks Default: 1.0
182+
*/
183+
SetCellularJitter(cellularJitter: number): void;
184+
/**
185+
* @description Sets the warp algorithm when using DomainWarp(...)
186+
* @remarks Default: OpenSimplex2
187+
*/
188+
SetDomainWarpType(domainWarpType: DomainWarpType): void;
189+
/**
190+
* @description Sets the maximum warp distance from original position when using DomainWarp(...)
191+
* @remarks Default: 1.0
192+
*/
193+
SetDomainWarpAmp(domainWarpAmp: number): void;
194+
/**
195+
* @description 2D/3D noise at given position using current settings
196+
* @return Noise output bounded between -1...1
197+
*/
198+
GetNoise(x: number, y: number, z?: number): number;
199+
/**
200+
* @description 2D/3D warps the input position using current domain warp settings
201+
*/
202+
DomainWarp(coord: Vector2 | Vector3): void;
203+
private _Gradients2D;
204+
private _RandVecs2D;
205+
private _Gradients3D;
206+
private _RandVecs3D;
207+
private _PrimeX;
208+
private _PrimeY;
209+
private _PrimeZ;
210+
private static _Lerp;
211+
private static _InterpHermite;
212+
private static _InterpQuintic;
213+
private static _CubicLerp;
214+
private static _PingPong;
215+
private _CalculateFractalBounding;
216+
private _HashR2;
217+
private _HashR3;
218+
private _ValCoordR2;
219+
private _ValCoordR3;
220+
private _GradCoordR2;
221+
private _GradCoordR3;
222+
private _GenNoiseSingleR2;
223+
private _GenNoiseSingleR3;
224+
private _UpdateTransformType3D;
225+
private _UpdateWarpTransformType3D;
226+
private _GenFractalFBmR2;
227+
private _GenFractalFBmR3;
228+
private _GenFractalRidgedR2;
229+
private _GenFractalRidgedR3;
230+
private _GenFractalPingPongR2;
231+
private _GenFractalPingPongR3;
232+
private _SingleOpenSimplex2R2;
233+
private _SingleOpenSimplex2R3;
234+
private _SingleOpenSimplex2SR2;
235+
private _SingleOpenSimplex2SR3;
236+
private _SingleCellularR2;
237+
private _SingleCellularR3;
238+
private _SinglePerlinR2;
239+
private _SinglePerlinR3;
240+
private _SingleValueCubicR2;
241+
private _SingleValueCubicR3;
242+
private _SingleValueR2;
243+
private _SingleValueR3;
244+
private _DoSingleDomainWarp;
245+
private _DomainWarpSingle;
246+
private _DomainWarpFractalProgressive;
247+
private _DomainWarpFractalIndependent;
248+
private _SingleDomainWarpBasicGrid;
249+
private _SingleDomainWarpOpenSimplex2Gradient;
250+
}

0 commit comments

Comments
 (0)