@needle-tools/engine/lib/engine-components/export/usdz/extensions/behavior/BehaviourComponents.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 { Material, Object3D } from "three";
import { Animation } from "../../../../Animation.js";
import { Animator } from "../../../../Animator.js";
import { AudioSource } from "../../../../AudioSource.js";
import { Behaviour, GameObject } from "../../../../Component.js";
import type { IPointerClickHandler, PointerEventData } from "../../../../ui/PointerEvents.js";
import { USDDocument, USDObject, USDZExporterContext } from "../../ThreeUSDZExporter.js";
import { AnimationExtension, RegisteredAnimationInfo, type UsdzAnimation } from "../Animation.js";
import type { BehaviorExtension, UsdzBehaviour } from "./Behaviour.js";
import { EmphasizeActionMotionType, GroupActionModel, Target } from "./BehavioursBuilder.js";
/**
 * Moves an object to the target object's transform when clicked.
 * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
 *
 * @see {@link SetActiveOnClick}to toggle visibility of objects when clicked
 * @see {@link PlayAnimationOnClick} to play animations when clicked
 * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
 * @summary Moves an object to a target transform upon click
 * @category Everywhere Actions
 * @group Components
 */
export declare class ChangeTransformOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {
    /** The object to move. */
    object?: Object3D;
    /** The target object whose transform to move to. */
    target?: Object3D;
    /** The duration of the movement animation in seconds. */
    duration: number;
    /** If true, the motion is relative to the object's current transform instead of moving to the target's absolute position. */
    relativeMotion: boolean;
    private coroutine;
    private targetPos;
    private targetRot;
    private targetScale;
    onEnable(): void;
    onDisable(): void;
    onDestroy(): void;
    onPointerEnter(): void;
    onPointerExit(): void;
    onPointerClick(args: PointerEventData): void;
    private moveToTarget;
    private moveRelative;
    beforeCreateDocument(ext: any): void;
}
/**
 * Switches the material of objects in the scene when clicked.
 * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
 *
 * Finds all objects in the scene that use `materialToSwitch` and replaces it with `variantMaterial`.
 * Multiple `ChangeMaterialOnClick` components using the same `materialToSwitch` can be combined to create a material selection UI.
 *
 * @see {@link SetActiveOnClick} to toggle visibility of objects when clicked
 * @see {@link PlayAnimationOnClick} to play animations when clicked
 * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
 * @summary Changes the material of objects when clicked
 * @category Everywhere Actions
 * @group Components
 */
export declare class ChangeMaterialOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {
    /**
     * The material that will be switched to the variant material
     */
    materialToSwitch?: Material;
    /**
     * The material that will be switched to
     */
    variantMaterial?: Material;
    /**
     * The duration of the fade effect in seconds (USDZ/Quicklook only)
     * @default 0
     */
    fadeDuration: number;
    start(): void;
    onEnable(): void;
    onDisable(): void;
    onDestroy(): void;
    onPointerEnter(_args: PointerEventData): void;
    onPointerExit(_: PointerEventData): void;
    onPointerClick(args: PointerEventData): void;
    private _objectsWithThisMaterial;
    /** Get all objects in the scene that have the assigned materialToSwitch */
    private get objectsWithThisMaterial();
    private selfModel;
    private targetModels;
    private static _materialTriggersPerId;
    private static _startHiddenBehaviour;
    private static _parallelStartHiddenActions;
    beforeCreateDocument(_ext: BehaviorExtension, _context: any): Promise<void>;
    createBehaviours(_ext: BehaviorExtension, model: USDObject, _context: any): void;
    afterCreateDocument(ext: BehaviorExtension, _context: any): void;
    private createAndAttachBehaviors;
    private static getMaterialName;
    static variantSwitchIndex: number;
    private createVariants;
}
/**
 * Shows or hides a target object when this object is clicked.
 * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
 *
 * Optionally hides itself after being clicked (`hideSelf`), or toggles the target's visibility on each click (`toggleOnClick`).
 *
 * @see {@link HideOnStart}to hide an object when the scene starts
 * @see {@link PlayAnimationOnClick} to play animations when clicked
 * @see {@link ChangeMaterialOnClick} to change material when clicked
 * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
 * @summary Sets the active state of an object when clicked
 * @category Everywhere Actions
 * @group Components
 */
