@needle-tools/engine/src/engine-components/export/usdz/extensions/behavior/BehaviourComponents.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 { AnimationClip, Material, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";

import { isDevEnvironment, showBalloonWarning } from "../../../../../engine/debug/index.js";
import { serializable } from "../../../../../engine/engine_serialization_decorator.js";
import { getWorldPosition, getWorldQuaternion, getWorldScale, setWorldPosition, setWorldQuaternion, setWorldScale } from "../../../../../engine/engine_three_utils.js";
import { getParam } from "../../../../../engine/engine_utils.js";
import { compareAssociation } from "../../../../../engine/extensions/extension_utils.js";
import type { State } from "../../../../../engine/extensions/NEEDLE_animator_controller_model.js";
import { NEEDLE_progressive } from "../../../../../engine/extensions/NEEDLE_progressive.js";
import { Animation } from "../../../../Animation.js";
import { Animator } from "../../../../Animator.js";
import { AudioSource } from "../../../../AudioSource.js";
import { Behaviour, GameObject } from "../../../../Component.js";
import { Rigidbody } from "../../../../RigidBody.js";
import type { IPointerClickHandler, PointerEventData } from "../../../../ui/PointerEvents.js";
import { makeNameSafeForUSD, USDDocument, USDObject, USDZExporterContext } from "../../ThreeUSDZExporter.js";
import { AnimationExtension, RegisteredAnimationInfo, type UsdzAnimation } from "../Animation.js";
import { AudioExtension } from "./AudioExtension.js";
import type { BehaviorExtension, UsdzBehaviour } from "./Behaviour.js";
import { ActionBuilder, ActionModel, BehaviorModel, EmphasizeActionMotionType, GroupActionModel, type IBehaviorElement, Target, TriggerBuilder } from "./BehavioursBuilder.js";

const debug = getParam("debugusdzbehaviours");

/**
 * 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 class ChangeTransformOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {

    /** The object to move. */
    @serializable(Object3D)
    object?: Object3D;

    /** The target object whose transform to move to. */
    @serializable(Object3D)
    target?: Object3D;

    /** The duration of the movement animation in seconds. */
    @serializable()
    duration: number = 1;

    /** If true, the motion is relative to the object's current transform instead of moving to the target's absolute position. */
    @serializable()
    relativeMotion: boolean = false;

    private coroutine: Generator | null = null;

    private targetPos = new Vector3();
    private targetRot = new Quaternion();
    private targetScale = new Vector3();

    onEnable(): void {
        this.context.accessibility.updateElement(this, {
            role: "button",
            label: "Move " + (this.object?.name || "object") + " to " + (this.target?.name || "target") + " on click",
            hidden: false,
        })
    }
    onDisable(): void {
        this.context.accessibility.updateElement(this, {
            hidden: true,
        });
    }
    onDestroy(): void {
        this.context.accessibility.removeElement(this);
    }

    onPointerEnter() {
        this.context.input.setCursor("pointer");
    }
    onPointerExit() {
        this.context.input.unsetCursor("pointer");
    }

    onPointerClick(args: PointerEventData) {

        const rbs = this.object?.getComponentsInChildren(Rigidbody);

        if (rbs) {
            for (const rb of rbs) {
                rb.resetVelocities();
                rb.resetForcesAndTorques();
            }
        }

        args.use();
        if (this.coroutine) this.stopCoroutine(this.coroutine);
        if (!this.relativeMotion)
            this.coroutine = this.startCoroutine(this.moveToTarget());
        else
            this.coroutine = this.startCoroutine(this.moveRelative());
    }

    private *moveToTarget() {

        if (!this.target || !this.object) return;

        const thisPos = getWorldPosition(this.object).clone();
        const targetPos = getWorldPosition(this.target).clone();

        const thisRot = getWorldQuaternion(this.object).clone();
        const targetRot = getWorldQuaternion(this.target).clone();

        const thisScale = getWorldScale(this.object).clone();
        const targetScale = getWorldScale(this.target).clone();

        const dist = thisPos.distanceTo(targetPos);
        const rotDist = thisRot.angleTo(targetRot);
        const scaleDist = thisScale.distanceTo(targetScale);

        if (dist < 0.01 && rotDist < 0.01 && scaleDist < 0.01) {
            setWorldPosition(this.object, targetPos);
            setWorldQuaternion(this.object, targetRot);
            setWorldScale(this.object, targetScale);
            this.coroutine = null;
            return;
        }

        let t01 = 0;
        let eased = 0;
        while (t01 < 1) {

            t01 += this.context.time.deltaTime / this.duration;
            if (t01 > 1) t01 = 1;

            // apply ease-in-out
            // https://easings.net/
            eased = t01 < 0.5 ? 4 * t01 * t01 * t01 : 1 - Math.pow(-2 * t01 + 2, 3) / 2;

            this.targetPos.lerpVectors(thisPos, targetPos, eased);
            this.targetRot.slerpQuaternions(thisRot, targetRot, eased);
            this.targetScale.lerpVectors(thisScale, targetScale, eased);

            setWorldPosition(this.object, this.targetPos);
            setWorldQuaternion(this.object, this.targetRot);
            setWorldScale(this.object, this.targetScale);

            yield;
        }

        this.coroutine = null;
    }

    private *moveRelative() {

        if (!this.target || !this.object) return;

        const thisPos = this.object.position.clone();
        const thisRot = this.object.quaternion.clone();
        const thisScale = this.object.scale.clone();

        const posOffset = this.target.position.clone();
        const rotOffset = this.target.quaternion.clone();
        const scaleOffset = this.target.scale.clone();

        // convert into right space
        posOffset.applyQuaternion(this.object.quaternion);

        this.targetPos.copy(this.object.position).add(posOffset);
        this.targetRot.copy(this.object.quaternion).multiply(rotOffset);
        this.targetScale.copy(this.object.scale).multiply(scaleOffset);

        let t01 = 0;
        let eased = 0;
        while (t01 < 1) {

            t01 += this.context.time.deltaTime / this.duration;
            if (t01 > 1) t01 = 1;

            // apply ease-in-out
            // https://easings.net/
            eased = t01 < 0.5 ? 4 * t01 * t01 * t01 : 1 - Math.pow(-2 * t01 + 2, 3) / 2;

            this.object.position.lerpVectors(thisPos, this.targetPos, eased);
            this.object.quaternion.slerpQuaternions(thisRot, this.targetRot, eased);
            this.object.scale.lerpVectors(thisScale, this.targetScale, eased);

            yield;
        }

        this.coroutine = null;
    }

    beforeCreateDocument(ext) {
        if (this.target && this.object && this.gameObject) {
            const moveForward = new BehaviorModel("Move to " + this.target?.name,
                TriggerBuilder.tapTrigger(this.gameObject),
                ActionBuilder.transformAction(this.object, this.target, this.duration, this.relativeMotion ? "relative" : "absolute"),
            );
            ext.addBehavior(moveForward);
        }
    }
}

