@needle-tools/engine/dist/needle-engine.d.ts

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.

import { AnimationAction } from 'three';
import { AnimationClip } from 'three';
import { AnimationMixer } from 'three';
import { Audio as Audio_2 } from 'three';
import { AudioListener as AudioListener_3 } from 'three';
import { BatchedMesh } from 'three';
import { BloomEffect as BloomEffect_2 } from 'postprocessing';
import { Box3 } from 'three';
import { BufferGeometry } from 'three';
import { Camera as Camera_2 } from 'three';
import { Collider as Collider_2 } from '@dimforge/rapier3d-compat';
import { ColliderDesc } from '@dimforge/rapier3d-compat';
import { Color } from 'three';
import { ColorRepresentation } from 'three';
import { Curve } from 'three';
import { default as default_2 } from 'peerjs';
import { default as default_3 } from 'three/src/materials/nodes/MeshPhysicalNodeMaterial.js';
import { DepthOfFieldEffect } from 'postprocessing';
import { DepthTexture } from 'three';
import { dimforgeRapier3dCompat } from '@dimforge/rapier3d-compat';
import { DocumentedOptions } from 'three-mesh-ui/build/types/core/elements/MeshUIBaseElement.js';
import { Effect } from 'postprocessing';
import { EffectComposer } from 'postprocessing';
import { EffectComposer as EffectComposer_2 } from 'three/examples/jsm/postprocessing/EffectComposer.js';
import { EmitterShape } from 'three.quarks';
import { Euler } from 'three';
import { EventDispatcher } from 'three';
import { Face } from 'three';
import * as fflate from 'three/examples/jsm/libs/fflate.module.js';
import * as flatbuffers from 'flatbuffers';
import { Fog as Fog_2 } from 'three';
import { Font } from 'three/examples/jsm/loaders/FontLoader.js';
import { Frustum } from 'three';
import { GLTF as GLTF_2 } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { GLTFExporter } from 'three/examples/jsm/exporters/GLTFExporter.js';
import { GLTFExporterOptions } from 'three/examples/jsm/exporters/GLTFExporter.js';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { GLTFLoaderPlugin } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { GLTFParser } from 'three/examples/jsm/loaders/GLTFLoader.js';
import { Group } from 'three';
import { InstancedMesh } from 'three';
import { Intersection } from 'three';
import { IParticleSystem as IParticleSystem_2 } from 'three.quarks';
import { KeyframeTrack } from 'three';
import { Layers } from 'three';
import { LightProbe } from 'three';
import { Line2 } from 'three/examples/jsm/lines/Line2.js';
import { Loader } from 'three';
import { LoadingManager } from 'three';
import { LOD_Results } from '@needle-tools/gltf-progressive';
import { LODsManager as LODsManager_2 } from '@needle-tools/gltf-progressive';
import { Material } from 'three';
import { Matrix4 } from 'three';
import { MediaConnection } from 'peerjs';
import { Mesh } from 'three';
import { MeshBasicMaterial } from 'three';
import { MeshPhysicalMaterial } from 'three';
import { MeshStandardMaterial } from 'three';
import { N8AOPostPass } from 'n8ao';
import { NEEDLE_progressive } from '@needle-tools/gltf-progressive';
import { NEEDLE_progressive_plugin } from '@needle-tools/gltf-progressive';
import { needleToolsMaterialx } from '@needle-tools/materialx';
import { NormalBufferAttributes } from 'three';
import { Object3D } from 'three';
import { Object3DEventMap } from 'three';
import { Options } from 'three-mesh-ui/build/types/core/elements/MeshUIBaseElement.js';
import { OrbitControls as OrbitControls_2 } from 'three/examples/jsm/controls/OrbitControls.js';
import { OrthographicCamera } from 'three';
import { ParticleSystem as ParticleSystem_2 } from 'three.quarks';
import { Pass } from 'postprocessing';
import { PeerJSOption } from 'peerjs';
import { PerspectiveCamera } from 'three';
import { PositionalAudio } from 'three';
import { postprocessing } from 'postprocessing';
import { Particle as QParticle } from 'three.quarks';
import { Behavior as QParticleBehaviour } from 'three.quarks';
import { TrailParticle as QTrailParticle } from 'three.quarks';
import { Quaternion } from 'three';
import { QueryFilterFlags } from '@dimforge/rapier3d-compat';
import { RawShaderMaterial } from 'three';
import { Ray } from 'three';
import { Raycaster } from 'three';
import { Scene } from 'three';
import { ShaderMaterial } from 'three';
import { ShapeJSON } from 'three.quarks';
import { SkinnedMesh } from 'three';
import { Sprite as Sprite_2 } from 'three';
import { SpriteMaterial } from 'three';
import { Texture } from 'three';
import * as ThreeMeshUI from 'three-mesh-ui';
import { TransformControls } from 'three/examples/jsm/controls/TransformControls.js';
import { Vector2 } from 'three';
import { Vector2Like } from 'three';
import { Vector3 } from 'three';
import { Vector3 as Vector3_2 } from 'three.quarks';
import { Vector3Like } from 'three';
import { Vector4 } from 'three';
import { Vector4 as Vector4_2 } from 'three.quarks';
import { Vector4Like } from 'three';
import { VideoTexture } from 'three';
import { WebGLCubeRenderTarget } from 'three';
import { WebGLRenderer } from 'three';
import { WebGLRendererParameters } from 'three';
import { WebGLRenderTarget } from 'three';
import { WebXRArrayCamera } from 'three';
import { World } from '@dimforge/rapier3d-compat';
import { XRControllerModelFactory } from 'three/examples/jsm/webxr/XRControllerModelFactory.js';
import { XRHandMeshModel } from 'three/examples/jsm/webxr/XRHandMeshModel.js';
import { XRHandSpace } from 'three';