export declare class SetActiveOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {
    /** The target object to show or hide. */
    target?: Object3D;
    /** If true, the target's visibility will be toggled on each click. When enabled, `hideSelf` and `targetState` are ignored. */
    toggleOnClick: boolean;
    /** The visibility state to apply to the target when clicked. Only used when `toggleOnClick` is false. */
    targetState: boolean;
    /** If true, this object will hide itself after being clicked. Only used when `toggleOnClick` is false. */
    hideSelf: boolean;
    onPointerEnter(): void;
    onPointerExit(): void;
    onPointerClick(args: PointerEventData): void;
    private selfModel;
    private selfModelClone;
    private targetModel?;
    private toggleModel?;
    createBehaviours(_: any, model: USDObject, _context: USDZExporterContext): void;
    private stateBeforeCreatingDocument;
    private targetStateBeforeCreatingDocument;
    private static clonedToggleIndex;
    private static wasVisible;
    private static toggleClone;
    private static reverseToggleClone;
    beforeCreateDocument(): void;
    afterCreateDocument(ext: BehaviorExtension, context: USDZExporterContext): void;
    afterSerialize(_ext: BehaviorExtension, _context: USDZExporterContext): void;
}
/**
 * Hides the object when the scene starts.
 * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
 *
 * Useful for setting up objects that should initially be hidden and shown later via a {@link SetActiveOnClick} component.
 *
 * @see {@link SetActiveOnClick} to show or hide objects on click
 * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
 * @summary Hides the object on scene start
 * @category Everywhere Actions
 * @group Components
 */
export declare class HideOnStart extends Behaviour implements UsdzBehaviour {
    private static _fadeBehaviour?;
    private static _fadeObjects;
    static add(target: Target, ext: BehaviorExtension): void;
    start(): void;
    createBehaviours(ext: any, model: any, _context: any): void;
    private wasVisible;
    beforeCreateDocument(): void;
}
/**
 * Applies an emphasis animation to a target object when this object is clicked.
 * Works in USDZ/QuickLook (Everywhere Actions).
 *
 * The emphasis effect can be a bounce, jiggle, or other motion type defined by `motionType`.
 *
 * @see {@link PlayAnimationOnClick} to play animations when clicked
 * @see {@link SetActiveOnClick} to toggle visibility when clicked
 * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
 * @summary Emphasizes the target object when clicked
 * @category Everywhere Actions
 * @group Components
 */
export declare class EmphasizeOnClick extends Behaviour implements UsdzBehaviour {
    /** The target object to emphasize. */
    target?: Object3D;
    /** The duration of the emphasis animation in seconds. */
    duration: number;
    /** The type of motion to use for the emphasis effect (e.g. `"bounce"`, `"jiggle"`). */
    motionType: EmphasizeActionMotionType;
    onEnable(): void;
    onDisable(): void;
    onDestroy(): void;
    beforeCreateDocument(): void;
    createBehaviours(ext: any, model: any, _context: any): void;
    afterCreateDocument(_ext: any, _context: any): void;
}
/**
 * Plays an audio clip when this object is clicked.
 * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
 *
 * Assign a `target` {@link AudioSource} to use its spatial audio settings, or assign a `clip` URL directly.
 * If no `target` is assigned, an {@link AudioSource} will be created automatically on this object.
 *
 * @see {@link AudioSource}for spatial audio settings
 * @see {@link PlayAnimationOnClick} to play animations when clicked
 * @see {@link SetActiveOnClick} to toggle visibility when clicked
 * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
 * @summary Plays an audio clip when clicked
 * @category Everywhere Actions
 * @group Components
 */
export declare class PlayAudioOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {
    /** The {@link AudioSource} to use for playback. If not set, one will be created automatically on this object. */
    target?: AudioSource;
    /** URL of the audio clip to play. If not set, the clip assigned to `target` is used. */
    clip: string;
    /** If true, clicking again while the audio is playing will stop it. */
    toggleOnClick: boolean;
    trigger: "tap" | "start";
    ensureAudioSource(): void;
    onEnable(): void;
    onDisable(): void;
    onDestroy(): void;
    onPointerEnter(): void;
    onPointerExit(): void;
    onPointerClick(args: PointerEventData): void;
    createBehaviours(ext: BehaviorExtension, model: USDObject, _context: USDZExporterContext): void;
}
/**
 * Plays an animation state when this object is clicked.
 * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
 *
 * Assign an {@link Animator} and a `stateName` to play a specific animation state,
 * or assign an {@link Animation} component to play a legacy animation clip.
 *
 * For USDZ export, the component follows animator state transitions automatically, including looping states.
 *
 * @see {@link Animator}for playing animator state machine animations
 * @see {@link Animation} for playing legacy animation clips
 * @see {@link PlayAudioOnClick} to play audio when clicked
 * @see {@link SetActiveOnClick} to toggle visibility when clicked
 * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
 * @summary Plays an animation when clicked
 * @category Everywhere Actions
 * @group Components
 */
export declare class PlayAnimationOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour, UsdzAnimation {
    /** The {@link Animator} component whose state to play when clicked. */
    animator?: Animator;
    /** The name of the animation state to play. Required when using an {@link Animator}. */
    stateName?: string;
    trigger: "tap" | "start";
    animation?: Animation;
    private get target();
    onEnable(): void;
    onDisable(): void;
    onDestroy(): void;
    onPointerEnter(): void;
    onPointerExit(): void;
    onPointerClick(args: PointerEventData): void;
    private selfModel;
    private stateAnimationModel;
    private animationSequence?;
    private animationLoopAfterSequence?;
    private randomOffsetNormalized;
    createBehaviours(_ext: BehaviorExtension, model: USDObject, _context: USDZExporterContext): void;
    private static animationActions;
    private static rootsWithExclusivePlayback;
    afterSerialize(): void;
    afterCreateDocument(ext: BehaviorExtension, context: USDZExporterContext): void;
    static getActionForSequences(_document: USDDocument, model: Target, animationSequence?: Array<RegisteredAnimationInfo>, animationLoopAfterSequence?: Array<RegisteredAnimationInfo>, randomOffsetNormalized?: number): GroupActionModel;
    static getAndRegisterAnimationSequences(ext: AnimationExtension, target: GameObject, stateName?: string): {
        animationSequence: Array<RegisteredAnimationInfo>;
        animationLoopAfterSequence: Array<RegisteredAnimationInfo>;
        randomTimeOffset: number;
    } | undefined;
    createAnimation(ext: AnimationExtension, model: USDObject, _context: USDZExporterContext): void;
}
export declare class PreliminaryAction extends Behaviour {
    getType(): string | void;
    target?: Object3D;
    getDuration(): number | void;
}
export declare class PreliminaryTrigger extends Behaviour {
    target?: PreliminaryAction;
}
/**
 * Action to show or hide an object.
 * Use together with a {@link TapGestureTrigger} to show or hide objects when tapped or clicked.
 *
 * @see {@link TapGestureTrigger} to trigger actions on tap/click
 * @see {@link SetActiveOnClick} for a combined trigger and action component
 * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
 * @summary Hides or shows the object when clicked
 * @category Everywhere Actions
 * @group Components
 */
export declare class VisibilityAction extends PreliminaryAction {
    /** The type of visibility action to apply. */
    type: VisibilityActionType;
    /** The duration of the fade animation in seconds. */
    duration: number;
    getType(): "show" | "hide";
    getDuration(): number;
}
/**
 * Triggers a {@link PreliminaryAction} (such as {@link VisibilityAction}) when the object is tapped or clicked.
 * Works in the browser and in USDZ/QuickLook (Everywhere Actions).
 *
 * @see {@link VisibilityAction} for controlling object visibility on tap
 * @see {@link SetActiveOnClick} for a combined trigger and action component
 * @see [Everywhere Actions](https://engine.needle.tools/docs/everywhere-actions)
 * @summary Triggers an action when the object is tapped/clicked
 * @category Everywhere Actions
 * @group Components
 */
export declare class TapGestureTrigger extends PreliminaryTrigger {
}
export declare enum VisibilityActionType {
    Show = 0,
    Hide = 1
}