@needle-tools/engine 3.28.6-beta → 3.28.7-beta.1

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -1,477 +1,477 @@
-import { delay, getParam, isiOS, isMobileDevice, isSafari } from "../../../engine/engine_utils.js";
-import { Object3D, Mesh, Matrix4 } from "three";
-import { USDZExporter as ThreeUSDZExporter } from "./ThreeUSDZExporter.js";
-import { AnimationExtension } from "./extensions/Animation.js"
-import { ensureQuicklookLinkIsCreated } from "./utils/quicklook.js";
-import { getFormattedDate } from "./utils/timeutils.js";
-import { registerAnimatorsImplictly } from "./utils/animationutils.js";
-import type { IUSDExporterExtension } from "./Extension.js";
-import { Behaviour, GameObject } from "../../Component.js";
-import { WebXR } from "../../webxr/WebXR.js"
-import { serializable } from "../../../engine/engine_serialization.js";
-import { showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
-import { Context } from "../../../engine/engine_setup.js";
-import { WebARSessionRoot } from "../../webxr/WebARSessionRoot.js";
-import { hasProLicense } from "../../../engine/engine_license.js";
-import { BehaviorExtension } from "./extensions/behavior/Behaviour.js";
-import { AudioExtension } from "./extensions/behavior/AudioExtension.js";
-import { TextExtension } from "./extensions/USDZText.js";
-import { USDZUIExtension } from "./extensions/USDZUI.js";
-import { Renderer } from "../../Renderer.js"
-import { XRFlag, XRState, XRStateFlag } from "../../XRFlag.js";
-
-const debug = getParam("debugusdz");
-
-export class CustomBranding {
-    @serializable()
-    callToAction?: string;
-    @serializable()
-    checkoutTitle?: string;
-    @serializable()
-    checkoutSubtitle?: string;
-
-    /** if assigned the call to action button in quicklook will open the URL. Otherwise it will just close quicklook. */
-    @serializable()
-    callToActionURL?: string;
-}
-
-export class USDZExporter extends Behaviour {
-
-    @serializable(Object3D)
-    objectToExport?: Object3D;
-
-    @serializable()
-    autoExportAnimations: boolean = false;
-
-    @serializable()
-    exportFileName?: string;
-
-    @serializable(URL)
-    customUsdzFile?: string;
-
-    @serializable(CustomBranding)
-    customBranding?: CustomBranding;
-
-    // Currently not exposed to integrations - not fully tested. Set from code (e.g. image tracking)
-    @serializable()
-    anchoringType: "plane" | "image" | "face" | "none" = "plane";
-
-    // Currently not exposed to integrations - not fully tested. Set from code (e.g. image tracking)
-    @serializable()
-    planeAnchoringAlignment: "horizontal" | "vertical" | "any" = "horizontal";
-
-    @serializable()
-    interactive: boolean = true;
-
-    @serializable()
-    allowCreateQuicklookButton: boolean = true;
-
-    @serializable()
-    quickLookCompatible: boolean = true;
-
-    // Registered extensions. Add your own extensions here
-    extensions: IUSDExporterExtension[] = [];
-
-    private link!: HTMLAnchorElement;
-    private webxr?: WebXR;
-
-    start() {
-        if (debug) {
-            console.log("USDZExporter", this);
-            console.log("Debug USDZ Mode. Press 'T' to export")
-            window.addEventListener("keydown", (evt) => {
-                switch (evt.key) {
-                    case "t":
-                        this.exportAsync();
-                        break;
-                }
-            });
-            if (isMobileDevice()) {
-                setTimeout(() => {
-                    this.exportAsync();
-                }, 2000)
-            }
-        }
-
-        // fall back to this object or to the scene if it's empty and doesn't have a mesh
-        if (!this.objectToExport)
-            this.objectToExport = this.gameObject;
-        if (!this.objectToExport?.children?.length && !(this.objectToExport as Mesh)?.isMesh)
-            this.objectToExport = this.context.scene;
-
-        if (this.interactive) {
-            this.extensions.push(new BehaviorExtension());
-            this.extensions.push(new AudioExtension());
-            this.extensions.push(new TextExtension());
-            this.extensions.push(new USDZUIExtension());
-        }
-    }
-
-    onEnable() {
-        const ios = isiOS()
-        const safari = isSafari();
-        if (debug || (ios && safari)) {
-            if (debug || this.allowCreateQuicklookButton)
-                this.addQuicklookButton();
-            this.lastCallback = this.quicklookCallback.bind(this);
-            this.link = ensureQuicklookLinkIsCreated(this.context);
-            this.link.addEventListener('message', this.lastCallback);
-        }
-        if (debug)
-            showBalloonMessage("USDZ Exporter enabled: " + this.name);
-
-        document.getElementById("open-in-ar")?.addEventListener("click", this.onClickedOpenInARElement);
-    }
-
-    onDisable() {
-        this.link?.removeEventListener('message', this.lastCallback);
-        const ios = isiOS()
-        const safari = isSafari();
-        if (debug || (ios && safari)) {
-            this.removeQuicklookButton();
-        }
-        if (debug)
-            showBalloonMessage("USDZ Exporter disabled: " + this.name);
-
-        document.getElementById("open-in-ar")?.removeEventListener("click", this.onClickedOpenInARElement);
-    }
-
-    private onClickedOpenInARElement = (evt) => {
-        evt.preventDefault();
-        this.exportAsync();
-    }
-
-    /**
-     * Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook.
-     * Use the various public properties of USDZExporter to customize export behaviour.
-     */
-    async exportAsync() {
-
-        let name = this.exportFileName ?? this.objectToExport?.name ?? this.name;
-        name += "-" + getFormattedDate(); // seems iOS caches the file in some cases, this ensures we always have a fresh file
-
-        if (!hasProLicense()) {
-            if (name !== "") name += "-";
-            name += "MadeWithNeedle";
-        }
-
-        if (!this.link) this.link = ensureQuicklookLinkIsCreated(this.context);
-        
-        // ability to specify a custom USDZ file to be used instead of a dynamic one
-        if (this.customUsdzFile) {
-            if (debug) console.log("Exporting custom usdz", this.customUsdzFile)
-            this.openInQuickLook(this.customUsdzFile, name);
-            return;
-        }
-
-        const blob = await this.export(this.objectToExport);
-        if (!blob) {
-            console.warn("No object to export", this);
-            return;
-        }
-
-        if (debug) console.log("USDZ generation done. Downloading as " + this.link.download);
-        
-        // TODO detect QuickLook availability:
-        // https://webkit.org/blog/8421/viewing-augmented-reality-assets-in-safari-for-ios/#:~:text=inside%20the%20anchor.-,Feature%20Detection,-To%20detect%20support
-
-
-        this.openInQuickLook(blob, name);
-    }
-
-    /**
-     * Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook.
-     * @returns a Promise<Blob> containing the USDZ file
-     */
-    async export(objectToExport: Object3D | undefined) : Promise<Blob | null> {
-
-        if (!objectToExport)
-            return null;
-
-        // trigger progressive textures to be loaded:
-        const renderers = GameObject.getComponentsInChildren(objectToExport, Renderer);
-        const progressiveLoading = new Array<Promise<any>>();
-        for (const rend of renderers) {
-            for (const mat of rend.sharedMaterials) {
-                if (mat) {
-                    const task = rend.loadProgressiveTextures(mat);
-                    if (task instanceof Promise)
-                        progressiveLoading.push(task);
-                }
-            }
-        }
-        if (debug) showBalloonMessage("Load textures: " + progressiveLoading.length);
-        await Promise.all(progressiveLoading);
-        if (debug) showBalloonMessage("Load textures: done");
-
-        // apply XRFlags
-        const currentXRState = XRState.Global.Mask;
-        XRState.Global.Set(XRStateFlag.AR);
-
-        // make sure we apply the AR scale
-        this.applyWebARSessionRoot();
-
-        const exporter = new ThreeUSDZExporter();
-        const extensions: any = [...this.extensions]
-
-        // collect animators and their clips
-        const animExt = new AnimationExtension(this.quickLookCompatible);
-        extensions.push(animExt);
-
-        const eventArgs = { self: this, exporter: exporter, extensions: extensions, object: objectToExport };
-        this.dispatchEvent(new CustomEvent("before-export", { detail: eventArgs }))
-
-        // Implicit registration and actions for Animators and Animation components
-        // Currently, Animators properly build PlayAnimation actions, but Animation components don't.
-        const implicitAnimationBehaviors = new Array<Object3D>();
-        if (this.autoExportAnimations) {
-            implicitAnimationBehaviors.push(...registerAnimatorsImplictly(objectToExport, animExt));
-        }
-
-        //@ts-ignore
-        exporter.debug = debug;
-
-        // sanitize anchoring types
-        if (this.anchoringType !== "plane" && this.anchoringType !== "none" && this.anchoringType !== "image" && this.anchoringType !== "face")
-            this.anchoringType = "plane";
-        if (this.planeAnchoringAlignment !== "horizontal" && this.planeAnchoringAlignment !== "vertical" && this.planeAnchoringAlignment !== "any")
-            this.planeAnchoringAlignment = "horizontal";
-
-        //@ts-ignore
-        const arraybuffer = await exporter.parse(this.objectToExport, {
-            ar: {
-                anchoring: {
-                    type: this.anchoringType,
-                },
-                planeAnchoring: {
-                    alignment: this.planeAnchoringAlignment,
-                },
-            },
-            extensions: extensions,
-            quickLookCompatible: this.quickLookCompatible,
-        });
-        const blob = new Blob([arraybuffer], { type: 'application/octet-stream' });
-
-        // cleanup – implicit animation behaviors need to be removed again
-        for (const go of implicitAnimationBehaviors) {
-            GameObject.destroy(go);
-        }
-
-        this.dispatchEvent(new CustomEvent("after-export", { detail: eventArgs }))
-
-        // restore XR flags
-        XRState.Global.Set(currentXRState);
-
-        // second file: USDA (without assets)
-        //@ts-ignore
-        // const usda = exporter.lastUsda;
-        // const blob2 = new Blob([usda], { type: 'text/plain' });
-        // this.link.download = name + ".usda";
-        // this.link.href = URL.createObjectURL(blob2);
-        // this.link.click();
-
-        return blob;
-    }
-
-    /**
-     * Opens QuickLook on iOS/iPadOS/visionOS with the given content in AR mode.
-     * @param content The URL to the .usdz or .reality file or a blob containing an USDZ file.
-     * @param name Download filename
-     */
-    openInQuickLook(content: Blob | string, name: string) {
-
-        const url = content instanceof Blob ? URL.createObjectURL(content) : content;
-
-        // see https://developer.apple.com/documentation/arkit/adding_an_apple_pay_button_or_a_custom_action_in_ar_quick_look
-        const overlay = this.buildQuicklookOverlay();
-        if (debug) console.log("QuickLook Overlay", overlay);
-        const callToAction = overlay.callToAction ? encodeURIComponent(overlay.callToAction) : "";
-        const checkoutTitle = overlay.checkoutTitle ? encodeURIComponent(overlay.checkoutTitle) : "";
-        const checkoutSubtitle = overlay.checkoutSubtitle ? encodeURIComponent(overlay.checkoutSubtitle) : "";
-        this.link.href = url + `#callToAction=${callToAction}&checkoutTitle=${checkoutTitle}&checkoutSubtitle=${checkoutSubtitle}&callToActionURL=${overlay.callToActionURL}`;
-
-        if (!this.lastCallback) {
-            this.lastCallback = this.quicklookCallback.bind(this)
-            this.link.addEventListener('message', this.lastCallback);
-        }
-
-        // open quicklook
-        this.link.download = name + ".usdz";
-        this.link.click();
-
-        // cleanup 
-        // TODO check if we can do that immediately or need to wait until the user returns
-        // if (content instanceof Blob) URL.revokeObjectURL(url);
-    }
-
-    /**
-     * Downloads the given blob as a file.
-     */
-    download(blob: Blob, name: string) {
-        USDZExporter.save(blob, name);
-    }
-
-    // Matches GltfExport.save(blob, filename)
-    private static save(blob, filename) {
-        const link = document.createElement('a');
-        link.style.display = 'none';
-        document.body.appendChild(link); // Firefox workaround, see #6594
-        if (typeof blob === "string")
-            link.href = blob;
-        else
-            link.href = URL.createObjectURL(blob);
-        link.download = filename;
-        link.click();
-        link.remove();
-        // console.log(link.href);
-        // URL.revokeObjectURL( url ); breaks Firefox...
-    }
-
-
-    private lastCallback?: any;
-
-    private quicklookCallback(event: Event) {
-        if ((event as any)?.data == '_apple_ar_quicklook_button_tapped') {
-            if (debug) showBalloonWarning("Quicklook closed via call to action button");
-            var evt = new CustomEvent("quicklook-button-tapped", { detail: this });
-            this.dispatchEvent(evt);
-            if (!evt.defaultPrevented) {
-                const url = new URLSearchParams(this.link.href);
-                if (url) {
-                    const callToActionURL = url.get("callToActionURL");
-                    if (debug)
-                        showBalloonMessage("Quicklook url: " + callToActionURL);
-                    if (callToActionURL) {
-                        if (!hasProLicense()) {
-                            console.warn("Quicklook closed: custom redirects require a Needle Engine Pro license: https://needle.tools/pricing", callToActionURL)
-                        }
-                        else {
-                            globalThis.open(callToActionURL, "_blank");
-                        }
-                    }
-                }
-            }
-        }
-    }
-
-    private buildQuicklookOverlay(): CustomBranding {
-        const obj: CustomBranding = {};
-        if (this.customBranding) Object.assign(obj, this.customBranding);
-        if (!hasProLicense()) {
-            console.log("Custom Quicklook banner text requires pro license: https://needle.tools/pricing");
-            obj.callToAction = "Close";
-            obj.checkoutTitle = "🌵 Made with Needle";
-            obj.checkoutSubtitle = "_";
-        }
-        const needsDefaultValues = obj.callToAction?.length || obj.checkoutTitle?.length || obj.checkoutSubtitle?.length;
-        if (needsDefaultValues) {
-            if (!obj.callToAction?.length)
-                obj.callToAction = "\0";
-            if (!obj.checkoutTitle?.length)
-                obj.checkoutTitle = "\0";
-            if (!obj.checkoutSubtitle?.length)
-                obj.checkoutSubtitle = "\0";
-        }
-        // Use the quicklook-overlay event to customize the overlay
-        this.dispatchEvent(new CustomEvent("quicklook-overlay", { detail: obj }));
-        return obj;
-    }
-
-
-
-
-    private _quicklookButton?: HTMLElement;
-
-    private async createQuicklookButton() {
-        if (!this.webxr) {
-            await delay(1);
-            this.webxr = GameObject.findObjectOfType(WebXR) ?? undefined;
-            if (this.webxr) {
-                if (this.webxr.VRButton) this.webxr.VRButton.parentElement?.removeChild(this.webxr.VRButton);
-                // check if we have an AR button already and re-use that
-                if (this.webxr.ARButton && this._quicklookButton !== this.webxr.ARButton) {
-                    this._quicklookButton = this.webxr.ARButton;
-                    // Hack to remove the immersiveweb link
-                    const linkInButton = this.webxr.ARButton.parentElement?.querySelector("a");
-                    if (linkInButton) {
-                        linkInButton.href = "";
-                    }
-                    this.webxr.ARButton.innerText = "Open in Quicklook";
-                    this.webxr.ARButton.disabled = false;
-                    this.webxr.ARButton.addEventListener("click", evt => {
-                        evt.preventDefault();
-                        this.exportAsync();
-                    });
-                    this.webxr.ARButton.classList.add("quicklook-ar-button");
-                    this._quicklookButtonContainer = this.webxr.ARButton.parentElement;
-                    this.dispatchEvent(new CustomEvent("created-button", { detail: this.webxr.ARButton }))
-                }
-                // create a button if WebXR didnt create one yet
-                else {
-                    this.webxr.createARButton = false;
-                    this.webxr.createVRButton = false;
-                    let container = this.context.domElement.shadowRoot!.querySelector(".webxr-buttons");
-                    if (!container) {
-                        container = document.createElement("div");
-                        container.classList.add("webxr-buttons");
-                    }
-                    const button = document.createElement("button");
-                    button.innerText = "Open in Quicklook";
-                    button.addEventListener("click", () => {
-                        this.exportAsync();
-                    });
-                    button.classList.add('webxr-ar-button');
-                    button.classList.add('webxr-button');
-                    button.classList.add("quicklook-ar-button");
-                    this._quicklookButton = button;
-                    container.appendChild(button);
-                    this._quicklookButtonContainer = container;
-                    this.dispatchEvent(new CustomEvent("created-button", { detail: button }))
-                }
-            }
-            else {
-                console.warn("Could not find WebXR component: will not create Quicklook button", Context.Current);
-            }
-        }
-    }
-
-
-    private _quicklookButtonContainer: Element | null = null;
-    private async addQuicklookButton() {
-        await this.createQuicklookButton();
-        if (this._quicklookButton && this._quicklookButtonContainer) {
-            this._quicklookButtonContainer.appendChild(this._quicklookButton);
-        }
-    }
-    private removeQuicklookButton() {
-        this._quicklookButton?.remove();
-    }
-
-    private applyWebARSessionRoot() {
-        if (!this.objectToExport) return;
-
-        // first check if the sessionroot is in the parent hierarchy
-        // if that's the case we apply the scale to the object being exported
-        let sessionRoot = GameObject.getComponentInParent(this.objectToExport, WebARSessionRoot);
-        const hasSessionRootInParentHierarchy = sessionRoot !== null && sessionRoot !== undefined;
-        // if it's not in the parent hierarchy BUT in the child hierarchy we apply it to the sessionRoot object itself
-        // that#s the case when no objectToExport is explictly assigned and the whole scene is being exported
-        if(!sessionRoot) sessionRoot = GameObject.getComponentInChildren(this.objectToExport, WebARSessionRoot);
-
-        if(debug) console.log("applyWebARSessionRoot", sessionRoot);
-
-        if (!sessionRoot) {
-            if(debug) console.warn("No WebARSessionRoot found in parent hierarchy", this.objectToExport);
-            return;
-        }
-
-        // either apply the scale to the object being exported or to the sessionRoot object itself
-        const target = hasSessionRootInParentHierarchy ? this.objectToExport : sessionRoot.gameObject;
-        const scale = 1 / sessionRoot!.arScale;
-        if (debug) console.log("AR Session Root scale", scale, target);
-        target.matrix.makeScale(scale, scale, scale);
-        if (sessionRoot.invertForward) {
-            target.matrix.multiply(new Matrix4().makeRotationY(Math.PI));
-        }
-    }
-}
+import { delay, getParam, isiOS, isMobileDevice, isSafari } from "../../../engine/engine_utils.js";
+import { Object3D, Mesh, Matrix4 } from "three";
+import { USDZExporter as ThreeUSDZExporter } from "./ThreeUSDZExporter.js";
+import { AnimationExtension } from "./extensions/Animation.js"
+import { ensureQuicklookLinkIsCreated } from "./utils/quicklook.js";
+import { getFormattedDate } from "./utils/timeutils.js";
+import { registerAnimatorsImplictly } from "./utils/animationutils.js";
+import type { IUSDExporterExtension } from "./Extension.js";
+import { Behaviour, GameObject } from "../../Component.js";
+import { WebXR } from "../../webxr/WebXR.js"
+import { serializable } from "../../../engine/engine_serialization.js";
+import { showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
+import { Context } from "../../../engine/engine_setup.js";
+import { WebARSessionRoot } from "../../webxr/WebARSessionRoot.js";
+import { hasProLicense } from "../../../engine/engine_license.js";
+import { BehaviorExtension } from "./extensions/behavior/Behaviour.js";
+import { AudioExtension } from "./extensions/behavior/AudioExtension.js";
+import { TextExtension } from "./extensions/USDZText.js";
+import { USDZUIExtension } from "./extensions/USDZUI.js";
+import { Renderer } from "../../Renderer.js"
+import { XRFlag, XRState, XRStateFlag } from "../../XRFlag.js";
+
+const debug = getParam("debugusdz");
+
+export class CustomBranding {
+    @serializable()
+    callToAction?: string;
+    @serializable()
+    checkoutTitle?: string;
+    @serializable()
+    checkoutSubtitle?: string;
+
+    /** if assigned the call to action button in quicklook will open the URL. Otherwise it will just close quicklook. */
+    @serializable()
+    callToActionURL?: string;
+}
+
+export class USDZExporter extends Behaviour {
+
+    @serializable(Object3D)
+    objectToExport?: Object3D;
+
+    @serializable()
+    autoExportAnimations: boolean = false;
+
+    @serializable()
+    exportFileName?: string;
+
+    @serializable(URL)
+    customUsdzFile?: string;
+
+    @serializable(CustomBranding)
+    customBranding?: CustomBranding;
+
+    // Currently not exposed to integrations - not fully tested. Set from code (e.g. image tracking)
+    @serializable()
+    anchoringType: "plane" | "image" | "face" | "none" = "plane";
+
+    // Currently not exposed to integrations - not fully tested. Set from code (e.g. image tracking)
+    @serializable()
+    planeAnchoringAlignment: "horizontal" | "vertical" | "any" = "horizontal";
+
+    @serializable()
+    interactive: boolean = true;
+
+    @serializable()
+    allowCreateQuicklookButton: boolean = true;
+
+    @serializable()
+    quickLookCompatible: boolean = true;
+
+    // Registered extensions. Add your own extensions here
+    extensions: IUSDExporterExtension[] = [];
+
+    private link!: HTMLAnchorElement;
+    private webxr?: WebXR;
+
+    start() {
+        if (debug) {
+            console.log("USDZExporter", this);
+            console.log("Debug USDZ Mode. Press 'T' to export")
+            window.addEventListener("keydown", (evt) => {
+                switch (evt.key) {
+                    case "t":
+                        this.exportAsync();
+                        break;
+                }
+            });
+            if (isMobileDevice()) {
+                setTimeout(() => {
+                    this.exportAsync();
+                }, 2000)
+            }
+        }
+
+        // fall back to this object or to the scene if it's empty and doesn't have a mesh
+        if (!this.objectToExport)
+            this.objectToExport = this.gameObject;
+        if (!this.objectToExport?.children?.length && !(this.objectToExport as Mesh)?.isMesh)
+            this.objectToExport = this.context.scene;
+
+        if (this.interactive) {
+            this.extensions.push(new BehaviorExtension());
+            this.extensions.push(new AudioExtension());
+            this.extensions.push(new TextExtension());
+            this.extensions.push(new USDZUIExtension());
+        }
+    }
+
+    onEnable() {
+        const ios = isiOS()
+        const safari = isSafari();
+        if (debug || (ios && safari)) {
+            if (debug || this.allowCreateQuicklookButton)
+                this.addQuicklookButton();
+            this.lastCallback = this.quicklookCallback.bind(this);
+            this.link = ensureQuicklookLinkIsCreated(this.context);
+            this.link.addEventListener('message', this.lastCallback);
+        }
+        if (debug)
+            showBalloonMessage("USDZ Exporter enabled: " + this.name);
+
+        document.getElementById("open-in-ar")?.addEventListener("click", this.onClickedOpenInARElement);
+    }
+
+    onDisable() {
+        this.link?.removeEventListener('message', this.lastCallback);
+        const ios = isiOS()
+        const safari = isSafari();
+        if (debug || (ios && safari)) {
+            this.removeQuicklookButton();
+        }
+        if (debug)
+            showBalloonMessage("USDZ Exporter disabled: " + this.name);
+
+        document.getElementById("open-in-ar")?.removeEventListener("click", this.onClickedOpenInARElement);
+    }
+
+    private onClickedOpenInARElement = (evt) => {
+        evt.preventDefault();
+        this.exportAsync();
+    }
+
+    /**
+     * Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook.
+     * Use the various public properties of USDZExporter to customize export behaviour.
+     */
+    async exportAsync() {
+
+        let name = this.exportFileName ?? this.objectToExport?.name ?? this.name;
+        name += "-" + getFormattedDate(); // seems iOS caches the file in some cases, this ensures we always have a fresh file
+
+        if (!hasProLicense()) {
+            if (name !== "") name += "-";
+            name += "MadeWithNeedle";
+        }
+
+        if (!this.link) this.link = ensureQuicklookLinkIsCreated(this.context);
+        
+        // ability to specify a custom USDZ file to be used instead of a dynamic one
+        if (this.customUsdzFile) {
+            if (debug) console.log("Exporting custom usdz", this.customUsdzFile)
+            this.openInQuickLook(this.customUsdzFile, name);
+            return;
+        }
+
+        const blob = await this.export(this.objectToExport);
+        if (!blob) {
+            console.warn("No object to export", this);
+            return;
+        }
+
+        if (debug) console.log("USDZ generation done. Downloading as " + this.link.download);
+        
+        // TODO detect QuickLook availability:
+        // https://webkit.org/blog/8421/viewing-augmented-reality-assets-in-safari-for-ios/#:~:text=inside%20the%20anchor.-,Feature%20Detection,-To%20detect%20support
+
+
+        this.openInQuickLook(blob, name);
+    }
+
+    /**
+     * Creates an USDZ file from the current scene or assigned objectToExport and opens it in QuickLook.
+     * @returns a Promise<Blob> containing the USDZ file
+     */
+    async export(objectToExport: Object3D | undefined) : Promise<Blob | null> {
+
+        if (!objectToExport)
+            return null;
+
+        // trigger progressive textures to be loaded:
+        const renderers = GameObject.getComponentsInChildren(objectToExport, Renderer);
+        const progressiveLoading = new Array<Promise<any>>();
+        for (const rend of renderers) {
+            for (const mat of rend.sharedMaterials) {
+                if (mat) {
+                    const task = rend.loadProgressiveTextures(mat);
+                    if (task instanceof Promise)
+                        progressiveLoading.push(task);
+                }
+            }
+        }
+        if (debug) showBalloonMessage("Load textures: " + progressiveLoading.length);
+        await Promise.all(progressiveLoading);
+        if (debug) showBalloonMessage("Load textures: done");
+
+        // apply XRFlags
+        const currentXRState = XRState.Global.Mask;
+        XRState.Global.Set(XRStateFlag.AR);
+
+        // make sure we apply the AR scale
+        this.applyWebARSessionRoot();
+
+        const exporter = new ThreeUSDZExporter();
+        const extensions: any = [...this.extensions]
+
+        // collect animators and their clips
+        const animExt = new AnimationExtension(this.quickLookCompatible);
+        extensions.push(animExt);
+
+        const eventArgs = { self: this, exporter: exporter, extensions: extensions, object: objectToExport };
+        this.dispatchEvent(new CustomEvent("before-export", { detail: eventArgs }))
+
+        // Implicit registration and actions for Animators and Animation components
+        // Currently, Animators properly build PlayAnimation actions, but Animation components don't.
+        const implicitAnimationBehaviors = new Array<Object3D>();
+        if (this.autoExportAnimations) {
+            implicitAnimationBehaviors.push(...registerAnimatorsImplictly(objectToExport, animExt));
+        }
+
+        //@ts-ignore
+        exporter.debug = debug;
+
+        // sanitize anchoring types
+        if (this.anchoringType !== "plane" && this.anchoringType !== "none" && this.anchoringType !== "image" && this.anchoringType !== "face")
+            this.anchoringType = "plane";
+        if (this.planeAnchoringAlignment !== "horizontal" && this.planeAnchoringAlignment !== "vertical" && this.planeAnchoringAlignment !== "any")
+            this.planeAnchoringAlignment = "horizontal";
+
+        //@ts-ignore
+        const arraybuffer = await exporter.parse(this.objectToExport, {
+            ar: {
+                anchoring: {
+                    type: this.anchoringType,
+                },
+                planeAnchoring: {
+                    alignment: this.planeAnchoringAlignment,
+                },
+            },
+            extensions: extensions,
+            quickLookCompatible: this.quickLookCompatible,
+        });
+        const blob = new Blob([arraybuffer], { type: 'application/octet-stream' });
+
+        // cleanup – implicit animation behaviors need to be removed again
+        for (const go of implicitAnimationBehaviors) {
+            GameObject.destroy(go);
+        }
+
+        this.dispatchEvent(new CustomEvent("after-export", { detail: eventArgs }))
+
+        // restore XR flags
+        XRState.Global.Set(currentXRState);
+
+        // second file: USDA (without assets)
+        //@ts-ignore
+        // const usda = exporter.lastUsda;
+        // const blob2 = new Blob([usda], { type: 'text/plain' });
+        // this.link.download = name + ".usda";
+        // this.link.href = URL.createObjectURL(blob2);
+        // this.link.click();
+
+        return blob;
+    }
+
+    /**
+     * Opens QuickLook on iOS/iPadOS/visionOS with the given content in AR mode.
+     * @param content The URL to the .usdz or .reality file or a blob containing an USDZ file.
+     * @param name Download filename
+     */
+    openInQuickLook(content: Blob | string, name: string) {
+
+        const url = content instanceof Blob ? URL.createObjectURL(content) : content;
+
+        // see https://developer.apple.com/documentation/arkit/adding_an_apple_pay_button_or_a_custom_action_in_ar_quick_look
+        const overlay = this.buildQuicklookOverlay();
+        if (debug) console.log("QuickLook Overlay", overlay);
+        const callToAction = overlay.callToAction ? encodeURIComponent(overlay.callToAction) : "";
+        const checkoutTitle = overlay.checkoutTitle ? encodeURIComponent(overlay.checkoutTitle) : "";
+        const checkoutSubtitle = overlay.checkoutSubtitle ? encodeURIComponent(overlay.checkoutSubtitle) : "";
+        this.link.href = url + `#callToAction=${callToAction}&checkoutTitle=${checkoutTitle}&checkoutSubtitle=${checkoutSubtitle}&callToActionURL=${overlay.callToActionURL}`;
+
+        if (!this.lastCallback) {
+            this.lastCallback = this.quicklookCallback.bind(this)
+            this.link.addEventListener('message', this.lastCallback);
+        }
+
+        // open quicklook
+        this.link.download = name + ".usdz";
+        this.link.click();
+
+        // cleanup 
+        // TODO check if we can do that immediately or need to wait until the user returns
+        // if (content instanceof Blob) URL.revokeObjectURL(url);
+    }
+
+    /**
+     * Downloads the given blob as a file.
+     */
+    download(blob: Blob, name: string) {
+        USDZExporter.save(blob, name);
+    }
+
+    // Matches GltfExport.save(blob, filename)
+    private static save(blob, filename) {
+        const link = document.createElement('a');
+        link.style.display = 'none';
+        document.body.appendChild(link); // Firefox workaround, see #6594
+        if (typeof blob === "string")
+            link.href = blob;
+        else
+            link.href = URL.createObjectURL(blob);
+        link.download = filename;
+        link.click();
+        link.remove();
+        // console.log(link.href);
+        // URL.revokeObjectURL( url ); breaks Firefox...
+    }
+
+
+    private lastCallback?: any;
+
+    private quicklookCallback(event: Event) {
+        if ((event as any)?.data == '_apple_ar_quicklook_button_tapped') {
+            if (debug) showBalloonWarning("Quicklook closed via call to action button");
+            var evt = new CustomEvent("quicklook-button-tapped", { detail: this });
+            this.dispatchEvent(evt);
+            if (!evt.defaultPrevented) {
+                const url = new URLSearchParams(this.link.href);
+                if (url) {
+                    const callToActionURL = url.get("callToActionURL");
+                    if (debug)
+                        showBalloonMessage("Quicklook url: " + callToActionURL);
+                    if (callToActionURL) {
+                        if (!hasProLicense()) {
+                            console.warn("Quicklook closed: custom redirects require a Needle Engine Pro license: https://needle.tools/pricing", callToActionURL)
+                        }
+                        else {
+                            globalThis.open(callToActionURL, "_blank");
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    private buildQuicklookOverlay(): CustomBranding {
+        const obj: CustomBranding = {};
+        if (this.customBranding) Object.assign(obj, this.customBranding);
+        if (!hasProLicense()) {
+            console.log("Custom Quicklook banner text requires pro license: https://needle.tools/pricing");
+            obj.callToAction = "Close";
+            obj.checkoutTitle = "🌵 Made with Needle";
+            obj.checkoutSubtitle = "_";
+        }
+        const needsDefaultValues = obj.callToAction?.length || obj.checkoutTitle?.length || obj.checkoutSubtitle?.length;
+        if (needsDefaultValues) {
+            if (!obj.callToAction?.length)
+                obj.callToAction = "\0";
+            if (!obj.checkoutTitle?.length)
+                obj.checkoutTitle = "\0";
+            if (!obj.checkoutSubtitle?.length)
+                obj.checkoutSubtitle = "\0";
+        }
+        // Use the quicklook-overlay event to customize the overlay
+        this.dispatchEvent(new CustomEvent("quicklook-overlay", { detail: obj }));
+        return obj;
+    }
+
+
+
+
+    private _quicklookButton?: HTMLElement;
+
+    private async createQuicklookButton() {
+        if (!this.webxr) {
+            await delay(1);
+            this.webxr = GameObject.findObjectOfType(WebXR) ?? undefined;
+            if (this.webxr) {
+                if (this.webxr.VRButton) this.webxr.VRButton.parentElement?.removeChild(this.webxr.VRButton);
+                // check if we have an AR button already and re-use that
+                if (this.webxr.ARButton && this._quicklookButton !== this.webxr.ARButton) {
+                    this._quicklookButton = this.webxr.ARButton;
+                    // Hack to remove the immersiveweb link
+                    const linkInButton = this.webxr.ARButton.parentElement?.querySelector("a");
+                    if (linkInButton) {
+                        linkInButton.href = "";
+                    }
+                    this.webxr.ARButton.innerText = "Open in Quicklook";
+                    this.webxr.ARButton.disabled = false;
+                    this.webxr.ARButton.addEventListener("click", evt => {
+                        evt.preventDefault();
+                        this.exportAsync();
+                    });
+                    this.webxr.ARButton.classList.add("quicklook-ar-button");
+                    this._quicklookButtonContainer = this.webxr.ARButton.parentElement;
+                    this.dispatchEvent(new CustomEvent("created-button", { detail: this.webxr.ARButton }))
+                }
+                // create a button if WebXR didnt create one yet
+                else {
+                    this.webxr.createARButton = false;
+                    this.webxr.createVRButton = false;
+                    let container = this.context.domElement.shadowRoot!.querySelector(".webxr-buttons");
+                    if (!container) {
+                        container = document.createElement("div");
+                        container.classList.add("webxr-buttons");
+                    }
+                    const button = document.createElement("button");
+                    button.innerText = "Open in Quicklook";
+                    button.addEventListener("click", () => {
+                        this.exportAsync();
+                    });
+                    button.classList.add('webxr-ar-button');
+                    button.classList.add('webxr-button');
+                    button.classList.add("quicklook-ar-button");
+                    this._quicklookButton = button;
+                    container.appendChild(button);
+                    this._quicklookButtonContainer = container;
+                    this.dispatchEvent(new CustomEvent("created-button", { detail: button }))
+                }
+            }
+            else {
+                console.warn("Could not find WebXR component: will not create Quicklook button", Context.Current);
+            }
+        }
+    }
+
+
+    private _quicklookButtonContainer: Element | null = null;
+    private async addQuicklookButton() {
+        await this.createQuicklookButton();
+        if (this._quicklookButton && this._quicklookButtonContainer) {
+            this._quicklookButtonContainer.appendChild(this._quicklookButton);
+        }
+    }
+    private removeQuicklookButton() {
+        this._quicklookButton?.remove();
+    }
+
+    private applyWebARSessionRoot() {
+        if (!this.objectToExport) return;
+
+        // first check if the sessionroot is in the parent hierarchy
+        // if that's the case we apply the scale to the object being exported
+        let sessionRoot = GameObject.getComponentInParent(this.objectToExport, WebARSessionRoot);
+        const hasSessionRootInParentHierarchy = sessionRoot !== null && sessionRoot !== undefined;
+        // if it's not in the parent hierarchy BUT in the child hierarchy we apply it to the sessionRoot object itself
+        // that#s the case when no objectToExport is explictly assigned and the whole scene is being exported
+        if(!sessionRoot) sessionRoot = GameObject.getComponentInChildren(this.objectToExport, WebARSessionRoot);
+
+        if(debug) console.log("applyWebARSessionRoot", sessionRoot);
+
+        if (!sessionRoot) {
+            if(debug) console.warn("No WebARSessionRoot found in parent hierarchy", this.objectToExport);
+            return;
+        }
+
+        // either apply the scale to the object being exported or to the sessionRoot object itself
+        const target = hasSessionRootInParentHierarchy ? this.objectToExport : sessionRoot.gameObject;
+        const scale = 1 / sessionRoot!.arScale;
+        if (debug) console.log("AR Session Root scale", scale, target);
+        target.matrix.makeScale(scale, scale, scale);
+        if (sessionRoot.invertForward) {
+            target.matrix.multiply(new Matrix4().makeRotationY(Math.PI));
+        }
+    }
+}