@types/three 0.182.0 → 0.183.0

three/src/lights/SpotLight.d.ts

@@ -1,6 +1,5 @@
 import { JSONMeta, Object3D } from "../core/Object3D.js";
 import { ColorRepresentation } from "../math/Color.js";
-import { Vector3 } from "../math/Vector3.js";
 import { Texture } from "../textures/Texture.js";
 import { Light, LightJSON } from "./Light.js";
 import { LightShadowJSON } from "./LightShadow.js";
@@ -19,35 +18,35 @@ export interface SpotLightJSON extends LightJSON {
 }
 
 /**
- * This light gets emitted from a single point in one direction, along a cone that increases in size the further from the light it gets.
- * @example
- * ```typescript
- * // white {@link SpotLight} shining from the side, modulated by a texture, casting a shadow
- * const {@link SpotLight} = new THREE.SpotLight(0xffffff);
- * spotLight.position.set(100, 1000, 100);
- * spotLight.map = new THREE.TextureLoader().load(url);
+ * This light gets emitted from a single point in one direction, along a cone
+ * that increases in size the further from the light it gets.
+ *
+ * This light can cast shadows - see the {@link SpotLightShadow} for details.
+ *
+ * ```js
+ * // white spotlight shining from the side, modulated by a texture
+ * const spotLight = new THREE.SpotLight( 0xffffff );
+ * spotLight.position.set( 100, 1000, 100 );
+ * spotLight.map = new THREE.TextureLoader().load( url );
+ *
  * spotLight.castShadow = true;
  * spotLight.shadow.mapSize.width = 1024;
  * spotLight.shadow.mapSize.height = 1024;
  * spotLight.shadow.camera.near = 500;
  * spotLight.shadow.camera.far = 4000;
- * spotLight.shadow.camera.fov = 30;
- * scene.add(spotLight);
+ * spotLight.shadow.camera.fov = 30;s
  * ```
- * @see Example: {@link https://threejs.org/examples/#webgl_lights_spotlight | lights / {@link SpotLight} }
- * @see Example: {@link https://threejs.org/examples/#webgl_lights_spotlights | lights / spotlights }
- * @see {@link https://threejs.org/docs/index.html#api/en/lights/SpotLight | Official Documentation}
- * @see {@link https://github.com/mrdoob/three.js/blob/master/src/lights/SpotLight.js | Source}
  */