export declare const $componentName: unique symbol;

export declare const $physicsKey: unique symbol;

export declare class __Ignore {
}

export declare function __internalNotifyObjectDestroyed(obj: Object3D): void;

/** Data describing the accessible semantics for a 3D object or component. */
declare type AccessibilityData = {
    /** ARIA role (e.g. `"button"`, `"img"`, `"region"`). */
    role: string;
    /** Human-readable label announced by screen readers. */
    label: string;
    /** When `true`, the element is hidden from the accessibility tree. */
    hidden?: boolean;
    /** When `true`, indicates the element's content is being updated. */
    busy?: boolean;
};

/**
 * Manages an accessible, screen-reader-friendly overlay for a Needle Engine {@link Context}.
 *
 * The manager maintains a visually-hidden DOM tree that mirrors relevant 3D scene objects
 * with appropriate ARIA roles and labels. It also provides a live region so that hover
 * events in the 3D scene can be announced to assistive technology without stealing focus.
 *
 * ## Automatic integration
 * Several built-in components register accessible elements automatically:
 * - {@link DragControls} — announces draggable objects and drag state
 * - {@link Button} — exposes UI buttons to the accessibility tree
 * - {@link Text} — exposes UI text content to screen readers
 * - {@link ChangeTransformOnClick} — announces clickable transform actions
 * - {@link ChangeMaterialOnClick} — announces clickable material changes
 * - {@link EmphasizeOnClick} — announces clickable emphasis effects
 * - {@link PlayAudioOnClick} — announces clickable audio playback
 * - {@link PlayAnimationOnClick} — announces clickable animation triggers
 *
 * ## What this unlocks
 * - Hovering over buttons and interactive objects with the cursor announces them to screen readers via an ARIA live region — no focus steal required
 * - Screen readers can discover and navigate interactive 3D objects in the scene
 * - Drag operations update the accessibility state (busy, label changes) in real time
 * - Custom components can participate by calling {@link updateElement}, {@link focus}, and {@link hover}
 *
 * Access the manager via `this.context.accessibility` from any component.
 */
declare class AccessibilityManager {
    private readonly context;
    private static readonly _managers;
    /** Returns the {@link AccessibilityManager} associated with the given context or component. */
    static get(obj: Context | IComponent): AccessibilityManager | undefined;
    constructor(context: Context);
    private _enabled;
    /** Enables or disables the accessibility overlay. When disabled, the overlay DOM is removed. */
    set enabled(value: boolean);
    /** Removes all tracked accessibility elements, keeping only the live region. */
    clear(): void;
    /** Removes the overlay from the DOM and unregisters this manager from the context. */
    dispose(): void;
    private readonly root;
    private readonly liveRegion;
    private readonly treeElements;
    /**
     * Creates or updates the accessible DOM element for a 3D object or component.
     * @param obj - The scene object or component to represent.
     * @param data - Partial accessibility data (role, label, hidden, busy) to apply.
     */
    updateElement<T extends Object3D | IComponent>(obj: T, data: Partial<AccessibilityData>): void;
    /** Moves keyboard focus to the accessible element representing the given object. */
    focus<T extends Object3D | IComponent>(obj: T): void;
    /** Removes keyboard focus from the accessible element representing the given object. */
    unfocus<T extends Object3D | IComponent>(obj: T): void;
    /**
     * Announces a hover event to screen readers via the ARIA live region.
     * @param obj - The hovered object (used to look up its label if `text` is not provided).
     * @param text - Optional text to announce. Falls back to the element's `aria-label`.
     */
    hover<T extends Object3D | IComponent>(obj: T, text?: string): void;
    /** Removes the accessible DOM element for the given object and stops tracking it. */
    removeElement(obj: Object3D | IComponent): void;
    private set liveRegionMode(value);
}