/**
 * 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 class ChangeMaterialOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {

    /**
     * The material that will be switched to the variant material
     */
    @serializable(Material)
    materialToSwitch?: Material;

    /**
     * The material that will be switched to
     */
    @serializable(Material)
    variantMaterial?: Material;

    /**
     * The duration of the fade effect in seconds (USDZ/Quicklook only)
     * @default 0
     */
    @serializable()
    fadeDuration: number = 0;

    start(): void {
        // initialize the object list
        this._objectsWithThisMaterial = this.objectsWithThisMaterial;
        if (isDevEnvironment() && this._objectsWithThisMaterial.length <= 0) {
            console.warn("ChangeMaterialOnClick: No objects found with material \"" + this.materialToSwitch?.name + "\"");
        }
    }

    onEnable(): void {
        this.context.accessibility.updateElement(this, {
            role: "button",
            label: "Change material to " + (this.variantMaterial?.name || "unknown material"),
            hidden: false,
        })
    }
    onDisable(): void {
        this.context.accessibility.updateElement(this, {
            hidden: true,
        });
    }
    onDestroy(): void {
        this.context.accessibility.removeElement(this);
    }

    onPointerEnter(_args: PointerEventData) {
        this.context.input.setCursor("pointer");
    }
    onPointerExit(_: PointerEventData) {
        this.context.input.unsetCursor("pointer");
    }
    onPointerClick(args: PointerEventData) {
        args.use();
        if (!this.variantMaterial) return;
        for (let i = 0; i < this.objectsWithThisMaterial.length; i++) {
            const obj = this.objectsWithThisMaterial[i];
            obj.material = this.variantMaterial;
        }
    }

    private _objectsWithThisMaterial: Mesh[] | null = null;
    /** Get all objects in the scene that have the assigned materialToSwitch */
    private get objectsWithThisMaterial(): Mesh[] {
        if (this._objectsWithThisMaterial != null) return this._objectsWithThisMaterial;
        this._objectsWithThisMaterial = [];
        if (this.variantMaterial && this.materialToSwitch) {
            this.context.scene.traverse(obj => {
                if (obj instanceof Mesh) {
                    if (Array.isArray(obj.material)) {
                        for (const mat of obj.material) {
                            if (mat === this.materialToSwitch) {
                                this.objectsWithThisMaterial.push(obj);
                                break;
                            }
                        }
                    }
                    else {
                        if (obj.material === this.materialToSwitch) {
                            this.objectsWithThisMaterial.push(obj);
                        }
                        else if (compareAssociation(obj.material, this.materialToSwitch)) {
                            this.objectsWithThisMaterial.push(obj);
                        }
                    }
                }
            });
        }
        return this._objectsWithThisMaterial;
    }

    private selfModel!: USDObject;
    private targetModels!: USDObject[];

    private static _materialTriggersPerId: { [key: string]: ChangeMaterialOnClick[] } = {}
    private static _startHiddenBehaviour: BehaviorModel | null = null;
    private static _parallelStartHiddenActions: USDObject[] = [];

    async beforeCreateDocument(_ext: BehaviorExtension, _context) {
        this.targetModels = [];
        ChangeMaterialOnClick._materialTriggersPerId = {}
        ChangeMaterialOnClick.variantSwitchIndex = 0;

        // Ensure that the progressive textures have been loaded for all variants and materials
        if (this.materialToSwitch) {
            await NEEDLE_progressive.assignTextureLOD(this.materialToSwitch, 0);
        }
        if (this.variantMaterial) {
            await NEEDLE_progressive.assignTextureLOD(this.variantMaterial, 0);
        }
    }


    createBehaviours(_ext: BehaviorExtension, model: USDObject, _context) {

        const shouldExport = this.objectsWithThisMaterial.find(o => o.uuid === model.uuid);
        if (shouldExport) {
            this.targetModels.push(model);
        }
        if (this.gameObject.uuid === model.uuid) {
            this.selfModel = model;
            if (this.materialToSwitch) {
                if (!ChangeMaterialOnClick._materialTriggersPerId[this.materialToSwitch.uuid])
                    ChangeMaterialOnClick._materialTriggersPerId[this.materialToSwitch.uuid] = [];
                ChangeMaterialOnClick._materialTriggersPerId[this.materialToSwitch.uuid].push(this);
            }
        }
    }

    afterCreateDocument(ext: BehaviorExtension, _context) {

        if (!this.materialToSwitch) return;
        const handlers = ChangeMaterialOnClick._materialTriggersPerId[this.materialToSwitch.uuid];
        if (handlers) {
            const variants: { [key: string]: Array<USDObject> } = {}
            for (const handler of handlers) {
                const createdVariants = handler.createVariants();
                if (createdVariants && createdVariants.length > 0)
                    variants[handler.selfModel.uuid] = createdVariants;
            }
            for (const handler of handlers) {
                const otherVariants: Array<USDObject> = [];
                for (const key in variants) {
                    if (key !== handler.selfModel.uuid) {
                        otherVariants.push(...variants[key]);
                    }
                }
                handler.createAndAttachBehaviors(ext, variants[handler.selfModel.uuid], otherVariants);
            }
        }
        delete ChangeMaterialOnClick._materialTriggersPerId[this.materialToSwitch.uuid];
    }

    private createAndAttachBehaviors(ext: BehaviorExtension, myVariants: Array<USDObject>, otherVariants: Array<USDObject>) {
        const select: ActionModel[] = [];

        const fadeDuration = Math.max(0, this.fadeDuration);

        select.push(ActionBuilder.fadeAction([...this.targetModels, ...otherVariants], fadeDuration, false));
        select.push(ActionBuilder.fadeAction(myVariants, fadeDuration, true));

        ext.addBehavior(new BehaviorModel("Select_" + this.selfModel.name,
            TriggerBuilder.tapTrigger(this.selfModel),
            ActionBuilder.parallel(...select))
        );
        ChangeMaterialOnClick._parallelStartHiddenActions.push(...myVariants);
        if (!ChangeMaterialOnClick._startHiddenBehaviour) {
            ChangeMaterialOnClick._startHiddenBehaviour =
                new BehaviorModel("StartHidden_" + this.selfModel.name,
                    TriggerBuilder.sceneStartTrigger(),
                    ActionBuilder.fadeAction(ChangeMaterialOnClick._parallelStartHiddenActions, fadeDuration, false));
            ext.addBehavior(ChangeMaterialOnClick._startHiddenBehaviour);
        }
    }

    private static getMaterialName(material: Material) {
        return makeNameSafeForUSD(material.name || 'Material') + "_" + material.id;
    }

    static variantSwitchIndex: number = 0;
    private createVariants() {
        if (!this.variantMaterial) return null;

        const variantModels: USDObject[] = [];
        for (const target of this.targetModels) {
            const variant = target.clone();
            variant.name += "_Variant_" + ChangeMaterialOnClick.variantSwitchIndex++ + "_" + ChangeMaterialOnClick.getMaterialName(this.variantMaterial);
            variant.displayName = variant.displayName + ": Variant with material " + this.variantMaterial.name;
            variant.material = this.variantMaterial;
            variant.geometry = target.geometry;
            variant.transform = target.transform;

            if (!target.parent || !target.parent.isEmpty()) {
                USDObject.createEmptyParent(target);
            }
            if (target.parent) target.parent.add(variant);
            variantModels.push(variant);
        }
        return variantModels;
    }
}

