@needle-tools/three 0.169.12 → 0.169.13

package/types/src/nodes/utils/TriplanarTexturesNode.d.ts

@@ -0,0 +1,36 @@
+import TextureNode from "../accessors/TextureNode.js";
+import Node from "../core/Node.js";
+import { NodeRepresentation, ShaderNodeObject } from "../tsl/TSLCore.js";
+
+export default class TriplanarTexturesNode extends Node {
+    textureXNode: TextureNode;
+    textureYNode: TextureNode | null;
+    textureZNode: TextureNode | null;
+
+    scaleNode: ShaderNodeObject<Node>;
+
+    positionNode: ShaderNodeObject<Node>;
+    normalNode: ShaderNodeObject<Node>;
+
+    constructor(
+        textureXNode: Node,
+        textureYNode?: TextureNode | null,
+        textureZNode?: TextureNode | null,
+        scaleNode?: ShaderNodeObject<Node>,
+        positionNode?: ShaderNodeObject<Node>,
+        normalNode?: ShaderNodeObject<Node>,
+    );
+}
+
+export const triplanarTextures: (
+    textureXNode: NodeRepresentation,
+    textureYNode?: NodeRepresentation,
+    textureZNode?: NodeRepresentation,
+    scaleNode?: NodeRepresentation,
+    positionNode?: NodeRepresentation,
+    normalNode?: NodeRepresentation,
+) => ShaderNodeObject<TriplanarTexturesNode>;
+export const triplanarTexture: (
+    texture: NodeRepresentation,
+    ...params: NodeRepresentation[]
+) => ShaderNodeObject<TriplanarTexturesNode>;

package/types/src/nodes/utils/UVUtils.d.ts

@@ -0,0 +1,14 @@
+import OperatorNode from "../math/OperatorNode.js";
+import { NodeRepresentation, ShaderNodeObject } from "../tsl/TSLCore.js";
+
+export const rotateUV: (
+    uv: NodeRepresentation,
+    rotation: NodeRepresentation,
+    center?: NodeRepresentation,
+) => ShaderNodeObject<OperatorNode>;
+
+export const spherizeUV: (
+    uv: NodeRepresentation,
+    strength: NodeRepresentation,
+    center?: NodeRepresentation,
+) => ShaderNodeObject<OperatorNode>;

package/types/src/nodes/utils/ViewportUtils.d.ts

@@ -0,0 +1,4 @@
+import Node from "../core/Node.js";
+import { NodeRepresentation, ShaderNodeObject } from "../tsl/TSLCore.js";
+
+export const viewportSafeUV: (uv?: NodeRepresentation | null) => ShaderNodeObject<Node>;

package/types/src/objects/BatchedMesh.d.ts