export declare class ActionBuilder {
    static sequence(...params: IBehaviorElement[]): GroupActionModel;
    static parallel(...params: IBehaviorElement[]): GroupActionModel;
    static fadeAction(targetObject: Target, duration: number, show: boolean): ActionModel;
    /**
     * creates an action that plays an animation
     * @param start offset in seconds!
     * @param duration in seconds! 0 means play to end
     */
    static startAnimationAction(targetObject: Target, anim: RegisteredAnimationInfo, reversed?: boolean, pingPong?: boolean): IBehaviorElement;
    static waitAction(duration: number): ActionModel;
    static lookAtCameraAction(targets: Target, duration?: number, front?: Vec3_2, up?: Vec3_2): ActionModel;
    static emphasize(targets: Target, duration: number, motionType?: EmphasizeActionMotionType, moveDistance?: number, style?: MotionStyle): ActionModel;
    static transformAction(targets: Target, transformTarget: Target, duration: number, transformType: Space, easeType?: EaseType): ActionModel;
    static playAudioAction(targets: Target, audio: string, type?: PlayAction, gain?: number, auralMode?: AuralMode): ActionModel;
    static impulseAction(targets: Target, velocity: Vec3_2): ActionModel;
}

export declare class ActionCollection {
    private actions;
    private sortedActions?;
    constructor(actions: DocumentAction[]);
    private organize;
    /** returns all document actions affecting the object passed in */
    getActions(obj: Object3D): DocumentAction[] | null;
}

export declare class ActionModel implements IBehaviorElement {
    private static global_id;
    id: string;
    tokenId?: "ChangeScene" | "Visibility" | "StartAnimation" | "Wait" | "LookAtCamera" | "Emphasize" | "Transform" | "Audio" | "Impulse";
    affectedObjects?: string | Target;
    easeType?: EaseType;
    motionType: EmphasizeActionMotionType | VisibilityActionMotionType | undefined;
    duration?: number;
    moveDistance?: number;
    style?: MotionStyle;
    type?: Space | PlayAction | VisibilityMode;
    front?: Vec3_2;
    up?: Vec3_2;
    start?: number;
    animationSpeed?: number;
    reversed?: boolean;
    pingPong?: boolean;
    xFormTarget?: Target | string;
    audio?: string;
    gain?: number;
    auralMode?: AuralMode;
    multiplePerformOperation?: MultiplePerformOperation;
    velocity?: Vec3_2;
    comment?: string;
    animationName?: string;
    clone(): ActionModel;
    constructor(affectedObjects?: string | Target, id?: string);
    writeTo(document: USDDocument, writer: USDWriter): void;
}

export declare const activeInHierarchyFieldName = "needle_isActiveInHierarchy";

/**
 * Register a callback when an {@link HTMLElement} attribute changes.
 * This is used, for example, by the Skybox component to watch for changes to the environment-* and skybox-* attributes.
 * @returns A function that can be used to unregister the callback
 */
export declare function addAttributeChangeCallback(domElement: HTMLElement, name: string, callback: AttributeChangeCallback): () => void;

export declare function addComponent<T extends IComponent>(obj: Object3D, componentInstance: T | ConstructorConcrete<T>, init?: ComponentInit<T>, opts?: {
    callAwake: boolean;
}): T;

/** Register callbacks for registering custom gltf importer or exporter plugins */
export declare function addCustomExtensionPlugin(ext: INeedleGLTFExtensionPlugin): void;

export declare function addNewComponent<T extends IComponent>(obj: Object3D, componentInstance: T, callAwake?: boolean): T;

/**
 * Use patcher for patching properties insteadof calling Object.defineProperty individually
 * since this will cause conflicts if multiple patches need to be applied to the same property
 */
export declare function addPatch<T extends object>(prototype: T, fieldName: string, beforeCallback?: Prefix | null, afterCallback?: Postfix | null): void;

/**
 * The Addressables class is used to register and manage {@link AssetReference} types
 * It can be accessed from components via {@link Context.Current} or {@link Context.addressables} (e.g. `this.context.addressables`)
 */
export declare class Addressables {
    private _context;
    private _assetReferences;
    /* Excluded from this release type: __constructor */
    /* Excluded from this release type: dispose */
    private preUpdate;
    /**
     * Find a registered AssetReference by its URL
     */
    findAssetReference(url: string): AssetReference | null;
    /* Excluded from this release type: registerAssetReference */
    /* Excluded from this release type: unregisterAssetReference */
}

/**[documentation](https://developer.apple.com/documentation/arkit/usdz_schemas_for_ar/preliminary_anchoringapi/preliminary_planeanchoring_alignment) */
declare type Alignment = "horizontal" | "vertical" | "any";

/**
 * The [AlignmentConstraint](https://engine.needle.tools/docs/api/AlignmentConstraint) positions and scales this GameObject to span between two target objects.
 * The object is rotated to face `to` and scaled along Z to match the distance.
 *
 * **Use cases:**
 * - Dynamic beams or laser effects between objects
 * - Stretchy connectors or ropes
 * - Visual links between UI elements
 * - Debug lines between transforms
 *
 * **How it works:**
 * - Position: Centered between `from` and `to` (or at `from` if not centered)
 * - Rotation: Looks at `to` from `from`
 * - Scale: Z-axis scales to match distance, X/Y use `width`
 *
 * @example Create a beam between two objects
 * ```ts
 * const beam = beamMesh.addComponent(AlignmentConstraint);
 * // Set targets via serialized properties in editor
 * // or via code if properties are exposed
 * ```
 *
 * @summary Aligns and scales object between two targets
 * @category Constraints
 * @group Components
 * @see {@link SmoothFollow} for following with smoothing
 **/
export declare class AlignmentConstraint extends Component {
    private from;
    private to;
    private width;
    private centered;
    private _centerPos;
    awake(): void;
    update(): void;
}

declare type AlphaKey = {
    time: number;
    alpha: number;
};

/* Excluded from this release type: AmbientMode */

/**[documentation](https://developer.apple.com/documentation/arkit/usdz_schemas_for_ar/preliminary_anchoringapi/preliminary_anchoring_type) */
declare type Anchoring = "plane" | "image" | "face" | "none";

/**
 * Animation component to play animations on a GameObject.
 * For simpler animation needs compared to {@link Animator}, this component directly
 * plays AnimationClips without state machine logic.
 *
 * **Key features:**
 * - Play animations by index, name, or clip reference
 * - Cross-fade between animations with `fadeDuration`
 * - Loop or play once with optional clamping
 * - Random start time and speed variation
 * - Promise-based completion handling
 *
 *
 * ![](https://cloud.needle.tools/-/media/zXQhLgtxr5ZaxLDTDb3MXA.gif)
 *
 * @example Play animation by name
 * ```ts
 * const anim = this.gameObject.getComponent(Animation);
 * await anim?.play("Walk", { loop: true, fadeDuration: 0.3 });
 * ```
 *
 * @example Play with options
 * ```ts
 * anim?.play(0, {
 *   loop: false,
 *   clampWhenFinished: true,
 *   speed: 2
 * });
 * ```
 *
 * @summary Plays animations from AnimationClips
 * @category Animation and Sequencing
 * @group Components
 * @see {@link Animator} for state machine-based animation
 * @see {@link PlayOptions} for all playback options
 * @link https://engine.needle.tools/samples/?overlay=samples&tag=animation
 * @link https://engine.needle.tools/samples/imunogard/
 *
 * @link https://engine.needle.tools/docs/blender/animation.html
 *
 * ![](https://cloud.needle.tools/-/media/vAYv-kU-eMpICqQZHJktCA.gif)
 *
 */
declare class Animation_2 extends Component implements IAnimationComponent {
    get isAnimationComponent(): boolean;
    addClip(clip: AnimationClip): void;
    /**
     * If true, the animation will start playing when the component is enabled
     */
    playAutomatically: boolean;
    /**
     * If true, the animation will start at a random time. This is used when the animation component is enabled
     * @default false
     */
    randomStartTime: boolean;
    /**
     * The animation min-max speed range
     * @default undefined
     */
    minMaxSpeed?: Vec2_2;
    /**
     * The normalized offset to start the animation at. This will override startTime
     * @default undefined
     */
    minMaxOffsetNormalized?: Vec2_2;
    /**
     * Set to true to loop the animation
     * @default true
     */
    loop: boolean;
    /**
     * If true, the animation will clamp when finished
     */
    clampWhenFinished: boolean;
    /**
     * The time in seconds of the first running animation action
     * @default 0
     */
    get time(): number;
    set time(val: number);
    get duration(): number;
    private _tempAnimationClipBeforeGameObjectExisted;
    /**
     * Get the first animation clip in the animations array
     */
    get clip(): AnimationClip | null;
    /**
     * Set the first animation clip in the animations array
     */
    set clip(val: AnimationClip | null);
    set clips(animations: AnimationClip[]);
    private _tempAnimationsArray;
    set animations(animations: AnimationClip[]);
    get animations(): AnimationClip[];
    private mixer;
    /**
     * The animation actions
     */
    get actions(): Array<AnimationAction>;
    set actions(val: Array<AnimationAction>);
    private _actions;
    private _handles;
    /* Excluded from this release type: awake */
    /* Excluded from this release type: onEnable */
    /* Excluded from this release type: update */
    /* Excluded from this release type: onDisable */
    /* Excluded from this release type: onDestroy */
    /** Get an animation action by the animation clip name */
    getAction(name: string): AnimationAction | null;
    /** Is any animation playing? */
    get isPlaying(): boolean;
    /** Stops all currently playing animations */
    stopAll(opts?: Pick<PlayOptions, "fadeDuration">): void;
    /**
     * Stops a specific animation clip or index. If clip is undefined then all animations will be stopped
     */
    stop(clip?: AnimationIdentifier, opts?: Pick<PlayOptions, "fadeDuration">): void;
    /**
     * Pause all animations or a specific animation clip or index
     * @param clip optional animation clip, index or name, if undefined all animations will be paused
     * @param unpause if true, the animation will be resumed
     */
    pause(clip?: AnimationIdentifier, unpause?: boolean): void;
    /**
     * Resume all paused animations.
     * Note that this will not fade animations in or out and just unpause previous animations. If an animation was faded out which means it's not running anymore, it will not be resumed.
     */
    resume(): void;
    /**
     * Play an animation clip or an clip at the specified index.
     * @param clipOrNumber the animation clip, index or name to play. If undefined, the first animation in the animations array will be played
     * @param options the play options. Use to set the fade duration, loop, speed, start time, end time, clampWhenFinished
     * @returns a promise that resolves when the animation is finished (note that it will not resolve if the animation is looping)
     */
    play(clipOrNumber?: AnimationIdentifier, options?: PlayOptions): Promise<AnimationAction> | void;
    private internalOnPlay;
    private tryFindHandle;
    private ensureMixer;
}
export { Animation_2 as Animation }

/**
 * @category Animation and Sequencing
 * @see {@link PlayableDirector} for the main component to control timelines in Needle Engine.
 */
export declare type AnimationClipModel = {
    clip: string | number | AnimationClip;
    loop: boolean;
    duration: number;
    removeStartOffset: boolean;
    position?: Vec3_3 | Vector3;
    rotation?: Quat | Quaternion;
};

/**
 * AnimationCurve is a representation of a curve that can be used to animate values over time.
 *
 * @category Animation
 * @group Utilities
 */
export declare class AnimationCurve {
    /**
     * Creates an animation curve that goes from the `from` value to the `to` value over the given `duration`.
     */
    static linearFromTo(from: number, to: number, duration: number): AnimationCurve;
    /** Creates an animation curve with just one keyframe */
    static constant(value: number): AnimationCurve;
    /**
     * The keyframes that define the curve.
     */
    keys: Array<Keyframe_2>;
    /**
     * Clones this AnimationCurve and returns a new instance with the same keyframes (the keyframes are also cloned).
     */
    clone(): AnimationCurve;
    /** The duration of the curve, which is the time of the last keyframe. */
    get duration(): number;
    /** Evaluates the curve at the given time and returns the value of the curve at that time.
     * @param time The time at which to evaluate the curve.
     * @returns The value of the curve at the given time.
     */
    evaluate(time: number): number;
    static interpolateValue(time: number, keyframe1: Keyframe_2, keyframe2: Keyframe_2): number;
}

export declare class AnimationExtension implements IUSDExporterExtension {
    get extensionName(): string;
    get animationData(): Map<Object3D<Object3DEventMap>, TransformData[]>;
    get registeredClips(): MapIterator<AnimationClip>;
    get animatedRoots(): MapIterator<Object3D<Object3DEventMap>>;
    get holdClipMap(): Map<AnimationClip, AnimationClip>;
    /** For each animated object, contains time/pos/rot/scale samples in the format that USD needs,
     *  ready to be written to the .usda file.
     */
    private dict;
    /** Map of all roots (Animation/Animator or scene) and all targets that they animate.
     *  We need that info so that we can ensure that each target has the same number of TransformData entries
     *  so that switching between animations doesn't result in data "leaking" to another clip.
     */
    private rootTargetMap;
    private rootAndClipToRegisteredAnimationMap;
    /** Clips registered for each root */
    private rootToRegisteredClip;
    private lastClipEndTime;
    private clipToStartTime;
    private clipToHoldClip;
    private serializers;
    /** Determines if we inject a rest pose clip for each root - only makes sense for QuickLook */
    injectRestPoses: boolean;
    /** Determines if we inject a PlayAnimationOnClick component with "scenestart" trigger - only makes sense for QuickLook */
    injectImplicitBehaviours: boolean;
    constructor(quickLookCompatible: boolean);
    getStartTimeCode(): number;
    /** Returns the end time code, based on 60 frames per second, for all registered animations.
     * This matches the highest time value in the USDZ file. */
    getEndTimeCode(): number;
    getClipCount(root: Object3D): number;
    getStartTimeByClip(clip: AnimationClip | null): number;
    /** Register an AnimationClip for a specific root object.
     * @param root The root object that the animation clip is targeting.
     * @param clip The animation clip to register. If null, a rest pose is registered.
     * @returns The registered animation info, which contains the start time and duration of the clip.
     */
    registerAnimation(root: Object3D, clip: AnimationClip | null): RegisteredAnimationInfo | null;
    onAfterHierarchy(_context: any): void;
    onAfterBuildDocument(_context: any): void;
    onExportObject(object: any, model: USDObject, _context: any): void;
}

declare type AnimationIdentifier = AnimationClip | number | string | undefined;

/**
 * Registry for animation related data. Use {@link registerAnimationMixer} to register an animation mixer instance.
 * Can be accessed from {@link Context.animations} and is used internally e.g. when exporting GLTF files.
 * @category Animation
 */
declare class AnimationsRegistry {
    readonly context: Context;
    readonly mixers: AnimationMixer[];
    constructor(context: Context);
    /* Excluded from this release type: onDestroy */
    /**
     * Register an animation mixer instance.
     */
    registerAnimationMixer(mixer: AnimationMixer): void;
    /**
     * Unregister an animation mixer instance.
     */
    unregisterAnimationMixer(mixer: AnimationMixer | null | undefined): void;
}

export declare class AnimationTrackHandler extends TrackHandler {
    /* Excluded from this release type: models */
    /* Excluded from this release type: trackOffset */
    /** The object that is being animated. */
    target?: Object3D;
    /** The AnimationMixer, should be shared with the animator if an animator is bound */
    mixer?: AnimationMixer;
    clips: Array<AnimationClip>;
    actions: Array<AnimationAction>;
    /**
     * You can use the weight to blend the timeline animation tracks with multiple animation tracks on the same object.
     * @default 1
     */
    weight: number;
    /** holds data/info about clips differences */
    private _actionOffsets;
    private _didBind;
    private _animator;
    onDisable(): void;
    onDestroy(): void;
    onStateChanged(): void;
    createHooks(clipModel: Models.AnimationClipModel, clip: any): void;
    bind(): void;
    private ensureTrackOffsets;
    private _useclipOffsets;
    private _totalOffsetPosition;
    private _totalOffsetRotation;
    private _totalOffsetPosition2;
    private _totalOffsetRotation2;
    private _summedPos;
    private _tempPos;
    private _summedRot;
    private _tempRot;
    private _clipRotQuat;
    evaluate(time: number): void;
    private createRotationInterpolant;
    private createPositionInterpolant;
}

declare class AnimationTriggers {
    disabledTrigger: string;
    highlightedTrigger: string;
    normalTrigger: string;
    pressedTrigger: string;
    selectedTrigger: string;
}

/**
 * Utility class for working with animations.
 */
export declare class AnimationUtils {
    /**
     * Tests if the root object of an AnimationAction can be animated. Objects where matrixAutoUpdate or matrixWorldAutoUpdate is set to false may not animate correctly.
     * @param action The AnimationAction to test
     * @param allowLog Whether to allow logging warnings. Default is false, which only allows logging in development environments.
     * @returns True if the root object can be animated, false otherwise
     */
    static testIfRootCanAnimate(action: AnimationAction, allowLog?: boolean): boolean;
    /**
     * Tries to get the animation actions from an animation mixer.
     * @param mixer The animation mixer to get the actions from
     * @returns The actions or null if the mixer is invalid
     */
    static tryGetActionsFromMixer(mixer: AnimationMixer): Array<AnimationAction> | null;
    static tryGetAnimationClipsFromObjectHierarchy(obj: Object3D, target?: Array<AnimationClip>): Array<AnimationClip>;
    /**
     * Assigns animations from a GLTF file to the objects in the scene.
     * This method will look for objects in the scene that have animations and assign them to the correct objects.
     * @param file The GLTF file to assign the animations from
     */
    static autoplayAnimations(file: Object3D | Pick<Model, "animations" | "scene">): Array<IAnimationComponent> | null;
    static emptyClip(): AnimationClip;
    static createScaleClip(options?: ScaleClipOptions): AnimationClip;
}