/**
 * 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 class SetActiveOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {

    /** The target object to show or hide. */
    @serializable(Object3D)
    target?: Object3D;

    /** If true, the target's visibility will be toggled on each click. When enabled, `hideSelf` and `targetState` are ignored. */
    @serializable()
    toggleOnClick: boolean = false;

    /** The visibility state to apply to the target when clicked. Only used when `toggleOnClick` is false. */
    @serializable()
    targetState: boolean = true;

    /** If true, this object will hide itself after being clicked. Only used when `toggleOnClick` is false. */
    @serializable()
    hideSelf: boolean = true;

    onPointerEnter() {
        this.context.input.setCursor("pointer");
    }
    onPointerExit() {
        this.context.input.unsetCursor("pointer");
    }

    onPointerClick(args: PointerEventData) {
        args.use();

        if (!this.toggleOnClick && this.hideSelf)
            this.gameObject.visible = false;

        if (this.target)
            this.target.visible = this.toggleOnClick ? !this.target.visible : this.targetState;
    }

    private selfModel!: USDObject;
    private selfModelClone!: USDObject;
    private targetModel?: USDObject;
    private toggleModel?: USDObject;

    createBehaviours(_, model: USDObject, _context: USDZExporterContext) {
        if (model.uuid === this.gameObject.uuid) {
            this.selfModel = model;
            this.selfModelClone = model.clone();
        }
    }

    private stateBeforeCreatingDocument: boolean = false;
    private targetStateBeforeCreatingDocument: boolean = false;
    private static clonedToggleIndex = 0;
    private static wasVisible = Symbol("usdz_SetActiveOnClick_wasVisible");
    private static toggleClone = Symbol("clone for toggling");
    private static reverseToggleClone = Symbol("clone for reverse toggling");

    beforeCreateDocument() {
        if (!this.target) return;

        // need to cache on the object itself, because otherwise different actions would override each other's visibility state
        // TODO would probably be better to have this somewhere on the exporter, not on this component
        if (this.gameObject[SetActiveOnClick.wasVisible] === undefined)
            this.gameObject[SetActiveOnClick.wasVisible] = this.gameObject.activeSelf;
        if (this.target[SetActiveOnClick.wasVisible] === undefined)
            this.target[SetActiveOnClick.wasVisible] = (this.target as GameObject).activeSelf;

        this.stateBeforeCreatingDocument = this.gameObject[SetActiveOnClick.wasVisible];
        this.targetStateBeforeCreatingDocument = this.target[SetActiveOnClick.wasVisible];

        // Objects need to be on so they are exported, as we're skipping invisible objects
        this.gameObject.visible = true;
        this.target.visible = true;
    }

    afterCreateDocument(ext: BehaviorExtension, context: USDZExporterContext) {
        if (!this.target) return;

        // Parameters:
        // - hideSelf: the trigger is hidden after clicking. Can basically only be used once.
        // - toggleOnClick: the target is toggled on/off when the trigger is clicked.
        // - targetState: the target is set to this state when the trigger is clicked.

        // Combinations:
        // - when toggleOnClick is on, hideSelf is ignored
        //   - we need to make a copy of our object
        //   - when the trigger is clicked
        //     - hide the original trigger
        //     - show the copied trigger
        //     - set the target to targetState
        //   - when the copied trigger is clicked
        //     - hide the copied trigger
        //     - show the original trigger again
        //     - set the target to !targetState
        // - when toggleOnClick is off, hideSelf is used
        //   - no copy is needed 
        //   - when the trigger is clicked
        //     - hide the trigger
        //     - set the target to the targetState

        this.targetModel = context.document.findById(this.target.uuid);
        const originalModel = this.selfModel;

        if (this.selfModel && this.targetModel) {
            let selfModel = this.selfModel;
            let targetState = this.targetState;

            // if we toggle, we need to create a copy of our object
            if (this.toggleOnClick) {
                // When toggling we want to respect the current state of the target,
                // so effectively this.targetState and this.hideSelf are ignored.
                targetState = !this.targetStateBeforeCreatingDocument;


                // Potentially it's easier/better to just "clone" and put the object as a sibling next
                // to the rest of the hierarchy. This way we would lose nested clicks (clicking on a child would not trigger events)
                // but we're not potentially duplicating tons of objects.
                // It's much easier to reason about nested actions when we're not duplicating tons of hierarchy...
                // We can probably only do a shallow clone when the tapped object has geometry of its own, otherwise
                // we end up with nothing to tap on.

                // Option A: we deep clone ourselves. This makes hierarchical cases and nested behaviours really complex.
                // We do this currently when the object doesn't have any geometry.
                if (!this.selfModelClone.geometry) {
                    if (!this.selfModel.parent || this.selfModel.parent.isEmpty())
                        USDDocument.createEmptyParent(this.selfModel);
                    this.toggleModel = this.selfModel.deepClone();
                    this.toggleModel.name += "_toggle";
                    this.selfModel.parent!.add(this.toggleModel);
                }
                else {
                    // Option B: we shallow clone ourselves and put the clone next to us. This means childs are not clickable anymore.
                    // We create clones exactly once for this gameObject, so that all SetActiveOnClick on the same object use the same trigger.
                    if (!this.gameObject[SetActiveOnClick.toggleClone]) {
                        const clone = this.selfModelClone.clone();
                        clone.setMatrix(new Matrix4());
                        clone.name += "_toggle" + (SetActiveOnClick.clonedToggleIndex++);
                        originalModel.add(clone);
                        this.gameObject[SetActiveOnClick.toggleClone] = clone;

                        console.warn("USDZExport: Toggle " + this.gameObject.name + " doesn't have geometry. It will be deep cloned and nested behaviours will likely not work.");
                    }
                    const clonedSelfModel = this.gameObject[SetActiveOnClick.toggleClone];

                    if (!this.gameObject[SetActiveOnClick.reverseToggleClone]) {
                        const clone = this.selfModelClone.clone();
                        clone.setMatrix(new Matrix4());
                        clone.name += "_toggleReverse" + (SetActiveOnClick.clonedToggleIndex++);
                        originalModel.add(clone);
                        this.gameObject[SetActiveOnClick.reverseToggleClone] = clone;
                    }
                    this.toggleModel = this.gameObject[SetActiveOnClick.reverseToggleClone];

                    if (!this.toggleModel!.geometry || !clonedSelfModel.geometry) {
                        console.error("triggers without childs and without geometry won't work!", this, originalModel.geometry)
                    }

                    // We're targeting the clone in the actions below, not the original object
                    selfModel = clonedSelfModel;

                    // Remove the geometry, we've duplicated it into the toggle/reverseToggle already
                    originalModel.geometry = null;
                    originalModel.material = null;

                    // Known issues: clone() does not clone skinned mesh geometry, lights, cameras;
                    // we still have them on the original object and the clones won't have it.
                }
            }

            // this.toggleOnClick is false, so we don't have a toggleModel – no need for clones,
            // just set the target object to targetState and optionally hide ourselves
            if (!this.toggleModel) {
                const sequence: ActionModel[] = [];
                if (this.hideSelf)
                    sequence.push(ActionBuilder.fadeAction(selfModel, 0, false));
                sequence.push(ActionBuilder.fadeAction(this.targetModel, 0, targetState));

                ext.addBehavior(new BehaviorModel("Toggle_" + selfModel.name + "_ToggleTo" + (targetState ? "On" : "Off"),
                    TriggerBuilder.tapTrigger(selfModel),
                    sequence.length > 1 ? ActionBuilder.parallel(...sequence) : sequence[0],
                ));
            }
            // We have a toggleModel, so we need to set up two sequences:
            // - one that hides the original object, shows the toggle and sets the target to targetState
            // - one that hides the toggle, shows the original object and sets the target to !targetState
            else if (this.toggleOnClick) {
                const toggleSequence: ActionModel[] = [];
                toggleSequence.push(ActionBuilder.fadeAction(selfModel, 0, false));
                toggleSequence.push(ActionBuilder.fadeAction(this.toggleModel, 0, true));
                toggleSequence.push(ActionBuilder.fadeAction(this.targetModel, 0, targetState));

                ext.addBehavior(new BehaviorModel("Toggle_" + selfModel.name + "_ToggleTo" + (targetState ? "On" : "Off"),
                    TriggerBuilder.tapTrigger(selfModel),
                    ActionBuilder.parallel(...toggleSequence)
                ));

                const reverseSequence: ActionModel[] = [];
                reverseSequence.push(ActionBuilder.fadeAction(this.toggleModel, 0, false));
                reverseSequence.push(ActionBuilder.fadeAction(selfModel, 0, true));
                reverseSequence.push(ActionBuilder.fadeAction(this.targetModel, 0, !targetState));

                ext.addBehavior(new BehaviorModel("Toggle_" + selfModel.name + "_ToggleTo" + (!targetState ? "On" : "Off"),
                    TriggerBuilder.tapTrigger(this.toggleModel),
                    ActionBuilder.parallel(...reverseSequence)
                ));
            }

            // Ensure initial states are set correctly so that we get the same result as was currently active in the runtime
            const objectsToHide = new Array<USDObject>();
            if (!this.targetStateBeforeCreatingDocument)
                objectsToHide.push(this.targetModel);
            if (!this.stateBeforeCreatingDocument)
                objectsToHide.push(originalModel);
            if (this.toggleModel)
                objectsToHide.push(this.toggleModel);

            HideOnStart.add(objectsToHide, ext);
        }
    }

    afterSerialize(_ext: BehaviorExtension, _context: USDZExporterContext): void {
        // cleanup visibility cache
        if (this.gameObject[SetActiveOnClick.wasVisible] !== undefined) {
            this.gameObject.visible = this.gameObject[SetActiveOnClick.wasVisible];
            delete this.gameObject[SetActiveOnClick.wasVisible];
        }
        if (this.target && this.target[SetActiveOnClick.wasVisible] !== undefined) {
            this.target.visible = this.target[SetActiveOnClick.wasVisible];
            delete this.target[SetActiveOnClick.wasVisible];
        }

        // cleanup trigger clones
        delete this.gameObject[SetActiveOnClick.toggleClone];
        delete this.gameObject[SetActiveOnClick.reverseToggleClone];
    }
}

