@types/three 0.149.0 → 0.150.0

three/src/core/Object3D.d.ts

@@ -15,186 +15,216 @@ import { BufferGeometry } from './BufferGeometry';
 import { AnimationClip } from '../animation/AnimationClip';
 
 /**
- * Base class for scene graph objects
+ * This is the base class for most objects in three.js and provides a set of properties and methods for manipulating objects in 3D space.
+ * @remarks Note that this can be used for grouping objects via the {@link THREE.Object3D.add | .add()} method which adds the object as a child,
+ * however it is better to use {@link THREE.Group | Group} for this.
+ * @see {@link https://threejs.org/docs/index.html#api/en/core/Object3D | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/core/Object3D.js | Source}
  */
 export class Object3D<E extends BaseEvent = Event> extends EventDispatcher<E> {
+    /**
+     * This creates a new {@link Object3D} object.
+     */
     constructor();
 
     /**
-     * Unique number of this object instance.
+     * Unique number for this object instance.
+     * @remarks Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.
+     * @remarks Expects a `Integer`
      */
-    id: number;
+    readonly id: number;
 
+    /**
+     * {@link http://en.wikipedia.org/wiki/Universally_unique_identifier | UUID} of this object instance.
+     * @remarks This gets automatically assigned and shouldn't be edited.
+     */
     uuid: string;
 
     /**
      * Optional name of the object (doesn't need to be unique).
-     * @default ''
+     * @defaultValue `''`
      */
     name: string;
 
     /**
-     * @default 'Object3D'
+     * @defaultValue `Object3D`
      */
-    type: string;
+    type: string; // TODO Replace for "Object3D" // TODO add readonly
 
     /**
-     * Object's parent in the scene graph.
-     * @default null
+     * Object's parent in the {@link https://en.wikipedia.org/wiki/Scene_graph | scene graph}.
+     * @remarks An object can have at most one parent.
+     * @defaultValue `null`
      */
     parent: Object3D | null;
 
     /**
      * Array with object's children.
-     * @default []
+     * @see {@link THREE.Object3DGroup | Group} for info on manually grouping objects.
+     * @defaultValue `[]`
      */
+
     children: Object3D[];
 
     /**
-     * This is used by the {@link lookAt} method, for example, to determine the orientation of the result.
-     *
-     * Default is {@link Object3D.DEFAULT_UP} - that is, `( 0, 1, 0 )`.
-     *
-     * @default {@link Object3D.DEFAULT_UP}
+     * This is used by the {@link lookAt | lookAt} method, for example, to determine the orientation of the result.
+     * @defaultValue {@link DEFAULT_UP | Object3D.DEFAULT_UP} - that is `(0, 1, 0)`.
      */
     up: Vector3;
 
     /**
      * Object's local position.
-     * @default new THREE.Vector3()
+     * @defaultValue `new THREE.Vector3()` - that is `(0, 0, 0)`.
      */
     readonly position: Vector3;
 
     /**
-     * Object's local rotation (Euler angles), in radians.
-     * @default new THREE.Euler()
+     * Object's local rotation ({@link https://en.wikipedia.org/wiki/Euler_angles | Euler angles}), in radians.
+     * @defaultValue `new THREE.Euler()` - that is `(0, 0, 0, Euler.DEFAULT_ORDER)`.
      */
     readonly rotation: Euler;
 
     /**
-     * Object's local rotation as a Quaternion.
-     * @default new THREE.Quaternion()
+     * Object's local rotation as a {@link THREE.Quaternion | Quaternion}.
+     * @defaultValue `new THREE.Quaternion()` - that is `(0,  0, 0, 1)`.
      */
     readonly quaternion: Quaternion;
 
     /**
-     * Object's local scale.
-     * @default new THREE.Vector3()
+     * The object's local scale.
+     * @defaultValue `new THREE.Vector3( 1, 1, 1 )`
      */
     readonly scale: Vector3;
 
     /**
-     * @default new THREE.Matrix4()
+     * @defaultValue `new THREE.Matrix4()`
      */
     readonly modelViewMatrix: Matrix4;
 
     /**
-     * @default new THREE.Matrix3()
+     * @defaultValue `new THREE.Matrix3()`
      */
     readonly normalMatrix: Matrix3;
 
     /**
-     * Local transform.
-     * @default new THREE.Matrix4()
+     * The local transform matrix.
+     * @defaultValue `new THREE.Matrix4()`
      */
     matrix: Matrix4;
 
     /**
-     * The global transform of the object. If the Object3d has no parent, then it's identical to the local transform.
-     * @default new THREE.Matrix4()
+     * The global transform of the object.
+     * @remarks If the {@link Object3D} has no parent, then it's identical to the local transform {@link THREE.Object3D.matrix | .matrix}.
+     * @defaultValue `new THREE.Matrix4()`
      */
     matrixWorld: Matrix4;
 
     /**
      * When this is set, it calculates the matrix of position, (rotation or quaternion) and
-     * scale every frame and also recalculates the matrixWorld property. Default is {@link Object3D.DEFAULT_MATRIX_AUTO_UPDATE} (true).
+     * scale every frame and also recalculates the matrixWorld property.
+     * @defaultValue {@link DEFAULT_MATRIX_AUTO_UPDATE} - that is `(true)`.
      */
     matrixAutoUpdate: boolean;
 
     /**
      * If set, then the renderer checks every frame if the object and its children need matrix updates.
      * When it isn't, then you have to maintain all matrices in the object and its children yourself.
-     * Default is {@link Object3D.DEFAULT_MATRIX_WORLD_AUTO_UPDATE} (true).
+     * @defaultValue {@link DEFAULT_MATRIX_WORLD_AUTO_UPDATE} - that is `(true)`.
      */
     matrixWorldAutoUpdate: boolean;
 
     /**
      * When this is set, it calculates the matrixWorld in that frame and resets this property to false.
-     * @default false
+     * @defaultValue `false`
      */
     matrixWorldNeedsUpdate: boolean;
 
     /**
-     * @default new THREE.Layers()
+     * The layer membership of the object.
+     * @remarks The object is only visible if it has at least one layer in common with the {@link THREE.Object3DCamera | Camera} in use.
+     * @remarks This property can also be used to filter out unwanted objects in ray-intersection tests when using {@link THREE.Raycaster | Raycaster}.
+     * @defaultValue `new THREE.Layers()`
      */
     layers: Layers;
 
     /**
-     * Object gets rendered if true.
-     * @default true
+     * Object gets rendered if `true`.
+     * @defaultValue `true`
      */
     visible: boolean;
 
     /**
-     * Gets rendered into shadow map.
-     * @default false
+     * Whether the object gets rendered into shadow map.
+     * @defaultValue `false`
      */
     castShadow: boolean;
 
     /**
-     * Material gets baked in shadow receiving.
-     * @default false
+     * Whether the material receives shadows.
+     * @defaultValue `false`
      */
     receiveShadow: boolean;
 
     /**
      * When this is set, it checks every frame if the object is in the frustum of the camera before rendering the object.
-     * If set to false the object gets rendered every frame even if it is not in the frustum of the camera.
-     * @default true
+     * If set to `false` the object gets rendered every frame even if it is not in the frustum of the camera.
+     * @defaultValue `true`
      */
     frustumCulled: boolean;
 
     /**
-     * Overrides the default rendering order of scene graph objects, from lowest to highest renderOrder.
-     * Opaque and transparent objects remain sorted independently though.
-     * When this property is set for an instance of Group, all descendants objects will be sorted and rendered together.
-     * @default 0
+     * This value allows the default rendering order of {@link https://en.wikipedia.org/wiki/Scene_graph | scene graph}
+     * objects to be overridden although opaque and transparent objects remain sorted independently.
+     * @remarks When this property is set for an instance of {@link Group | Group}, all descendants objects will be sorted and rendered together.
+     * @remarks Sorting is from lowest to highest renderOrder.
+     * @defaultValue `0`
      */
     renderOrder: number;
 
     /**
-     * Array with animation clips.
-     * @default []
+     * Array with object's animation clips.
+     * @defaultValue `[]`
      */
     animations: AnimationClip[];
 
     /**
-     * An object that can be used to store custom data about the Object3d. It should not hold references to functions as these will not be cloned.
-     * @default {}
+     * An object that can be used to store custom data about the {@link Object3D}.
+     * @remarks It should not hold references to _functions_ as these **will not** be cloned.
+     * @default `{}`
      */
-    userData: { [key: string]: any };
+    userData: { [key: string]: any }; // TODO Replace this to a Record?
 
     /**
-     * Custom depth material to be used when rendering to the depth map. Can only be used in context of meshes.
-     * When shadow-casting with a DirectionalLight or SpotLight, if you are (a) modifying vertex positions in
-     * the vertex shader, (b) using a displacement map, (c) using an alpha map with alphaTest, or (d) using a
-     * transparent texture with alphaTest, you must specify a customDepthMaterial for proper shadows.
+     * Custom depth material to be used when rendering to the depth map.
+     * @remarks Can only be used in context of meshes.
+     * @remarks When shadow-casting with a {@link THREE.DirectionalLight | DirectionalLight} or {@link THREE.SpotLight | SpotLight},
+     * if you are modifying vertex positions in the vertex shader you must specify a customDepthMaterial for proper shadows.
+     * @defaultValue `undefined`
      */
-    customDepthMaterial: Material;
+    customDepthMaterial?: Material | undefined;
 
     /**
-     * Same as customDepthMaterial, but used with PointLight.
+     * Same as {@link customDepthMaterial}, but used with {@link THREE.Object3DPointLight | PointLight}.
+     * @defaultValue `undefined`
      */
-    customDistanceMaterial: Material;
+    customDistanceMaterial?: Material | undefined;
 
     /**
-     * Used to check whether this or derived classes are Object3Ds. Default is true.
-     * You should not change this, as it is used internally for optimisation.
+     * Flag to check if a given object is of type {@link Object3D}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
      */
     readonly isObject3D: true;
 
     /**
-     * Calls before rendering object
+     * An optional callback that is executed immediately before a 3D object is rendered.
+     * @remarks This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
+     * @remarks Please notice that this callback is only executed for `renderable` 3D objects.
+     * Meaning 3D objects which define their visual appearance with geometries and materials like
+     * instances of {@link THREE.Object3DMesh | Mesh}, {@link THREE.Object3DLine | Line}, {@link THREE.Object3DPoints | Points} or {@link THREE.Object3DSprite | Sprite}.
+     * Instances of {@link THREE.Object3DObject3D | Object3D}, {@link THREE.Object3DGroup | Group} or {@link THREE.Object3DBone | Bone}
+     * are not renderable and thus this callback is not executed for such objects.
+     * @defaultValue `() => {}`
      */
     onBeforeRender: (
         renderer: WebGLRenderer,
@@ -206,7 +236,14 @@ export class Object3D<E extends BaseEvent = Event> extends EventDispatcher<E> {
     ) => void;
 
     /**
-     * Calls after rendering object
+     * An optional callback that is executed immediately after a 3D object is rendered.
+     * @remarks This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
+     * @remarks Please notice that this callback is only executed for `renderable` 3D objects.
+     * Meaning 3D objects which define their visual appearance with geometries and materials like
+     * instances of {@link THREE.Object3DMesh | Mesh}, {@link THREE.Object3DLine | Line}, {@link THREE.Object3DPoints | Points} or {@link THREE.Object3DSprite | Sprite}.
+     * Instances of {@link THREE.Object3DObject3D | Object3D}, {@link THREE.Object3DGroup | Group} or {@link THREE.Object3DBone | Bone}
+     * are not renderable and thus this callback is not executed for such objects.
+     * @defaultValue `() => {}`
      */
     onAfterRender: (
         renderer: WebGLRenderer,
@@ -218,146 +255,165 @@ export class Object3D<E extends BaseEvent = Event> extends EventDispatcher<E> {
     ) => void;
 
     /**
-     * The default {@link up} direction for objects, also used as the default position for {@link DirectionalLight},
-     * {@link HemisphereLight} and {@link Spotlight} (which creates lights shining from the top down).
-     *
-     * Set to ( 0, 1, 0 ) by default.
+     * The default {@link up} direction for objects, also used as the default position for {@link THREE.DirectionalLight | DirectionalLight},
+     * {@link THREE.HemisphereLight | HemisphereLight} and {@link THREE.Spotlight | Spotlight} (which creates lights shining from the top down).
+     * @defaultValue `new THREE.Vector3( 0, 1, 0)`
      */
     static DEFAULT_UP: Vector3;
 
     /**
      * The default setting for {@link matrixAutoUpdate} for newly created Object3Ds.
+     * @defaultValue `true`
      */
     static DEFAULT_MATRIX_AUTO_UPDATE: boolean;
 
     /**
      * The default setting for {@link matrixWorldAutoUpdate} for newly created Object3Ds.
+     * @defaultValue `true`
      */
     static DEFAULT_MATRIX_WORLD_AUTO_UPDATE: boolean;
 
     /**
      * Applies the matrix transform to the object and updates the object's position, rotation and scale.
+     * @param matrix
      */
     applyMatrix4(matrix: Matrix4): void;
 
     /**
      * Applies the rotation represented by the quaternion to the object.
+     * @param quaternion
      */
     applyQuaternion(quaternion: Quaternion): this;
 
     /**
-     * axis -- A normalized vector in object space.
-     * angle -- angle in radians
+     * Calls {@link THREE.Quaternion.setFromAxisAngle | setFromAxisAngle}({@link axis}, {@link angle}) on the {@link quaternion | .quaternion}.
      * @param axis A normalized vector in object space.
-     * @param angle angle in radians
+     * @param angle Angle in radians. Expects a `Float`
      */
     setRotationFromAxisAngle(axis: Vector3, angle: number): void;
 
     /**
-     * Calls setRotationFromEuler(euler) on the .quaternion.
+     * Calls {@link THREE.Quaternion.setFromEuler | setFromEuler}({@link euler}) on the {@link quaternion | .quaternion}.
      * @param euler Euler angle specifying rotation amount.
      */
     setRotationFromEuler(euler: Euler): void;
 
     /**
-     * Calls setFromRotationMatrix(m) on the .quaternion.
-     *
-     * Note that this assumes that the upper 3x3 of m is a pure rotation matrix (i.e, unscaled).
-     * @param m rotate the quaternion by the rotation component of the matrix.
+     * Calls {@link THREE.Quaternion.setFromRotationMatrix | setFromRotationMatrix}({@link m}) on the {@link quaternion | .quaternion}.
+     * @remarks Note that this assumes that the upper 3x3 of m is a pure rotation matrix (i.e, unscaled).
+     * @param m Rotate the quaternion by the rotation component of the matrix.
      */
     setRotationFromMatrix(m: Matrix4): void;
 
     /**
-     * Copy the given quaternion into .quaternion.
-     * @param q normalized Quaternion
+     * Copy the given {@link THREE.Quaternion | Quaternion} into {@link quaternion | .quaternion}.
+     * @param q Normalized Quaternion.
      */
     setRotationFromQuaternion(q: Quaternion): void;
 
     /**
-     * Rotate an object along an axis in object space. The axis is assumed to be normalized.
-     * @param axis	A normalized vector in object space.
-     * @param angle	The angle in radians.
+     * Rotate an object along an axis in object space.
+     * @remarks The axis is assumed to be normalized.
+     * @param axis A normalized vector in object space.
+     * @param angle The angle in radians. Expects a `Float`
      */
     rotateOnAxis(axis: Vector3, angle: number): this;
 
     /**
-     * Rotate an object along an axis in world space. The axis is assumed to be normalized. Method Assumes no rotated parent.
-     * @param axis	A normalized vector in object space.
-     * @param angle	The angle in radians.
+     * Rotate an object along an axis in world space.
+     * @remarks The axis is assumed to be normalized
+     * @remarks Method Assumes no rotated parent.
+     * @param axis A normalized vector in world space.
+     * @param angle The angle in radians. Expects a `Float`
      */
     rotateOnWorldAxis(axis: Vector3, angle: number): this;
 
     /**
-     * Rotates the object around x axis in local space.
-     * @param angle the angle to rotate in radians.
+     * Rotates the object around _x_ axis in local space.
+     * @param rad The angle to rotate in radians. Expects a `Float`
      */
     rotateX(angle: number): this;
 
     /**
-     * Rotates the object around y axis in local space.
-     * @param angle the angle to rotate in radians.
+     * Rotates the object around _y_ axis in local space.
+     * @param rad The angle to rotate in radians. Expects a `Float`
      */
     rotateY(angle: number): this;
 
     /**
-     * Rotates the object around z axis in local space.
-     * @param angle the angle to rotate in radians.
+     * Rotates the object around _z_ axis in local space.
+     * @param rad The angle to rotate in radians. Expects a `Float`
      */
     rotateZ(angle: number): this;
 
     /**
-     * Translate an object by distance along an axis in object space. The axis is assumed to be normalized.
-     * @param axis	A normalized vector in object space.
-     * @param distance	The distance to translate.
+     * Translate an object by distance along an axis in object space
+     * @remarks The axis is assumed to be normalized.
+     * @param axis A normalized vector in object space.
+     * @param distance The distance to translate. Expects a `Float`
      */
     translateOnAxis(axis: Vector3, distance: number): this;
 
     /**
-     * Translates object along x axis by distance.
-     * @param distance Distance.
+     * Translates object along x axis in object space by {@link distance} units.
+     * @param distance Expects a `Float`
      */
     translateX(distance: number): this;
 
     /**
-     * Translates object along y axis by distance.
-     * @param distance Distance.
+     * Translates object along _y_ axis in object space by {@link distance} units.
+     * @param distance Expects a `Float`
      */
     translateY(distance: number): this;
 
     /**
-     * Translates object along z axis by distance.
-     * @param distance Distance.
+     * Translates object along _z_ axis in object space by {@link distance} units.
+     * @param distance Expects a `Float`
      */
     translateZ(distance: number): this;
 
     /**
-     * Updates the vector from local space to world space.
-     * @param vector A local vector.
+     * Converts the vector from this object's local space to world space.
+     * @param vector A vector representing a position in this object's local space.
      */
     localToWorld(vector: Vector3): Vector3;
 
     /**
-     * Updates the vector from world space to local space.
-     * @param vector A world vector.
+     * Converts the vector from world space to this object's local space.
+     * @param vector A vector representing a position in world space.
      */
     worldToLocal(vector: Vector3): Vector3;
 
     /**
-     * Optionally, the x, y and z components of the world space position.
      * Rotates the object to face a point in world space.
-     * This method does not support objects having non-uniformly-scaled parent(s).
-     * @param vector A world vector to look at.
+     * @remarks This method does not support objects having non-uniformly-scaled parent(s).
+     * @param vector A vector representing a position in world space to look at.
      */
     lookAt(vector: Vector3): void;
+    /**
+     * Rotates the object to face a point in world space.
+     * @remarks This method does not support objects having non-uniformly-scaled parent(s).
+     * @param x Expects a `Float`
+     * @param y Expects a `Float`
+     * @param z Expects a `Float`
+     */
     lookAt(x: number, y: number, z: number): void;
 
     /**
-     * Adds object as child of this object.
+     * Adds another {@link Object3D} as child of this {@link Object3D}.
+     * @remarks An arbitrary number of objects may be added
+     * @remarks Any current parent on an {@link object} passed in here will be removed, since an {@link Object3D} can have at most one parent.
+     * @see {@link attach}
+     * @see {@link THREE.Group | Group} for info on manually grouping objects.
+     * @param object
      */
     add(...object: Object3D[]): this;
 
     /**
-     * Removes object as child of this object.
+     * Removes a {@link Object3D} as child of this {@link Object3D}.
+     * @remarks An arbitrary number of objects may be removed.
+     * @see {@link THREE.Group | Group} for info on manually grouping objects.
+     * @param object
      */
     remove(...object: Object3D[]): this;
 
@@ -372,19 +428,26 @@ export class Object3D<E extends BaseEvent = Event> extends EventDispatcher<E> {
     clear(): this;
 
     /**
-     * Adds object as a child of this, while maintaining the object's world transform.
+     * Adds a {@link Object3D} as a child of this, while maintaining the object's world transform.
+     * @remarks Note: This method does not support scene graphs having non-uniformly-scaled nodes(s).
+     * @see {@link add}
+     * @param object
      */
     attach(object: Object3D): this;
 
     /**
-     * Searches through the object's children and returns the first with a matching id.
-     * @param id	Unique number of the object instance
+     * Searches through an object and its children, starting with the object itself, and returns the first with a matching id.
+     * @remarks Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.
+     * @see {@link id}
+     * @param id Unique number of the object instance. Expects a `Integer`
      */
     getObjectById(id: number): Object3D | undefined;
 
     /**
-     * Searches through the object's children and returns the first with a matching name.
-     * @param name	String to match to the children's Object3d.name property.
+     * Searches through an object and its children, starting with the object itself, and returns the first with a matching name.
+     * @remarks Note that for most objects the name is an empty string by default
+     * @remarks You will have to set it manually to make use of this method.
+     * @param name String to match to the children's Object3D.name property.
      */
     getObjectByName(name: string): Object3D | undefined;
 
@@ -399,24 +462,66 @@ export class Object3D<E extends BaseEvent = Event> extends EventDispatcher<E> {
 
     /**
      * Searches through an object and its children, starting with the object itself,
-     * and returns all the objects with a property that matches the value given.
-     *
-     * @param name - the property name to search for.
-     * @param value - value of the given property.
+     * and returns the first with a property that matches the value given.
+     * @param name The property name to search for.
+     * @param value Value of the given property.
      */
     getObjectsByProperty(name: string, value: any): Object3D[];
 
+    /**
+     * Returns a vector representing the position of the object in world space.
+     * @param target The result will be copied into this Vector3.
+     */
     getWorldPosition(target: Vector3): Vector3;
+
+    /**
+     * Returns a quaternion representing the rotation of the object in world space.
+     * @param target The result will be copied into this Quaternion.
+     */
     getWorldQuaternion(target: Quaternion): Quaternion;
+
+    /**
+     * Returns a vector of the scaling factors applied to the object for each axis in world space.
+     * @param target The result will be copied into this Vector3.
+     */
     getWorldScale(target: Vector3): Vector3;
+
+    /**
+     * Returns a vector representing the direction of object's positive z-axis in world space.
+     * @param target The result will be copied into this Vector3.
+     */
     getWorldDirection(target: Vector3): Vector3;
 
+    /**
+     * Abstract (empty) method to get intersections between a casted ray and this object
+     * @remarks Subclasses such as {@link THREE.Mesh | Mesh}, {@link THREE.Line | Line}, and {@link THREE.Points | Points} implement this method in order to use raycasting.
+     * @see {@link THREE.Raycaster | Raycaster}
+     * @param raycaster
+     * @param intersects
+     * @defaultValue `() => {}`
+     */
     raycast(raycaster: Raycaster, intersects: Intersection[]): void;
 
+    /**
+     * Executes the callback on this object and all descendants.
+     * @remarks Note: Modifying the scene graph inside the callback is discouraged.
+     * @param callback A function with as first argument an {@link Object3D} object.
+     */
     traverse(callback: (object: Object3D) => any): void;
 
+    /**
+     * Like traverse, but the callback will only be executed for visible objects
+     * @remarks Descendants of invisible objects are not traversed.
+     * @remarks Note: Modifying the scene graph inside the callback is discouraged.
+     * @param callback A function with as first argument an {@link Object3D} object.
+     */
     traverseVisible(callback: (object: Object3D) => any): void;
 
+    /**
+     * Executes the callback on all ancestors.
+     * @remarks Note: Modifying the scene graph inside the callback is discouraged.
+     * @param callback A function with as first argument an {@link Object3D} object.
+     */
     traverseAncestors(callback: (object: Object3D) => any): void;
 
     /**
@@ -425,25 +530,37 @@ export class Object3D<E extends BaseEvent = Event> extends EventDispatcher<E> {
     updateMatrix(): void;
 
     /**
-     * Updates global transform of the object and its children.
+     * Updates the global transform of the object.
+     * And will update the object descendants if {@link matrixWorldNeedsUpdate | .matrixWorldNeedsUpdate} is set to true or if the {@link force} parameter is set to `true`.
+     * @param force A boolean that can be used to bypass {@link matrixWorldAutoUpdate | .matrixWorldAutoUpdate}, to recalculate the world matrix of the object and descendants on the current frame.
+     * Useful if you cannot wait for the renderer to update it on the next frame, assuming {@link matrixWorldAutoUpdate | .matrixWorldAutoUpdate} set to `true`.
      */
     updateMatrixWorld(force?: boolean): void;
 
     /**
      * Updates the global transform of the object.
-     * @param updateParents recursively updates global transform of ancestors.
-     * @param updateChildren recursively updates global transform of descendants.
+     * @param updateParents Recursively updates global transform of ancestors.
+     * @param updateChildren Recursively updates global transform of descendants.
      */
     updateWorldMatrix(updateParents: boolean, updateChildren: boolean): void;
 
+    /**
+     * Convert the object to three.js {@link https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4 | JSON Object/Scene format}.
+     * @param meta Object containing metadata such as materials, textures or images for the object.
+     */
     toJSON(meta?: { geometries: any; materials: any; textures: any; images: any }): any;
 
+    /**
+     * Returns a clone of this object and optionally all descendants.
+     * @param recursive If true, descendants of the object are also cloned. Default `true`
+     */
     clone(recursive?: boolean): this;
 
     /**
-     *
-     * @param object
-     * @param recursive
+     * Copy the given object into this object
+     * @remarks Note: event listeners and user-defined callbacks ({@link onAfterRender | .onAfterRender} and {@link onBeforeRender | .onBeforeRender}) are not copied.
+     * @param source
+     * @param recursive If true, descendants of the object are also copied. Default `true`
      */
-    copy(source: this, recursive?: boolean): this;
+    copy(source: Object3D, recursive?: boolean): this;
 }