@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/math/Octree.js

@@ -81,19 +81,67 @@ function lineToLineClosestPoints( line1, line2, target1 = null, target2 = null )
 
 }
 
+/**
+ * An octree is a hierarchical tree data structure used to partition a three-dimensional
+ * space by recursively subdividing it into eight octants.
+ *
+ * This particular implementation can have up to sixteen levels and stores up to eight triangles
+ * in leaf nodes.
+ *
+ * `Octree` can be used in games to compute collision between the game world and colliders from
+ * the player or other dynamic 3D objects.
+ *
+ *
+ * ```js
+ * const octree = new Octree().fromGraphNode( scene );
+ * const result = octree.capsuleIntersect( playerCollider ); // collision detection
+ * ```
+ */
 class Octree {
 
+	/**
+	 * Constructs a new Octree.
+	 *
+	 * @param {Box3} [box] - The base box with enclose the entire Octree.
+	 */
 	constructor( box ) {
 
+		/**
+		 * The base box with enclose the entire Octree.
+		 *
+		 * @type {Box3}
+		 */
 		this.box = box;
+
+		/**
+		 * The bounds of the Octree. Compared to {@link Octree#box}, no
+		 * margin is applied.
+		 *
+		 * @type {Box3}
+		 */
 		this.bounds = new Box3();
 
+		/**
+		 * Can by used for layers configuration for refine testing.
+		 *
+		 * @type {Layers}
+		 */
+		this.layers = new Layers();
+
+		// private
+
 		this.subTrees = [];
 		this.triangles = [];
-		this.layers = new Layers();
 
 	}
 
+	/**
+	 * Adds the given triangle to the Octree. The triangle vertices are clamped if they exceed
+	 * the bounds of the Octree.
+	 *
+	 * @param {Triangle} triangle - The triangle to add.
+	 * @return {Octree} A reference to this Octree.
+	 */
 	addTriangle( triangle ) {
 
 		this.bounds.min.x = Math.min( this.bounds.min.x, triangle.a.x, triangle.b.x, triangle.c.x );
@@ -109,6 +157,11 @@ class Octree {
 
 	}
 
+	/**
+	 * Prepares {@link Octree#box} for the build.
+	 *
+	 * @return {Octree} A reference to this Octree.
+	 */
 	calcBox() {
 
 		this.box = this.bounds.clone();
@@ -122,6 +175,13 @@ class Octree {
 
 	}
 
+	/**
+	 * Splits the Octree. This method is used recursively when
+	 * building the Octree.
+	 *
+	 * @param {number} level - The current level.
+	 * @return {Octree} A reference to this Octree.
+	 */
 	split( level ) {
 
 		if ( ! this.box ) return;
@@ -187,6 +247,11 @@ class Octree {
 
 	}
 
+	/**
+	 * Builds the Octree.
+	 *
+	 * @return {Octree} A reference to this Octree.
+	 */
 	build() {
 
 		this.calcBox();
@@ -196,6 +261,12 @@ class Octree {
 
 	}
 
+	/**
+	 * Computes the triangles that potentially intersect with the given ray.
+	 *
+	 * @param {Ray} ray - The ray to test.
+	 * @param {Array<Triangle>} triangles - The target array that holds the triangles.
+	 */
 	getRayTriangles( ray, triangles ) {
 
 		for ( let i = 0; i < this.subTrees.length; i ++ ) {
@@ -219,10 +290,16 @@ class Octree {
 
 		}
 
-		return triangles;
-
 	}
 
+	/**
+	 * Computes the intersection between the given capsule and triangle.
+	 *
+	 * @param {Capsule} capsule - The capsule to test.
+	 * @param {Triangle} triangle - The triangle to test.
+	 * @return {Object|false} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	triangleCapsuleIntersect( capsule, triangle ) {
 
 		triangle.getPlane( _plane );
@@ -277,6 +354,14 @@ class Octree {
 
 	}
 
+	/**
+	 * Computes the intersection between the given sphere and triangle.
+	 *
+	 * @param {Sphere} sphere - The sphere to test.
+	 * @param {Triangle} triangle - The triangle to test.
+	 * @return {Object|false} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	triangleSphereIntersect( sphere, triangle ) {
 
 		triangle.getPlane( _plane );
@@ -319,6 +404,12 @@ class Octree {
 
 	}
 
+	/**
+	 * Computes the triangles that potentially intersect with the given bounding sphere.
+	 *
+	 * @param {Sphere} sphere - The sphere to test.
+	 * @param {Array<Triangle>} triangles - The target array that holds the triangles.
+	 */
 	getSphereTriangles( sphere, triangles ) {
 
 		for ( let i = 0; i < this.subTrees.length; i ++ ) {
@@ -345,6 +436,12 @@ class Octree {
 
 	}
 
+	/**
+	 * Computes the triangles that potentially intersect with the given capsule.
+	 *
+	 * @param {Capsule} capsule - The capsule to test.
+	 * @param {Array<Triangle>} triangles - The target array that holds the triangles.
+	 */
 	getCapsuleTriangles( capsule, triangles ) {
 
 		for ( let i = 0; i < this.subTrees.length; i ++ ) {
@@ -371,6 +468,13 @@ class Octree {
 
 	}
 
+	/**
+	 * Performs a bounding sphere intersection test with this Octree.
+	 *
+	 * @param {Sphere} sphere - The bounding sphere to test.
+	 * @return {Object|boolean} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	sphereIntersect( sphere ) {
 
 		_sphere.copy( sphere );
@@ -405,6 +509,13 @@ class Octree {
 
 	}
 
+	/**
+	 * Performs a capsule intersection test with this Octree.
+	 *
+	 * @param {Capsule} capsule - The capsule to test.
+	 * @return {Object|boolean} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	capsuleIntersect( capsule ) {
 
 		_capsule.copy( capsule );
@@ -439,10 +550,15 @@ class Octree {
 
 	}
 
+	/**
+	 * Performs a ray intersection test with this Octree.
+	 *
+	 * @param {Ray} ray - The ray to test.
+	 * @return {Object|boolean} The nearest intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	rayIntersect( ray ) {
 
-		if ( ray.direction.length() === 0 ) return;
-
 		const triangles = [];
 		let triangle, position, distance = 1e100;
 
@@ -472,6 +588,12 @@ class Octree {
 
 	}
 
+	/**
+	 * Constructs the Octree from the given 3D object.
+	 *
+	 * @param {Object3D} group - The scene graph node.
+	 * @return {Octree} A reference to this Octree.
+	 */
 	fromGraphNode( group ) {
 
 		group.updateWorldMatrix( true, true );
@@ -529,6 +651,11 @@ class Octree {
 
 	}
 
+	/**
+	 * Clears the Octree by making it empty.
+	 *
+	 * @return {Octree} A reference to this Octree.
+	 */
 	clear() {
 
 		this.box = null;

package/examples/jsm/math/SimplexNoise.js

@@ -1,17 +1,17 @@
-// Ported from Stefan Gustavson's java implementation
-// http://staffwww.itn.liu.se/~stegu/simplexnoise/simplexnoise.pdf
-// Read Stefan's excellent paper for details on how this code works.
-//
-// Sean McCullough banksean@gmail.com
-//
-// Added 4D noise
-
 /**
- * You can pass in a random number generator object if you like.
- * It is assumed to have a random() method.
+ * A utility class providing noise functions.
+ *
+ * The code is based on [Simplex noise demystified]{@link https://web.archive.org/web/20210210162332/http://staffwww.itn.liu.se/~stegu/simplexnoise/simplexnoise.pdf}
+ * by Stefan Gustavson, 2005.
  */
 class SimplexNoise {
 
+	/**
+	 * Constructs a new simplex noise object.
+	 *
+	 * @param {Object} [r=Math] - A math utility class that holds a `random()` method. This makes it
+	 * possible to pass in custom random number generator.
+	 */
 	constructor( r = Math ) {
 
 		this.grad3 = [[ 1, 1, 0 ], [ - 1, 1, 0 ], [ 1, - 1, 0 ], [ - 1, - 1, 0 ],
@@ -58,24 +58,13 @@ class SimplexNoise {
 
 	}
 
-	dot( g, x, y ) {
-
-		return g[ 0 ] * x + g[ 1 ] * y;
-
-	}
-
-	dot3( g, x, y, z ) {
-
-		return g[ 0 ] * x + g[ 1 ] * y + g[ 2 ] * z;
-
-	}
-
-	dot4( g, x, y, z, w ) {
-
-		return g[ 0 ] * x + g[ 1 ] * y + g[ 2 ] * z + g[ 3 ] * w;
-
-	}
-
+	/**
+	 * A 2D simplex noise method.
+	 *
+	 * @param {number} xin - The x coordinate.
+	 * @param {number} yin - The y coordinate.
+	 * @return {number} The noise value.
+	 */
 	noise( xin, yin ) {
 
 		let n0; // Noise contributions from the three corners
@@ -129,7 +118,7 @@ class SimplexNoise {
 		else {
 
 			t0 *= t0;
-			n0 = t0 * t0 * this.dot( this.grad3[ gi0 ], x0, y0 ); // (x,y) of grad3 used for 2D gradient
+			n0 = t0 * t0 * this._dot( this.grad3[ gi0 ], x0, y0 ); // (x,y) of grad3 used for 2D gradient
 
 		}
 
@@ -138,7 +127,7 @@ class SimplexNoise {
 		else {
 
 			t1 *= t1;
-			n1 = t1 * t1 * this.dot( this.grad3[ gi1 ], x1, y1 );
+			n1 = t1 * t1 * this._dot( this.grad3[ gi1 ], x1, y1 );
 
 		}
 
@@ -147,7 +136,7 @@ class SimplexNoise {
 		else {
 
 			t2 *= t2;
-			n2 = t2 * t2 * this.dot( this.grad3[ gi2 ], x2, y2 );
+			n2 = t2 * t2 * this._dot( this.grad3[ gi2 ], x2, y2 );
 
 		}
 
@@ -157,7 +146,14 @@ class SimplexNoise {
 
 	}
 
-	// 3D simplex noise
+	/**
+	 * A 3D simplex noise method.
+	 *
+	 * @param {number} xin - The x coordinate.
+	 * @param {number} yin - The y coordinate.
+	 * @param {number} zin - The z coordinate.
+	 * @return {number} The noise value.
+	 */
 	noise3d( xin, yin, zin ) {
 
 		let n0; // Noise contributions from the four corners
@@ -257,7 +253,7 @@ class SimplexNoise {
 		else {
 
 			t0 *= t0;
-			n0 = t0 * t0 * this.dot3( this.grad3[ gi0 ], x0, y0, z0 );
+			n0 = t0 * t0 * this._dot3( this.grad3[ gi0 ], x0, y0, z0 );
 
 		}
 
@@ -266,7 +262,7 @@ class SimplexNoise {
 		else {
 
 			t1 *= t1;
-			n1 = t1 * t1 * this.dot3( this.grad3[ gi1 ], x1, y1, z1 );
+			n1 = t1 * t1 * this._dot3( this.grad3[ gi1 ], x1, y1, z1 );
 
 		}
 
@@ -275,7 +271,7 @@ class SimplexNoise {
 		else {
 
 			t2 *= t2;
-			n2 = t2 * t2 * this.dot3( this.grad3[ gi2 ], x2, y2, z2 );
+			n2 = t2 * t2 * this._dot3( this.grad3[ gi2 ], x2, y2, z2 );
 
 		}
 
@@ -284,7 +280,7 @@ class SimplexNoise {
 		else {
 
 			t3 *= t3;
-			n3 = t3 * t3 * this.dot3( this.grad3[ gi3 ], x3, y3, z3 );
+			n3 = t3 * t3 * this._dot3( this.grad3[ gi3 ], x3, y3, z3 );
 
 		}
 
@@ -294,7 +290,15 @@ class SimplexNoise {
 
 	}
 
-	// 4D simplex noise
+	/**
+	 * A 4D simplex noise method.
+	 *
+	 * @param {number} x - The x coordinate.
+	 * @param {number} y - The y coordinate.
+	 * @param {number} z - The z coordinate.
+	 * @param {number} w - The w coordinate.
+	 * @return {number} The noise value.
+	 */
 	noise4d( x, y, z, w ) {
 
 		// For faster and easier lookups
@@ -394,7 +398,7 @@ class SimplexNoise {
 		else {
 
 			t0 *= t0;
-			n0 = t0 * t0 * this.dot4( grad4[ gi0 ], x0, y0, z0, w0 );
+			n0 = t0 * t0 * this._dot4( grad4[ gi0 ], x0, y0, z0, w0 );
 
 		}
 
@@ -403,7 +407,7 @@ class SimplexNoise {
 		else {
 
 			t1 *= t1;
-			n1 = t1 * t1 * this.dot4( grad4[ gi1 ], x1, y1, z1, w1 );
+			n1 = t1 * t1 * this._dot4( grad4[ gi1 ], x1, y1, z1, w1 );
 
 		}
 
@@ -412,7 +416,7 @@ class SimplexNoise {
 		else {
 
 			t2 *= t2;
-			n2 = t2 * t2 * this.dot4( grad4[ gi2 ], x2, y2, z2, w2 );
+			n2 = t2 * t2 * this._dot4( grad4[ gi2 ], x2, y2, z2, w2 );
 
 		}
 
@@ -421,7 +425,7 @@ class SimplexNoise {
 		else {
 
 			t3 *= t3;
-			n3 = t3 * t3 * this.dot4( grad4[ gi3 ], x3, y3, z3, w3 );
+			n3 = t3 * t3 * this._dot4( grad4[ gi3 ], x3, y3, z3, w3 );
 
 		}
 
@@ -430,7 +434,7 @@ class SimplexNoise {
 		else {
 
 			t4 *= t4;
-			n4 = t4 * t4 * this.dot4( grad4[ gi4 ], x4, y4, z4, w4 );
+			n4 = t4 * t4 * this._dot4( grad4[ gi4 ], x4, y4, z4, w4 );
 
 		}
 
@@ -439,6 +443,26 @@ class SimplexNoise {
 
 	}
 
+	// private
+
+	_dot( g, x, y ) {
+
+		return g[ 0 ] * x + g[ 1 ] * y;
+
+	}
+
+	_dot3( g, x, y, z ) {
+
+		return g[ 0 ] * x + g[ 1 ] * y + g[ 2 ] * z;
+
+	}
+
+	_dot4( g, x, y, z, w ) {
+
+		return g[ 0 ] * x + g[ 1 ] * y + g[ 2 ] * z + g[ 3 ] * w;
+
+	}
+
 }
 
 export { SimplexNoise };

package/examples/jsm/misc/ConvexObjectBreaker.js

@@ -6,39 +6,33 @@ import {
 } from 'three';
 import { ConvexGeometry } from '../geometries/ConvexGeometry.js';
 
+const _v1 = new Vector3();
+
 /**
- * @fileoverview This class can be used to subdivide a convex Geometry object into pieces.
- *
- * Usage:
+ * This class can be used to subdivide a convex Geometry object into pieces.
  *
  * Use the function prepareBreakableObject to prepare a Mesh object to be broken.
- *
- * Then, call the various functions to subdivide the object (subdivideByImpact, cutByPlane)
- *
+ * Then, call the various functions to subdivide the object (subdivideByImpact, cutByPlane).
  * Sub-objects that are product of subdivision don't need prepareBreakableObject to be called on them.
  *
  * Requisites for the object:
- *
- *  - Mesh object must have a buffer geometry and a material
- *
- *  - Vertex normals must be planar (not smoothed)
- *
- *  - The geometry must be convex (this is not checked in the library). You can create convex
- *  geometries with ConvexGeometry. The BoxGeometry, SphereGeometry and other convex primitives
- *  can also be used.
+ * - Mesh object must have a buffer geometry and a material.
+ * - Vertex normals must be planar (not smoothed).
+ * - The geometry must be convex (this is not checked in the library). You can create convex
+ * geometries with {@link ConvexGeometry}. The {@link BoxGeometry}, {@link SphereGeometry} and other
+ * convex primitives can also be used.
  *
  * Note: This lib adds member variables to object's userData member (see prepareBreakableObject function)
  * Use with caution and read the code when using with other libs.
- *
- * @param {double} minSizeForBreak Min size a debris can have to break.
- * @param {double} smallDelta Max distance to consider that a point belongs to a plane.
- *
 */
-
-const _v1 = new Vector3();
-
 class ConvexObjectBreaker {
 
+	/**
+	 * Constructs a new convex object breaker.
+	 *
+	 * @param {number} [minSizeForBreak=1.4] - Min size a debris can have to break.
+ 	 * @param {number} [smallDelta=0.0001] - Max distance to consider that a point belongs to a plane.
+	 */
 	constructor( minSizeForBreak = 1.4, smallDelta = 0.0001 ) {
 
 		this.minSizeForBreak = minSizeForBreak;
@@ -68,6 +62,15 @@ class ConvexObjectBreaker {
 
 	}
 
+	/**
+	 * Must be called for all 3D objects that should be breakable.
+	 *
+	 * @param {Object3D} object - The 3D object. It must have a convex geometry.
+	 * @param {number} mass - The 3D object's mass in kg. Must be greater than `0`.
+	 * @param {Vector3} velocity - The 3D object's velocity.
+	 * @param {Vector3} angularVelocity - The 3D object's angular velocity.
+	 * @param {boolean} breakable - Whether the 3D object is breakable or not.
+	 */
 	prepareBreakableObject( object, mass, velocity, angularVelocity, breakable ) {
 
 		// object is a Object3d (normally a Mesh), must have a buffer geometry, and it must be convex.
@@ -82,11 +85,16 @@ class ConvexObjectBreaker {
 
 	}
 
-	/*
-	 * @param {int} maxRadialIterations Iterations for radial cuts.
-	 * @param {int} maxRandomIterations Max random iterations for not-radial cuts
+	/**
+	 * Subdivides the given 3D object into pieces by an impact (meaning another object hits
+	 * the given 3D object at a certain surface point).
 	 *
-	 * Returns the array of pieces
+	 * @param {Object3D} object - The 3D object to subdivide.
+	 * @param {Vector3} pointOfImpact - The point of impact.
+	 * @param {Vector3} normal - The impact normal.
+	 * @param {number} maxRadialIterations - Iterations for radial cuts.
+	 * @param {number} maxRandomIterations - Max random iterations for not-radial cuts.
+	 * @return {Array<Object3D>} The array of pieces.
 	 */
 	subdivideByImpact( object, pointOfImpact, normal, maxRadialIterations, maxRandomIterations ) {
 
@@ -168,6 +176,14 @@ class ConvexObjectBreaker {
 
 	}
 
+	/**
+	 * Subdivides the given 3D object into pieces by a plane.
+	 *
+	 * @param {Object3D} object - The 3D object to subdivide.
+	 * @param {Plane} plane - The plane to cut the 3D object.
+	 * @param {{object1:?Mesh,object2:?Mesh}} output - An object that stores the pieces.
+	 * @return {number} The number of pieces.
+	 */
 	cutByPlane( object, plane, output ) {
 
 		// Returns breakable objects in output.object1 and output.object2 members, the resulting 2 pieces of the cut.
@@ -449,6 +465,8 @@ class ConvexObjectBreaker {
 
 	}
 
+	// internal helpers
+
 	static transformFreeVector( v, m ) {
 
 		// input: