@types/three 0.167.1 → 0.168.0

three/README.md

@@ -8,8 +8,8 @@ This package contains type definitions for three (https://threejs.org/).
 Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/three.
 
 ### Additional Details
- * Last updated: Fri, 26 Jul 2024 22:07:36 GMT
- * Dependencies: [@tweenjs/tween.js](https://npmjs.com/package/@tweenjs/tween.js), [@types/stats.js](https://npmjs.com/package/@types/stats.js), [@types/webxr](https://npmjs.com/package/@types/webxr), [fflate](https://npmjs.com/package/fflate), [meshoptimizer](https://npmjs.com/package/meshoptimizer)
+ * Last updated: Fri, 30 Aug 2024 17:36:33 GMT
+ * Dependencies: [@tweenjs/tween.js](https://npmjs.com/package/@tweenjs/tween.js), [@types/stats.js](https://npmjs.com/package/@types/stats.js), [@types/webxr](https://npmjs.com/package/@types/webxr), [@webgpu/types](https://npmjs.com/package/@webgpu/types), [fflate](https://npmjs.com/package/fflate), [meshoptimizer](https://npmjs.com/package/meshoptimizer)
 
 # Credits
 These definitions were written by [Josh Ellis](https://github.com/joshuaellis), and [Nathan Bierema](https://github.com/Methuselah96).

three/examples/jsm/Addons.d.ts

@@ -100,7 +100,6 @@ export * from "./loaders/KMZLoader.js";
 export * from "./loaders/KTX2Loader.js";
 export * from "./loaders/KTXLoader.js";
 export * from "./loaders/LDrawLoader.js";
-export * from "./loaders/LogLuvLoader.js";
 export * from "./loaders/LottieLoader.js";
 export * from "./loaders/LUT3dlLoader.js";
 export * from "./loaders/LUTCubeLoader.js";
@@ -170,8 +169,13 @@ export * from "./objects/ReflectorForSSRPass.js";
 export * from "./objects/Refractor.js";
 export * from "./objects/ShadowMesh.js";
 export * from "./objects/Sky.js";
+export * from "./objects/SkyMesh.js";
 export * from "./objects/Water.js";
 export { Water as Water2 } from "./objects/Water2.js";
+export type { WaterOptions as Water2Options } from "./objects/Water2.js";
+export { WaterMesh as Water2Mesh } from "./objects/Water2Mesh.js";
+export type { WaterMeshOptions as Water2MeshOptions } from "./objects/Water2Mesh.js";
+export * from "./objects/WaterMesh.js";
 
 export * from "./physics/AmmoPhysics.js";
 export * from "./physics/RapierPhysics.js";

three/examples/jsm/capabilities/WebGL.d.ts

@@ -1,9 +1,17 @@
-// tslint:disable-next-line:no-unnecessary-class
 export default class WebGL {
-    static isWebGLAvailable(): boolean;
     static isWebGL2Available(): boolean;
     static isColorSpaceAvailable(colorSpace: PredefinedColorSpace): boolean;
-    static getWebGLErrorMessage(): HTMLElement;
     static getWebGL2ErrorMessage(): HTMLElement;
     static getErrorMessage(version: number): HTMLElement;
+
+    /**
+     * @deprecated isWebGLAvailable() has been deprecated and will be removed in r178. Use isWebGL2Available() instead.
+     */
+    static isWebGLAvailable(): boolean;
+
+    /**
+     * @deprecated getWebGLErrorMessage() has been deprecated and will be removed in r178. Use getWebGL2ErrorMessage()
+     * instead.
+     */
+    static getWebGLErrorMessage(): HTMLElement;
 }

three/examples/jsm/controls/ArcballControls.d.ts

@@ -1,169 +1,203 @@
-import { Camera, EventDispatcher, Raycaster, Scene, Vector3 } from "three";
+import { Camera, Controls, Raycaster, Scene } from "three";
 
-export enum ArcballControlsMouseActionOperations {
-    PAN = "PAN",
-    ROTATE = "ROTATE",
-    ZOOM = "ZOOM",
-    FOV = "FOV",
-}
+export type ArcballControlsMouseActionOperation = "PAN" | "ROTATE" | "ZOOM" | "FOV";
 
 export type ArcballControlsMouseActionMouse = 0 | 1 | 2 | "WHEEL";
 
-export enum ArcballControlsMouseActionKeys {
-    SHIFT = "SHIFT",
-    CTRL = "CTRL",
-}
+export type ArcballControlsMouseActionKey = "SHIFT" | "CTRL";
 
 export interface ArcballControlsEventMap {
-    change: {};
-    start: {};
-    end: {};
-}
-
-export class ArcballControls extends EventDispatcher<ArcballControlsEventMap> {
-    camera: Camera | null;
-    domElement: HTMLElement;
-    scene?: Scene | null | undefined;
-
     /**
-     * @default 500
+     * Fires when the camera has been transformed by the controls.
      */
-    focusAnimationTime: number;
+    change: {};
 
     /**
-     * @default true
+     * Fires when an interaction was initiated.
      */
-    enabled: boolean;
+    start: {};
 
     /**
-     * @default true
+     * Fires when an interaction has finished.
      */
-    enablePan: boolean;
+    end: {};
+}
 
+/**
+ * Arcball controls allow the camera to be controlled by a virtual trackball with full touch support and advanced
+ * navigation functionality.
+ */
+declare class ArcballControls extends Controls<ArcballControlsEventMap> {
     /**
-     * @default true
+     * The scene rendered by the camera.
      */
-    enableRotate: boolean;
+    scene: Scene | null;
 
     /**
-     * @default true
+     * The size of the gizmo relative to the screen width and height. Default is 0.67.
      */
-    enableZoom: boolean;
+    radiusFactor: number;
 
     /**
-     * @default true
+     * Duration time of focus animation.
      */
-    enableGizmos: boolean;
+    focusAnimationTime: number;
 
     /**
-     * @default true
+     * If true, camera's near and far values will be adjusted every time zoom is performed trying to mantain the same
+     * visible portion given by initial near and far values ( {@link PerspectiveCamera} only ). Default is false.
      */
     adjustNearFar: boolean;
 
     /**
-     * @default 1.1
+     * The scaling factor used when performing zoom operation.
      */
     scaleFactor: number;
 
     /**
-     * @default 25
+     * The damping inertia used if [page:.enableAnimations] is set to true.
      */
     dampingFactor: number;
 
     /**
-     * @default 20
+     * Maximum angular velocity allowed on rotation animation start.
      */
-    wMax: number; // maximum angular velocity allowed
+    wMax: number;
 
     /**
-     * @default true
+     * Set to true to enable animations for rotation (damping) and focus operation. Default is true.
      */
-    enableAnimations: boolean; // if animations should be performed
+    enableAnimations: boolean;
 
     /**
-     * @default false
+     * When set to true, a grid will appear when panning operation is being performed (desktop interaction only). Default is false.
      */
-    enableGrid: boolean; // if grid should be showed during pan operation
+    enableGrid: boolean;
 
     /**
-     * @default false
+     * Set to true to make zoom become cursor centered.
      */
-    cursorZoom: boolean; // if wheel zoom should be cursor centered
+    cursorZoom: boolean;
 
     /**
-     * @default 5
+     * Speed of rotation. Default is 1.
      */
-    minFov: number;
+    rotateSpeed: number;
 
     /**
-     * @default 90
+     * Enable or disable camera panning. Default is true.
      */
-    maxFov: number;
+    enablePan: boolean;
+
+    /**
+     * Enable or disable camera rotation. Default is true.
+     */
+    enableRotate: boolean;
+
+    /**
+     * Enable or disable zooming of the camera.
+     */
+    enableZoom: boolean;
 
     /**
-     * @default 0
+     * How far you can dolly in ( {@link PerspectiveCamera} only ). Default is 0.
      */
     minDistance: number;
 
     /**
-     * @default Infinity
+     * How far you can dolly out ( {@link PerspectiveCamera} only ). Default is Infinity.
      */
     maxDistance: number;
 
     /**
-     * @default 0
+     * How far you can zoom in ( {@link OrthographicCamera} only ). Default is 0.
      */
     minZoom: number;
 
     /**
-     * @default Infinity
+     * How far you can zoom out ( {@link OrthographicCamera} only ). Default is Infinity.
      */
     maxZoom: number;
 
     /**
-     * @default Vector3(0,0,0)
+     * @param camera The camera to be controlled. The camera must not be a child of another object, unless that object
+     * is the scene itself.
+     * @param domElement The HTML element used for event listeners. (optional)
+     * @param scene The scene rendered by the camera. If not given, gizmos cannot be shown. (optional)
      */
-    target: Vector3;
+    constructor(camera: Camera, domElement?: HTMLElement | null, scene?: Scene | null);
 
     /**
-     * @default 0.67
+     * Set a new mouse action by specifying the operation to be performed and a mouse/key combination. In case of
+     * conflict, replaces the existing one.
+     * @param operation Operations can be specified as 'ROTATE', 'PAN', 'FOV' or 'ZOOM'.
+     * @param mouse Mouse inputs can be specified as mouse buttons 0, 1 and 2 or 'WHEEL' for wheel notches.
+     * @param key Keyboard modifiers can be specified as 'CTRL', 'SHIFT' or null if not needed.
      */
-    radiusFactor: number;
+    setMouseAction(
+        operation: ArcballControlsMouseActionOperation,
+        mouse: ArcballControlsMouseActionMouse,
+        key?: ArcballControlsMouseActionKey | null,
+    ): boolean;
 
     /**
-     * @default 1
+     * Removes a mouse action by specifying its mouse/key combination.
+     * @param mouse Mouse inputs can be specified as mouse buttons 0, 1 and 2 or 'WHEEL' for wheel notches.
+     * @param key Keyboard modifiers can be specified as 'CTRL', 'SHIFT' or null if not needed.
      */
-    rotateSpeed: number;
-
-    constructor(camera: Camera, domElement: HTMLElement, scene?: Scene | null);
-
-    getRaycaster(): Raycaster;
+    unsetMouseAction(mouse: ArcballControlsMouseActionMouse, key?: ArcballControlsMouseActionKey | null): boolean;
 
+    /**
+     * Make gizmos more or less visible.
+     */
     activateGizmos(isActive: boolean): void;
 
-    copyState(): void;
+    /**
+     * Set the camera to be controlled. Must be called in order to set a new camera to be controlled.
+     */
+    setCamera(camera: Camera): void;
 
-    pasteState(): void;
+    /**
+     * Set the visible property of gizmos.
+     */
+    setGizmosVisible(value: boolean): void;
 
-    saveState(): void;
+    /**
+     * Update the `radiusFactor` value, redraw the gizmo and send a `changeEvent` to visualise the changes.
+     */
+    setTbRadius(value: number): void;
 
+    /**
+     * Reset the controls to their state from either the last time the {@link .saveState} was called, or the initial
+     * state.
+     */
     reset(): void;
 
-    setCamera(camera: Camera): void;
-
-    setGizmosVisible(value: boolean): void;
+    /**
+     * Copy the current state to clipboard (as a readable JSON text).
+     */
+    copyState(): void;
 
-    setTbRadius(value: number): void;
+    /**
+     * Set the controls state from the clipboard, assumes that the clipboard stores a JSON text as saved from
+     * {@link .copyState}.
+     */
+    pasteState(): void;
 
-    setMouseAction(
-        operation: ArcballControlsMouseActionOperations,
-        mouse: ArcballControlsMouseActionMouse,
-        key?: ArcballControlsMouseActionKeys,
-    ): boolean;
+    /**
+     * Save the current state of the controls. This can later be recovered with {@link .reset}.
+     */
+    saveState(): void;
 
-    unsetMouseAction(mouse: ArcballControlsMouseActionMouse, key?: ArcballControlsMouseActionKeys): boolean;
+    /**
+     * Returns the {@link Raycaster} object that is used for user interaction. This object is shared between all
+     * instances of ArcballControls. If you set the [.layers]{@link Object3D.layers} property of the
+     * {@link ArcballControls}, you will also want to set the [.layers]{@link Raycaster.layers} property on the
+     * {@link Raycaster} with a matching value, or else the {@link ArcballControls} won't work as expected.
+     */
+    getRaycaster(): Raycaster;
 
     update(): void;
-
-    dispose(): void;
 }
+
+export { ArcballControls };

three/examples/jsm/controls/DragControls.d.ts

@@ -1,4 +1,4 @@
-import { Camera, EventDispatcher, Object3D, Raycaster } from "three";
+import { Camera, Controls, MOUSE, Object3D, Raycaster, TOUCH } from "three";
 
 export interface DragControlsEventMap {
     /**
@@ -27,21 +27,11 @@ export interface DragControlsEventMap {
     dragend: { object: Object3D };
 }
 
-export type DragControlsMode = "translate" | "rotate";
-
-export class DragControls extends EventDispatcher<DragControlsEventMap> {
-    /**
-     * Creates a new instance of DragControls.
-     * @param objects An array of draggable 3D objects.
-     * @param camera The camera of the rendered scene.
-     * @param domElement The HTML element used for event listeners.
-     */
-    constructor(objects: Object3D[], camera: Camera, domElement?: HTMLElement);
-
+declare class DragControls extends Controls<DragControlsEventMap> {
     /**
-     * Whether or not the controls are enabled.
+     * An array of draggable 3D objects.
      */
-    enabled: boolean;
+    objects: Object3D[];
 
     /**
      * Whether children of draggable objects can be dragged independently from their parent. Default is `true`.
@@ -54,44 +44,83 @@ export class DragControls extends EventDispatcher<DragControlsEventMap> {
      */
     transformGroup: boolean;
 
-    /**
-     * The current transformation mode. Possible values are `translate`, and `rotate`. Default is `translate`.
-     */
-    mode: DragControlsMode;
-
     /**
      * The speed at which the object will rotate when dragged in `rotate` mode. The higher the number the faster the
      * rotation. Default is `1`.
      */
     rotateSpeed: number;
 
+    /**
+     * The internal raycaster used for detecting 3D objects.
+     */
+    raycaster: Raycaster;
+
+    /**
+     * This object defines what type of actions are assigned to the available mouse buttons.
+     */
+    mouseButtons: {
+        LEFT?: MOUSE | null | undefined;
+        MIDDLE?: MOUSE | null | undefined;
+        RIGHT?: MOUSE | null | undefined;
+    };
+
+    /**
+     * This object defines what type of actions are assigned to what kind of touch interaction.
+     */
+    touches: { ONE?: TOUCH | null | undefined };
+
+    /**
+     * Creates a new instance of DragControls.
+     * @param objects An array of draggable 3D objects.
+     * @param camera The camera of the rendered scene.
+     * @param domElement The HTML element used for event listeners. (optional)
+     */
+    constructor(objects: Object3D[], camera: Camera, domElement?: HTMLElement | null);
+
     /**
      * Adds the event listeners of the controls.
      */
-    activate: () => void;
+    connect(): void;
 
     /**
      * Removes the event listeners of the controls.
      */
-    deactivate: () => void;
+    disconnect(): void;
 
     /**
      * Should be called if the controls is no longer required.
      */
-    dispose: () => void;
+    dispose(): void;
+
+    /**
+     * Returns the internal {@link Raycaster} instance that is used for intersection tests.
+     * @deprecated getRaycaster() has been deprecated. Use controls.raycaster instead.
+     */
+    getRaycaster(): Raycaster;
+
+    /**
+     * Sets an array of draggable objects by overwriting the existing one.
+     * @deprecated setObjects() has been deprecated. Use controls.objects instead.
+     */
+    setObjects(objects: readonly Object3D[]): void;
 
     /**
      * Returns the array of draggable objects.
+     * @deprecated getObjects() has been deprecated. Use controls.objects instead.
      */
-    getObjects: () => Object3D[];
+    getObjects(): Object3D[];
 
     /**
-     * Returns the internal {@link Raycaster} instance that is used for intersection tests.
+     * Adds the event listeners of the controls.
+     * @deprecated activate() has been renamed to connect().
      */
-    getRaycaster: () => Raycaster;
+    activate(): void;
 
     /**
-     * Sets an array of draggable objects by overwriting the existing one.
+     * Removes the event listeners of the controls.
+     * @deprecated deactivate() has been renamed to disconnect().
      */
-    setObjects: (objects: readonly Object3D[]) => void;
+    deactivate(): void;
 }
+
+export { DragControls };

three/examples/jsm/controls/FirstPersonControls.d.ts

@@ -1,31 +1,101 @@
-import { Camera, Vector3 } from "three";
+import { Camera, Controls, Vector3 } from "three";
 
-export class FirstPersonControls {
-    constructor(object: Camera, domElement?: HTMLElement);
-
-    object: Camera;
-    domElement: HTMLElement | Document;
-
-    enabled: boolean;
+/**
+ * This class is an alternative implementation of {@link FlyControls}.
+ */
+declare class FirstPersonControls extends Controls<{}> {
+    /**
+     * The movement speed. Default is *1*.
+     */
     movementSpeed: number;
+
+    /**
+     * The look around speed. Default is `0.005`.
+     */
     lookSpeed: number;
+
+    /**
+     * Whether or not it's possible to vertically look around. Default is `true`.
+     */
     lookVertical: boolean;
+
+    /**
+     * Whether or not the camera is automatically moved forward. Default is `false`.
+     */
     autoForward: boolean;
+
+    /**
+     * Whether or not it's possible to look around. Default is `true`.
+     */
     activeLook: boolean;
+
+    /**
+     * Whether or not the camera's height influences the forward movement speed. Default is `false`.
+     * Use the properties {@link .heightCoef}, {@link .heightMin} and {@link .heightMax} for configuration
+     */
     heightSpeed: boolean;
+
+    /**
+     * Determines how much faster the camera moves when it's y-component is near {@link .heightMax}. Default is *1*.
+     */
     heightCoef: number;
+
+    /**
+     * Lower camera height limit used for movement speed adjustment. Default is *0*.
+     */
     heightMin: number;
+
+    /**
+     * Upper camera height limit used for movement speed adjustment. Default is *1*.
+     */
     heightMax: number;
+
+    /**
+     * Whether or not looking around is vertically constrained by [{@link .verticalMin}, {@link .verticalMax}]. Default
+     * is `false`.
+     */
     constrainVertical: boolean;
+
+    /**
+     * How far you can vertically look around, lower limit. Range is 0 to Math.PI radians. Default is *0*.
+     */
     verticalMin: number;
+
+    /**
+     * How far you can vertically look around, upper limit. Range is 0 to Math.PI radians. Default is `Math.PI`.
+     */
     verticalMax: number;
+
+    /**
+     * Whether or not the mouse is pressed down. Read-only property.
+     */
     mouseDragOn: boolean;
 
+    /**
+     * Creates a new instance of {@link FirstPersonControls}.
+     * @param object The camera to be controlled.
+     * @param domElement The HTML element used for event listeners. (optional)
+     */
+    constructor(object: Camera, domElement?: HTMLElement);
+
+    /**
+     * Should be called if the application window is resized.
+     */
     handleResize(): void;
 
-    lookAt(x: Vector3): this;
-    lookAt(x: number, y: number, z: number): this;
+    /**
+     * Ensures the controls orient the camera towards the defined target position.
+     * @param vector A vector representing the target position.
+     */
+    lookAt(vector: Vector3): this;
 
-    update(delta: number): this;
-    dispose(): void;
+    /**
+     * Ensures the controls orient the camera towards the defined target position.
+     * @param x The x component of the world space position.
+     * @param y The y component of the world space position.
+     * @param z The z component of the world space position.
+     */
+    lookAt(x: number, y: number, z: number): this;
 }
+
+export { FirstPersonControls };

three/examples/jsm/controls/FlyControls.d.ts

@@ -1,20 +1,44 @@
-import { Camera, EventDispatcher } from "three";
+import { Camera, Controls } from "three";
 
 export interface FlyControlsEventMap {
+    /**
+     * Fires when the camera has been transformed by the controls.
+     */
     change: {};
 }
 
-export class FlyControls extends EventDispatcher<FlyControlsEventMap> {
-    constructor(object: Camera, domElement?: HTMLElement);
-
-    autoForward: boolean;
-    domElement: HTMLElement | Document;
-    dragToLook: boolean;
-    enabled: boolean;
+/**
+ * {@link FlyControls} enables a navigation similar to fly modes in DCC tools like Blender. You can arbitrarily
+ * transform the camera in 3D space without any limitations (e.g. focus on a specific target).
+ */
+declare class FlyControls extends Controls<FlyControlsEventMap> {
+    /**
+     * The movement speed. Default is `1`.
+     */
     movementSpeed: number;
-    object: Camera;
+
+    /**
+     * The rotation speed. Default is `0.005`.
+     */
     rollSpeed: number;
 
-    dispose(): void;
-    update(delta: number): void;
+    /**
+     * If set to `true`, you can only look around by performing a drag interaction. Default is `false`.
+     */
+    dragToLook: boolean;
+
+    /**
+     * If set to `true`, the camera automatically moves forward (and does not stop) when initially translated. Default
+     * is `false`.
+     */
+    autoForward: boolean;
+
+    /**
+     * Creates a new instance of {@link FlyControls}.
+     * @param object The camera to be controlled.
+     * @param domElement The HTML element used for event listeners. (optional)
+     */
+    constructor(object: Camera, domElement?: HTMLElement | null);
 }
+
+export { FlyControls };