@@ -0,0 +1,230 @@
+import { Camera } from "../cameras/Camera.js";
+import { BufferGeometry } from "../core/BufferGeometry.js";
+import { Material } from "../materials/Material.js";
+import { Box3 } from "../math/Box3.js";
+import { Color } from "../math/Color.js";
+import { Matrix4 } from "../math/Matrix4.js";
+import { Sphere } from "../math/Sphere.js";
+import { Mesh } from "./Mesh.js";
+
+/**
+ * A special version of {@link Mesh} with multi draw batch rendering support. Use {@link BatchedMesh} if you have to
+ * render a large number of objects with the same material but with different world transformations. The  usage of
+ * {@link BatchedMesh} will help you to reduce the number of draw calls and thus improve the overall rendering
+ * performance in your application.
+ *
+ * If the {@link https://developer.mozilla.org/en-US/docs/Web/API/WEBGL_multi_draw WEBGL_multi_draw extension} is not
+ * supported then a less performant fallback is used.
+ *
+ * @example
+ * const box = new THREE.BoxGeometry( 1, 1, 1 );
+ * const sphere = new THREE.SphereGeometry( 1, 12, 12 );
+ * const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } );
+ *
+ * // initialize and add geometries into the batched mesh
+ * const batchedMesh = new BatchedMesh( 10, 5000, 10000, material );
+ * const boxGeometryId = batchedMesh.addGeometry( box );
+ * const sphereGeometryId = batchedMesh.addGeometry( sphere );
+ *
+ * // create instances of those geometries
+ * const boxInstancedId1 = batchedMesh.addInstance( boxGeometryId );
+ * const boxInstancedId2 = batchedMesh.addInstance( boxGeometryId );
+ *
+ * const sphereInstancedId1 = batchedMesh.addInstance( sphereGeometryId );
+ * const sphereInstancedId2 = batchedMesh.addInstance( sphereGeometryId );
+ *
+ * // position the geometries
+ * batchedMesh.setMatrixAt( boxInstancedId1, boxMatrix1 );
+ * batchedMesh.setMatrixAt( boxInstancedId2, boxMatrix2 );
+ *
+ * batchedMesh.setMatrixAt( sphereInstancedId1, sphereMatrix1 );
+ * batchedMesh.setMatrixAt( sphereInstancedId2, sphereMatrix2 );
+ *
+ * scene.add( batchedMesh );
+ *
+ * @also Example: {@link https://threejs.org/examples/#webgl_mesh_batch WebGL / mesh / batch}
+ */
+declare class BatchedMesh extends Mesh<BufferGeometry, Material> {
+    /**
+     * This bounding box encloses all instances of the {@link BatchedMesh}. Can be calculated with
+     * {@link .computeBoundingBox()}.
+     * @default null
+     */
+    boundingBox: Box3 | null;
+
+    /**
+     * This bounding sphere encloses all instances of the {@link BatchedMesh}. Can be calculated with
+     * {@link .computeBoundingSphere()}.
+     * @default null
+     */
+    boundingSphere: Sphere | null;
+
+    customSort: ((this: this, list: Array<{ start: number; count: number; z: number }>, camera: Camera) => void) | null;
+
+    /**
+     * If true then the individual objects within the {@link BatchedMesh} are frustum culled.
+     * @default true
+     */
+    perObjectFrustumCulled: boolean;
+
+    /**
+     * If true then the individual objects within the {@link BatchedMesh} are sorted to improve overdraw-related
+     * artifacts. If the material is marked as "transparent" objects are rendered back to front and if not then they are
+     * rendered front to back.
+     * @default true
+     */
+    sortObjects: boolean;
+
+    /**
+     * The maximum number of individual geometries that can be stored in the {@link BatchedMesh}. Read only.
+     */
+    get maxInstanceCount(): number;
+
+    /**
+     * Read-only flag to check if a given object is of type {@link BatchedMesh}.
+     */
+    readonly isBatchedMesh: true;
+
+    /**
+     * @param maxInstanceCount the max number of individual geometries planned to be added.
+     * @param maxVertexCount the max number of vertices to be used by all geometries.
+     * @param maxIndexCount the max number of indices to be used by all geometries.
+     * @param material an instance of {@link Material}. Default is a new {@link MeshBasicMaterial}.
+     */
+    constructor(maxInstanceCount: number, maxVertexCount: number, maxIndexCount?: number, material?: Material);
+
+    /**
+     * Computes the bounding box, updating {@link .boundingBox} attribute.
+     * Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are `null`.
+     */
+    computeBoundingBox(): void;
+
+    /**
+     * Computes the bounding sphere, updating {@link .boundingSphere} attribute.
+     * Bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are `null`.
+     */
+    computeBoundingSphere(): void;
+
+    /**
+     * Frees the GPU-related resources allocated by this instance. Call this method whenever this instance is no longer
+     * used in your app.
+     */
+    dispose(): this;
+
+    /**
+     * Takes a sort a function that is run before render. The function takes a list of instances to sort and a camera.
+     * The objects in the list include a "z" field to perform a depth-ordered sort with.
+     */
+    setCustomSort(
+        sortFunction:
+            | ((this: this, list: Array<{ start: number; count: number; z: number }>, camera: Camera) => void)
+            | null,
+    ): this;
+
+    /**
+     * Get the color of the defined geometry.
+     * @param instanceId The id of an instance to get the color of.
+     * @param target The target object to copy the color in to.
+     */
+    getColorAt(instanceId: number, target: Color): void;
+
+    /**
+     * Get the local transformation matrix of the defined instance.
+     * @param instanceId The id of an instance to get the matrix of.
+     * @param target This 4x4 matrix will be set to the local transformation matrix of the defined instance.
+     */
+    getMatrixAt(instanceId: number, target: Matrix4): Matrix4;
+
+    /**
+     * Get whether the given instance is marked as "visible" or not.
+     * @param instanceId The id of an instance to get the visibility state of.
+     */
+    getVisibleAt(instanceId: number): boolean;
+
+    /**
+     * Get the range representing the subset of triangles related to the attached geometry, indicating the starting
+     * offset and count, or `null` if invalid.
+     *
+     * Return an object of the form: { start: Integer, count: Integer }
+     * @param geometryId The id of the geometry to get the range of.
+     * @param target Optional target object to copy the range in to.
+     */
+    getGeometryRangeAt(
+        geometryId: number,
+        target?: { start: number; count: number },
+    ): { start: number; count: number } | null;
+
+    /**
+     * Get the geometryIndex of the defined instance.
+     * @param instanceId The id of an instance to get the geometryIndex of.
+     */
+    getGeometryIdAt(instanceId: number): number;
+
+    /**
+     * Sets the given color to the defined geometry instance.
+     * @param instanceId The id of the instance to set the color of.
+     * @param color The color to set the instance to.
+     */
+    setColorAt(instanceId: number, color: Color): void;
+
+    /**
+     * Sets the given local transformation matrix to the defined instance.
+     * @param instanceId The id of an instance to set the matrix of.
+     * @param matrix A 4x4 matrix representing the local transformation of a single instance.
+     */
+    setMatrixAt(instanceId: number, matrix: Matrix4): this;
+
+    /**
+     * Sets the visibility of the instance at the given index.
+     * @param instanceId The id of the instance to set the visibility of.
+     * @param visible A boolean value indicating the visibility state.
+     */
+    setVisibleAt(instanceId: number, visible: boolean): this;
+
+    /**
+     * Sets the geometryIndex of the instance at the given index.
+     * @param instanceId The id of the instance to set the geometryIndex of.
+     * @param geometryId The geometryIndex to be use by the instance.
+     */
+    setGeometryIdAt(instanceId: number, geometryId: number): this;
+
+    /**
+     * Adds the given geometry to the {@link BatchedMesh} and returns the associated index referring to it.
+     * @param geometry The geometry to add into the {@link BatchedMesh}.
+     * @param reservedVertexRange Optional parameter specifying the amount of vertex buffer space to reserve for the
+     * added geometry. This is necessary if it is planned to set a new geometry at this index at a later time that is
+     * larger than the original geometry. Defaults to the length of the given geometry vertex buffer.
+     * @param reservedIndexRange Optional parameter specifying the amount of index buffer space to reserve for the added
+     * geometry. This is necessary if it is planned to set a new geometry at this index at a later time that is larger
+     * than the original geometry. Defaults to the length of the given geometry index buffer.
+     */
+    addGeometry(geometry: BufferGeometry, reservedVertexRange?: number, reservedIndexRange?: number): number;
+
+    /**
+     * Adds a new instance to the {@link BatchedMesh} using the geometry of the given geometryId and returns a new id
+     * referring to the new instance to be used by other functions.
+     * @param geometryId The id of a previously added geometry via "addGeometry" to add into the {@link BatchedMesh} to
+     * render.
+     */
+    addInstance(geometryId: number): number;
+
+    /**
+     * Removes an existing instance from the BatchedMesh using the given instanceId.
+     * @param instanceId The id of an instance to remove from the BatchedMesh that was previously added via
+     * "addInstance".
+     */
+    deleteInstance(instanceId: number): this;
+
+    /**
+     * Replaces the geometry at `geometryId` with the provided geometry. Throws an error if there is not enough space
+     * reserved for geometry. Calling this will change all instances that are rendering that geometry.
+     * @param geometryId Which geometry id to replace with this geometry.
+     * @param geometry The geometry to substitute at the given geometry id.
+     */
+    setGeometryAt(geometryId: number, geometry: BufferGeometry): number;
+
+    getBoundingBoxAt(geometryId: number, target: Box3): Box3 | null;
+    getBoundingSphereAt(geometryId: number, target: Sphere): Sphere | null;
+}
+
+export { BatchedMesh };

