@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
254 lines (253 loc) • 10 kB
TypeScript
import type { AnimationAction, AnimationActionLoopStyles, AnimationMixer } from "three";
import { IAnimationComponent } from "../engine/engine_types.js";
import type { AnimatorControllerModel } from "../engine/extensions/NEEDLE_animator_controller_model.js";
import { AnimatorController } from "./AnimatorController.js";
import { Behaviour } from "./Component.js";
/**
* Represents an event emitted by an animation mixer
* @category Animation and Sequencing
* @group Components
*/
export declare class MixerEvent {
/** The type of event that occurred */
type: string;
/** The animation action that triggered this event */
action: AnimationAction;
/** Number of loops completed in this cycle */
loopDelta: number;
/** The animation mixer that emitted this event */
target: AnimationMixer;
}
/**
* Configuration options for playing animations
* @category Animation and Sequencing
*/
export declare class PlayOptions {
/** Whether the animation should loop, and if so, which loop style to use */
loop?: boolean | AnimationActionLoopStyles;
/** Whether the final animation state should be maintained after playback completes */
clampWhenFinished?: boolean;
}
/**
* Animator plays and manages state-machine based animations on a GameObject.
* Uses an {@link AnimatorController} for state transitions, blending, and parameters.
*
* **State machine animations:**
* Define animation states and transitions in Unity's Animator window or in [Blender's Animator Controller editor](https://engine.needle.tools/docs/blender/animation.html)
* Control transitions via parameters (bool, int, float, trigger).
*
* 
*
* **Creating at runtime:**
* Use `AnimatorController.createFromClips()` to create controllers from code.
*
* **Parameters:**
* - `setTrigger(name)` - Trigger a one-shot transition
* - `setBool(name, value)` - Set boolean parameter
* - `setFloat(name, value)` - Set float parameter
* - `setInteger(name, value)` - Set integer parameter
*
* @example Trigger animation state
* ```ts
* const animator = myCharacter.getComponent(Animator);
* animator.setTrigger("Jump");
* animator.setFloat("Speed", 5);
* animator.setBool("IsRunning", true);
* ```
*
* @example Listen to animation events
* ```ts
* animator.onLoop(evt => console.log("Animation looped"));
* animator.onFinished(evt => console.log("Animation finished"));
* ```
*
* @summary Plays and manages animations on a GameObject based on an AnimatorController
* @category Animation and Sequencing
* @group Components
* @see {@link AnimatorController} for state machine configuration
* @see {@link Animation} for simple clip playback
* @see {@link PlayableDirector} for timeline-based animation
*
* @link https://engine.needle.tools/docs/blender/animation.html
*/
export declare class Animator extends Behaviour implements IAnimationComponent {
/**
* Identifies this component as an animation component in the engine
*/
get isAnimationComponent(): boolean;
/**
* When enabled, animation will affect the root transform position and rotation
*/
applyRootMotion: boolean;
/**
* Indicates whether this animator contains root motion data
*/
hasRootMotion: boolean;
/**
* When enabled, the animator will maintain its state when the component is disabled
*/
keepAnimatorControllerStateOnDisable: boolean;
/**
* Sets or replaces the animator controller for this component.
* Handles binding the controller to this animator instance and ensures
* proper initialization when the controller changes.
* @param val The animator controller model or instance to use
*/
set runtimeAnimatorController(val: AnimatorControllerModel | AnimatorController | undefined | null);
/**
* Gets the current animator controller instance
* @returns The current animator controller or null if none is assigned
*/
get runtimeAnimatorController(): AnimatorController | undefined | null;
/**
* Retrieves information about the current animation state
* @returns The current state information, or undefined if no state is playing
*/
getCurrentStateInfo(): import("../engine/extensions/NEEDLE_animator_controller_model.js").AnimatorStateInfo | null | undefined;
/**
* The currently playing animation action that can be used to modify animation properties
* @returns The current animation action, or null if no animation is playing
*/
get currentAction(): AnimationAction | null;
/**
* Indicates whether animation parameters have been modified since the last update
* @returns True if parameters have been changed
*/
get parametersAreDirty(): boolean;
private _parametersAreDirty;
/**
* Indicates whether the animator state has changed since the last update
* @returns True if the animator has been changed
*/
get isDirty(): boolean;
private _isDirty;
/**@deprecated use play() */
Play(name: string | number, layer?: number, normalizedTime?: number, transitionDurationInSec?: number): void;
/**
* Plays an animation on the animator
* @param name The name or hash of the animation to play
* @param layer The layer to play the animation on (-1 for default layer)
* @param normalizedTime The time position to start playing (0-1 range, NEGATIVE_INFINITY for current position)
* @param transitionDurationInSec The duration of the blend transition in seconds
*/
play(name: string | number, layer?: number, normalizedTime?: number, transitionDurationInSec?: number): void;
/**@deprecated use reset */
Reset(): void;
/**
* Resets the animator controller to its initial state
*/
reset(): void;
/**@deprecated use setBool */
SetBool(name: string | number, val: boolean): void;
/**
* Sets a boolean parameter in the animator
* @param name The name or hash of the parameter
* @param value The boolean value to set
*/
setBool(name: string | number, value: boolean): void;
/**@deprecated use getBool */
GetBool(name: string | number): boolean;
/**
* Gets a boolean parameter from the animator
* @param name The name or hash of the parameter
* @returns The value of the boolean parameter, or false if not found
*/
getBool(name: string | number): boolean;
/**
* Toggles a boolean parameter between true and false
* @param name The name or hash of the parameter
*/
toggleBool(name: string | number): void;
/**@deprecated use setFloat */
SetFloat(name: string | number, val: number): void;
/**
* Sets a float parameter in the animator
* @param name The name or hash of the parameter
* @param val The float value to set
*/
setFloat(name: string | number, val: number): void;
/**@deprecated use getFloat */
GetFloat(name: string | number): number;
/**
* Gets a float parameter from the animator
* @param name The name or hash of the parameter
* @returns The value of the float parameter, or -1 if not found
*/
getFloat(name: string | number): number;
/**@deprecated use setInteger */
SetInteger(name: string | number, val: number): void;
/**
* Sets an integer parameter in the animator
* @param name The name or hash of the parameter
* @param val The integer value to set
*/
setInteger(name: string | number, val: number): void;
/**@deprecated use getInteger */
GetInteger(name: string | number): number;
/**
* Gets an integer parameter from the animator
* @param name The name or hash of the parameter
* @returns The value of the integer parameter, or -1 if not found
*/
getInteger(name: string | number): number;
/**@deprecated use setTrigger */
SetTrigger(name: string | number): void;
/**
* Activates a trigger parameter in the animator
* @param name The name or hash of the trigger parameter
*/
setTrigger(name: string | number): void;
/**@deprecated use resetTrigger */
ResetTrigger(name: string | number): void;
/**
* Resets a trigger parameter in the animator
* @param name The name or hash of the trigger parameter
*/
resetTrigger(name: string | number): void;
/**@deprecated use getTrigger */
GetTrigger(name: string | number): void;
/**
* Gets the state of a trigger parameter from the animator
* @param name The name or hash of the trigger parameter
* @returns The state of the trigger parameter
*/
getTrigger(name: string | number): boolean | undefined;
/**@deprecated use isInTransition */
IsInTransition(): boolean;
/**
* Checks if the animator is currently in a transition between states
* @returns True if the animator is currently blending between animations
*/
isInTransition(): boolean;
/**@deprecated use setSpeed */
SetSpeed(speed: number): void;
/**
* Sets the playback speed of the animator
* @param speed The new playback speed multiplier
*/
setSpeed(speed: number): void;
/**
* Sets a random playback speed between the min and max values
* @param minMax Object with x (minimum) and y (maximum) speed values
*/
set minMaxSpeed(minMax: {
x: number;
y: number;
});
/**
* Sets a random normalized time offset for animations between min (x) and max (y) values
* @param minMax Object with x (min) and y (max) values for the offset range
*/
set minMaxOffsetNormalized(minMax: {
x: number;
y: number;
});
private _speed;
private _normalizedStartOffset;
private _animatorController?;
awake(): void;
private _initializeWithRuntimeAnimatorController?;
initializeRuntimeAnimatorController(force?: boolean): void;
onDisable(): void;
onBeforeRender(): void;
}