@types/three 0.174.0 → 0.175.0

three/src/animation/AnimationAction.d.ts

@@ -2,85 +2,285 @@ import { AnimationActionLoopStyles, AnimationBlendMode } from "../constants.js";
 import { Object3D } from "../core/Object3D.js";
 import { AnimationClip } from "./AnimationClip.js";
 import { AnimationMixer } from "./AnimationMixer.js";
-// Animation ////////////////////////////////////////////////////////////////////////////////////////
 
+/**
+ * An instance of `AnimationAction` schedules the playback of an animation which is
+ * stored in {@link AnimationClip}.
+ */
 export class AnimationAction {
-    constructor(mixer: AnimationMixer, clip: AnimationClip, localRoot?: Object3D, blendMode?: AnimationBlendMode);
-
+    /**
+     * Constructs a new animation action.
+     *
+     * @param {AnimationMixer} mixer - The mixer that is controlled by this action.
+     * @param {AnimationClip} clip - The animation clip that holds the actual keyframes.
+     * @param {?Object3D} [localRoot=null] - The root object on which this action is performed.
+     * @param {(NormalAnimationBlendMode|AdditiveAnimationBlendMode)} [blendMode] - The blend mode.
+     */
+    constructor(
+        mixer: AnimationMixer,
+        clip: AnimationClip,
+        localRoot?: Object3D | null,
+        blendMode?: AnimationBlendMode,
+    );
+    /**
+     * Defines how the animation is blended/combined when two or more animations
+     * are simultaneously played.
+     */
     blendMode: AnimationBlendMode;
-
     /**
-     * @default THREE.LoopRepeat
+     * The loop mode, set via {@link AnimationAction#setLoop}.
+     *
+     * @default LoopRepeat
      */
     loop: AnimationActionLoopStyles;
-
     /**
-     * @default 0
+     * The local time of this action (in seconds, starting with `0`).
+     *
+     * The value gets clamped or wrapped to `[0,clip.duration]` (according to the
+     * loop state).
+     *
+     * @default Infinity
      */
     time: number;
-
     /**
+     * Scaling factor for the {@link AnimationAction#time}. A value of `0` causes the
+     * animation to pause. Negative values cause the animation to play backwards.
+     *
      * @default 1
      */
     timeScale: number;
-
     /**
+     * The degree of influence of this action (in the interval `[0, 1]`). Values
+     * between `0` (no impact) and `1` (full impact) can be used to blend between
+     * several actions.
+     *
      * @default 1
      */
     weight: number;
-
     /**
+     * The number of repetitions of the performed clip over the course of this action.
+     * Can be set via {@link AnimationAction#setLoop}.
+     *
+     * Setting this number has no effect if {@link AnimationAction#loop} is set to
+     * `THREE:LoopOnce`.
+     *
      * @default Infinity
      */
     repetitions: number;
-
     /**
+     * If set to `true`, the playback of the action is paused.
+     *
      * @default false
      */
     paused: boolean;
-
     /**
+     * If set to `false`, the action is disabled so it has no impact.
+     *
+     * When the action is re-enabled, the animation continues from its current
+     * time (setting `enabled` to `false` doesn't reset the action).
+     *
      * @default true
      */
     enabled: boolean;
-
     /**
+     * If set to true the animation will automatically be paused on its last frame.
+     *
+     * If set to false, {@link AnimationAction#enabled} will automatically be switched
+     * to `false` when the last loop of the action has finished, so that this action has
+     * no further impact.
+     *
+     * Note: This member has no impact if the action is interrupted (it
+     * has only an effect if its last loop has really finished).
+     *
      * @default false
      */
     clampWhenFinished: boolean;
-
     /**
+     * Enables smooth interpolation without separate clips for start, loop and end.
+     *
      * @default true
      */
     zeroSlopeAtStart: boolean;
-
     /**
+     * Enables smooth interpolation without separate clips for start, loop and end.
+     *
      * @default true
      */
     zeroSlopeAtEnd: boolean;
-
+    /**
+     * Starts the playback of the animation.
+     *
+     * @return {AnimationAction} A reference to this animation action.
+     */
     play(): AnimationAction;
+    /**
+     * Stops the playback of the animation.
+     *
+     * @return {AnimationAction} A reference to this animation action.
+     */
     stop(): AnimationAction;
+    /**
+     * Resets the playback of the animation.
+     *
+     * @return {AnimationAction} A reference to this animation action.
+     */
     reset(): AnimationAction;
+    /**
+     * Returns `true` if the animation is running.
+     *
+     * @return {boolean} Whether the animation is running or not.
+     */
     isRunning(): boolean;
+    /**
+     * Returns `true` when {@link AnimationAction#play} has been called.
+     *
+     * @return {boolean} Whether the animation is scheduled or not.
+     */
     isScheduled(): boolean;
+    /**
+     * Defines the time when the animation should start.
+     *
+     * @param {number} time - The start time in seconds.
+     * @return {AnimationAction} A reference to this animation action.
+     */
     startAt(time: number): AnimationAction;
+    /**
+     * Configures the loop settings for this action.
+     *
+     * @param {(LoopRepeat|LoopOnce|LoopPingPong)} mode - The loop mode.
+     * @param {number} repetitions - The number of repetitions.
+     * @return {AnimationAction} A reference to this animation action.
+     */
     setLoop(mode: AnimationActionLoopStyles, repetitions: number): AnimationAction;
+    /**
+     * Sets the effective weight of this action.
+     *
+     * An action has no effect and thus an effective weight of zero when the
+     * action is disabled.
+     *
+     * @param {number} weight - The weight to set.
+     * @return {AnimationAction} A reference to this animation action.
+     */
     setEffectiveWeight(weight: number): AnimationAction;
+    /**
+     * Returns the effective weight of this action.
+     *
+     * @return {number} The effective weight.
+     */
     getEffectiveWeight(): number;
+    /**
+     * Fades the animation in by increasing its weight gradually from `0` to `1`,
+     * within the passed time interval.
+     *
+     * @param {number} duration - The duration of the fade.
+     * @return {AnimationAction} A reference to this animation action.
+     */
     fadeIn(duration: number): AnimationAction;
+    /**
+     * Fades the animation out by decreasing its weight gradually from `1` to `0`,
+     * within the passed time interval.
+     *
+     * @param {number} duration - The duration of the fade.
+     * @return {AnimationAction} A reference to this animation action.
+     */
     fadeOut(duration: number): AnimationAction;
-    crossFadeFrom(fadeOutAction: AnimationAction, duration: number, warp: boolean): AnimationAction;
-    crossFadeTo(fadeInAction: AnimationAction, duration: number, warp: boolean): AnimationAction;
+    /**
+     * Causes this action to fade in and the given action to fade out,
+     * within the passed time interval.
+     *
+     * @param {AnimationAction} fadeOutAction - The animation action to fade out.
+     * @param {number} duration - The duration of the fade.
+     * @param {boolean} [warp=false] - Whether warping should be used or not.
+     * @return {AnimationAction} A reference to this animation action.
+     */
+    crossFadeFrom(fadeOutAction: AnimationAction, duration: number, warp?: boolean): AnimationAction;
+    /**
+     * Causes this action to fade out and the given action to fade in,
+     * within the passed time interval.
+     *
+     * @param {AnimationAction} fadeInAction - The animation action to fade in.
+     * @param {number} duration - The duration of the fade.
+     * @param {boolean} [warp=false] - Whether warping should be used or not.
+     * @return {AnimationAction} A reference to this animation action.
+     */
+    crossFadeTo(fadeInAction: AnimationAction, duration: number, warp?: boolean): AnimationAction;
+    /**
+     * Stops any fading which is applied to this action.
+     *
+     * @return {AnimationAction} A reference to this animation action.
+     */
     stopFading(): AnimationAction;
+    /**
+     * Sets the effective time scale of this action.
+     *
+     * An action has no effect and thus an effective time scale of zero when the
+     * action is paused.
+     *
+     * @param {number} timeScale - The time scale to set.
+     * @return {AnimationAction} A reference to this animation action.
+     */
     setEffectiveTimeScale(timeScale: number): AnimationAction;
+    /**
+     * Returns the effective time scale of this action.
+     *
+     * @return {number} The effective time scale.
+     */
     getEffectiveTimeScale(): number;
+    /**
+     * Sets the duration for a single loop of this action.
+     *
+     * @param {number} duration - The duration to set.
+     * @return {AnimationAction} A reference to this animation action.
+     */
     setDuration(duration: number): AnimationAction;
+    /**
+     * Synchronizes this action with the passed other action.
+     *
+     * @param {AnimationAction} action - The action to sync with.
+     * @return {AnimationAction} A reference to this animation action.
+     */
     syncWith(action: AnimationAction): AnimationAction;
+    /**
+     * Decelerates this animation's speed to `0` within the passed time interval.
+     *
+     * @param {number} duration - The duration.
+     * @return {AnimationAction} A reference to this animation action.
+     */
     halt(duration: number): AnimationAction;
-    warp(statTimeScale: number, endTimeScale: number, duration: number): AnimationAction;
+    /**
+     * Changes the playback speed, within the passed time interval, by modifying
+     * {@link AnimationAction#timeScale} gradually from `startTimeScale` to
+     * `endTimeScale`.
+     *
+     * @param {number} startTimeScale - The start time scale.
+     * @param {number} endTimeScale - The end time scale.
+     * @param {number} duration - The duration.
+     * @return {AnimationAction} A reference to this animation action.
+     */
+    warp(startTimeScale: number, endTimeScale: number, duration: number): AnimationAction;
+    /**
+     * Stops any scheduled warping which is applied to this action.
+     *
+     * @return {AnimationAction} A reference to this animation action.
+     */
     stopWarping(): AnimationAction;
+    /**
+     * Returns the animation mixer of this animation action.
+     *
+     * @return {AnimationMixer} The animation mixer.
+     */
     getMixer(): AnimationMixer;
+    /**
+     * Returns the animation clip of this animation action.
+     *
+     * @return {AnimationClip} The animation clip.
+     */
     getClip(): AnimationClip;
+    /**
+     * Returns the root object of this animation action.
+     *
+     * @return {Object3D} The root object.
+     */
     getRoot(): Object3D;
+    _scheduleFading(duration: number, weightNow: number, weightThen: number): this;
 }

three/src/animation/AnimationClip.d.ts

@@ -2,7 +2,6 @@ import { AnimationBlendMode } from "../constants.js";
 import { Object3D } from "../core/Object3D.js";
 import { Vector3 } from "../math/Vector3.js";
 import { Bone } from "../objects/Bone.js";
-import { Mesh } from "../objects/Mesh.js";
 import { KeyframeTrack, KeyframeTrackJSON } from "./KeyframeTrack.js";
 
 export interface AnimationClipJSON {
@@ -18,44 +17,157 @@ export interface MorphTarget {
     vertices: Vector3[];
 }
 
+/**
+ * A reusable set of keyframe tracks which represent an animation.
+ */
 export class AnimationClip {
-    constructor(name?: string, duration?: number, tracks?: KeyframeTrack[], blendMode?: AnimationBlendMode);
-
-    name: string;
-    tracks: KeyframeTrack[];
-
     /**
-     * @default THREE.NormalAnimationBlendMode
+     * Factory method for creating an animation clip from the given JSON.
+     *
+     * @static
+     * @param {Object} json - The serialized animation clip.
+     * @return {AnimationClip} The new animation clip.
      */
-    blendMode: AnimationBlendMode;
-
+    static parse(json: AnimationClipJSON): AnimationClip;
     /**
-     * @default -1
+     * Serializes the given animation clip into JSON.
+     *
+     * @static
+     * @param {AnimationClip} clip - The animation clip to serialize.
+     * @return {Object} The JSON object.
+     */
+    static toJSON(clip: AnimationClip): AnimationClipJSON;
+    /**
+     * Returns a new animation clip from the passed morph targets array of a
+     * geometry, taking a name and the number of frames per second.
+     *
+     * Note: The fps parameter is required, but the animation speed can be
+     * overridden via {@link AnimationAction#setDuration}.
+     *
+     * @static
+     * @param {string} name - The name of the animation clip.
+     * @param {Array<Object>} morphTargetSequence - A sequence of morph targets.
+     * @param {number} fps - The Frames-Per-Second value.
+     * @param {boolean} noLoop - Whether the clip should be no loop or not.
+     * @return {AnimationClip} The new animation clip.
      */
-    duration: number;
-    uuid: string;
-    results: any[];
-
-    resetDuration(): AnimationClip;
-    trim(): AnimationClip;
-    validate(): boolean;
-    optimize(): AnimationClip;
-    clone(): this;
-    toJSON(): AnimationClipJSON;
-
     static CreateFromMorphTargetSequence(
         name: string,
-        morphTargetSequence: MorphTarget[],
+        morphTargetSequence: Array<MorphTarget>,
         fps: number,
         noLoop: boolean,
     ): AnimationClip;
-    static findByName(objectOrClipArray: AnimationClip[] | Object3D | Mesh, name: string): AnimationClip;
+    /**
+     * Searches for an animation clip by name, taking as its first parameter
+     * either an array of clips, or a mesh or geometry that contains an
+     * array named "animations" property.
+     *
+     * @static
+     * @param {(Array<AnimationClip>|Object3D)} objectOrClipArray - The array or object to search through.
+     * @param {string} name - The name to search for.
+     * @return {?AnimationClip} The found animation clip. Returns `null` if no clip has been found.
+     */
+    static findByName(objectOrClipArray: Array<AnimationClip> | Object3D, name: string): AnimationClip | null;
+    /**
+     * Returns an array of new AnimationClips created from the morph target
+     * sequences of a geometry, trying to sort morph target names into
+     * animation-group-based patterns like "Walk_001, Walk_002, Run_001, Run_002...".
+     *
+     * See {@link MD2Loader#parse} as an example for how the method should be used.
+     *
+     * @static
+     * @param {Array<Object>} morphTargets - A sequence of morph targets.
+     * @param {number} fps - The Frames-Per-Second value.
+     * @param {boolean} noLoop - Whether the clip should be no loop or not.
+     * @return {Array<AnimationClip>} An array of new animation clips.
+     */
     static CreateClipsFromMorphTargetSequences(
-        morphTargets: MorphTarget[],
+        morphTargets: Array<MorphTarget>,
         fps: number,
         noLoop: boolean,
-    ): AnimationClip[];
-    static parse(json: AnimationClipJSON): AnimationClip;
-    static parseAnimation(animation: AnimationClipJSON, bones: Bone[]): AnimationClip;
-    static toJSON(clip: AnimationClip): AnimationClipJSON;
+    ): Array<AnimationClip>;
+    /**
+     * Parses the `animation.hierarchy` format and returns a new animation clip.
+     *
+     * @static
+     * @deprecated since r175.
+     * @param {Object} animation - A serialized animation clip as JSON.
+     * @param {Array<Bones>} bones - An array of bones.
+     * @return {?AnimationClip} The new animation clip.
+     */
+    static parseAnimation(animation: AnimationClipJSON, bones: Array<Bone>): AnimationClip | null;
+    /**
+     * Constructs a new animation clip.
+     *
+     * Note: Instead of instantiating an AnimationClip directly with the constructor, you can
+     * use the static interface of this class for creating clips. In most cases though, animation clips
+     * will automatically be created by loaders when importing animated 3D assets.
+     *
+     * @param {string} [name=''] - The clip's name.
+     * @param {number} [duration=-1] - The clip's duration in seconds. If a negative value is passed,
+     * the duration will be calculated from the passed keyframes.
+     * @param {Array<KeyframeTrack>} tracks - An array of keyframe tracks.
+     * @param {(NormalAnimationBlendMode|AdditiveAnimationBlendMode)} [blendMode=NormalAnimationBlendMode] - Defines how the animation
+     * is blended/combined when two or more animations are simultaneously played.
+     */
+    constructor(name?: string, duration?: number, tracks?: Array<KeyframeTrack>, blendMode?: AnimationBlendMode);
+    /**
+     * The clip's name.
+     */
+    name: string;
+    /**
+     *  An array of keyframe tracks.
+     */
+    tracks: Array<KeyframeTrack>;
+    /**
+     * The clip's duration in seconds.
+     */
+    duration: number;
+    /**
+     * Defines how the animation is blended/combined when two or more animations
+     * are simultaneously played.
+     */
+    blendMode: AnimationBlendMode;
+    /**
+     * The UUID of the animation clip.
+     */
+    readonly uuid: string;
+    /**
+     * Sets the duration of this clip to the duration of its longest keyframe track.
+     *
+     * @return {AnimationClip} A reference to this animation clip.
+     */
+    resetDuration(): AnimationClip;
+    /**
+     * Trims all tracks to the clip's duration.
+     *
+     * @return {AnimationClip} A reference to this animation clip.
+     */
+    trim(): AnimationClip;
+    /**
+     * Performs minimal validation on each track in the clip. Returns `true` if all
+     * tracks are valid.
+     *
+     * @return {boolean} Whether the clip's keyframes are valid or not.
+     */
+    validate(): boolean;
+    /**
+     * Optimizes each track by removing equivalent sequential keys (which are
+     * common in morph target sequences).
+     *
+     * @return {AnimationClip} A reference to this animation clip.
+     */
+    optimize(): AnimationClip;
+    /**
+     * Returns a new animation clip with copied values from this instance.
+     *
+     * @return {AnimationClip} A clone of this instance.
+     */
+    clone(): this;
+    /**
+     * Serializes this animation clip into JSON.
+     *
+     * @return {Object} The JSON object.
+     */
+    toJSON(): AnimationClipJSON;
 }