/**
 * 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 class HideOnStart extends Behaviour implements UsdzBehaviour {

    private static _fadeBehaviour?: BehaviorModel;
    private static _fadeObjects: Array<USDObject | Object3D> = [];

    static add(target: Target, ext: BehaviorExtension) {
        const arr = Array.isArray(target) ? target : [target];
        for (const entry of arr) {
            if (!HideOnStart._fadeObjects.includes(entry)) {
                console.log("adding hide on start", entry);
                HideOnStart._fadeObjects.push(entry);
            }
        }
        if (HideOnStart._fadeBehaviour === undefined) {
            HideOnStart._fadeBehaviour = new BehaviorModel("HideOnStart",
                TriggerBuilder.sceneStartTrigger(),
                //@ts-ignore
                ActionBuilder.fadeAction(HideOnStart._fadeObjects, 0, false)
            );
            ext.addBehavior(HideOnStart._fadeBehaviour);
        }
    }

    start() {
        GameObject.setActive(this.gameObject, false);
    }

    createBehaviours(ext, model, _context) {
        if (model.uuid === this.gameObject.uuid) {
            // we only want to mark the object as HideOnStart if it's still hidden
            if (!this.wasVisible) {
                HideOnStart.add(model, ext);
            }
        }
    }

    private wasVisible: boolean = false;

    beforeCreateDocument() {
        this.wasVisible = GameObject.isActiveSelf(this.gameObject);
    }
}

/**
 * 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 class EmphasizeOnClick extends Behaviour implements UsdzBehaviour {

    /** The target object to emphasize. */
    @serializable()
    target?: Object3D;

    /** The duration of the emphasis animation in seconds. */
    @serializable()
    duration: number = 0.5;

    /** The type of motion to use for the emphasis effect (e.g. `"bounce"`, `"jiggle"`). */
    @serializable()
    motionType: EmphasizeActionMotionType = "bounce";

    onEnable(): void {
        this.context.accessibility.updateElement(this, {
            role: "button",
            label: "Emphasize " + this.target?.name + " on click",
            hidden: false,
        })
    }
    onDisable(): void {
        this.context.accessibility.updateElement(this, {
            hidden: true,
        });
    }
    onDestroy(): void {
        this.context.accessibility.removeElement(this);
    }

    beforeCreateDocument() { }

    createBehaviours(ext, model, _context) {
        if (!this.target) return;

        if (model.uuid === this.gameObject.uuid) {
            const emphasize = new BehaviorModel("emphasize " + this.name,
                TriggerBuilder.tapTrigger(this.gameObject),
                ActionBuilder.emphasize(this.target, this.duration, this.motionType, undefined, "basic"),
            );
            ext.addBehavior(emphasize);
        }
    }

    afterCreateDocument(_ext, _context) { }
}