/**
 * 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).
 *
 * ![](https://cloud.needle.tools/-/media/zXQhLgtxr5ZaxLDTDb3MXA.gif)
 *
 * **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 Component 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(): 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;
}

export declare enum AnimatorConditionMode {
    If = 1,
    IfNot = 2,
    Greater = 3,
    Less = 4,
    Equals = 6,
    NotEqual = 7
}

/**
 * Controls the playback of animations using a state machine architecture.
 *
 * The AnimatorController manages animation states, transitions between states,
 * and parameters that affect those transitions. It is used by the {@link Animator}
 * component to control animation behavior on 3D models.
 *
 * Use the static method {@link AnimatorController.createFromClips} to create
 * an animator controller from a set of animation clips.
 *
 * @category Animation and Sequencing
 * @group Utilities
 */
export declare class AnimatorController {
    /**
     * Creates an AnimatorController from a set of animation clips.
     * Each clip becomes a state in the controller's state machine.
     *
     * @param clips - The animation clips to use for creating states
     * @param options - Configuration options for the controller including looping behavior and transitions
     * @returns A new AnimatorController instance
     */
    static createFromClips(clips: AnimationClip[], options?: CreateAnimatorControllerOptions): AnimatorController;
    /**
     * Plays an animation state by name or hash.
     *
     * @param name - The name or hash identifier of the state to play
     * @param layerIndex - The layer index (defaults to 0)
     * @param normalizedTime - The normalized time to start the animation from (0-1)
     * @param durationInSec - Transition duration in seconds
     */
    play(name: string | number, layerIndex?: number, normalizedTime?: number, durationInSec?: number): void;
    /**
     * Resets the controller to its initial state.
     */
    reset(): void;
    /**
     * Sets a boolean parameter value by name or hash.
     *
     * @param name - The name or hash identifier of the parameter
     * @param value - The boolean value to set
     */
    setBool(name: string | number, value: boolean): void;
    /**
     * Gets a boolean parameter value by name or hash.
     *
     * @param name - The name or hash identifier of the parameter
     * @returns The boolean value of the parameter, or false if not found
     */
    getBool(name: string | number): boolean;
    /**
     * Sets a float parameter value by name or hash.
     *
     * @param name - The name or hash identifier of the parameter
     * @param val - The float value to set
     * @returns True if the parameter was found and set, false otherwise
     */
    setFloat(name: string | number, val: number): boolean;
    /**
     * Gets a float parameter value by name or hash.
     *
     * @param name - The name or hash identifier of the parameter
     * @returns The float value of the parameter, or 0 if not found
     */
    getFloat(name: string | number): number;
    /**
     * Sets an integer parameter value by name or hash.
     *
     * @param name - The name or hash identifier of the parameter
     * @param val - The integer value to set
     */
    setInteger(name: string | number, val: number): void;
    /**
     * Gets an integer parameter value by name or hash.
     *
     * @param name - The name or hash identifier of the parameter
     * @returns The integer value of the parameter, or 0 if not found
     */
    getInteger(name: string | number): number;
    /**
     * Sets a trigger parameter to active (true).
     * Trigger parameters are automatically reset after they are consumed by a transition.
     *
     * @param name - The name or hash identifier of the trigger parameter
     */
    setTrigger(name: string | number): void;
    /**
     * Resets a trigger parameter to inactive (false).
     *
     * @param name - The name or hash identifier of the trigger parameter
     */
    resetTrigger(name: string | number): void;
    /**
     * Gets the current state of a trigger parameter.
     *
     * @param name - The name or hash identifier of the trigger parameter
     * @returns The boolean state of the trigger, or false if not found
     */
    getTrigger(name: string | number): boolean;
    /**
     * Checks if the controller is currently in a transition between states.
     *
     * @returns True if a transition is in progress, false otherwise
     */
    isInTransition(): boolean;
    /** Set the speed of the animator controller. Larger values will make the animation play faster. */
    setSpeed(speed: number): void;
    private _speed;
    /**
     * Finds an animation state by name or hash.
     * @deprecated Use findState instead
     *
     * @param name - The name or hash identifier of the state to find
     * @returns The found state or null if not found
     */
    FindState(name: string | number | undefined | null): State | null;
    /**
     * Finds an animation state by name or hash.
     *
     * @param name - The name or hash identifier of the state to find
     * @returns The found state or null if not found
     */
    findState(name: string | number | undefined | null): State | null;
    /**
     * Gets information about the current playing animation state.
     *
     * @returns An AnimatorStateInfo object with data about the current state, or null if no state is active
     */
    getCurrentStateInfo(): AnimatorStateInfo | null;
    /**
     * Gets the animation action currently playing.
     *
     * @returns The current animation action, or null if no action is playing
     */
    get currentAction(): AnimationAction | null;
    /**
     * The normalized time (0-1) to start playing the first state at.
     * This affects the initial state when the animator is first enabled.
     */
    normalizedStartOffset: number;
    /**
     * The Animator component this controller is bound to.
     */
    animator?: Animator;
    /**
     * The data model describing the animation states and transitions.
     */
    model: AnimatorControllerModel;
    /**
     * Gets the engine context from the bound animator.
     */
    get context(): Context | undefined | null;
    /**
     * Gets the animation mixer used by this controller.
     */
    get mixer(): AnimationMixer;
    /**
     * Cleans up resources used by this controller.
     * Stops all animations and unregisters the mixer from the animation system.
     */
    dispose(): void;
    /**
     * Binds this controller to an animator component.
     * Creates a new animation mixer and sets up animation actions.
     *
     * @param animator - The animator to bind this controller to
     */
    bind(animator: Animator): void;
    /**
     * Creates a deep copy of this controller.
     * Clones the model data but does not copy runtime state.
     *
     * @returns A new AnimatorController instance with the same configuration
     */
    clone(): AnimatorController | null;
    /**
     * Updates the controller's state machine and animations.
     * Called each frame by the animator component.
     *
     * @param weight - The weight to apply to the animations (for blending)
     */
    update(weight: number): void;
    private _mixer;
    private _activeState?;
    /**
     * Gets the currently active animation state.
     *
     * @returns The active state or undefined if no state is active
     */
    get activeState(): State | undefined;
    constructor(model: AnimatorControllerModel);
    private _activeStates;
    private updateActiveStates;
    private setStartTransition;
    private evaluateTransitions;
    private setTimescale;
    private getState;
    /**
     * These actions have been active previously but not faded out because we entered a state that has no real animation - no duration. In which case we hold the previously active actions until they are faded out.
     */
    private readonly _heldActions;
    private releaseHeldActions;
    private transitionTo;
    private createAction;
    private evaluateCondition;
    private createActions;
    /**
     * Yields all animation actions managed by this controller.
     * Iterates through all states in all layers and returns their actions.
     */
    enumerateActions(): Generator<AnimationAction, void, unknown>;
    private rootMotionHandler?;
}

