@needle-tools/three 0.169.20-experimental.0 → 0.183.2-canary.0

package/examples/jsm/objects/Water2.js

@@ -1,5 +1,5 @@
 import {
-	Clock,
+	Timer,
 	Color,
 	Matrix4,
 	Mesh,
@@ -14,19 +14,41 @@ import {
 import { Reflector } from '../objects/Reflector.js';
 import { Refractor } from '../objects/Refractor.js';
 
+/** @module Water2 */
+
 /**
+ * An advanced water effect that supports reflections, refractions and flow maps.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link module:Water2Mesh}.
+ *
  * References:
- *	https://alex.vlachos.com/graphics/Vlachos-SIGGRAPH10-WaterFlow.pdf
- *	http://graphicsrunner.blogspot.de/2010/08/water-using-flow-maps.html
  *
+ * - {@link https://alex.vlachos.com/graphics/Vlachos-SIGGRAPH10-WaterFlow.pdf}
+ * - {@link http://graphicsrunner.blogspot.de/2010/08/water-using-flow-maps.html}
+ *
+ * @augments Mesh
+ * @three_import import { Water } from 'three/addons/objects/Water2.js';
  */
-
 class Water extends Mesh {
 
+	/**
+	 * Constructs a new water instance.
+	 *
+	 * @param {BufferGeometry} geometry - The water's geometry.
+	 * @param {module:Water2~Options} [options] - The configuration options.
+	 */
 	constructor( geometry, options = {} ) {
 
 		super( geometry );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isWater = true;
 
 		this.type = 'Water';
@@ -52,7 +74,7 @@ class Water extends Mesh {
 		const cycle = 0.15; // a cycle of a flow map phase
 		const halfCycle = cycle * 0.5;
 		const textureMatrix = new Matrix4();
-		const clock = new Clock();
+		const timer = new Timer();
 
 		// internal components
 
@@ -132,7 +154,7 @@ class Water extends Mesh {
 		this.material.uniforms[ 'reflectivity' ].value = reflectivity;
 		this.material.uniforms[ 'textureMatrix' ].value = textureMatrix;
 
-		// inital values
+		// initial values
 
 		this.material.uniforms[ 'config' ].value.x = 0; // flowMapOffset0
 		this.material.uniforms[ 'config' ].value.y = halfCycle; // flowMapOffset1
@@ -158,7 +180,7 @@ class Water extends Mesh {
 
 		function updateFlow() {
 
-			const delta = clock.getDelta();
+			const delta = timer.getDelta();
 			const config = scope.material.uniforms[ 'config' ];
 
 			config.value.x += flowSpeed * delta; // flowMapOffset0
@@ -185,6 +207,8 @@ class Water extends Mesh {
 
 		this.onBeforeRender = function ( renderer, scene, camera ) {
 
+			timer.update();
+
 			updateTextureMatrix( camera );
 			updateFlow();
 
@@ -358,4 +382,22 @@ Water.WaterShader = {
 
 };
 
+/**
+ * Constructor options of `Water`.
+ *
+ * @typedef {Object} module:Water2~Options
+ * @property {number|Color|string} [color=0xFFFFFF] - The water color.
+ * @property {number} [textureWidth=512] - The texture width. A higher value results in better quality but is also more expensive.
+ * @property {number} [textureHeight=512] - The texture height. A higher value results in better quality but is also more expensive.
+ * @property {number} [clipBias=0] - The clip bias.
+ * @property {Vector2} [flowDirection=(1,0)] - The water's flow direction.
+ * @property {number} [flowSpeed=0.03] - The water's flow speed.
+ * @property {number} [reflectivity=0.02] - The water's reflectivity.
+ * @property {number} [scale=1] - The water's scale.
+ * @property {Object} [shader] - A custom water shader.
+ * @property {?Texture} [flowMap=null] - The flow map. If no flow map is assigned, the water flow is defined by `flowDirection`.
+ * @property {?Texture} [normalMap0] - The first water normal map.
+ * @property {?Texture} [normalMap1] -  The second water normal map.
+ **/
+
 export { Water };

package/examples/jsm/objects/Water2Mesh.js

@@ -2,28 +2,55 @@ import {
 	Color,
 	Mesh,
 	Vector2,
-	Vector3
-} from 'three';
-import { Fn, NodeMaterial, NodeUpdateType, TempNode, vec2, viewportSafeUV, viewportSharedTexture, reflector, pow, float, abs, texture, uniform, vec4, cameraPosition, positionWorld, uv, mix, vec3, normalize, max, dot, screenUV } from 'three/tsl';
+	Vector3,
+	NodeMaterial,
+	NodeUpdateType,
+	TempNode
+} from 'three/webgpu';
+
+import { Fn, vec2, viewportSafeUV, viewportSharedTexture, reflector, pow, float, abs, texture, uniform, vec4, cameraPosition, positionWorld, uv, mix, vec3, normalize, max, dot, screenUV } from 'three/tsl';
+
+/** @module Water2Mesh */
 
 /**
+ * An advanced water effect that supports reflections, refractions and flow maps.
+ *
+ * Note that this class can only be used with {@link WebGPURenderer}.
+ * When using {@link WebGLRenderer}, use {@link module:Water2}.
+ *
  * References:
- *	https://alex.vlachos.com/graphics/Vlachos-SIGGRAPH10-WaterFlow.pdf
- *	http://graphicsrunner.blogspot.de/2010/08/water-using-flow-maps.html
  *
+ * - {@link https://alex.vlachos.com/graphics/Vlachos-SIGGRAPH10-WaterFlow.pdf}
+ * - {@link http://graphicsrunner.blogspot.de/2010/08/water-using-flow-maps.html}
+ *
+ * @augments Mesh
+ * @three_import import { WaterMesh } from 'three/addons/objects/Water2Mesh.js';
  */
-
 class WaterMesh extends Mesh {
 
+	/**
+	 * Constructs a new water mesh.
+	 *
+	 * @param {BufferGeometry} geometry - The water's geometry.
+	 * @param {module:Water2~Options} [options] - The configuration options.
+	 */
 	constructor( geometry, options = {} ) {
 
 		const material = new NodeMaterial();
+		material.transparent = true;
 
 		super( geometry, material );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isWater = true;
 
-		material.fragmentNode = new WaterNode( options, this );
+		material.colorNode = new WaterNode( options, this );
 
 	}
 
@@ -118,8 +145,8 @@ class WaterNode extends TempNode {
 			const normalUv0 = uvs.mul( this.scale ).add( flow.mul( flowMapOffset0 ) );
 			const normalUv1 = uvs.mul( this.scale ).add( flow.mul( flowMapOffset1 ) );
 
-			const normalColor0 = this.normalMap0.uv( normalUv0 );
-			const normalColor1 = this.normalMap1.uv( normalUv1 );
+			const normalColor0 = this.normalMap0.sample( normalUv0 );
+			const normalColor1 = this.normalMap1.sample( normalUv1 );
 
 			// linear interpolate to get the final normal color
 			const flowLerp = abs( halfCycle.sub( flowMapOffset0 ) ).div( halfCycle );
@@ -155,4 +182,18 @@ class WaterNode extends TempNode {
 
 }
 
+/**
+ * Constructor options of `WaterMesh`.
+ *
+ * @typedef {Object} module:Water2Mesh~Options
+ * @property {number|Color|string} [color=0xFFFFFF] - The water color.
+ * @property {Vector2} [flowDirection=(1,0)] - The water's flow direction.
+ * @property {number} [flowSpeed=0.03] - The water's flow speed.
+ * @property {number} [reflectivity=0.02] - The water's reflectivity.
+ * @property {number} [scale=1] - The water's scale.
+ * @property {?Texture} [flowMap=null] - The flow map. If no flow map is assigned, the water flow is defined by `flowDirection`.
+ * @property {Texture} normalMap0 - The first water normal map.
+ * @property {Texture} normalMap1 - The second water normal map.
+ **/
+
 export { WaterMesh };

package/examples/jsm/objects/WaterMesh.js

@@ -1,54 +1,130 @@
 import {
 	Color,
 	Mesh,
-	Vector3
-} from 'three';
-import { Fn, NodeMaterial, add, cameraPosition, div, normalize, positionWorld, sub, timerLocal, texture, vec2, vec3, vec4, max, dot, reflect, pow, length, float, uniform, reflector, mul, mix } from 'three/tsl';
+	Vector3,
+	NodeMaterial
+} from 'three/webgpu';
+
+import { Fn, add, cameraPosition, div, normalize, positionWorld, sub, time, texture, vec2, max, dot, reflect, pow, length, float, uniform, reflector, mul, mix } from 'three/tsl';
 
 /**
- * Work based on :
- * https://github.com/Slayvin: Flat mirror for three.js
- * https://home.adelphi.edu/~stemkoski/ : An implementation of water shader based on the flat mirror
- * http://29a.ch/ && http://29a.ch/slides/2012/webglwater/ : Water shader explanations in WebGL
+ * A basic flat, reflective water effect.
+ *
+ * Note that this class can only be used with {@link WebGPURenderer}.
+ * When using {@link WebGLRenderer}, use {@link Water}.
+ *
+ * References:
+ *
+ * - [Flat mirror for three.js](https://github.com/Slayvin)
+ * - [An implementation of water shader based on the flat mirror](https://home.adelphi.edu/~stemkoski/)
+ * - [Water shader explanations in WebGL](http://29a.ch/slides/2012/webglwater/ )
+ *
+ * @augments Mesh
+ * @three_import import { WaterMesh } from 'three/addons/objects/WaterMesh.js';
  */
-
 class WaterMesh extends Mesh {
 
+	/**
+	 * Constructs a new water mesh.
+	 *
+	 * @param {BufferGeometry} geometry - The water mesh's geometry.
+	 * @param {WaterMesh~Options} [options] - The configuration options.
+	 */
 	constructor( geometry, options ) {
 
 		const material = new NodeMaterial();
 
 		super( geometry, material );
 
-		this.isWater = true;
-
-		this.resolution = options.resolution !== undefined ? options.resolution : 0.5;
-
-		// uniforms
-
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isWaterMesh = true;
+
+		/**
+		 * The effect's resolution scale.
+		 *
+		 * @type {number}
+		 * @default 0.5
+		 */
+		this.resolutionScale = options.resolutionScale !== undefined ? options.resolutionScale : 0.5;
+
+		// Uniforms
+
+		/**
+		 * The water's normal map.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.waterNormals = texture( options.waterNormals );
+
+		/**
+		 * The alpha value.
+		 *
+		 * @type {UniformNode<float>}
+		 * @default 1
+		 */
 		this.alpha = uniform( options.alpha !== undefined ? options.alpha : 1.0 );
+
+		/**
+		 * The size value.
+		 *
+		 * @type {UniformNode<float>}
+		 * @default 1
+		 */
 		this.size = uniform( options.size !== undefined ? options.size : 1.0 );
+
+		/**
+		 * The sun color.
+		 *
+		 * @type {UniformNode<color>}
+		 * @default 0xffffff
+		 */
 		this.sunColor = uniform( new Color( options.sunColor !== undefined ? options.sunColor : 0xffffff ) );
+
+		/**
+		 * The sun direction.
+		 *
+		 * @type {UniformNode<vec3>}
+		 * @default (0.70707,0.70707,0.0)
+		 */
 		this.sunDirection = uniform( options.sunDirection !== undefined ? options.sunDirection : new Vector3( 0.70707, 0.70707, 0.0 ) );
+
+		/**
+		 * The water color.
+		 *
+		 * @type {UniformNode<color>}
+		 * @default 0x7f7f7f
+		 */
 		this.waterColor = uniform( new Color( options.waterColor !== undefined ? options.waterColor : 0x7f7f7f ) );
+
+		/**
+		 * The distortion scale.
+		 *
+		 * @type {UniformNode<float>}
+		 * @default 20
+		 */
 		this.distortionScale = uniform( options.distortionScale !== undefined ? options.distortionScale : 20.0 );
 
 		// TSL
 
-		const timeNode = timerLocal();
-
 		const getNoise = Fn( ( [ uv ] ) => {
 
-			const uv0 = add( div( uv, 103 ), vec2( div( timeNode, 17 ), div( timeNode, 29 ) ) ).toVar();
-			const uv1 = div( uv, 107 ).sub( vec2( div( timeNode, - 19 ), div( timeNode, 31 ) ) ).toVar();
-			const uv2 = add( div( uv, vec2( 8907.0, 9803.0 ) ), vec2( div( timeNode, 101 ), div( timeNode, 97 ) ) ).toVar();
-			const uv3 = sub( div( uv, vec2( 1091.0, 1027.0 ) ), vec2( div( timeNode, 109 ), div( timeNode, - 113 ) ) ).toVar();
+			const offset = time;
+
+			const uv0 = add( div( uv, 103 ), vec2( div( offset, 17 ), div( offset, 29 ) ) ).toVar();
+			const uv1 = div( uv, 107 ).sub( vec2( div( offset, - 19 ), div( offset, 31 ) ) ).toVar();
+			const uv2 = add( div( uv, vec2( 8907.0, 9803.0 ) ), vec2( div( offset, 101 ), div( offset, 97 ) ) ).toVar();
+			const uv3 = sub( div( uv, vec2( 1091.0, 1027.0 ) ), vec2( div( offset, 109 ), div( offset, - 113 ) ) ).toVar();
 
-			const sample0 = this.waterNormals.uv( uv0 );
-			const sample1 = this.waterNormals.uv( uv1 );
-			const sample2 = this.waterNormals.uv( uv2 );
-			const sample3 = this.waterNormals.uv( uv3 );
+			const sample0 = this.waterNormals.sample( uv0 );
+			const sample1 = this.waterNormals.sample( uv1 );
+			const sample2 = this.waterNormals.sample( uv2 );
+			const sample3 = this.waterNormals.sample( uv3 );
 
 			const noise = sample0.add( sample1 ).add( sample2 ).add( sample3 );
 
@@ -56,46 +132,63 @@ class WaterMesh extends Mesh {
 
 		} );
 
-		const fragmentNode = Fn( () => {
+		const noise = getNoise( positionWorld.xz.mul( this.size ) );
+		const surfaceNormal = normalize( noise.xzy.mul( 1.5, 1.0, 1.5 ) );
+
+		const worldToEye = cameraPosition.sub( positionWorld );
+		const eyeDirection = normalize( worldToEye );
+
+		const reflection = normalize( reflect( this.sunDirection.negate(), surfaceNormal ) );
+		const direction = max( 0.0, dot( eyeDirection, reflection ) );
+		const specularLight = pow( direction, 100 ).mul( this.sunColor ).mul( 2.0 );
+		const diffuseLight = max( dot( this.sunDirection, surfaceNormal ), 0.0 ).mul( this.sunColor ).mul( 0.5 );
 
-			const noise = getNoise( positionWorld.xz.mul( this.size ) );
-			const surfaceNormal = normalize( noise.xzy.mul( 1.5, 1.0, 1.5 ) );
+		const distance = length( worldToEye );
 
-			const diffuseLight = vec3( 0 ).toVar();
-			const specularLight = vec3( 0 ).toVar();
+		const distortion = surfaceNormal.xz.mul( float( 0.001 ).add( float( 1.0 ).div( distance ) ) ).mul( this.distortionScale );
 
-			const worldToEye = cameraPosition.sub( positionWorld );
-			const eyeDirection = normalize( worldToEye );
+		// Material
 
-			const reflection = normalize( reflect( this.sunDirection.negate(), surfaceNormal ) );
-			const direction = max( 0.0, dot( eyeDirection, reflection ) );
-			specularLight.addAssign( pow( direction, 100 ).mul( this.sunColor ).mul( 2.0 ) );
-			diffuseLight.addAssign( max( dot( this.sunDirection, surfaceNormal ), 0.0 ).mul( this.sunColor ).mul( 0.5 ) );
+		material.transparent = true;
 
-			const distance = length( worldToEye );
+		material.opacityNode = this.alpha;
 
-			const distortion = surfaceNormal.xy.mul( float( 0.001 ).add( float( 1.0 ).div( distance ) ) ).mul( this.distortionScale );
+		material.receivedShadowPositionNode = positionWorld.add( distortion );
+
+		material.colorNode = Fn( () => {
 
 			const mirrorSampler = reflector();
 			mirrorSampler.uvNode = mirrorSampler.uvNode.add( distortion );
-			mirrorSampler.resolution = this.resolution;
+			mirrorSampler.reflector.resolutionScale = this.resolutionScale;
 
 			this.add( mirrorSampler.target );
 
 			const theta = max( dot( eyeDirection, surfaceNormal ), 0.0 );
-			const rf0 = float( 0.3 );
+			const rf0 = float( 0.02 );
 			const reflectance = mul( pow( float( 1.0 ).sub( theta ), 5.0 ), float( 1.0 ).sub( rf0 ) ).add( rf0 );
 			const scatter = max( 0.0, dot( surfaceNormal, eyeDirection ) ).mul( this.waterColor );
-			const albedo = mix( this.sunColor.mul( diffuseLight ).mul( 0.3 ).add( scatter ), mirrorSampler.rgb.mul( specularLight ).add( mirrorSampler.rgb.mul( 0.9 ) ).add( vec3( 0.1 ) ), reflectance );
+			const albedo = mix( this.sunColor.mul( diffuseLight ).mul( 0.3 ).add( scatter ), mirrorSampler.rgb.add( specularLight ), reflectance );
 
-			return vec4( albedo, this.alpha );
+			return albedo;
 
 		} )();
 
-		material.fragmentNode = fragmentNode;
-
 	}
 
 }
 
+/**
+ * Constructor options of `WaterMesh`.
+ *
+ * @typedef {Object} WaterMesh~Options
+ * @property {number} [resolutionScale=0.5] - The resolution scale.
+ * @property {?Texture} [waterNormals=null] - The water's normal map.
+ * @property {number} [alpha=1] - The alpha value.
+ * @property {number} [size=1] - The size value.
+ * @property {number|Color|string} [sunColor=0xffffff] - The sun color.
+ * @property {Vector3} [sunDirection=(0.70707,0.70707,0.0)] - The sun direction.
+ * @property {number|Color|string} [waterColor=0x7F7F7F] - The water color.
+ * @property {number} [distortionScale=20] - The distortion scale.
+ **/
+
 export { WaterMesh };

package/examples/jsm/physics/AmmoPhysics.js

@@ -1,3 +1,19 @@
+/**
+ * @classdesc Can be used to include Ammo.js as a Physics engine into
+ * `three.js` apps. Make sure to include `ammo.wasm.js` first:
+ * ```
+ * <script src="jsm/libs/ammo.wasm.js"></script>
+ * ```
+ * It is then possible to initialize the API via:
+ * ```js
+ * const physics = await AmmoPhysics();
+ * ```
+ *
+ * @name AmmoPhysics
+ * @class
+ * @hideconstructor
+ * @three_import import { AmmoPhysics } from 'three/addons/physics/AmmoPhysics.js';
+ */
 async function AmmoPhysics() {
 
 	if ( 'Ammo' in window === false ) {
@@ -7,7 +23,7 @@ async function AmmoPhysics() {
 
 	}
 
-	const AmmoLib = await Ammo(); // eslint-disable-line no-undef
+	const AmmoLib = await Ammo();
 
 	const frameRate = 60;
 
@@ -50,6 +66,8 @@ async function AmmoPhysics() {
 
 		}
 
+		console.error( 'AmmoPhysics: Unsupported geometry type:', geometry.type );
+
 		return null;
 
 	}
@@ -67,7 +85,7 @@ async function AmmoPhysics() {
 
 				if ( physics ) {
 
-					addMesh( child, physics.mass );
+					addMesh( child, physics.mass, physics.restitution );
 
 				}
 
@@ -77,7 +95,7 @@ async function AmmoPhysics() {
 
 	}
 
-	function addMesh( mesh, mass = 0 ) {
+	function addMesh( mesh, mass = 0, restitution = 0 ) {
 
 		const shape = getShape( mesh.geometry );
 
@@ -85,11 +103,11 @@ async function AmmoPhysics() {
 
 			if ( mesh.isInstancedMesh ) {
 
-				handleInstancedMesh( mesh, mass, shape );
+				handleInstancedMesh( mesh, shape, mass, restitution );
 
 			} else if ( mesh.isMesh ) {
 
-				handleMesh( mesh, mass, shape );
+				handleMesh( mesh, shape, mass, restitution );
 
 			}
 
@@ -97,7 +115,7 @@ async function AmmoPhysics() {
 
 	}
 
-	function handleMesh( mesh, mass, shape ) {
+	function handleMesh( mesh, shape, mass, restitution ) {
 
 		const position = mesh.position;
 		const quaternion = mesh.quaternion;
@@ -113,6 +131,7 @@ async function AmmoPhysics() {
 		shape.calculateLocalInertia( mass, localInertia );
 
 		const rbInfo = new AmmoLib.btRigidBodyConstructionInfo( mass, motionState, shape, localInertia );
+		rbInfo.set_m_restitution( restitution );
 
 		const body = new AmmoLib.btRigidBody( rbInfo );
 		// body.setFriction( 4 );
@@ -128,7 +147,7 @@ async function AmmoPhysics() {
 
 	}
 
-	function handleInstancedMesh( mesh, mass, shape ) {
+	function handleInstancedMesh( mesh, shape, mass, restitution ) {
 
 		const array = mesh.instanceMatrix.array;
 
@@ -147,6 +166,7 @@ async function AmmoPhysics() {
 			shape.calculateLocalInertia( mass, localInertia );
 
 			const rbInfo = new AmmoLib.btRigidBodyConstructionInfo( mass, motionState, shape, localInertia );
+			rbInfo.set_m_restitution( restitution );
 
 			const body = new AmmoLib.btRigidBody( rbInfo );
 			world.addRigidBody( body );
@@ -265,8 +285,41 @@ async function AmmoPhysics() {
 	setInterval( step, 1000 / frameRate );
 
 	return {
+		/**
+		 * Adds the given scene to this physics simulation. Only meshes with a
+		 * `physics` object in their {@link Object3D#userData} field will be honored.
+		 * The object can be used to store the mass of the mesh. E.g.:
+		 * ```js
+		 * box.userData.physics = { mass: 1 };
+		 * ```
+		 *
+		 * @method
+		 * @name AmmoPhysics#addScene
+		 * @param {Object3D} scene The scene or any type of 3D object to add.
+		 */
 		addScene: addScene,
+
+		/**
+		 * Adds the given mesh to this physics simulation.
+		 *
+		 * @method
+		 * @name AmmoPhysics#addMesh
+		 * @param {Mesh} mesh The mesh to add.
+		 * @param {number} [mass=0] The mass in kg of the mesh.
+		 * @param {number} [restitution=0] The restitution of the mesh, usually from 0 to 1. Represents how "bouncy" objects are when they collide with each other.
+		 */
 		addMesh: addMesh,
+
+		/**
+		 * Set the position of the given mesh which is part of the physics simulation. Calling this
+		 * method will reset the current simulated velocity of the mesh.
+		 *
+		 * @method
+		 * @name AmmoPhysics#setMeshPosition
+		 * @param {Mesh} mesh The mesh to update the position for.
+		 * @param {Vector3} position - The new position.
+		 * @param {number} [index=0] - If the mesh is instanced, the index represents the instanced ID.
+		 */
 		setMeshPosition: setMeshPosition
 		// addCompoundMesh
 	};