/**
 * 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 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. */
    @serializable(AudioSource)
    target?: AudioSource;

    /** URL of the audio clip to play. If not set, the clip assigned to `target` is used. */
    @serializable(URL)
    clip: string = "";

    /** If true, clicking again while the audio is playing will stop it. */
    @serializable()
    toggleOnClick: boolean = false;

    // Not exposed, but used for implicit playback of PlayOnAwake audio sources
    trigger: "tap" | "start" = "tap";

    ensureAudioSource() {
        if (!this.target) {
            const newAudioSource = this.gameObject.addComponent(AudioSource);
            if (newAudioSource) {
                this.target = newAudioSource;
                newAudioSource.spatialBlend = 1;
                newAudioSource.volume = 1;
                newAudioSource.loop = false;
                newAudioSource.preload = true;
            }
        }
    }

    onEnable(): void {
        this.context.accessibility.updateElement(this, {
            role: "button",
            label: "Play audio: " + (this.clip || this.target?.clip || "unknown clip"),
            hidden: false,
        })
    }
    onDisable(): void {
        this.context.accessibility.updateElement(this, {
            hidden: true,
        });
    }
    onDestroy(): void {
        this.context.accessibility.removeElement(this);
    }

    onPointerEnter() {
        this.context.input.setCursor("pointer");
    }
    onPointerExit() {
        this.context.input.unsetCursor("pointer");
    }
    onPointerClick(args: PointerEventData) {
        args.use();

        if (!this.target?.clip && !this.clip) return;

        this.ensureAudioSource();

        if (this.target) {

            if (this.target.isPlaying && this.toggleOnClick) {
                this.target.stop();
            }
            else {
                if (!this.toggleOnClick && this.target.isPlaying) {
                    this.target.stop();
                }
                if (this.clip) this.target.play(this.clip);
                else this.target.play();
            }
        }
    }

    createBehaviours(ext: BehaviorExtension, model: USDObject, _context: USDZExporterContext) {
        if (!this.target && !this.clip) return;
        if (model.uuid === this.gameObject.uuid) {

            const clipUrl = this.clip ? this.clip : this.target ? this.target.clip : undefined;
            if (!clipUrl) return;
            if (typeof clipUrl !== "string") return;

            const playbackTarget = this.target ? this.target.gameObject : this.gameObject;
            const clipName = AudioExtension.getName(clipUrl);
            const volume = this.target ? this.target.volume : 1;
            const auralMode = this.target && this.target.spatialBlend == 0 ? "nonSpatial" : "spatial";

            // This checks if any child is clickable – if yes, the tap trigger is added; if not, we omit it.
            let anyChildHasGeometry = false;
            this.gameObject.traverse(c => {
                if (c instanceof Mesh && c.visible) anyChildHasGeometry = true;
            });
            // Workaround: seems iOS often simply doesn't play audio on scene start when this is NOT present.
            // unclear why, but having a useless tap action (nothing to tap on) "fixes" it.
            anyChildHasGeometry = true;

            const audioClip = ext.addAudioClip(clipUrl);
            // const stopAction: IBehaviorElement = ActionBuilder.playAudioAction(playbackTarget, audioClip, "stop", volume, auralMode);
            let playAction: IBehaviorElement = ActionBuilder.playAudioAction(playbackTarget, audioClip, "play", volume, auralMode);
            if (this.target && this.target.loop)
                playAction = ActionBuilder.sequence(playAction).makeLooping();

            const behaviorName = (this.name ? "_" + this.name : "");

            if (anyChildHasGeometry && this.trigger === "tap") {
                // does not seem to work in iOS / QuickLook...
                // TODO use play "type" which can be start/stop/pause
                if (this.toggleOnClick) (playAction as ActionModel).multiplePerformOperation = "stop";
                const playClipOnTap = new BehaviorModel("playAudio" + behaviorName,
                    TriggerBuilder.tapTrigger(model),
                    playAction,
                );
                ext.addBehavior(playClipOnTap);
            }

            // automatically play audio on start too if the referenced AudioSource has playOnAwake enabled
            if (this.target && this.target.playOnAwake && this.target.enabled) {
                if (anyChildHasGeometry && this.trigger === "tap") {
                    // WORKAROUND Currently (20240509) we MUST not emit this behaviour if we're also expecting the tap trigger to work.
                    // Seems to be a regression in QuickLook... audio clips can't be stopped anymore as soon as they start playing.
                    console.warn("USDZExport: Audio sources that are played on tap can't also auto-play at scene start due to a QuickLook bug.");
                }
                else {
                    const playClipOnStart = new BehaviorModel("playAudioOnStart" + behaviorName,
                        TriggerBuilder.sceneStartTrigger(),
                        playAction,
                    );
                    ext.addBehavior(playClipOnStart);
                }
            }
        }
    }
}