package/types/src/objects/Bone.d.ts

@@ -0,0 +1,36 @@
+import { Object3D, Object3DEventMap } from "../core/Object3D.js";
+
+/**
+ * A {@link Bone} which is part of a {@link THREE.Skeleton | Skeleton}
+ * @remarks
+ * The skeleton in turn is used by the {@link THREE.SkinnedMesh | SkinnedMesh}
+ * Bones are almost identical to a blank {@link THREE.Object3D | Object3D}.
+ * @example
+ * ```typescript
+ * const root = new THREE.Bone();
+ * const child = new THREE.Bone();
+ * root.add(child);
+ * child.position.y = 5;
+ * ```
+ * @see {@link https://threejs.org/docs/index.html#api/en/objects/Bone | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/objects/Bone.js | Source}
+ */
+export class Bone<TEventMap extends Object3DEventMap = Object3DEventMap> extends Object3D<TEventMap> {
+    /**
+     * Creates a new {@link Bone}.
+     */
+    constructor();
+
+    /**
+     * Read-only flag to check if a given object is of type {@link Bone}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isBone: true;
+
+    /**
+     * @override
+     * @defaultValue `Bone`
+     */
+    override readonly type: string | "Bone";
+}

package/types/src/objects/Group.d.ts

@@ -0,0 +1,37 @@
+import { Object3D, Object3DEventMap } from "../core/Object3D.js";
+
+/**
+ * Its purpose is to make working with groups of objects syntactically clearer.
+ * @remarks This is almost identical to an {@link Object3D | Object3D}
+ * @example
+ * ```typescript
+ * const geometry = new THREE.BoxGeometry(1, 1, 1);
+ * const material = new THREE.MeshBasicMaterial({
+ *     color: 0x00ff00
+ * });
+ * const cubeA = new THREE.Mesh(geometry, material);
+ * cubeA.position.set(100, 100, 0);
+ * const cubeB = new THREE.Mesh(geometry, material);
+ * cubeB.position.set(-100, -100, 0);
+ * //create a {@link Group} and add the two cubes
+ * //These cubes can now be rotated / scaled etc as a {@link Group}  * const {@link Group} = new THREE.Group();
+ * group.add(cubeA);
+ * group.add(cubeB);
+ * scene.add(group);
+ * ```
+ * @see {@link https://threejs.org/docs/index.html#api/en/objects/Group | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/objects/Group.js | Source}
+ */
+export class Group<TEventMap extends Object3DEventMap = Object3DEventMap> extends Object3D<TEventMap> {
+    /**
+     * Creates a new {@link Group}.
+     */
+    constructor();
+
+    /**
+     * Read-only flag to check if a given object is of type {@link Group}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isGroup: true;
+}

package/types/src/objects/InstancedMesh.d.ts

@@ -0,0 +1,179 @@
+import { BufferAttributeJSON } from "./../core/BufferAttribute.js";
+import { BufferGeometry } from "../core/BufferGeometry.js";
+import { InstancedBufferAttribute } from "../core/InstancedBufferAttribute.js";
+import { JSONMeta, Object3DEventMap } from "../core/Object3D.js";
+import { Material } from "../materials/Material.js";
+import { Box3 } from "../math/Box3.js";
+import { Color } from "../math/Color.js";
+import { Matrix4 } from "../math/Matrix4.js";
+import { Sphere } from "../math/Sphere.js";
+import { DataTexture } from "../textures/DataTexture.js";
+import { Mesh, MeshJSONObject } from "./Mesh.js";
+
+export interface InstancedMeshJSONObject extends MeshJSONObject {
+    count: number;
+    instanceMatrix: BufferAttributeJSON;
+    instanceColor?: BufferAttributeJSON;
+}
+
+export interface InstancedMeshJSON extends MeshJSONObject {
+    object: InstancedMeshJSONObject;
+}
+
+export interface InstancedMeshEventMap extends Object3DEventMap {
+    dispose: {};
+}
+
+/**
+ * A special version of {@link THREE.Mesh | Mesh} with instanced rendering support
+ * @remarks
+ * Use {@link InstancedMesh} if you have to render a large number of objects with the same geometry and material(s) but with different world transformations
+ * @remarks
+ * The usage of {@link InstancedMesh} will help you to reduce the number of draw calls and thus improve the overall rendering performance in your application.
+ * @see Example: {@link https://threejs.org/examples/#webgl_instancing_dynamic | WebGL / instancing / dynamic}
+ * @see Example: {@link https://threejs.org/examples/#webgl_instancing_performance | WebGL / instancing / performance}
+ * @see Example: {@link https://threejs.org/examples/#webgl_instancing_scatter | WebGL / instancing / scatter}
+ * @see Example: {@link https://threejs.org/examples/#webgl_instancing_raycast | WebGL / instancing / raycast}
+ * @see {@link https://threejs.org/docs/index.html#api/en/objects/InstancedMesh | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/objects/InstancedMesh.js | Source}
+ */
+export class InstancedMesh<
+    TGeometry extends BufferGeometry = BufferGeometry,
+    TMaterial extends Material | Material[] = Material | Material[],
+    TEventMap extends InstancedMeshEventMap = InstancedMeshEventMap,
+> extends Mesh<TGeometry, TMaterial, TEventMap> {
+    /**
+     * Create a new instance of {@link InstancedMesh}
+     * @param geometry An instance of {@link BufferGeometry}.
+     * @param material A single or an array of {@link Material}. Default is a new {@link MeshBasicMaterial}.
+     * @param count The **maximum** number of instances of this Mesh. Expects a `Integer`
+     */
+    constructor(geometry: TGeometry | undefined, material: TMaterial | undefined, count: number);
+
+    /**
+     * Read-only flag to check if a given object is of type {@link InstancedMesh}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isInstancedMesh: true;
+
+    /**
+     * This bounding box encloses all instances of the {@link InstancedMesh},, which can be calculated with {@link computeBoundingBox | .computeBoundingBox()}.
+     * @remarks Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are `null`.
+     * @defaultValue `null`
+     */
+    boundingBox: Box3 | null;
+
+    /**
+     * This bounding sphere encloses all instances of the {@link InstancedMesh}, which can be calculated with {@link computeBoundingSphere | .computeBoundingSphere()}.
+     * @remarks bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are `null`.
+     * @defaultValue `null`
+     */
+    boundingSphere: Sphere | null;
+
+    /**
+     * The number of instances.
+     * @remarks
+     * The `count` value passed into the {@link InstancedMesh | constructor} represents the **maximum** number of instances of this mesh.
+     * You can change the number of instances at runtime to an integer value in the range `[0, count]`.
+     * @remarks If you need more instances than the original `count` value, you have to create a new InstancedMesh.
+     * @remarks Expects a `Integer`
+     */
+    count: number;
+
+    /**
+     * Represents the colors of all instances.
+     * You have to set {@link InstancedBufferAttribute.needsUpdate | .instanceColor.needsUpdate()} flag to `true` if you modify instanced data via {@link setColorAt | .setColorAt()}.
+     * @defaultValue `null`
+     */
+    instanceColor: InstancedBufferAttribute | null;
+
+    /**
+     * Represents the local transformation of all instances.
+     * You have to set {@link InstancedBufferAttribute.needsUpdate | .instanceMatrix.needsUpdate()} flag to `true` if you modify instanced data via {@link setMatrixAt | .setMatrixAt()}.
+     */
+    instanceMatrix: InstancedBufferAttribute;
+
+    /**
+     * Represents the morph target weights of all instances. You have to set its {@link .needsUpdate} flag to true if
+     * you modify instanced data via {@link .setMorphAt}.
+     */
+    morphTexture: DataTexture | null;
+
+    /**
+     * Computes the bounding box of the instanced mesh, and updates the {@link .boundingBox} attribute. The bounding box
+     * is not computed by the engine; it must be computed by your app. You may need to recompute the bounding box if an
+     * instance is transformed via {@link .setMatrixAt()}.
+     */
+    computeBoundingBox(): void;
+
+    /**
+     * Computes the bounding sphere of the instanced mesh, and updates the {@link .boundingSphere} attribute. The engine
+     * automatically computes the bounding sphere when it is needed, e.g., for ray casting or view frustum culling. You
+     * may need to recompute the bounding sphere if an instance is transformed via [page:.setMatrixAt]().
+     */
+    computeBoundingSphere(): void;
+
+    /**
+     * Get the color of the defined instance.
+     * @param index The index of an instance. Values have to be in the range `[0, count]`. Expects a `Integer`
+     * @param color This color object will be set to the color of the defined instance.
+     */
+    getColorAt(index: number, color: Color): void;
+
+    /**
+     * Sets the given color to the defined instance
+     * @remarks
+     * Make sure you set {@link InstancedBufferAttribute.needsUpdate | .instanceColor.needsUpdate()} to `true` after updating all the colors.
+     * @param index The index of an instance. Values have to be in the range `[0, count]`. Expects a `Integer`
+     * @param color The color of a single instance.
+     */
+    setColorAt(index: number, color: Color): void;
+
+    /**
+     * Get the local transformation matrix of the defined instance.
+     * @param index The index of an instance Values have to be in the range `[0, count]`. Expects a `Integer`
+     * @param matrix This 4x4 matrix will be set to the local transformation matrix of the defined instance.
+     */
+    getMatrixAt(index: number, matrix: Matrix4): void;
+
+    /**
+     * Get the morph target weights of the defined instance.
+     * @param index The index of an instance. Values have to be in the range [0, count].
+     * @param mesh The {@link .morphTargetInfluences} property of this mesh will be filled with the morph target weights of the defined instance.
+     */
+    getMorphAt(index: number, mesh: Mesh): void;
+
+    /**
+     * Sets the given local transformation matrix to the defined instance.
+     * @remarks
+     * Make sure you set {@link InstancedBufferAttribute.needsUpdate | .instanceMatrix.needsUpdate()} flag to `true` after updating all the matrices.
+     * @param index The index of an instance. Values have to be in the range `[0, count]`. Expects a `Integer`
+     * @param matrix A 4x4 matrix representing the local transformation of a single instance.
+     */
+    setMatrixAt(index: number, matrix: Matrix4): void;
+
+    /**
+     * Sets the morph target weights to the defined instance. Make sure you set {@link .morphTexture}{@link .needsUpdate}
+     * to true after updating all the influences.
+     * @param index The index of an instance. Values have to be in the range [0, count].
+     * @param mesh A mesh with {@link .morphTargetInfluences} property containing the morph target weights of a single instance.
+     */
+    setMorphAt(index: number, mesh: Mesh): void;
+
+    /**
+     * No effect in {@link InstancedMesh}.
+     * @ignore
+     * @hidden
+     */
+    override updateMorphTargets(): void;
+
+    /**
+     * Frees the GPU-related resources allocated by this instance
+     * @remarks
+     * Call this method whenever this instance is no longer used in your app.
+     */
+    dispose(): this;
+
+    toJSON(meta?: JSONMeta): InstancedMeshJSON;
+}

package/types/src/objects/LOD.d.ts

@@ -0,0 +1,111 @@
+import { Camera } from "../cameras/Camera.js";
+import { JSONMeta, Object3D, Object3DEventMap, Object3DJSON, Object3DJSONObject } from "../core/Object3D.js";
+
+export interface LODJSONObject extends Object3DJSONObject {
+    autoUpdate?: boolean;
+
+    levels: Array<{
+        object: string;
+        distance: number;
+        hysteresis: number;
+    }>;
+}
+
+export interface LODJSON extends Object3DJSON {
+    object: LODJSONObject;
+}
+
+/**
+ * Every level is associated with an object, and rendering can be switched between them at the distances specified
+ * @remarks
+ * Typically you would create, say, three meshes, one for far away (low detail), one for mid range (medium detail) and one for close up (high detail).
+ * @example
+ * ```typescript
+ * const {@link LOD} = new THREE.LOD();
+ * //Create spheres with 3 levels of detail and create new {@link LOD} levels for them
+ * for (let i = 0; i & lt; 3; i++) {
+ *     const geometry = new THREE.IcosahedronGeometry(10, 3 - i)
+ *     const mesh = new THREE.Mesh(geometry, material);
+ *     lod.addLevel(mesh, i * 75);
+ * }
+ * scene.add(lod);
+ * ```
+ * @see Example: {@link https://threejs.org/examples/#webgl_lod | webgl / {@link LOD} }
+ * @see {@link https://threejs.org/docs/index.html#api/en/objects/LOD | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/objects/LOD.js | Source}
+ */
+export class LOD<TEventMap extends Object3DEventMap = Object3DEventMap> extends Object3D<TEventMap> {
+    /**
+     * Creates a new {@link LOD}.
+     */
+    constructor();
+
+    /**
+     * Read-only flag to check if a given object is of type {@link LOD}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isLOD: true;
+
+    /**
+     * @override
+     * @defaultValue `LOD`
+     */
+    override readonly type: string | "LOD";
+
+    /**
+     * An array of level objects
+     */
+    levels: Array<{
+        /** The Object3D to display at this level. */
+        object: Object3D;
+        /** The distance at which to display this level of detail. Expects a `Float`. */
+        distance: number;
+        /** Threshold used to avoid flickering at LOD boundaries, as a fraction of distance. Expects a `Float`. */
+        hysteresis: number;
+    }>;
+
+    /**
+     * Whether the {@link LOD} object is updated automatically by the renderer per frame or not.
+     * If set to `false`, you have to call {@link update | .update()} in the render loop by yourself.
+     * @defaultValue `true`
+     */
+    autoUpdate: boolean;
+
+    /**
+     * Adds a mesh that will display at a certain distance and greater. Typically the further away the distance, the lower the detail on the mesh.
+     *
+     * @param object The Object3D to display at this level.
+     * @param distance The distance at which to display this level of detail. Expects a `Float`. Default `0.0`.
+     * @param hysteresis Threshold used to avoid flickering at LOD boundaries, as a fraction of distance. Expects a `Float`. Default `0.0`.
+     */
+    addLevel(object: Object3D, distance?: number, hysteresis?: number): this;
+
+    /**
+     * Removes an existing level, based on the distance from the camera. Returns `true` when the level has been removed.
+     * Otherwise `false`.
+     * @param distance Distance of the level to delete.
+     */
+    removeLabel(distance: number): boolean;
+
+    /**
+     * Get the currently active {@link LOD} level
+     * @remarks
+     * As index of the levels array.
+     */
+    getCurrentLevel(): number;
+
+    /**
+     * Get a reference to the first {@link THREE.Object3D | Object3D} (mesh) that is greater than {@link distance}.
+     * @param distance Expects a `Float`
+     */
+    getObjectForDistance(distance: number): Object3D | null;
+
+    /**
+     * Set the visibility of each {@link levels | level}'s {@link THREE.Object3D | object} based on distance from the {@link THREE.Camera | camera}.
+     * @param camera
+     */
+    update(camera: Camera): void;
+
+    toJSON(meta?: JSONMeta): LODJSON;
+}