@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/misc/MD2CharacterComplex.js

@@ -10,45 +10,147 @@ import {
 import { MD2Loader } from '../loaders/MD2Loader.js';
 import { MorphBlendMesh } from '../misc/MorphBlendMesh.js';
 
+/**
+ * This class represents a management component for animated MD2
+ * character assets. It provides a larger API compared to {@link MD2Character}.
+ */
 class MD2CharacterComplex {
 
+	/**
+	 * Constructs a new MD2 character.
+	 */
 	constructor() {
 
+		/**
+		 * The mesh scale.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.scale = 1;
 
-		// animation parameters
-
+		/**
+		 * The FPS
+		 *
+		 * @type {number}
+		 * @default 6
+		 */
 		this.animationFPS = 6;
-		this.transitionFrames = 15;
 
-		// movement model parameters
+		/**
+		 * The transition frames.
+		 *
+		 * @type {number}
+		 * @default 15
+		 */
+		this.transitionFrames = 15;
 
+		/**
+		 * The character's maximum speed.
+		 *
+		 * @type {number}
+		 * @default 275
+		 */
 		this.maxSpeed = 275;
+
+		/**
+		 * The character's maximum reverse speed.
+		 *
+		 * @type {number}
+		 * @default - 275
+		 */
 		this.maxReverseSpeed = - 275;
 
+		/**
+		 * The character's front acceleration.
+		 *
+		 * @type {number}
+		 * @default 600
+		 */
 		this.frontAcceleration = 600;
+
+		/**
+		 * The character's back acceleration.
+		 *
+		 * @type {number}
+		 * @default 600
+		 */
 		this.backAcceleration = 600;
 
+		/**
+		 * The character's front decceleration.
+		 *
+		 * @type {number}
+		 * @default 600
+		 */
 		this.frontDecceleration = 600;
 
+		/**
+		 * The character's angular speed.
+		 *
+		 * @type {number}
+		 * @default 2.5
+		 */
 		this.angularSpeed = 2.5;
 
-		// rig
-
+		/**
+		 * The root 3D object
+		 *
+		 * @type {Object3D}
+		 */
 		this.root = new Object3D();
 
+		/**
+		 * The body mesh.
+		 *
+		 * @type {?Mesh}
+		 * @default null
+		 */
 		this.meshBody = null;
+
+		/**
+		 * The weapon mesh.
+		 *
+		 * @type {?Mesh}
+		 * @default null
+		 */
 		this.meshWeapon = null;
 
+		/**
+		 * The movement controls.
+		 *
+		 * @type {Object}
+		 * @default null
+		 */
 		this.controls = null;
 
-		// skins
-
+		/**
+		 * The body skins.
+		 *
+		 * @type {Array<Texture>}
+		 */
 		this.skinsBody = [];
+
+		/**
+		 * The weapon skins.
+		 *
+		 * @type {Array<Texture>}
+		 */
 		this.skinsWeapon = [];
 
+		/**
+		 * The weapon meshes.
+		 *
+		 * @type {Array<Mesh>}
+		 */
 		this.weapons = [];
 
+		/**
+		 * The current skin.
+		 *
+		 * @type {Texture}
+		 * @default undefined
+		 */
 		this.currentSkin = undefined;
 
 		//
@@ -79,6 +181,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Toggles shadow casting and receiving on the character's meshes.
+	 *
+	 * @param {boolean} enable - Whether to enable shadows or not.
+	 */
 	enableShadows( enable ) {
 
 		for ( let i = 0; i < this.meshes.length; i ++ ) {
@@ -90,6 +197,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Toggles visibility on the character's meshes.
+	 *
+	 * @param {boolean} enable - Whether the character is visible or not.
+	 */
 	setVisible( enable ) {
 
 		for ( let i = 0; i < this.meshes.length; i ++ ) {
@@ -101,6 +213,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Shares certain resources from a different character model.
+	 *
+	 * @param {MD2CharacterComplex} original - The original MD2 character.
+	 */
 	shareParts( original ) {
 
 		this.animations = original.animations;
@@ -143,6 +260,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Loads the character model for the given config.
+	 *
+	 * @param {Object} config - The config which defines the model and textures paths.
+	 */
 	loadParts( config ) {
 
 		const scope = this;
@@ -241,6 +363,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Sets the animation playback rate.
+	 *
+	 * @param {number} rate - The playback rate to set.
+	 */
 	setPlaybackRate( rate ) {
 
 		if ( this.meshBody ) this.meshBody.duration = this.meshBody.baseDuration / rate;
@@ -248,6 +375,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Sets the wireframe material flag.
+	 *
+	 * @param {boolean} wireframeEnabled - Whether to enable wireframe rendering or not.
+	 */
 	setWireframe( wireframeEnabled ) {
 
 		if ( wireframeEnabled ) {
@@ -264,6 +396,12 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Sets the skin defined by the given skin index. This will result in a different texture
+	 * for the body mesh.
+	 *
+	 * @param {number} index - The skin index.
+	 */
 	setSkin( index ) {
 
 		if ( this.meshBody && this.meshBody.material.wireframe === false ) {
@@ -275,6 +413,12 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Sets the weapon defined by the given weapon index. This will result in a different weapon
+	 * hold by the character.
+	 *
+	 * @param {number} index - The weapon index.
+	 */
 	setWeapon( index ) {
 
 		for ( let i = 0; i < this.weapons.length; i ++ ) this.weapons[ i ].visible = false;
@@ -297,6 +441,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Sets the defined animation clip as the active animation.
+	 *
+	 * @param {string} animationName - The name of the animation clip.
+	 */
 	setAnimation( animationName ) {
 
 		if ( animationName === this.activeAnimation || ! animationName ) return;
@@ -336,6 +485,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Updates the animations of the mesh. Must be called inside the animation loop.
+	 *
+	 * @param {number} delta - The delta time in seconds.
+	 */
 	updateAnimations( delta ) {
 
 		let mix = 1;
@@ -367,6 +521,9 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Updates the animation state based on the control inputs.
+	 */
 	updateBehaviors() {
 
 		const controls = this.controls;
@@ -476,6 +633,11 @@ class MD2CharacterComplex {
 
 	}
 
+	/**
+	 * Transforms the character model based on the control input.
+	 *
+	 * @param {number} delta - The delta time in seconds.
+	 */
 	updateMovementModel( delta ) {
 
 		function exponentialEaseOut( k ) {

package/examples/jsm/misc/MorphAnimMesh.js

@@ -4,31 +4,69 @@ import {
 	Mesh
 } from 'three';
 
+/**
+ * A special type of an animated mesh with a simple interface
+ * for animation playback. It allows to playback just one animation
+ * without any transitions or fading between animation changes.
+ *
+ * @augments Mesh
+ */
 class MorphAnimMesh extends Mesh {
 
+	/**
+	 * Constructs a new morph anim mesh.
+	 *
+	 * @param {BufferGeometry} [geometry] - The mesh geometry.
+	 * @param {Material|Array<Material>} [material] - The mesh material.
+	 */
 	constructor( geometry, material ) {
 
 		super( geometry, material );
 
 		this.type = 'MorphAnimMesh';
 
+		/**
+		 * The internal animation mixer.
+		 *
+		 * @type {AnimationMixer}
+		 */
 		this.mixer = new AnimationMixer( this );
+
+		/**
+		 * The current active animation action.
+		 *
+		 * @type {?AnimationAction}
+		 * @default null
+		 */
 		this.activeAction = null;
 
 	}
 
+	/**
+	 * Sets the animation playback direction to "forward".
+	 */
 	setDirectionForward() {
 
 		this.mixer.timeScale = 1.0;
 
 	}
 
+	/**
+	 * Sets the animation playback direction to "backward".
+	 */
 	setDirectionBackward() {
 
 		this.mixer.timeScale = - 1.0;
 
 	}
 
+	/**
+	 * Plays the defined animation clip. The implementation assumes the animation
+	 * clips are stored in {@link Object3D#animations} or the geometry.
+	 *
+	 * @param {string} label - The name of the animation clip.
+	 * @param {number} fps - The FPS of the animation clip.
+	 */
 	playAnimation( label, fps ) {
 
 		if ( this.activeAction ) {
@@ -54,6 +92,11 @@ class MorphAnimMesh extends Mesh {
 
 	}
 
+	/**
+	 * Updates the animations of the mesh. Must be called inside the animation loop.
+	 *
+	 * @param {number} delta - The delta time in seconds.
+	 */
 	updateAnimation( delta ) {
 
 		this.mixer.update( delta );

package/examples/jsm/misc/MorphBlendMesh.js

@@ -3,13 +3,38 @@ import {
 	Mesh
 } from 'three';
 
+/**
+ * A special type of an animated mesh with a more advanced interface
+ * for animation playback. Unlike {@link MorphAnimMesh}. It allows to
+ * playback more than one morph animation at the same time but without
+ * fading options.
+ *
+ * @augments Mesh
+ */
 class MorphBlendMesh extends Mesh {
 
+	/**
+	 * Constructs a new morph blend mesh.
+	 *
+	 * @param {BufferGeometry} [geometry] - The mesh geometry.
+	 * @param {Material|Array<Material>} [material] - The mesh material.
+	 */
 	constructor( geometry, material ) {
 
 		super( geometry, material );
 
+		/**
+		 * A dictionary of animations.
+		 *
+		 * @type {Object<string,Object>}
+		 */
 		this.animationsMap = {};
+
+		/**
+		 * A list of animations.
+		 *
+		 * @type {Array<Object>}
+		 */
 		this.animationsList = [];
 
 		// prepare default animation
@@ -29,6 +54,14 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Creates a new animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @param {number} start - The start time.
+	 * @param {number} end - The end time.
+	 * @param {number} fps - The FPS.
+	 */
 	createAnimation( name, start, end, fps ) {
 
 		const animation = {
@@ -60,6 +93,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Automatically creates animations based on the values in
+	 * {@link Mesh#morphTargetDictionary}.
+	 *
+	 * @param {number} fps - The FPS of all animations.
+	 */
 	autoCreateAnimations( fps ) {
 
 		const pattern = /([a-z]+)_?(\d+)/i;
@@ -104,6 +143,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Sets the animation playback direction to "forward" for the
+	 * defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 */
 	setAnimationDirectionForward( name ) {
 
 		const animation = this.animationsMap[ name ];
@@ -117,6 +162,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Sets the animation playback direction to "backward" for the
+	 * defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 */
 	setAnimationDirectionBackward( name ) {
 
 		const animation = this.animationsMap[ name ];
@@ -130,6 +181,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Sets the FPS to the given value for the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @param {number} fps - The FPS to set.
+	 */
 	setAnimationFPS( name, fps ) {
 
 		const animation = this.animationsMap[ name ];
@@ -143,6 +200,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Sets the duration to the given value for the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @param {number} duration - The duration to set.
+	 */
 	setAnimationDuration( name, duration ) {
 
 		const animation = this.animationsMap[ name ];
@@ -156,6 +219,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Sets the weight to the given value for the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @param {number} weight - The weight to set.
+	 */
 	setAnimationWeight( name, weight ) {
 
 		const animation = this.animationsMap[ name ];
@@ -168,6 +237,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Sets the time to the given value for the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @param {number} time - The time to set.
+	 */
 	setAnimationTime( name, time ) {
 
 		const animation = this.animationsMap[ name ];
@@ -180,6 +255,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Returns the time for the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @return {number} The time.
+	 */
 	getAnimationTime( name ) {
 
 		let time = 0;
@@ -196,6 +277,12 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Returns the duration for the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 * @return {number} The duration.
+	 */
 	getAnimationDuration( name ) {
 
 		let duration = - 1;
@@ -212,6 +299,11 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Plays the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 */
 	playAnimation( name ) {
 
 		const animation = this.animationsMap[ name ];
@@ -229,6 +321,11 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Stops the defined animation.
+	 *
+	 * @param {string} name - The animation name.
+	 */
 	stopAnimation( name ) {
 
 		const animation = this.animationsMap[ name ];
@@ -241,6 +338,11 @@ class MorphBlendMesh extends Mesh {
 
 	}
 
+	/**
+	 * Updates the animations of the mesh.
+	 *
+	 * @param {number} delta - The delta time in seconds.
+	 */
 	update( delta ) {
 
 		for ( let i = 0, il = this.animationsList.length; i < il; i ++ ) {

package/examples/jsm/misc/ProgressiveLightMap.js

@@ -2,7 +2,7 @@ import { DoubleSide, FloatType, HalfFloatType, Mesh, MeshBasicMaterial, MeshPhon
 import { potpack } from '../libs/potpack.module.js';
 
 /**
- * Progressive Light Map Accumulator, by [zalo](https://github.com/zalo/)
+ * Progressive Light Map Accumulator, by [zalo]{@link https://github.com/zalo/}.
  *
  * To use, simply construct a `ProgressiveLightMap` object,
  * `plmap.addObjectsToLightMap(object)` an array of semi-static
@@ -13,17 +13,37 @@ import { potpack } from '../libs/potpack.module.js';
  * This should begin accumulating lightmaps which apply to
  * your objects, so you can start jittering lighting to achieve
  * the texture-space effect you're looking for.
+ *
+ * This class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, import from `ProgressiveLightMapGPU.js`.
  */
 class ProgressiveLightMap {
 
 	/**
-	 * @param {WebGLRenderer} renderer An instance of WebGLRenderer.
- 	 * @param {number} [res=1024] The side-long dimension of you total lightmap.
+	 * Constructs a new progressive light map.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+ 	 * @param {number} [res=1024] - The side-long dimension of the total lightmap.
 	 */
 	constructor( renderer, res = 1024 ) {
 
+		/**
+		 * The renderer.
+		 *
+		 * @type {WebGLRenderer}
+		 */
 		this.renderer = renderer;
+
+		/**
+		 * The side-long dimension of the total lightmap.
+		 *
+		 * @type {number}
+		 * @default 1024
+		 */
 		this.res = res;
+
+		// internals
+
 		this.lightMapContainers = [];
 		this.scene = new Scene();
 		this.buffer1Active = false;
@@ -76,7 +96,8 @@ class ProgressiveLightMap {
 
 	/**
 	 * Sets these objects' materials' lightmaps and modifies their uv1's.
-	 * @param {Object3D} objects An array of objects and lights to set up your lightmap.
+	 *
+	 * @param {Array<Object3D>} objects - An array of objects and lights to set up your lightmap.
 	 */
 	addObjectsToLightMap( objects ) {
 
@@ -142,10 +163,11 @@ class ProgressiveLightMap {
 	}
 
 	/**
-	 * This function renders each mesh one at a time into their respective surface maps
-	 * @param {Camera} camera Standard Rendering Camera
-	 * @param {number} blendWindow When >1, samples will accumulate over time.
-	 * @param {boolean} blurEdges  Whether to fix UV Edges via blurring
+	 * This function renders each mesh one at a time into their respective surface maps.
+	 *
+	 * @param {Camera} camera - The camera the scene is rendered with.
+	 * @param {number} [blendWindow=100] - When >1, samples will accumulate over time.
+	 * @param {boolean} [blurEdges=true] - Whether to fix UV Edges via blurring.
 	 */
 	update( camera, blendWindow = 100, blurEdges = true ) {
 
@@ -215,10 +237,11 @@ class ProgressiveLightMap {
 
 	}
 
-	/** DEBUG
-	 * Draw the lightmap in the main scene.  Call this after adding the objects to it.
-	 * @param {boolean} visible Whether the debug plane should be visible
-	 * @param {Vector3} position Where the debug plane should be drawn
+	/**
+	 * Draws the lightmap in the main scene. Call this after adding the objects to it.
+	 *
+	 * @param {boolean} visible - Whether the debug plane should be visible
+	 * @param {Vector3} [position] - Where the debug plane should be drawn
 	*/
 	showDebugLightmap( visible, position = undefined ) {
 
@@ -251,9 +274,11 @@ class ProgressiveLightMap {
 	}
 
 	/**
-	 * INTERNAL Creates the Blurring Plane
-	 * @param {number} res The square resolution of this object's lightMap.
-	 * @param {WebGLRenderTexture} lightMap The lightmap to initialize the plane with.
+	 * Creates the Blurring Plane.
+	 *
+	 * @private
+	 * @param {number} res - The square resolution of this object's lightMap.
+	 * @param {WebGLRenderTarget} [lightMap] - The lightmap to initialize the plane with.
 	 */
 	_initializeBlurPlane( res, lightMap = null ) {