@needle-tools/engine 4.4.0-beta.3 → 4.4.0-beta.5

package/src/engine-components/export/usdz/extensions/behavior/BehaviourComponents.ts

@@ -1,1226 +1,1226 @@
-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 type { IPointerClickHandler, PointerEventData } from "../../../../ui/PointerEvents.js";
-import { ObjectRaycaster,Raycaster } from "../../../../ui/Raycaster.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");
-
-function ensureRaycaster(obj: GameObject) {
-    if (!obj) return;
-    if (!obj.getComponentInParent(Raycaster)) {
-        if (isDevEnvironment())
-            console.debug("Raycaster on \"" + obj.name + "\" was automatically added, because no raycaster was found in the parent hierarchy.")
-        obj.addComponent(ObjectRaycaster);
-    }
-}
-
-/**
- * @category Everywhere Actions
- * @group Components
- */
-export class ChangeTransformOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {
-
-    @serializable(Object3D)
-    object?: Object3D;
-
-    @serializable(Object3D)
-    target?: Object3D;
-
-    @serializable()
-    duration: number = 1;
-
-    @serializable()
-    relativeMotion: boolean = false;
-
-    private coroutine: Generator | null = null;
-
-    private targetPos = new Vector3();
-    private targetRot = new Quaternion();
-    private targetScale = new Vector3();
-
-    start(): void {
-        ensureRaycaster(this.gameObject);
-    }
-
-    onPointerClick(args: PointerEventData) {
-        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);
-        }
-    }
-}
-
-/**
- * @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;
-        ensureRaycaster(this.gameObject);
-        if (isDevEnvironment() && this._objectsWithThisMaterial.length <= 0) {
-            console.warn("ChangeMaterialOnClick: No objects found with material \"" + this.materialToSwitch?.name + "\"");
-        }
-    }
-
-    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;
-    }
-}
-
-/**
- * @category Everywhere Actions
- * @group Components
- */
-export class SetActiveOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {
-
-    @serializable(Object3D)
-    target?: Object3D;
-
-    @serializable()
-    toggleOnClick: boolean = false;
-
-    @serializable()
-    targetState: boolean = true;
-
-    @serializable()
-    hideSelf: boolean = true;
-
-    start(): void {
-        ensureRaycaster(this.gameObject);
-    }
-
-    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];
-    }
-}
-
-/**
- * @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);
-    }
-}
-
-/**
- * @category Everywhere Actions
- * @group Components
- */
-export class EmphasizeOnClick extends Behaviour implements UsdzBehaviour {
-
-    @serializable()
-    target?: Object3D;
-
-    @serializable()
-    duration: number = 0.5;
-
-    @serializable()
-    motionType: EmphasizeActionMotionType = "bounce";
-
-    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) { }
-}
-
-/**
- * @category Everywhere Actions
- * @group Components
- */
-export class PlayAudioOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {
-
-    @serializable(AudioSource)
-    target?: AudioSource;
-
-    @serializable(URL)
-    clip: string = "";
-
-    @serializable()
-    toggleOnClick: boolean = false;
-
-    // Not exposed, but used for implicit playback of PlayOnAwake audio sources
-    trigger: "tap" | "start" = "tap";
-
-    start(): void {
-        ensureRaycaster(this.gameObject);
-    }
-
-    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;
-            }
-        }
-    }
-
-    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);
-                }
-            }
-        }
-    }
-}
-
-/**
- * @category Everywhere Actions
- * @group Components
- */
-export class PlayAnimationOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour, UsdzAnimation {
-
-    @serializable(Animator)
-    animator?: 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 }
-
-    start(): void {
-        ensureRaycaster(this.gameObject);
-    }
-
-    onPointerClick(args: PointerEventData) {
-        args.use();
-        if (!this.target) return;
-        if (this.stateName) {
-            // 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 transition chain until we find a loop.
-        // There are some edge cases:
-        // - (0 > 1.looping) should keep looping (1).
-        // - (0 > 1 > 1) should keep looping (1).
-        // - (0 > 1 > 2 > 3 > 2) should keep looping (2,3).
-        // - (0 > 1 > 2 > 3 > 0) should keep looping (0,1,2,3).
-        const runtimeController = animator?.runtimeAnimatorController;
-        let currentState = runtimeController?.findState(stateName);
-        let statesUntilLoop: State[] = [];
-        let statesLooping: State[] = [];
-
-        if (runtimeController && currentState) {
-            // starting point – we have set this above already as startAction
-            const visitedStates = new Array<State>;
-            visitedStates.push(currentState);
-            let foundLoop = false;
-
-            while (true && visitedStates.length < 100) {
-                if (!currentState || currentState === null || !currentState.transitions || currentState.transitions.length === 0) {
-                    if (currentState.motion?.isLooping)
-                        foundLoop = true;
-                    break;
-                }
-
-                // find the first transition without parameters
-                // TODO we could also find the first _valid_ transition here instead based on the current parameters.
-                const transition = currentState.transitions.find(t => t.conditions.length === 0);
-                const nextState: State | null = transition ? runtimeController["getState"](transition.destinationState, 0) : null;
-                // abort: we found a state loop
-                if (nextState && visitedStates.includes(nextState)) {
-                    currentState = nextState;
-                    foundLoop = true;
-                    break;
-                }
-                // keep looking: transition to another state
-                else if (transition) {
-                    currentState = nextState;
-                    if (!currentState)
-                        break;
-                    visitedStates.push(currentState);
-                }
-                // abort: no transition found. check if last state is looping
-                else {
-                    foundLoop = currentState.motion?.isLooping ?? false;
-                    break;
-                }
-            }
-
-            if (foundLoop && currentState) {
-                // check what the first state in the loop is – it must be matching the last one we added
-                const firstStateInLoop = visitedStates.indexOf(currentState);
-                statesUntilLoop = visitedStates.slice(0, firstStateInLoop); // can be empty, which means we're looping all
-                statesLooping = visitedStates.slice(firstStateInLoop); // can be empty, which means nothing is looping
-
-                // Potentially we need to prevent self-transitions into a non-looping state, these do not result in a loop in the runtime
-                /*
-                if (statesLooping.length === 1 && !statesLooping[0].motion?.isLooping) {
-                    statesUntilLoop.push(statesLooping[0]);
-                    statesLooping = [];
-                }
-                */
-                if (debug) console.log("found loop from " + stateName, "states until loop", statesUntilLoop, "states looping", statesLooping);
-            }
-            else {
-                statesUntilLoop = visitedStates;
-                statesLooping = [];
-                if (debug) console.log("found no loop from " + stateName, "states", statesUntilLoop);
-            }
-            // If we do NOT loop, we need to explicitly add a single-keyframe clip with a "hold" pose
-            // to prevent the animation from resetting to the start.
-            if (!statesLooping.length) {
-                const lastState = statesUntilLoop[statesUntilLoop.length - 1];
-                const lastClip = lastState.motion?.clip;
-                if (lastClip) {
-                    let clipCopy: AnimationClip | undefined;
-                    if (ext.holdClipMap.has(lastClip)) {
-                        clipCopy = ext.holdClipMap.get(lastClip);    
-                    }
-                    else {
-                        // We're creating a "hold" clip here; exactly 1 second long, and inteprolates exactly on the duration of the clip
-                        const holdStateName = lastState.name + "_hold";
-                        clipCopy = lastClip.clone();
-                        clipCopy.duration = 1;
-                        clipCopy.name = holdStateName;
-                        const lastFrame = lastClip.duration;
-                        clipCopy.tracks = lastClip.tracks.map(t => {
-                            const trackCopy = t.clone();
-                            trackCopy.times = new Float32Array([0, lastFrame]);
-                            const len = t.values.length;
-                            const size = t.getValueSize();;
-                            const lastValue = t.values.slice(len - size, len);
-                            // we need this twice
-                            trackCopy.values = new Float32Array(2 * size);
-                            trackCopy.values.set(lastValue, 0);
-                            trackCopy.values.set(lastValue, size);
-                            return trackCopy;
-                        });
-                        clipCopy.name = holdStateName;
-                        ext.holdClipMap.set(lastClip, clipCopy);
-                    }
-
-                    if (clipCopy) {
-                        const holdState = {
-                            name: clipCopy.name,
-                            motion: { clip: clipCopy, isLooping: false, name: clipCopy.name },
-                            speed: 1,
-                            transitions: [],
-                            behaviours: [],
-                            hash: lastState.hash + 1,
-                        }
-                        statesLooping.push(holdState);
-                    }
-                }
-            }
-        }
-
-        // Special case: someone's trying to play an empty clip without any motion data, no loops or anything.
-        // In that case, we simply go to the rest clip – this is a common case for "idle" states.
-        if (statesUntilLoop.length === 1 && (!statesUntilLoop[0].motion?.clip || statesUntilLoop[0].motion?.clip.tracks?.length === 0)) {
-            animationSequence = new Array<RegisteredAnimationInfo>();
-            const anim = ext.registerAnimation(target, null);
-            if (anim) animationSequence.push(anim);
-            return undefined;
-        }
-
-        // filter out any states that don't have motion data
-        statesUntilLoop = statesUntilLoop.filter(s => s.motion?.clip && s.motion?.clip.tracks?.length > 0);
-        statesLooping = statesLooping.filter(s => s.motion?.clip && s.motion?.clip.tracks?.length > 0);
-
-        // If none of the found states have motion, we need to warn
-        if (statesUntilLoop.length === 0 && statesLooping.length === 0) {
-            console.warn("No clips found for state " + stateName + " on " + animator?.name + ", can't export animation data");
-            return undefined;
-        }
-
-        const addStateToSequence = (state: State, sequence: Array<RegisteredAnimationInfo>) => {
-            if (!target) return;
-            const anim = ext.registerAnimation(target, state.motion.clip ?? null);
-            if (anim) {
-                anim.speed = state.speed;
-                sequence.push(anim);
-            }
-            else console.warn("Couldn't register animation for state " + state.name + " on " + animator?.name);
-        };
-
-        // Register all the animation states we found.
-        if (statesUntilLoop.length > 0) {
-            animationSequence = new Array<RegisteredAnimationInfo>();
-            for (const state of statesUntilLoop) {
-                addStateToSequence(state, animationSequence);
-            }
-        }
-        if (statesLooping.length > 0) {
-            animationLoopAfterSequence = new Array<RegisteredAnimationInfo>();
-            for (const state of statesLooping) {
-                addStateToSequence(state, animationLoopAfterSequence);
-            }
-        }
-
-        let randomTimeOffset = 0;
-        if (animator && runtimeController && animator.minMaxOffsetNormalized) {
-            const from = animator.minMaxOffsetNormalized.x;
-            const to = animator.minMaxOffsetNormalized.y;
-            // first state in the sequence
-            const firstState = statesUntilLoop.length ? statesUntilLoop[0] : statesLooping.length ? statesLooping[0] : null;
-            randomTimeOffset = (firstState?.motion.clip?.duration || 1) * (from + Math.random() * (to - from));
-        }
-        return {
-            animationSequence,
-            animationLoopAfterSequence,
-            randomTimeOffset,
-        }
-    }
-
-    createAnimation(ext: AnimationExtension, model: USDObject, _context: USDZExporterContext) {
-
-        if (!this.target || (!this.animator && !this.animation)) return;
-
-        const result = PlayAnimationOnClick.getAndRegisterAnimationSequences(ext, this.target, this.stateName);
-        if (!result) return;
-
-        this.animationSequence = result.animationSequence;
-        this.animationLoopAfterSequence = result.animationLoopAfterSequence;
-        this.randomOffsetNormalized = result.randomTimeOffset;
-
-        this.stateAnimationModel = model;
-    }
-
-}
-
-export class PreliminaryAction extends Behaviour {
-    getType(): string | void { }
-    @serializable(Object3D)
-    target?: Object3D;
-
-
-    getDuration(): number | void { };
-}
-
-export class PreliminaryTrigger extends Behaviour {
-
-    @serializable(PreliminaryAction)
-    target?: PreliminaryAction;
-}
-
-/**
- * @category Everywhere Actions
- * @group Components
- */
-export class VisibilityAction extends PreliminaryAction {
-
-    //@type int
-    @serializable()
-    type: VisibilityActionType = VisibilityActionType.Hide;
-
-    @serializable()
-    duration: number = 1;
-
-    getType() {
-        switch (this.type) {
-            case VisibilityActionType.Hide: return "hide";
-            case VisibilityActionType.Show: return "show";
-        }
-    }
-
-    getDuration() {
-        return this.duration;
-    }
-}
-
-/**
- * @category Everywhere Actions
- * @group Components
- */
-export class TapGestureTrigger extends PreliminaryTrigger {
-
-}
-
-export enum VisibilityActionType {
-    Show = 0,
-    Hide = 1,
+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 type { IPointerClickHandler, PointerEventData } from "../../../../ui/PointerEvents.js";
+import { ObjectRaycaster,Raycaster } from "../../../../ui/Raycaster.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");
+
+function ensureRaycaster(obj: GameObject) {
+    if (!obj) return;
+    if (!obj.getComponentInParent(Raycaster)) {
+        if (isDevEnvironment())
+            console.debug("Raycaster on \"" + obj.name + "\" was automatically added, because no raycaster was found in the parent hierarchy.")
+        obj.addComponent(ObjectRaycaster);
+    }
+}
+
+/**
+ * @category Everywhere Actions
+ * @group Components
+ */
+export class ChangeTransformOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {
+
+    @serializable(Object3D)
+    object?: Object3D;
+
+    @serializable(Object3D)
+    target?: Object3D;
+
+    @serializable()
+    duration: number = 1;
+
+    @serializable()
+    relativeMotion: boolean = false;
+
+    private coroutine: Generator | null = null;
+
+    private targetPos = new Vector3();
+    private targetRot = new Quaternion();
+    private targetScale = new Vector3();
+
+    start(): void {
+        ensureRaycaster(this.gameObject);
+    }
+
+    onPointerClick(args: PointerEventData) {
+        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);
+        }
+    }
+}
+
+/**
+ * @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;
+        ensureRaycaster(this.gameObject);
+        if (isDevEnvironment() && this._objectsWithThisMaterial.length <= 0) {
+            console.warn("ChangeMaterialOnClick: No objects found with material \"" + this.materialToSwitch?.name + "\"");
+        }
+    }
+
+    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;
+    }
+}
+
+/**
+ * @category Everywhere Actions
+ * @group Components
+ */
+export class SetActiveOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {
+
+    @serializable(Object3D)
+    target?: Object3D;
+
+    @serializable()
+    toggleOnClick: boolean = false;
+
+    @serializable()
+    targetState: boolean = true;
+
+    @serializable()
+    hideSelf: boolean = true;
+
+    start(): void {
+        ensureRaycaster(this.gameObject);
+    }
+
+    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];
+    }
+}
+
+/**
+ * @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);
+    }
+}
+
+/**
+ * @category Everywhere Actions
+ * @group Components
+ */
+export class EmphasizeOnClick extends Behaviour implements UsdzBehaviour {
+
+    @serializable()
+    target?: Object3D;
+
+    @serializable()
+    duration: number = 0.5;
+
+    @serializable()
+    motionType: EmphasizeActionMotionType = "bounce";
+
+    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) { }
+}
+
+/**
+ * @category Everywhere Actions
+ * @group Components
+ */
+export class PlayAudioOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour {
+
+    @serializable(AudioSource)
+    target?: AudioSource;
+
+    @serializable(URL)
+    clip: string = "";
+
+    @serializable()
+    toggleOnClick: boolean = false;
+
+    // Not exposed, but used for implicit playback of PlayOnAwake audio sources
+    trigger: "tap" | "start" = "tap";
+
+    start(): void {
+        ensureRaycaster(this.gameObject);
+    }
+
+    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;
+            }
+        }
+    }
+
+    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);
+                }
+            }
+        }
+    }
+}
+
+/**
+ * @category Everywhere Actions
+ * @group Components
+ */
+export class PlayAnimationOnClick extends Behaviour implements IPointerClickHandler, UsdzBehaviour, UsdzAnimation {
+
+    @serializable(Animator)
+    animator?: 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 }
+
+    start(): void {
+        ensureRaycaster(this.gameObject);
+    }
+
+    onPointerClick(args: PointerEventData) {
+        args.use();
+        if (!this.target) return;
+        if (this.stateName) {
+            // 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 transition chain until we find a loop.
+        // There are some edge cases:
+        // - (0 > 1.looping) should keep looping (1).
+        // - (0 > 1 > 1) should keep looping (1).
+        // - (0 > 1 > 2 > 3 > 2) should keep looping (2,3).
+        // - (0 > 1 > 2 > 3 > 0) should keep looping (0,1,2,3).
+        const runtimeController = animator?.runtimeAnimatorController;
+        let currentState = runtimeController?.findState(stateName);
+        let statesUntilLoop: State[] = [];
+        let statesLooping: State[] = [];
+
+        if (runtimeController && currentState) {
+            // starting point – we have set this above already as startAction
+            const visitedStates = new Array<State>;
+            visitedStates.push(currentState);
+            let foundLoop = false;
+
+            while (true && visitedStates.length < 100) {
+                if (!currentState || currentState === null || !currentState.transitions || currentState.transitions.length === 0) {
+                    if (currentState.motion?.isLooping)
+                        foundLoop = true;
+                    break;
+                }
+
+                // find the first transition without parameters
+                // TODO we could also find the first _valid_ transition here instead based on the current parameters.
+                const transition = currentState.transitions.find(t => t.conditions.length === 0);
+                const nextState: State | null = transition ? runtimeController["getState"](transition.destinationState, 0) : null;
+                // abort: we found a state loop
+                if (nextState && visitedStates.includes(nextState)) {
+                    currentState = nextState;
+                    foundLoop = true;
+                    break;
+                }
+                // keep looking: transition to another state
+                else if (transition) {
+                    currentState = nextState;
+                    if (!currentState)
+                        break;
+                    visitedStates.push(currentState);
+                }
+                // abort: no transition found. check if last state is looping
+                else {
+                    foundLoop = currentState.motion?.isLooping ?? false;
+                    break;
+                }
+            }
+
+            if (foundLoop && currentState) {
+                // check what the first state in the loop is – it must be matching the last one we added
+                const firstStateInLoop = visitedStates.indexOf(currentState);
+                statesUntilLoop = visitedStates.slice(0, firstStateInLoop); // can be empty, which means we're looping all
+                statesLooping = visitedStates.slice(firstStateInLoop); // can be empty, which means nothing is looping
+
+                // Potentially we need to prevent self-transitions into a non-looping state, these do not result in a loop in the runtime
+                /*
+                if (statesLooping.length === 1 && !statesLooping[0].motion?.isLooping) {
+                    statesUntilLoop.push(statesLooping[0]);
+                    statesLooping = [];
+                }
+                */
+                if (debug) console.log("found loop from " + stateName, "states until loop", statesUntilLoop, "states looping", statesLooping);
+            }
+            else {
+                statesUntilLoop = visitedStates;
+                statesLooping = [];
+                if (debug) console.log("found no loop from " + stateName, "states", statesUntilLoop);
+            }
+            // If we do NOT loop, we need to explicitly add a single-keyframe clip with a "hold" pose
+            // to prevent the animation from resetting to the start.
+            if (!statesLooping.length) {
+                const lastState = statesUntilLoop[statesUntilLoop.length - 1];
+                const lastClip = lastState.motion?.clip;
+                if (lastClip) {
+                    let clipCopy: AnimationClip | undefined;
+                    if (ext.holdClipMap.has(lastClip)) {
+                        clipCopy = ext.holdClipMap.get(lastClip);    
+                    }
+                    else {
+                        // We're creating a "hold" clip here; exactly 1 second long, and inteprolates exactly on the duration of the clip
+                        const holdStateName = lastState.name + "_hold";
+                        clipCopy = lastClip.clone();
+                        clipCopy.duration = 1;
+                        clipCopy.name = holdStateName;
+                        const lastFrame = lastClip.duration;
+                        clipCopy.tracks = lastClip.tracks.map(t => {
+                            const trackCopy = t.clone();
+                            trackCopy.times = new Float32Array([0, lastFrame]);
+                            const len = t.values.length;
+                            const size = t.getValueSize();;
+                            const lastValue = t.values.slice(len - size, len);
+                            // we need this twice
+                            trackCopy.values = new Float32Array(2 * size);
+                            trackCopy.values.set(lastValue, 0);
+                            trackCopy.values.set(lastValue, size);
+                            return trackCopy;
+                        });
+                        clipCopy.name = holdStateName;
+                        ext.holdClipMap.set(lastClip, clipCopy);
+                    }
+
+                    if (clipCopy) {
+                        const holdState = {
+                            name: clipCopy.name,
+                            motion: { clip: clipCopy, isLooping: false, name: clipCopy.name },
+                            speed: 1,
+                            transitions: [],
+                            behaviours: [],
+                            hash: lastState.hash + 1,
+                        }
+                        statesLooping.push(holdState);
+                    }
+                }
+            }
+        }
+
+        // Special case: someone's trying to play an empty clip without any motion data, no loops or anything.
+        // In that case, we simply go to the rest clip – this is a common case for "idle" states.
+        if (statesUntilLoop.length === 1 && (!statesUntilLoop[0].motion?.clip || statesUntilLoop[0].motion?.clip.tracks?.length === 0)) {
+            animationSequence = new Array<RegisteredAnimationInfo>();
+            const anim = ext.registerAnimation(target, null);
+            if (anim) animationSequence.push(anim);
+            return undefined;
+        }
+
+        // filter out any states that don't have motion data
+        statesUntilLoop = statesUntilLoop.filter(s => s.motion?.clip && s.motion?.clip.tracks?.length > 0);
+        statesLooping = statesLooping.filter(s => s.motion?.clip && s.motion?.clip.tracks?.length > 0);
+
+        // If none of the found states have motion, we need to warn
+        if (statesUntilLoop.length === 0 && statesLooping.length === 0) {
+            console.warn("No clips found for state " + stateName + " on " + animator?.name + ", can't export animation data");
+            return undefined;
+        }
+
+        const addStateToSequence = (state: State, sequence: Array<RegisteredAnimationInfo>) => {
+            if (!target) return;
+            const anim = ext.registerAnimation(target, state.motion.clip ?? null);
+            if (anim) {
+                anim.speed = state.speed;
+                sequence.push(anim);
+            }
+            else console.warn("Couldn't register animation for state " + state.name + " on " + animator?.name);
+        };
+
+        // Register all the animation states we found.
+        if (statesUntilLoop.length > 0) {
+            animationSequence = new Array<RegisteredAnimationInfo>();
+            for (const state of statesUntilLoop) {
+                addStateToSequence(state, animationSequence);
+            }
+        }
+        if (statesLooping.length > 0) {
+            animationLoopAfterSequence = new Array<RegisteredAnimationInfo>();
+            for (const state of statesLooping) {
+                addStateToSequence(state, animationLoopAfterSequence);
+            }
+        }
+
+        let randomTimeOffset = 0;
+        if (animator && runtimeController && animator.minMaxOffsetNormalized) {
+            const from = animator.minMaxOffsetNormalized.x;
+            const to = animator.minMaxOffsetNormalized.y;
+            // first state in the sequence
+            const firstState = statesUntilLoop.length ? statesUntilLoop[0] : statesLooping.length ? statesLooping[0] : null;
+            randomTimeOffset = (firstState?.motion.clip?.duration || 1) * (from + Math.random() * (to - from));
+        }
+        return {
+            animationSequence,
+            animationLoopAfterSequence,
+            randomTimeOffset,
+        }
+    }
+
+    createAnimation(ext: AnimationExtension, model: USDObject, _context: USDZExporterContext) {
+
+        if (!this.target || (!this.animator && !this.animation)) return;
+
+        const result = PlayAnimationOnClick.getAndRegisterAnimationSequences(ext, this.target, this.stateName);
+        if (!result) return;
+
+        this.animationSequence = result.animationSequence;
+        this.animationLoopAfterSequence = result.animationLoopAfterSequence;
+        this.randomOffsetNormalized = result.randomTimeOffset;
+
+        this.stateAnimationModel = model;
+    }
+
+}
+
+export class PreliminaryAction extends Behaviour {
+    getType(): string | void { }
+    @serializable(Object3D)
+    target?: Object3D;
+
+
+    getDuration(): number | void { };
+}
+
+export class PreliminaryTrigger extends Behaviour {
+
+    @serializable(PreliminaryAction)
+    target?: PreliminaryAction;
+}
+
+/**
+ * @category Everywhere Actions
+ * @group Components
+ */
+export class VisibilityAction extends PreliminaryAction {
+
+    //@type int
+    @serializable()
+    type: VisibilityActionType = VisibilityActionType.Hide;
+
+    @serializable()
+    duration: number = 1;
+
+    getType() {
+        switch (this.type) {
+            case VisibilityActionType.Hide: return "hide";
+            case VisibilityActionType.Show: return "show";
+        }
+    }
+
+    getDuration() {
+        return this.duration;
+    }
+}
+
+/**
+ * @category Everywhere Actions
+ * @group Components
+ */
+export class TapGestureTrigger extends PreliminaryTrigger {
+
+}
+
+export enum VisibilityActionType {
+    Show = 0,
+    Hide = 1,
 }