export declare type AnimatorControllerModel = {
    name: string;
    guid: string;
    parameters: Parameter[];
    layers: Layer[];
};

export declare enum AnimatorControllerParameterType {
    Float = 1,
    Int = 3,
    Bool = 4,
    Trigger = 9
}

export declare class AnimatorStateInfo {
    /** The name of the animation */
    readonly name: string;
    /** The hash of the name */
    readonly nameHash: number;
    /** The normalized time of the animation */
    readonly normalizedTime: number;
    /** The length of the animation */
    readonly length: number;
    /** The current speed of the animation */
    readonly speed: number;
    /** The current action playing. It can be used to modify the action */
    readonly action: AnimationAction | null;
    /**
     * If the state has any transitions
     */
    readonly hasTransitions: boolean;
    constructor(state: State, normalizedTime: number, length: number, speed: number);
}

/**
 * [Antialiasing](https://engine.needle.tools/docs/api/Antialiasing) provides SMAA (Subpixel Morphological Antialiasing) post-processing effect to smooth edges in the rendered scene.
 * @category Effects
 * @group Components
 */
export declare class Antialiasing extends PostProcessingEffect {
    get typeName(): string;
    readonly preset: VolumeParameter;
    onCreateEffect(): EffectProviderResult;
}

declare type AnyString = string & {
    _brand?: never;
};

/**
 * The Application class can be used to mute audio globally, and to check if the application (canvas) is currently visible (it's tab is active and not minimized).
 */
export declare class Application extends EventTarget {
    static get userInteractionRegistered(): boolean;
    /**  @deprecated use Application.registerWaitForInteraction instead */
    static readonly registerWaitForAllowAudio: typeof Application.registerWaitForInteraction;
    /**
     * Register a callback that will be called when the user interacts with the page (click, touch, keypress, etc).
     * If the user has already interacted with the page, the callback will be called immediately.
     * This can be used to wait for user interaction before playing audio, for example.
     */
    static registerWaitForInteraction(cb: Function): void;
    /**
     * Unregister a callback that was previously registered with registerWaitForInteraction.
     */
    static unregisterWaitForInteraction(cb: Function): void;
    private _mute;
    /** audio muted? */
    get muted(): boolean;
    /** set global audio mute */
    set muted(value: boolean);
    private readonly context;
    /** @returns true if the document is focused */
    get hasFocus(): boolean;
    /**
     * @returns true if the application is currently visible (it's tab is active and not minimized)
     */
    get isVisible(): boolean;
    private _isVisible;
    /* Excluded from this release type: __constructor */
    private onVisiblityChanged;
}

/* Excluded from thi