-export class SpotLight extends Light<SpotLightShadow> {
+export class SpotLight extends Light {
     /**
-     * Creates a new SpotLight.
-     * @param color Hexadecimal color of the light. Default `0xffffff` _(white)_.
-     * @param intensity Numeric value of the light's strength/intensity. Expects a `Float`. Default `1`.
-     * @param distance Maximum range of the light. Default is 0 (no limit). Expects a `Float`.
-     * @param angle Maximum angle of light dispersion from its direction whose upper bound is Math.PI/2.
-     * @param penumbra Percent of the {@link SpotLight} cone that is attenuated due to penumbra. Takes values between zero and 1. Expects a `Float`. Default `0`.
-     * @param decay The amount the light dims along the distance of the light. Expects a `Float`. Default `2`.
+     * Constructs a new spot light.
+     *
+     * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+     * @param {number} [intensity=1] - The light's strength/intensity measured in candela (cd).
+     * @param {number} [distance=0] - Maximum range of the light. `0` means no limit.
+     * @param {number} [angle=Math.PI/3] - Maximum angle of light dispersion from its direction whose upper bound is `Math.PI/2`.
+     * @param {number} [penumbra=0] - Percent of the spotlight cone that is attenuated due to penumbra. Value range is `[0,1]`.
+     * @param {number} [decay=2] - The amount the light dims along the distance of the light.
      */
     constructor(
         color?: ColorRepresentation,
@@ -57,123 +56,70 @@ export class SpotLight extends Light<SpotLightShadow> {
         penumbra?: number,
         decay?: number,
     );
-
-    /**
-     * Read-only flag to check if a given object is of type {@link SpotLight}.
-     * @remarks This is a _constant_ value
-     * @defaultValue `true`
-     */
-    readonly isSpotLight: true;
-
     /**
-     * A Read-only _string_ to check if `this` object type.
-     * @remarks Sub-classes will update this value.
-     * @defaultValue `SpotLight`
-     */
-    override readonly type: string | "SpotLight";
-
-    /**
-     * This is set equal to {@link THREE.Object3D.DEFAULT_UP | Object3D.DEFAULT_UP} (0, 1, 0), so that the light shines from the top down.
-     * @defaultValue `{@link Object3D.DEFAULT_UP}`
+     * This flag can be used for type testing.
+     *
+     * @default true
      */
-    readonly position: Vector3;
-
+    readonly isSpotLight: boolean;
     /**
-     * The {@link SpotLight} points from its {@link SpotLight.position | position} to target.position.
-     * @remarks
-     * **Note**: For the target's position to be changed to anything other than the default,
-     * it must be added to the {@link Scene | scene} using
+     * The spot light points from its position to the
+     * target's position.
      *
-     * ```typescript
-     * scene.add( light.target );
-     * ```
+     * For the target's position to be changed to anything other
+     * than the default, it must be added to the scene.
      *
-     * This is so that the target's {@link Object3D.matrixWorld | matrixWorld} gets automatically updated each frame.
-     * It is also possible to set the target to be another object in the scene (anything with a {@link THREE.Object3D.position | position} property), like so:
-     * ```typescript
-     * const targetObject = new THREE.Object3D();
-     * scene.add(targetObject);
-     * light.target = targetObject;
-     * ```
-     * The {@link SpotLight} will now track the target object.
-     * @defaultValue `new THREE.Object3D()` _The default position of the target is *(0, 0, 0)*._
+     * It is also possible to set the target to be another 3D object
+     * in the scene. The light will now track the target object.
      */
     target: Object3D;
-
     /**
-     * If set to `true` light will cast dynamic shadows.
-     * @remarks  **Warning**: This is expensive and requires tweaking to get shadows looking right. the {@link THREE.SpotLightShadow | SpotLightShadow} for details.
-     * @defaultValue `false`
-     */
-    override castShadow: boolean;
-
-    /**
-     * The light's intensity.
-     * @remarks Changing the intensity will also change the light's power.
-     * When **{@link WebGLRenderer.useLegacyLights | legacy lighting mode} is disabled** — intensity is the luminous intensity of the light measured in candela (cd).
-     * @remarks Expects a `Float`
-     * @defaultValue `1`
-     */
-    intensity: number;
-
-    /**
-     * When **Default mode** — When distance is zero, light does not attenuate. When distance is non-zero,
-     * light will attenuate linearly from maximum intensity at the light's position down to zero at this distance from the light.
+     * Maximum range of the light. `0` means no limit.
      *
-     * When **{@link WebGLRenderer.useLegacyLights | legacy lighting mode} is disabled** — When distance is zero,
-     * light will attenuate according to inverse-square law to infinite distance.
-     * When distance is non-zero, light will attenuate according to inverse-square law until near the distance cutoff,
-     * where it will then attenuate quickly and smoothly to `0`. Inherently, cutoffs are not physically correct.
-     * @remarks Expects a `Float`
-     * @defaultValue `0.0`
+     * @default 0
      */
     distance: number;
-
     /**
-     * Maximum extent of the spotlight, in radians, from its direction.
-     * @remarks Should be no more than `Math.PI/2`.
-     * @remarks Expects a `Float`
-     * @defaultValue `Math.PI / 3`
+     * Maximum angle of light dispersion from its direction whose upper bound is `Math.PI/2`.
+     *
+     * @default Math.PI/3
      */
     angle: number;
-
     /**
-     * The amount the light dims along the distance of the light.
-     * In context of physically-correct rendering the default value should not be changed.
-     * @remarks Expects a `Float`
-     * @defaultValue `2`
+     * Percent of the spotlight cone that is attenuated due to penumbra.
+     * Value range is `[0,1]`.
+     *
+     * @default 0
      */
-    decay: number;
-
+    penumbra: number;
     /**
-     * A {@link THREE.SpotLightShadow | SpotLightShadow} used to calculate shadows for this light.
-     * @defaultValue `new THREE.SpotLightShadow()`
+     * The amount the light dims along the distance of the light. In context of
+     * physically-correct rendering the default value should not be changed.
+     *
+     * @default 2
      */
-    shadow: SpotLightShadow;
-
+    decay: number;
     /**
-     * The light's power.
-     * @remarks Changing the power will also change the light's intensity.
-     * When **{@link WebGLRenderer.useLegacyLights | legacy lighting mode} is disabled** —  power is the luminous power of the light measured in lumens (lm).
-     * @remarks Expects a `Float`
+     * A texture used to modulate the color of the light. The spot light
+     * color is mixed with the RGB value of this texture, with a ratio
+     * corresponding to its alpha value. The cookie-like masking effect is
+     * reproduced using pixel values (0, 0, 0, 1-cookie_value).
+     *
+     * *Warning*: This property is disabled if {@link Object3D#castShadow} is set to `false`.
+     *
+     * @default null
      */
-    power: number;
-
+    map: Texture | null;
     /**
-     * Percent of the {@link SpotLight} cone that is attenuated due to penumbra.
-     * @remarks Takes values between zero and 1.
-     * @remarks Expects a `Float`
-     * @defaultValue `0.0`
+     * This property holds the light's shadow configuration.
      */
-    penumbra: number;
-
+    shadow: SpotLightShadow;
+    set power(power: number);
     /**
-     * A {@link THREE.Texture | Texture} used to modulate the color of the light.
-     * The spot light color is mixed with the _RGB_ value of this texture, with a ratio corresponding to its alpha value.
-     * The cookie-like masking effect is reproduced using pixel values (0, 0, 0, 1-cookie_value).
-     * @remarks **Warning**: {@link SpotLight.map} is disabled if {@link SpotLight.castShadow} is `false`.
+     * The light's power. Power is the luminous power of the light measured in lumens (lm).
+     *  Changing the power will also change the light's intensity.
      */
-    map: Texture | null;
-
+    get power(): number;
+    copy(source: SpotLight, recursive?: boolean): this;
     toJSON(meta?: JSONMeta): SpotLightJSON;
 }

three/src/lights/SpotLightShadow.d.ts

@@ -2,73 +2,31 @@ import { PerspectiveCamera } from "../cameras/PerspectiveCamera.js";
 import { LightShadow } from "./LightShadow.js";
 
 /**
- * This is used internally by {@link SpotLight | SpotLights} for calculating shadows.
- * @example
- * ```typescript
- * //Create a WebGLRenderer and turn on shadows in the renderer
- * const renderer = new THREE.WebGLRenderer();
- * renderer.shadowMap.enabled = true;
- * renderer.shadowMap.type = THREE.PCFSoftShadowMap; // default THREE.PCFShadowMap
- * //Create a SpotLight and turn on shadows for the light
- * const light = new THREE.SpotLight(0xffffff);
- * light.castShadow = true; // default false
- * scene.add(light);
- * //Set up shadow properties for the light
- * light.shadow.mapSize.width = 512; // default
- * light.shadow.mapSize.height = 512; // default
- * light.shadow.camera.near = 0.5; // default
- * light.shadow.camera.far = 500; // default
- * light.shadow.focus = 1; // default
- * //Create a sphere that cast shadows (but does not receive them)
- * const sphereGeometry = new THREE.SphereGeometry(5, 32, 32);
- * const sphereMaterial = new THREE.MeshStandardMaterial({
- *     color: 0xff0000
- * });
- * const sphere = new THREE.Mesh(sphereGeometry, sphereMaterial);
- * sphere.castShadow = true; //default is false
- * sphere.receiveShadow = false; //default
- * scene.add(sphere);
- * //Create a plane that receives shadows (but does not cast them)
- * const planeGeometry = new THREE.PlaneGeometry(20, 20, 32, 32);
- * const planeMaterial = new THREE.MeshStandardMaterial({
- *     color: 0x00ff00
- * })
- * const plane = new THREE.Mesh(planeGeometry, planeMaterial);
- * plane.receiveShadow = true;
- * scene.add(plane);
- * //Create a helper for the shadow camera (optional)
- * const helper = new THREE.CameraHelper(light.shadow.camera);
- * scene.add(helper);
- * ```
- * @see {@link https://threejs.org/docs/index.html#api/en/lights/shadows/SpotLightShadow | Official Documentation}
- * @see {@link https://github.com/mrdoob/three.js/blob/master/src/lights/SpotLightShadow.js | Source}
+ * Represents the shadow configuration of directional lights.
  */
 export class SpotLightShadow extends LightShadow<PerspectiveCamera> {
     /**
-     * Read-only flag to check if a given object is of type {@link SpotLightShadow}.
-     * @remarks This is a _constant_ value
-     * @defaultValue `true`
+     * Constructs a new spot light shadow.
      */
-    readonly isSpotLightShadow: true;
-
+    constructor();
     /**
-     * The light's view of the world.
-     * @remarks This is used to generate a depth map of the scene; objects behind other objects from the light's perspective will be in shadow.
-     * @remarks
-     * The {@link THREE.PerspectiveCamera.fov | fov} will track the {@link THREE.SpotLight.angle | angle} property
-     * of the owning {@link SpotLight | SpotLight} via the {@link SpotLightShadow.update | update} method.
-     * Similarly, the {@link THREE.PerspectiveCamera.aspect | aspect} property will track the aspect of the {@link LightShadow.mapSize | mapSize}.
-     * If the {@link SpotLight.distance | distance} property of the light is set, the {@link THREE.PerspectiveCamera.far | far} clipping plane will track that, otherwise it defaults to `500`.
-     * @defaultValue is a {@link THREE.PerspectiveCamera | PerspectiveCamera} with {@link THREE.PerspectiveCamera.near | near} clipping plane at `0.5`.
+     * This flag can be used for type testing.
+     *
+     * @default true
      */
-    camera: PerspectiveCamera;
-
+    readonly isSpotLightShadow: boolean;
     /**
-     * Used to focus the shadow camera.
-     * @remarks The camera's field of view is set as a percentage of the spotlight's field-of-view. Range is `[0, 1]`. 0`.
-     * @defaultValue `1`
+     * Used to focus the shadow camera. The camera's field of view is set as a
+     * percentage of the spotlight's field-of-view. Range is `[0, 1]`.
+     *
+     * @default 1
      */
     focus: number;
-
+    /**
+     * Texture aspect ratio.
+     *
+     * @default 1
+     */
     aspect: number;
+    copy(source: SpotLightShadow): this;
 }

three/src/lights/webgpu/IESSpotLight.d.ts

@@ -1,6 +1,18 @@
 import { Texture } from "../../textures/Texture.js";
 import { SpotLight } from "../SpotLight.js";
 
-export default class IESSpotLight extends SpotLight {
+/**
+ * A IES version of {@link SpotLight}. Can only be used with {@link WebGPURenderer}.
+ */
+declare class IESSpotLight extends SpotLight {
+    /**
+     * The IES map. It's a lookup table that stores normalized attenuation factors
+     * (0.0 to 1.0) that represent the light's intensity at a specific angle.
+     *
+     * @default null
+     */
     iesMap: Texture | null;
+    copy(source: IESSpotLight, recursive?: boolean): this;
 }
+
+export default IESSpotLight;

three/src/lights/webgpu/ProjectorLight.d.ts

@@ -1,17 +1,16 @@
-import { ColorRepresentation } from "../../math/Color.js";
 import { SpotLight } from "../SpotLight.js";
 
+/**
+ * A projector light version of {@link SpotLight}. Can only be used with {@link WebGPURenderer}.
+ */
 declare class ProjectorLight extends SpotLight {
+    /**
+     * Aspect ratio of the light. Set to `null` to use the texture aspect ratio.
+     *
+     * @default null
+     */
     aspect: number | null;
-
-    constructor(
-        color?: ColorRepresentation,
-        intensity?: number,
-        distance?: number,
-        angle?: number,
-        penumbra?: number,
-        decay?: number,
-    );
+    copy(source: ProjectorLight, recursive?: boolean): this;
 }
 
 export default ProjectorLight;

three/src/materials/MeshLambertMaterial.d.ts

@@ -180,6 +180,12 @@ export interface MeshLambertMaterialProperties extends MaterialProperties {
      * @default 1
      */
     reflectivity: number;
+    /**
+     * Scales the effect of the environment map by multiplying its color.
+     *
+     * @default 1
+     */
+    envMapIntensity: number;
     /**
      * The index of refraction (IOR) of air (approximately 1) divided by the
      * index of refraction of the material. It is used with environment mapping

three/src/materials/MeshPhongMaterial.d.ts

@@ -194,6 +194,12 @@ export interface MeshPhongMaterialProperties extends MaterialProperties {
      * @default 1
      */
     reflectivity: number;
+    /**
+     * Scales the effect of the environment map by multiplying its color.
+     *
+     * @default 1
+     */
+    envMapIntensity: number;
     /**
      * The index of refraction (IOR) of air (approximately 1) divided by the
      * index of refraction of the material. It is used with environment mapping

three/src/materials/nodes/Line2NodeMaterial.d.ts

@@ -4,12 +4,6 @@ import { MapColorPropertiesToColorRepresentations } from "../Material.js";
 import NodeMaterial, { NodeMaterialNodeProperties } from "./NodeMaterial.js";
 
 export interface Line2NodeMaterialNodeProperties extends NodeMaterialNodeProperties {
-    /**
-     * Whether vertex colors should be used or not.
-     *
-     * @default false
-     */
-    useColor: boolean;
     /**
      * The dash offset.
      *

three/src/materials/nodes/LineBasicNodeMaterial.d.ts

@@ -15,8 +15,6 @@ export interface LineBasicNodeMaterialParameters
 
 /**
  * Node material version of {@link LineBasicMaterial}.
- *
- * @augments NodeMaterial
  */
 declare class LineBasicNodeMaterial extends NodeMaterial {
     /**
@@ -28,8 +26,6 @@ declare class LineBasicNodeMaterial extends NodeMaterial {
     /**
      * This flag can be used for type testing.
      *
-     * @type {boolean}
-     * @readonly
      * @default true
      */
     readonly isLineBasicNodeMaterial: boolean;

three/src/materials/nodes/MeshBasicNodeMaterial.d.ts

@@ -5,6 +5,7 @@ import { MapColorPropertiesToColorRepresentations } from "../Material.js";
 import { MeshBasicMaterialParameters, MeshBasicMaterialProperties } from "../MeshBasicMaterial.js";
 import NodeMaterial, { NodeMaterialNodeProperties } from "./NodeMaterial.js";
 
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface MeshBasicNodeMaterialNodeProperties extends NodeMaterialNodeProperties {
 }
 
@@ -28,8 +29,6 @@ declare class MeshBasicNodeMaterial extends NodeMaterial {
     /**
      * This flag can be used for type testing.
      *
-     * @type {boolean}
-     * @readonly
      * @default true
      */
     readonly isMeshBasicNodeMaterial: boolean;

three/src/materials/nodes/MeshLambertNodeMaterial.d.ts

@@ -29,8 +29,6 @@ declare class MeshLambertNodeMaterial extends NodeMaterial {
     /**
      * This flag can be used for type testing.
      *
-     * @type {boolean}
-     * @readonly
      * @default true
      */
     readonly isMeshLambertNodeMaterial: boolean;

three/src/materials/nodes/MeshNormalNodeMaterial.d.ts

@@ -25,8 +25,6 @@ declare class MeshNormalNodeMaterial extends NodeMaterial {
     constructor(parameters?: MeshNormalNodeMaterialParameters);
     /**
      * This flag can be used for type testing.
-     *
-     * @type {boolean}
      */
     readonly isMeshNormalNodeMaterial: boolean;
     setValues(values?: MeshNormalNodeMaterialParameters): void;

three/src/materials/nodes/MeshSSSNodeMaterial.d.ts

@@ -1,4 +1,3 @@
-import InputNode from "../../nodes/core/InputNode.js";
 import { LightingModelDirectInput } from "../../nodes/core/LightingModel.js";
 import Node from "../../nodes/core/Node.js";
 import NodeBuilder from "../../nodes/core/NodeBuilder.js";
@@ -58,23 +57,23 @@ export interface MeshSSSNodeMaterialNodeProperties extends MeshPhysicalNodeMater
     /**
      * Represents the distortion factor.
      */
-    thicknessDistortionNode: InputNode<number>;
+    thicknessDistortionNode: Node<"float">;
     /**
      * Represents the thickness ambient factor.
      */
-    thicknessAmbientNode: InputNode<number>;
+    thicknessAmbientNode: Node<"float">;
     /**
      * Represents the thickness attenuation.
      */
-    thicknessAttenuationNode: InputNode<number>;
+    thicknessAttenuationNode: Node<"float">;
     /**
      * Represents the thickness power.
      */
-    thicknessPowerNode: InputNode<number>;
+    thicknessPowerNode: Node<"float">;
     /**
      * Represents the thickness scale.
      */
-    thicknessScaleNode: InputNode<number>;
+    thicknessScaleNode: Node<"float">;
 }
 
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
@@ -87,8 +86,6 @@ export interface MeshSSSNodeMaterialParameters
 /**
  * This node material is an experimental extension of {@link MeshPhysicalNodeMaterial}
  * that implements a Subsurface scattering (SSS) term.
- *
- * @augments MeshPhysicalNodeMaterial
  */
 declare class MeshSSSNodeMaterial extends MeshPhysicalNodeMaterial {
     constructor(parameters?: MeshSSSNodeMaterialParameters);

three/src/materials/nodes/MeshToonNodeMaterial.d.ts

@@ -16,8 +16,6 @@ export interface MeshToonNodeMaterialParameters
 
 /**
  * Node material version of {@link MeshToonMaterial}.
- *
- * @augments NodeMaterial
  */
 declare class MeshToonNodeMaterial extends NodeMaterial {
     /**
@@ -29,8 +27,6 @@ declare class MeshToonNodeMaterial extends NodeMaterial {
     /**
      * This flag can be used for type testing.
      *
-     * @type {boolean}
-     * @readonly
      * @default true
      */
     readonly isMeshToonNodeMaterial: boolean;

three/src/materials/nodes/NodeMaterial.d.ts

@@ -88,7 +88,7 @@ export interface NodeMaterialNodeProperties {
      *
      * @default null
      */
-    colorNode: Node | null;
+    colorNode: Node<"float"> | Node<"vec2"> | Node<"vec3"> | Node<"vec4"> | Node<"color"> | null;
     /**
      * The normals of node materials are by default inferred from the `normalMap`/`normalScale`
      * or `bumpMap`/`bumpScale` properties. This node property allows to overwrite the default
@@ -153,6 +153,12 @@ export interface NodeMaterialNodeProperties {
      * @default null
      */
     maskNode: Node | null;
+    /**
+     * This node can be used to implement a shadow mask for the material.
+     *
+     * @default null
+     */
+    maskShadowNode: Node | null;
     /**
      * The local vertex positions are computed based on multiple factors like the
      * attribute data, morphing or skinning. This node property allows to overwrite
@@ -181,7 +187,7 @@ export interface NodeMaterialNodeProperties {
      *
      * @default null
      */
-    geometryNode: (() => Node) | null;
+    geometryNode: Node | null;
     /**
      * Allows to overwrite depth values in the fragment shader.
      *
@@ -278,7 +284,7 @@ export interface NodeMaterialNodeProperties {
      *
      * @default null
      */
-    contextNode: ContextNode | null;
+    contextNode: ContextNode<unknown> | null;
 }
 
 // eslint-disable-next-line @typescript-eslint/no-empty-interface

three/src/materials/nodes/SpriteNodeMaterial.d.ts

@@ -28,7 +28,6 @@ export interface SpriteNodeMaterialNodeProperties extends NodeMaterialNodeProper
     /**
      * Whether to use size attenuation or not.
      *
-     * @type {boolean}
      * @default true
      */
     get sizeAttenuation(): boolean;
@@ -55,8 +54,6 @@ declare class SpriteNodeMaterial extends NodeMaterial {
     /**
      * This flag can be used for type testing.
      *
-     * @type {boolean}
-     * @readonly
      * @default true
      */
     readonly isSpriteNodeMaterial: boolean;

three/src/materials/nodes/VolumeNodeMaterial.d.ts

@@ -32,8 +32,6 @@ export interface VolumeNodeMaterialParameters
 
 /**
  * Volume node material.
- *
- * @augments NodeMaterial
  */
 declare class VolumeNodeMaterial extends NodeMaterial {
     /**