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

package/examples/jsm/webxr/XRControllerModelFactory.js

@@ -16,17 +16,44 @@ import {
 const DEFAULT_PROFILES_PATH = 'https://cdn.jsdelivr.net/npm/@webxr-input-profiles/assets@1.0/dist/profiles';
 const DEFAULT_PROFILE = 'generic-trigger';
 
+/**
+ * Represents a XR controller model.
+ *
+ * @augments Object3D
+ */
 class XRControllerModel extends Object3D {
 
+	/**
+	 * Constructs a new XR controller model.
+	 */
 	constructor() {
 
 		super();
 
+		/**
+		 * The motion controller.
+		 *
+		 * @type {?MotionController}
+		 * @default null
+		 */
 		this.motionController = null;
+
+		/**
+		 * The controller's environment map.
+		 *
+		 * @type {?Texture}
+		 * @default null
+		 */
 		this.envMap = null;
 
 	}
 
+	/**
+	 * Sets an environment map that is applied to the controller model.
+	 *
+	 * @param {?Texture} envMap - The environment map to apply.
+	 * @return {XRControllerModel} A reference to this instance.
+	 */
 	setEnvironmentMap( envMap ) {
 
 		if ( this.envMap == envMap ) {
@@ -52,8 +79,11 @@ class XRControllerModel extends Object3D {
 	}
 
 	/**
-	 * Polls data from the XRInputSource and updates the model's components to match
-	 * the real world data
+	 * Overwritten with a custom implementation. Polls data from the XRInputSource and updates the
+	 * model's components to match the real world data.
+	 *
+	 * @param {boolean} [force=false] - When set to `true`, a recomputation of world matrices is forced even
+	 * when {@link Object3D#matrixWorldAutoUpdate} is set to `false`.
 	 */
 	updateMatrixWorld( force ) {
 
@@ -107,8 +137,12 @@ class XRControllerModel extends Object3D {
 
 /**
  * Walks the model's tree to find the nodes needed to animate the components and
- * saves them to the motionContoller components for use in the frame loop. When
+ * saves them to the motionController components for use in the frame loop. When
  * touchpads are found, attaches a touch dot to them.
+ *
+ * @private
+ * @param {MotionController} motionController
+ * @param {Object3D} scene
  */
 function findNodes( motionController, scene ) {
 
@@ -215,13 +249,58 @@ function addAssetSceneToControllerModel( controllerModel, scene ) {
 
 }
 
+/**
+ * Allows to create controller models for WebXR controllers that can be added as a visual
+ * representation to your scene. `XRControllerModelFactory` will automatically fetch controller
+ * models that match what the user is holding as closely as possible. The models should be
+ * attached to the object returned from getControllerGrip in order to match the orientation of
+ * the held device.
+ *
+ * This module depends on the [motion-controllers](https://github.com/immersive-web/webxr-input-profiles/blob/main/packages/motion-controllers/README.md)
+ * third-part library.
+ *
+ * ```js
+ * const controllerModelFactory = new XRControllerModelFactory();
+ *
+ * const controllerGrip = renderer.xr.getControllerGrip( 0 );
+ * controllerGrip.add( controllerModelFactory.createControllerModel( controllerGrip ) );
+ * scene.add( controllerGrip );
+ * ```
+ *
+ * @three_import import { XRControllerModelFactory } from 'three/addons/webxr/XRControllerModelFactory.js';
+ */
 class XRControllerModelFactory {
 
+	/**
+	 * Constructs a new XR controller model factory.
+	 *
+	 * @param {?GLTFLoader} [gltfLoader=null] - A glTF loader that is used to load controller models.
+	 * @param {?Function} [onLoad=null] - A callback that is executed when a controller model has been loaded.
+	 */
 	constructor( gltfLoader = null, onLoad = null ) {
 
+		/**
+		 * A glTF loader that is used to load controller models.
+		 *
+		 * @type {?GLTFLoader}
+		 * @default null
+		 */
 		this.gltfLoader = gltfLoader;
+
+		/**
+		 * The path to the model repository.
+		 *
+		 * @type {string}
+		 */
 		this.path = DEFAULT_PROFILES_PATH;
 		this._assetCache = {};
+
+		/**
+		 * A callback that is executed when a controller model has been loaded.
+		 *
+		 * @type {?Function}
+		 * @default null
+		 */
 		this.onLoad = onLoad;
 
 		// If a GLTFLoader wasn't supplied to the constructor create a new one.
@@ -233,6 +312,12 @@ class XRControllerModelFactory {
 
 	}
 
+	/**
+	 * Sets the path to the model repository.
+	 *
+	 * @param {string} path - The path to set.
+	 * @return {XRControllerModelFactory} A reference to this instance.
+	 */
 	setPath( path ) {
 
 		this.path = path;
@@ -241,6 +326,12 @@ class XRControllerModelFactory {
 
 	}
 
+	/**
+	 * Creates a controller model for the given WebXR controller.
+	 *
+	 * @param {Group} controller - The controller.
+	 * @return {XRControllerModel} The XR controller model.
+	 */
 	createControllerModel( controller ) {
 
 		const controllerModel = new XRControllerModel();

package/examples/jsm/webxr/XREstimatedLight.js

@@ -79,7 +79,7 @@ class SessionLightProbe {
 
 	onXRFrame( time, xrFrame ) {
 
-		// If either this obejct or the XREstimatedLight has been destroyed, stop
+		// If either this object or the XREstimatedLight has been destroyed, stop
 		// running the frame loop.
 		if ( ! this.xrLight ) {
 
@@ -133,22 +133,50 @@ class SessionLightProbe {
 
 }
 
+/**
+ * This class can be used to represent the environmental light of
+ * a XR session. It relies on the WebXR Lighting Estimation API.
+ *
+ * @augments Group
+ * @three_import import { XREstimatedLight } from 'three/addons/webxr/XREstimatedLight.js';
+ */
 export class XREstimatedLight extends Group {
 
+	/**
+	 * Constructs a new light.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 * @param {boolean} [environmentEstimation=true] - Whether to use environment estimation or not.
+	 */
 	constructor( renderer, environmentEstimation = true ) {
 
 		super();
 
+		/**
+		 * The light probe that represents the estimated light.
+		 *
+		 * @type {LightProbe}
+		 */
 		this.lightProbe = new LightProbe();
 		this.lightProbe.intensity = 0;
 		this.add( this.lightProbe );
 
+		/**
+		 * Represents the primary light from the XR environment.
+		 *
+		 * @type {DirectionalLight}
+		 */
 		this.directionalLight = new DirectionalLight();
 		this.directionalLight.intensity = 0;
 		this.add( this.directionalLight );
 
-		// Will be set to a cube map in the SessionLightProbe if environment estimation is
-		// available and requested.
+		/**
+		 * Will be set to a cube map in the SessionLightProbe if environment estimation is
+		 * available and requested.
+		 *
+		 * @type {?Texture}
+		 * @default null
+		 */
 		this.environment = null;
 
 		let sessionLightProbe = null;
@@ -198,7 +226,10 @@ export class XREstimatedLight extends Group {
 
 		} );
 
-		// Done inline to provide access to sessionLightProbe.
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
 		this.dispose = () => {
 
 			if ( sessionLightProbe ) {

package/examples/jsm/webxr/XRHandMeshModel.js

@@ -2,13 +2,47 @@ import { GLTFLoader } from '../loaders/GLTFLoader.js';
 
 const DEFAULT_HAND_PROFILE_PATH = 'https://cdn.jsdelivr.net/npm/@webxr-input-profiles/assets@1.0/dist/profiles/generic-hand/';
 
+/**
+ * Represents one of the hand model types {@link XRHandModelFactory} might produce
+ * depending on the selected profile. `XRHandMeshModel` represents a hand with a
+ * custom asset.
+ *
+ * @three_import import { XRHandMeshModel } from 'three/addons/webxr/XRHandMeshModel.js';
+ */
 class XRHandMeshModel {
 
+	/**
+	 * Constructs a new XR hand mesh model.
+	 *
+	 * @param {XRHandModel} handModel - The hand model.
+	 * @param {Group} controller - The WebXR controller.
+	 * @param {?string} path - The model path.
+	 * @param {XRHandedness} handedness - The handedness of the XR input source.
+	 * @param {?Loader} [loader=null] - The loader. If not provided, an instance of `GLTFLoader` will be used to load models.
+	 * @param {?Function} [onLoad=null] - A callback that is executed when a controller model has been loaded.
+	 */
 	constructor( handModel, controller, path, handedness, loader = null, onLoad = null ) {
 
+		/**
+		 * The WebXR controller.
+		 *
+		 * @type {Group}
+		 */
 		this.controller = controller;
+
+		/**
+		 * The hand model.
+		 *
+		 * @type {XRHandModel}
+		 */
 		this.handModel = handModel;
 
+		/**
+		 * An array of bones representing the bones
+		 * of the hand skeleton.
+		 *
+		 * @type {Array<Bone>}
+		 */
 		this.bones = [];
 
 		if ( loader === null ) {
@@ -82,6 +116,9 @@ class XRHandMeshModel {
 
 	}
 
+	/**
+	 * Updates the mesh based on the tracked XR joints data.
+	 */
 	updateMesh() {
 
 		// XR Joints

package/examples/jsm/webxr/XRHandModelFactory.js

@@ -10,20 +10,61 @@ import {
 	XRHandMeshModel
 } from './XRHandMeshModel.js';
 
+/**
+ * Represents a XR hand model.
+ *
+ * @augments Object3D
+ */
 class XRHandModel extends Object3D {
 
+	/**
+	 * Constructs a new XR hand model.
+	 *
+	 * @param {Group} controller - The hand controller.
+	 */
 	constructor( controller ) {
 
 		super();
 
+		/**
+		 * The hand controller.
+		 *
+		 * @type {Group}
+		 */
 		this.controller = controller;
+
+		/**
+		 * The motion controller.
+		 *
+		 * @type {?MotionController}
+		 * @default null
+		 */
 		this.motionController = null;
+
+		/**
+		 * The controller's environment map.
+		 *
+		 * @type {?Texture}
+		 * @default null
+		 */
 		this.envMap = null;
 
+		/**
+		 * The model mesh.
+		 *
+		 * @type {Mesh}
+		 * @default null
+		 */
 		this.mesh = null;
 
 	}
 
+	/**
+	 * Overwritten with a custom implementation. Makes sure the motion controller updates the mesh.
+	 *
+	 * @param {boolean} [force=false] - When set to `true`, a recomputation of world matrices is forced even
+	 * when {@link Object3D#matrixWorldAutoUpdate} is set to `false`.
+	 */
 	updateMatrixWorld( force ) {
 
 		super.updateMatrixWorld( force );
@@ -38,16 +79,62 @@ class XRHandModel extends Object3D {
 
 }
 
+/**
+ * Similar to {@link XRControllerModelFactory}, this class allows to create hand models
+ * for WebXR controllers that can be added as a visual representation to your scene.
+ *
+ * ```js
+ * const handModelFactory = new XRHandModelFactory();
+ *
+ * const hand = renderer.xr.getHand( 0 );
+ * hand.add( handModelFactory.createHandModel( hand ) );
+ * scene.add( hand );
+ * ```
+ *
+ * @three_import import { XRHandModelFactory } from 'three/addons/webxr/XRHandModelFactory.js';
+ */
 class XRHandModelFactory {
 
+	/**
+	 * Constructs a new XR hand model factory.
+	 *
+	 * @param {?GLTFLoader} [gltfLoader=null] - A glTF loader that is used to load hand models.
+	 * @param {?Function} [onLoad=null] - A callback that is executed when a hand model has been loaded.
+	 */
 	constructor( gltfLoader = null, onLoad = null ) {
 
+		/**
+		 * A glTF loader that is used to load hand models.
+		 *
+		 * @type {?GLTFLoader}
+		 * @default null
+		 */
 		this.gltfLoader = gltfLoader;
+
+		/**
+		 * The path to the model repository.
+		 *
+		 * @type {?string}
+		 * @default null
+		 */
 		this.path = null;
+
+		/**
+		 * A callback that is executed when a hand model has been loaded.
+		 *
+		 * @type {?Function}
+		 * @default null
+		 */
 		this.onLoad = onLoad;
 
 	}
 
+	/**
+	 * Sets the path to the hand model repository.
+	 *
+	 * @param {string} path - The path to set.
+	 * @return {XRHandModelFactory} A reference to this instance.
+	 */
 	setPath( path ) {
 
 		this.path = path;
@@ -56,6 +143,13 @@ class XRHandModelFactory {
 
 	}
 
+	/**
+	 * Creates a controller model for the given WebXR hand controller.
+	 *
+	 * @param {Group} controller - The hand controller.
+	 * @param {('spheres'|'boxes'|'mesh')} [profile] - The model profile that defines the model type.
+	 * @return {XRHandModel} The XR hand model.
+	 */
 	createHandModel( controller, profile ) {
 
 		const handModel = new XRHandModel( controller );
@@ -85,16 +179,12 @@ class XRHandModelFactory {
 
 			}
 
-			controller.visible = true;
-
 		} );
 
 		controller.addEventListener( 'disconnected', () => {
 
-			controller.visible = false;
-			// handModel.motionController = null;
-			// handModel.remove( scene );
-			// scene = null;
+			handModel.clear();
+			handModel.motionController = null;
 
 		} );
 

package/examples/jsm/webxr/XRHandPrimitiveModel.js

@@ -11,12 +11,46 @@ import {
 const _matrix = new Matrix4();
 const _vector = new Vector3();
 
+/**
+ * Represents one of the hand model types {@link XRHandModelFactory} might produce
+ * depending on the selected profile. `XRHandPrimitiveModel` represents a hand
+ * with sphere or box primitives according to the selected `primitive` option.
+ *
+ * @three_import import { XRHandPrimitiveModel } from 'three/addons/webxr/XRHandPrimitiveModel.js';
+ */
 class XRHandPrimitiveModel {
 
+	/**
+	 * Constructs a new XR hand primitive model.
+	 *
+	 * @param {XRHandModel} handModel - The hand model.
+	 * @param {Group} controller - The WebXR controller.
+	 * @param {string} path - The model path.
+	 * @param {XRHandedness} handedness - The handedness of the XR input source.
+	 * @param {XRHandPrimitiveModel~Options} options - The model options.
+	 */
 	constructor( handModel, controller, path, handedness, options ) {
 
+		/**
+		 * The WebXR controller.
+		 *
+		 * @type {Group}
+		 */
 		this.controller = controller;
+
+		/**
+		 * The hand model.
+		 *
+		 * @type {XRHandModel}
+		 */
 		this.handModel = handModel;
+
+		/**
+		 * The model's environment map.
+		 *
+		 * @type {?Texture}
+		 * @default null
+		 */
 		this.envMap = null;
 
 		let geometry;
@@ -72,6 +106,9 @@ class XRHandPrimitiveModel {
 
 	}
 
+	/**
+	 * Updates the mesh based on the tracked XR joints data.
+	 */
 	updateMesh() {
 
 		const defaultRadius = 0.008;
@@ -102,4 +139,11 @@ class XRHandPrimitiveModel {
 
 }
 
+/**
+ * Constructor options of `XRHandPrimitiveModel`.
+ *
+ * @typedef {Object} XRHandPrimitiveModel~Options
+ * @property {('box'|'sphere')} [primitive] - The primitive type.
+ **/
+
 export { XRHandPrimitiveModel };

package/examples/jsm/webxr/XRPlanes.js

@@ -6,8 +6,26 @@ import {
 	Object3D
 } from 'three';
 
+/**
+ * A utility class for the WebXR Plane Detection Module. If planes
+ * are detected by WebXR, this class will automatically add them
+ * as thin box meshes to the scene when below code snippet is used.
+ *
+ * ```js
+ * const planes = new XRPlanes( renderer );
+ * scene.add( planes );
+ * ```
+ *
+ * @augments Object3D
+ * @three_import import { XRPlanes } from 'three/addons/webxr/XRPlanes.js';
+ */
 class XRPlanes extends Object3D {
 
+	/**
+	 * Constructs a new XR plane container.
+	 *
+	 * @param {WebGLRenderer|WebGPURenderer} renderer - The renderer.
+	 */
 	constructor( renderer ) {
 
 		super();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/three",
-  "version": "0.169.20",
+  "version": "0.183.2-canary.0",
   "description": "JavaScript 3D library",
   "type": "module",
   "main": "./build/three.cjs",
@@ -16,13 +16,15 @@
     "./addons/*": "./examples/jsm/*",
     "./src/*": "./src/*",
     "./webgpu": "./build/three.webgpu.js",
-    "./tsl": "./build/three.webgpu.js"
+    "./tsl": "./build/three.tsl.js"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/mrdoob/three.js"
+    "url": "https://github.com/@needle-tools/three.js"
   },
-  "sideEffects": [ "./src/nodes/**/*" ],
+  "sideEffects": [
+    "./src/nodes/**/*"
+  ],
   "files": [
     "build",
     "examples/jsm",
@@ -45,27 +47,26 @@
     "test": "npm run lint && npm run test-unit && npm run test-unit-addons",
     "prebuild": "node utils/update-revision.js",
     "build": "rollup -c utils/build/rollup.config.js",
+    "build-docs": "jsdoc -c utils/docs/jsdoc.config.json && npm run build-llms",
+    "build-llms": "node utils/llms/build.js",
     "build-module": "rollup -c utils/build/rollup.config.js --configOnlyModule",
-    "dev": "concurrently --names \"ROLLUP,HTTP\" -c \"bgBlue.bold,bgGreen.bold\" \"rollup -c utils/build/rollup.config.js -w -m inline\" \"servez -p 8080\"",
-    "dev-ssl": "concurrently --names \"ROLLUP,HTTPS\" -c \"bgBlue.bold,bgGreen.bold\" \"rollup -c utils/build/rollup.config.js -w -m inline\" \"servez -p 8080 --ssl\"",
+    "dev": "node utils/build/dev.js && node utils/server.js -p 8080",
+    "preview": "node utils/build/preview.js",
     "lint-core": "eslint src",
-    "lint-addons": "eslint examples/jsm --ext .js --ignore-pattern libs --ignore-pattern ifc",
-    "lint-examples": "eslint examples --ext .html",
-    "lint-docs": "eslint docs --ignore-pattern prettify.js",
-    "lint-editor": "eslint editor --ignore-pattern libs",
-    "lint-playground": "eslint playground --ignore-pattern libs",
-    "lint-manual": "eslint manual --ignore-pattern 3rdparty --ignore-pattern prettify.js --ignore-pattern shapefile.js",
-    "lint-test": "eslint test --ignore-pattern vendor",
+    "lint-addons": "eslint examples/jsm",
+    "lint-examples": "eslint examples",
+    "lint-editor": "eslint editor",
+    "lint-manual": "eslint manual",
+    "lint-test": "eslint test",
     "lint-utils": "eslint utils",
     "lint": "npm run lint-core",
-    "lint-fix": "npm run lint-core -- --fix && npm run lint-addons -- --fix && npm run lint-examples -- --fix && npm run lint-docs -- --fix && npm run lint-editor -- --fix && npm run lint-playground -- --fix && npm run lint-manual -- --fix && npm run lint-test -- --fix && npm run lint-utils -- --fix",
-    "test-unit": "qunit -r failonlyreporter -f !-webonly test/unit/three.source.unit.js",
-    "test-unit-addons": "qunit -r failonlyreporter -f !-webonly test/unit/three.addons.unit.js",
+    "lint-fix": "npm run lint-core -- --fix && npm run lint-addons -- --fix && npm run lint-examples -- --fix && npm run lint-editor -- --fix && npm run lint-manual -- --fix && npm run lint-test -- --fix && npm run lint-utils -- --fix",
+    "test-unit": "qunit test/unit/three.source.unit.js",
+    "test-unit-addons": "qunit test/unit/three.addons.unit.js",
     "test-e2e": "node test/e2e/puppeteer.js",
     "test-e2e-cov": "node test/e2e/check-coverage.js",
     "test-e2e-webgpu": "node test/e2e/puppeteer.js --webgpu",
     "test-treeshake": "rollup -c test/rollup.treeshake.config.js",
-    "test-circular-deps": "dpdm --no-warning --no-tree --exit-code circular:1 src/nodes/Nodes.js",
     "make-screenshot": "node test/e2e/puppeteer.js --make"
   },
   "keywords": [
@@ -91,29 +92,23 @@
   },
   "homepage": "https://threejs.org/",
   "devDependencies": {
-    "@rollup/plugin-node-resolve": "^15.0.1",
+    "@eslint/js": "^9.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.0",
     "@rollup/plugin-terser": "^0.4.0",
-    "chalk": "^5.2.0",
-    "concurrently": "^9.0.0",
-    "dpdm": "^3.14.0",
-    "eslint": "^8.37.0",
+    "eslint": "^9.0.0",
     "eslint-config-mdcs": "^5.0.0",
     "eslint-plugin-compat": "^6.0.0",
-    "eslint-plugin-html": "^8.0.0",
-    "eslint-plugin-import": "^2.27.5",
-    "failonlyreporter": "^1.0.0",
-    "jimp": "^0.22.7",
+    "eslint-plugin-html": "^8.1.3",
+    "eslint-plugin-jsdoc": "^62.0.0",
+    "globals": "^17.0.0",
+    "jpeg-js": "^0.4.4",
+    "jsdoc": "^4.0.5",
     "magic-string": "^0.30.0",
-    "pixelmatch": "^6.0.0",
-    "puppeteer": "^22.0.0",
+    "pngjs": "^7.0.0",
+    "puppeteer": "^24.25.0",
     "qunit": "^2.19.4",
     "rollup": "^4.6.0",
-    "rollup-plugin-filesize": "^10.0.0",
-    "rollup-plugin-visualizer": "^5.9.0",
-    "servez": "^2.0.0"
-  },
-  "overrides": {
-    "jpeg-js": "^0.4.4"
+    "turndown": "^7.2.2"
   },
   "jspm": {
     "files": [