/**
 * 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 class PlayAnimationOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour, UsdzAnimation {

    /** The {@link Animator} component whose state to play when clicked. */
    @serializable(Animator)
    animator?: Animator;

    /** The name of the animation state to play. Required when using an {@link Animator}. */
    @serializable()
    stateName?: string;

    // Not editable from the outside yet, but from code
    // we want to expose this once we have a nice drawer for "Triggers" (e.g. shows proximity distance)
    // and once we rename the component to "PlayAnimation" or "PlayAnimationOnTrigger"
    trigger: "tap" | "start" = "tap"; // "proximity"
    animation?: Animation;

    private get target() { return this.animator?.gameObject || this.animation?.gameObject }

    onEnable(): void {
        this.context.accessibility.updateElement(this, {
            role: "button",
            label: "Plays animation " + (this.stateName || "") + " on " + (this.target ? this.target.name : ""),
            hidden: false
        });
    }
    onDisable(): void {
        this.context.accessibility.updateElement(this, {
            hidden: true,
        });
    }
    onDestroy(): void {
        this.context.accessibility.removeElement(this);
    }

    onPointerEnter() {
        this.context.input.setCursor("pointer");
        this.context.accessibility.hover(this, "Click to play animation " + (this.stateName || "") + " on " + (this.target ? this.target.name : ""));
    }
    onPointerExit() {
        this.context.input.unsetCursor("pointer");
    }
    onPointerClick(args: PointerEventData) {
        args.use();
        if (!this.target) return;
        if (this.stateName) {
            this.context.accessibility.focus(this);
            // TODO this is currently quite annoying to use,
            // as for the web we use the Animator component and its states directly,
            // while in QuickLook we use explicit animations / states.
            this.animator?.play(this.stateName, 0, 0, .1);
        }
    }

    private selfModel: any;

    private stateAnimationModel: any;

    private animationSequence?= new Array<RegisteredAnimationInfo>();
    private animationLoopAfterSequence?= new Array<RegisteredAnimationInfo>();
    private randomOffsetNormalized: number = 0;

    createBehaviours(_ext: BehaviorExtension, model: USDObject, _context: USDZExporterContext) {

        if (model.uuid === this.gameObject.uuid)
            this.selfModel = model;
    }

    private static animationActions: ActionModel[] = [];
    private static rootsWithExclusivePlayback: Set<Object3D> = new Set();

    // Cleanup. TODO This is not the best way as it's called multiple times (once for each component).
    afterSerialize() {
        if (PlayAnimationOnClick.rootsWithExclusivePlayback.size > 1) {
            const message = "Multiple root objects targeted by more than one animation. To work around QuickLook bug FB13410767, animations will be set as \"exclusive\" and activating them will stop other animations being marked as exclusive.";
            if (isDevEnvironment()) showBalloonWarning(message);
            console.warn(message, ...PlayAnimationOnClick.rootsWithExclusivePlayback);
        }
        PlayAnimationOnClick.animationActions = [];
        PlayAnimationOnClick.rootsWithExclusivePlayback = new Set();
    }

    afterCreateDocument(ext: BehaviorExtension, context: USDZExporterContext) {
        if ((this.animationSequence === undefined && this.animationLoopAfterSequence === undefined) || !this.stateAnimationModel) return;
        if (!this.target) return;

        const document = context.document;

        // check if the AnimationExtension has been attached and what data it has for the current object
        const animationExt = context.extensions.find(ext => ext instanceof AnimationExtension) as AnimationExtension;
        if (!animationExt) return;

        // This is a workaround for FB13410767 - StartAnimationAction in USDZ preliminary behaviours does not stop when another StartAnimationAction is called on the same prim
        // When we play multiple animations on the same root, QuickLook just overlaps them and glitches around instead of stopping an earlier one.
        // Once this is fixed, we can relax this check and just always make it non-exclusive again.
        // Setting exclusive playback has the side effect of unfortunately canceling all other playing actions that are exclusive too -
        // seems there is no finer-grained control over which actions should stop which other actions...
        const requiresExclusivePlayback = animationExt.getClipCount(this.target) > 1;
        if (requiresExclusivePlayback) {
            if (isDevEnvironment())
                console.warn("Setting exclusive playback for " + this.target.name + "@" + this.stateName + " because it has " + animationExt.getClipCount(this.target) + " animations. This works around QuickLook bug FB13410767.");

            PlayAnimationOnClick.rootsWithExclusivePlayback.add(this.target);
        }

        const behaviorName = (this.name ? this.name : "");

        document.traverse(model => {
            if (model.uuid === this.target?.uuid) {
                const sequence = PlayAnimationOnClick.getActionForSequences(
                    document,
                    model,
                    this.animationSequence,
                    this.animationLoopAfterSequence,
                    this.randomOffsetNormalized,
                );

                const playAnimationOnTap = new BehaviorModel(this.trigger + "_" + behaviorName + "_toPlayAnimation_" + this.stateName + "_on_" + this.target?.name,
                    this.trigger == "tap" ? TriggerBuilder.tapTrigger(this.selfModel) : TriggerBuilder.sceneStartTrigger(),
                    sequence
                );

                // See comment above for why exclusive playback is currently required when playing multiple animations on the same root.
                if (requiresExclusivePlayback)
                    playAnimationOnTap.makeExclusive(true);
                ext.addBehavior(playAnimationOnTap);
            }
        });
    }

    static getActionForSequences(_document: USDDocument, model: Target, animationSequence?: Array<RegisteredAnimationInfo>, animationLoopAfterSequence?: Array<RegisteredAnimationInfo>, randomOffsetNormalized?: number) {

        const getOrCacheAction = (model: Target, anim: RegisteredAnimationInfo) => {
            let action = PlayAnimationOnClick.animationActions.find(a => a.affectedObjects == model && a.start == anim.start && a.duration == anim.duration && a.animationSpeed == anim.speed);
            if (!action) {
                action = ActionBuilder.startAnimationAction(model, anim) as ActionModel;
                PlayAnimationOnClick.animationActions.push(action);
            }
            return action;
        }

        const sequence = ActionBuilder.sequence();

        if (animationSequence && animationSequence.length > 0) {
            for (const anim of animationSequence) {
                sequence.addAction(getOrCacheAction(model, anim));
            }
        }

        if (animationLoopAfterSequence && animationLoopAfterSequence.length > 0) {
            // only make a new action group if there's already stuff in the existing one
            const loopSequence = sequence.actions.length == 0 ? sequence : ActionBuilder.sequence();
            for (const anim of animationLoopAfterSequence) {
                loopSequence.addAction(getOrCacheAction(model, anim));
            }
            loopSequence.makeLooping();
            if (sequence !== loopSequence)
                sequence.addAction(loopSequence);
        }

        if (randomOffsetNormalized && randomOffsetNormalized > 0) {
            sequence.actions.unshift(ActionBuilder.waitAction(randomOffsetNormalized));
        }

        return sequence;
    }

    static getAndRegisterAnimationSequences(ext: AnimationExtension, target: GameObject, stateName?: string): {
        animationSequence: Array<RegisteredAnimationInfo>,
        animationLoopAfterSequence: Array<RegisteredAnimationInfo>,
        randomTimeOffset: number,
    } | undefined {

        if (!target) return undefined;

        const animator = target.getComponent(Animator);
        const animation = target.getComponent(Animation);

        if (!animator && !animation) return undefined;

        if (animator && !stateName) {
            throw new Error("PlayAnimationOnClick: No stateName specified for animator " + animator.name + " on " + target.name);
        }

        let animationSequence: Array<RegisteredAnimationInfo> = [];
        let animationLoopAfterSequence: Array<RegisteredAnimationInfo> = [];

        if (animation) {
            const anim = ext.registerAnimation(target, animation.clip);
            if (anim) {
                if (animation.loop)
                    animationLoopAfterSequence.push(anim);
                else
                    animationSequence.push(anim);
            }

            let randomTimeOffset = 0;
            if (animation.minMaxOffsetNormalized) {
                const from = animation.minMaxOffsetNormalized.x;
                const to = animation.minMaxOffsetNormalized.y;
                randomTimeOffset = (animation.clip?.duration || 1) * (from + Math.random() * (to - from));
            }

            return {
                animationSequence,
                animationLoopAfterSequence,
                randomTimeOffset,
            }
        }

        // If there's a separate state specified to play after this one, we 
        // play it automatically. Theoretically an animator state machine flow could be encoded here.

        // We're parsing the Animator states here and follow the transitio