three/src/animation/AnimationMixer.d.ts

@@ -10,30 +10,122 @@ export interface AnimationMixerEventMap {
     finished: { action: AnimationAction; direction: number };
 }
 
+/**
+ * `AnimationMixer` is a player for animations on a particular object in
+ * the scene. When multiple objects in the scene are animated independently,
+ * one `AnimationMixer` may be used for each object.
+ */
 export class AnimationMixer extends EventDispatcher<AnimationMixerEventMap> {
+    /**
+     * Constructs a new animation mixer.
+     *
+     * @param {Object3D} root - The object whose animations shall be played by this mixer.
+     */
     constructor(root: Object3D | AnimationObjectGroup);
-
     /**
+     * The global mixer time (in seconds; starting with `0` on the mixer's creation).
+     *
      * @default 0
      */
     time: number;
-
     /**
-     * @default 1.0
+     * A scaling factor for the global time.
+     *
+     * Note: Setting this member to `0` and later back to `1` is a
+     * possibility to pause/unpause all actions that are controlled by this
+     * mixer.
+     *
+     * @default 1
      */
     timeScale: number;
-
+    /**
+     * Returns an instance of {@link AnimationAction} for the passed clip.
+     *
+     * If an action fitting the clip and root parameters doesn't yet exist, it
+     * will be created by this method. Calling this method several times with the
+     * same clip and root parameters always returns the same action.
+     *
+     * @param {AnimationClip|string} clip - An animation clip or alternatively the name of the animation clip.
+     * @param {Object3D} [optionalRoot] - An alternative root object.
+     * @param {(NormalAnimationBlendMode|AdditiveAnimationBlendMode)} [blendMode] - The blend mode.
+     * @return {?AnimationAction} The animation action.
+     */
     clipAction(
         clip: AnimationClip,
-        root?: Object3D | AnimationObjectGroup,
+        optionalRoot?: Object3D | AnimationObjectGroup,
         blendMode?: AnimationBlendMode,
     ): AnimationAction;
-    existingAction(clip: AnimationClip, root?: Object3D | AnimationObjectGroup): AnimationAction | null;
+    clipAction(
+        clip: AnimationClip | string,
+        optionalRoot?: Object3D | AnimationObjectGroup,
+        blendMode?: AnimationBlendMode,
+    ): AnimationAction | null;
+    /**
+     * Returns an existing animation action for the passed clip.
+     *
+     * @param {AnimationClip|string} clip - An animation clip or alternatively the name of the animation clip.
+     * @param {Object3D} [optionalRoot] - An alternative root object.
+     * @return {?AnimationAction} The animation action. Returns `null` if no action was found.
+     */
+    existingAction(
+        clip: AnimationClip | string,
+        optionalRoot?: Object3D | AnimationObjectGroup,
+    ): AnimationAction | null;
+    /**
+     * Deactivates all previously scheduled actions on this mixer.
+     *
+     * @return {AnimationMixer} A reference to thi animation mixer.
+     */
     stopAllAction(): AnimationMixer;
+    /**
+     * Advances the global mixer time and updates the animation.
+     *
+     * This is usually done in the render loop by passing the delta
+     * time from {@link Clock} or {@link Timer}.
+     *
+     * @param {number} deltaTime - The delta time in seconds.
+     * @return {AnimationMixer} A reference to thi animation mixer.
+     */
     update(deltaTime: number): AnimationMixer;
-    setTime(timeInSeconds: number): AnimationMixer;
+    /**
+     * Sets the global mixer to a specific time and updates the animation accordingly.
+     *
+     * This is useful when you need to jump to an exact time in an animation. The
+     * input parameter will be scaled by {@link AnimationMixer#timeScale}
+     *
+     * @param {number} time - The time to set in seconds.
+     * @return {AnimationMixer} A reference to thi animation mixer.
+     */
+    setTime(time: number): AnimationMixer;
+    /**
+     * Returns this mixer's root object.
+     *
+     * @return {Object3D} The mixer's root object.
+     */
     getRoot(): Object3D | AnimationObjectGroup;
+    /**
+     * Deallocates all memory resources for a clip. Before using this method make
+     * sure to call {@link AnimationAction#stop} for all related actions.
+     *
+     * @param {AnimationClip} clip - The clip to uncache.
+     */
     uncacheClip(clip: AnimationClip): void;
+    /**
+     * Deallocates all memory resources for a root object. Before using this
+     * method make sure to call {@link AnimationAction#stop} for all related
+     * actions or alternatively {@link AnimationMixer#stopAllAction} when the
+     * mixer operates on a single root.
+     *
+     * @param {Object3D} root - The root object to uncache.
+     */
     uncacheRoot(root: Object3D | AnimationObjectGroup): void;
-    uncacheAction(clip: AnimationClip, root?: Object3D | AnimationObjectGroup): void;
+    /**
+     * Deallocates all memory resources for an action. The action is identified by the
+     * given clip and an optional root object. Before using this method make
+     * sure to call {@link AnimationAction#stop} to deactivate the action.
+     *
+     * @param {AnimationClip|string} clip - An animation clip or alternatively the name of the animation clip.
+     * @param {Object3D} [optionalRoot] - An alternative root object.
+     */
+    uncacheAction(clip: AnimationClip | string, optionalRoot?: Object3D | AnimationObjectGroup): void;
 }