Needle Engine 3.37.6-beta

Files changed (8) hide show

plugins/common/buildinfo.js +1 -8
src/engine-components/export/usdz/extensions/Animation.ts +119 -32
src/engine-components/export/usdz/utils/animationutils.ts +18 -0
src/engine-components/export/usdz/extensions/behavior/BehaviourComponents.ts +21 -12
src/engine/engine_lifecycle_functions_internal.ts +8 -4
src/engine/extensions/NEEDLE_animator_controller_model.ts +5 -0
src/engine-components/export/usdz/ThreeUSDZExporter.ts +5 -4
src/engine-components/export/usdz/USDZExporter.ts +9 -2

plugins/common/buildinfo.js CHANGED Viewed

@@ -52,14 +52,7 @@
                 hash: filehash.digest('hex'),
                 size: stats.size
             });
-            try {
-                const fullpath = `${ directory } / ${ entry.name }`;
-                const stats = fs.statSync(fullpath);
-                info.totalsize += stats.size;
-            }
-            catch {
-                //ignore
-            }
+            info.totalsize += stats.size;
         }
     }
 }

src/engine-components/export/usdz/extensions/Animation.ts CHANGED Viewed

@@ -24,13 +24,13 @@
         }
         return this._start;
     }
-    get duration(): number { return this.clip.duration; }
+    get duration(): number { return this.clip?.duration ?? TransformData.restPoseClipDuration; }
     private ext: AnimationExtension;
     private root: Object3D;
-    private clip: AnimationClip;
+    private clip: AnimationClip | null;
-    constructor(ext: AnimationExtension, root: Object3D, clip: AnimationClip) {
+    constructor(ext: AnimationExtension, root: Object3D, clip: AnimationClip | null) {
         this.ext = ext;
         this.root = root;
         this.clip = clip;
@@ -38,7 +38,7 @@
 }
 export class TransformData {
-    clip?: AnimationClip;
+    clip: AnimationClip | null;
     pos?: KeyframeTrack;
     rot?: KeyframeTrack;
     scale?: KeyframeTrack;
@@ -55,7 +55,7 @@
     static animationDurationPadding = 1 / 60;
     static restPoseClipDuration = 1 / 60;
-    constructor(root: Object3D | null, target: Object3D, clip: AnimationClip | undefined) {
+    constructor(root: Object3D | null, target: Object3D, clip: AnimationClip | null) {
         this.root = root;
         this.target = target;
         this.clip = clip;
@@ -177,10 +177,18 @@
     get extensionName(): string { return "animation" }
+    /** For each animated object, contains time/pos/rot/scale samples in the format that USD needs,
+     *  ready to be written to the .usda file.
+     */
     private dict: AnimationDict = new Map();
-    private rootTargetMap = new Map<Object3D, Object3D[]>();
+    /** Map of all roots (Animation/Animator or scene) and all targets that they animate.
+     *  We need that info so that we can ensure that each target has the same number of TransformData entries
+     *  so that switching between animations doesn't result in data "leaking" to another clip.
+     */
+    private rootTargetMap = new Map<Object3D, Array<Object3D>>();
     private rootAndClipToRegisteredAnimationMap = new Map<string, RegisteredAnimationInfo>();
-    private rootToRegisteredClipCount = new Map<Object3D, number>();
+    /** Clips registered for each root */
+    private rootToRegisteredClip = new Map<Object3D, Array<AnimationClip>>();
     private serializers: SerializeAnimation[] = [];
@@ -214,14 +222,16 @@
     getClipCount(root: Object3D): number {
         // don't count the rest pose
-        let currentCount = this.rootToRegisteredClipCount.get(root);
+        let currentCount = this.rootToRegisteredClip.get(root)?.length ?? 0;
         if (this.injectRestPoses) currentCount = currentCount ? currentCount - 1 : 0;
         return currentCount ?? 0;
     }
     // TODO why do we have this here and on TransformData? Can RegisteredAnimationInfo not cache this value?
     // TODO we probably want to assert here that this is the same value on all nodes
-    getStartTime01(root: Object3D, clip: AnimationClip) {
+    getStartTime01(root: Object3D, clip: AnimationClip | null) {
+        // This is a rest pose clip, it always starts at 0
+        if (!clip) return 0;
         const targets = this.rootTargetMap.get(root);
         if (!targets) return 0;
@@ -241,14 +251,38 @@
     }
     // The same clip could be registered for different roots. All of them need written animation data then.
-    // The same root could have multiple clips registered to it.
-    registerAnimation(root: Object3D, clip: AnimationClip): RegisteredAnimationInfo | null {
-        if (!clip || !root) return null;
+    // The same root could have multiple clips registered to it. If it does, the clips need to write
+    // independent time data, so that playing back an animation on that root doesn't result in data "leaking"/"overlapping".
+    // The structure we need is:
+    // - MyRoot
+    //   Animator
+    //     - Clip1: CubeScale (only animates MyCube), duration: 3s
+    //     - Clip2: SphereRotation (only animates MySphere), duration: 2s
+    //   - MyCube
+    //   - MySphere
+    // Results in:
+    // - MyRoot
+    //   - MyCube
+    //     - # rest clip (0..0.1)
+    //     - # CubeScale (0.2..3.2)
+    //     - # rest clip for SphereRotation (3.3..5.3)
+    //   - MySphere
+    //     - # rest clip (0..0.1)
+    //     - # rest clip for CubeScale (0.2..3.2)
+    //     - # SphereRotation (3.3..5.3)
+    /** Register an AnimationClip for a specific root object.
+     * @param root The root object that the animation clip is targeting.
+     * @param clip The animation clip to register. If null, a rest pose is registered.
+     * @returns The registered animation info, which contains the start time and duration of the clip.
+     */
+    registerAnimation(root: Object3D, clip: AnimationClip | null): RegisteredAnimationInfo | null {
+        if(!root) return null;
         if (!this.rootTargetMap.has(root)) this.rootTargetMap.set(root, []);
         // if we registered that exact pair already, just return the info
         // no proper tuples in JavaScript, but we can use the uuids for a unique key here
-        const hash = root.uuid + clip.uuid;
+        const hash = root.uuid + (clip?.uuid ?? "-rest");
         if (this.rootAndClipToRegisteredAnimationMap.has(hash)) {
             return this.rootAndClipToRegisteredAnimationMap.get(hash)!;
         }
@@ -261,11 +295,11 @@
         // in animation 0 and some data overrides each other incorrectly.
         // When we don't inject a rest clip, we start at 0.
         const startIndex = this.injectRestPoses ? 1 : 0;
-        const currentCount = this.rootToRegisteredClipCount.get(root) ?? startIndex;
+        const currentCount = (this.rootToRegisteredClip.get(root)?.length ?? 0) + startIndex;
         const targets = this.rootTargetMap.get(root);
         const unregisteredNodesForThisClip = new Set(targets);
-        if (clip.tracks) {
+        if (clip && clip.tracks) {
         for (const track of clip.tracks) {
             const parsedPath = PropertyBinding.parseTrackName(track.name);
             const animationTarget = PropertyBinding.findNode(root, parsedPath.nodeName);
@@ -298,19 +332,13 @@
             // TODO most likely doesn't work for overlapping clips (clips where a root is a child of another root)
             // TODO in that case we may need to pad globally, not per root
-            // check if we have a rest pose already
+            // Inject a rest pose if we don't have it already
             if (this.injectRestPoses && !transformDataForTarget[0]) {
-                const model = new TransformData(null, animationTarget, undefined);
-                transformDataForTarget[0] = model;
+                transformDataForTarget[0] = new TransformData(null, animationTarget, null);
             }
             // These all need to be at the same index, otherwise our padding went wrong
             let model = transformDataForTarget[currentCount];
-            // validation (for debugging)
-            // let modelFoundByClip = transformDataForTarget.find(x => x.clip === clip);
-            // let modelFoundByClipIndex = modelFoundByClip ? transformDataForTarget.indexOf(modelFoundByClip) : -1;
-            // console.assert(model === modelFoundByClip, "We should find the same model by index and by clip; " + currentCount + " !== " + modelFoundByClipIndex);
             if (!model) {
                 model = new TransformData(root, animationTarget, clip);
                 transformDataForTarget[currentCount] = model;
@@ -322,14 +350,17 @@
         }
         }
+        if (debug) console.log("Unregistered nodes for this clip", unregisteredNodesForThisClip, "clip", clip, "at slot", currentCount, "for root", root, "targets", targets)
         // add padding for nodes that are not animated by this clip
         for (const target of unregisteredNodesForThisClip) {
             const transformDataForTarget = this.dict.get(target);
             if (!transformDataForTarget) continue;
-            // inject rest pose
+            // Inject rest pose if these nodes don't have it yet for some reason – this is likely a bug
             if (this.injectRestPoses && !transformDataForTarget[0]) {
-                const model = new TransformData(null, target, undefined);
+                console.warn("Adding rest pose for ", target, clip, "at slot", currentCount, "This is likely a bug, should have been added earlier.");
+                const model = new TransformData(null, target, null);
                 transformDataForTarget[0] = model;
             }
@@ -345,7 +376,13 @@
         // This doesnt work if we have clips animating multiple objects
         const info = new RegisteredAnimationInfo(this, root, clip);
         this.rootAndClipToRegisteredAnimationMap.set(hash, info);
-        this.rootToRegisteredClipCount.set(root, currentCount + 1);
+        if (debug) console.log({root, clip, info});
+        if (clip) {
+            const registered = this.rootToRegisteredClip.get(root);
+            if (!registered) this.rootToRegisteredClip.set(root, [clip]);
+            else registered.push(clip);
+        }
         return info;
     }
@@ -354,6 +391,49 @@
     }
     onAfterBuildDocument(_context: any) {
+        // Validation: go through all roots, check if their data and lengths are consistent.
+        // There are some cases that we can patch up here, especially if non-overlapping animations have resulted in "holes"
+        // in TransformData where only now we know what the matching animation clip actually is.
+        if (debug) console.log("Animation data", { dict: this.dict, rootTargetMap: this.rootTargetMap, rootToRegisteredClip: this.rootToRegisteredClip});
+        for (const root of this.rootTargetMap.keys()) {
+            const targets = this.rootTargetMap.get(root);
+            if (!targets) continue;
+            // The TransformData[] arrays here should have the same length, and the same durations
+            let arrayLength: number | undefined = undefined;
+            const durations: Array<number | undefined> = [];
+            for (const target of targets) {
+                const datas = this.dict.get(target);
+                if (!datas) {
+                    console.error("No data found for target on USDZ export – please report a bug!", target);
+                    continue;
+                }
+                if (arrayLength === undefined) arrayLength = datas?.length;
+                if (arrayLength !== datas?.length) console.error("Different array lengths for targets – please report a bug!", datas);
+                for (let i = 0; i < datas.length; i++) {
+                    let data = datas[i];
+                    if (!data) {
+                        // If we don't have TransformData for this object yet, we're emitting a rest pose with the duration
+                        // of the matching clip that was registered for this root.
+                        const index = i - (this.injectRestPoses ? 1 : 0);
+                        datas[i] = new TransformData(null, target, this.rootToRegisteredClip.get(root)![index]);
+                        data = datas[i];
+                    }
+                    if (!durations[i]) durations[i] = data.getDuration();
+                    else if (durations[i] !== data.getDuration()) {
+                        console.error("Different durations for targets – please report a bug!", datas);
+                        continue;
+                    }
+                }
+            }
+        }
         for (const ser of this.serializers) {
             const parent = ser.model?.parent;
             const isEmptyParent = parent?.isDynamic === true;
@@ -567,7 +647,7 @@
                     // if we don't have animation data, create an empty one –
                     // it will automatically map to the rest pose, albeit inefficiently
                     else
-                        emptyTransformData = new TransformData(null, bone, undefined);
+                        emptyTransformData = new TransformData(null, bone, null);
                     for (let i = 0; i < count; i++) {
                         const transformData = boneEntryInData ? boneEntryInData[i] : emptyTransformData!;
@@ -751,7 +831,7 @@
         if (arr0) {
             for (let i = 0; i < arr0.length; i++) {
                 if (arr0[i] !== undefined) continue;
-                arr0[i] = new TransformData(null, this.object, undefined);
+                arr0[i] = new TransformData(null, this.object, null);
             }
         }
@@ -802,6 +882,11 @@
             currentStartTime += arr[i].getDuration() + TransformData.animationDurationPadding;
         }
+        const formatter = Intl.NumberFormat("en", {
+            maximumFractionDigits: 2,
+            minimumFractionDigits: 0,
+        });
         for (let i = 0; i < arr.length; i++) {
             const transformData = arr[i];
             if (!transformData) continue;
@@ -814,17 +899,19 @@
                     continue;
                 }
-                if (debug) {
+                // if (debug) // writing out the clip name and duration is useful even when not debugging
+                {
                     const clipName = transformData.clip?.name ?? "rest";
                     const duration = transformData.getDuration();
-                    console.log("Write .timeSamples:", clipName, startTime, duration, arr);
-                    writer.appendLine("# " + clipName + ": start=" + (startTime * transformData.frameRate).toFixed(3) + ", length=" + (duration * transformData.frameRate).toFixed(3) + ", frames=" + transformData.getFrames());
+                    if (debug) console.log("Write .timeSamples:", clipName, startTime, duration, arr);
+                    writer.appendLine("# " + clipName + ": start=" + formatter.format(startTime * transformData.frameRate) + ", length=" + formatter.format(duration * transformData.frameRate) + ", frames=" + transformData.getFrames());
                 }
                 for (const { time, translation, rotation, scale } of transformData.getValues(timesArray)) {
                     composedTransform.compose(translation, rotation, scale);
-                    const line = `${(startTime + time) * transformData.frameRate}: ${buildMatrix(composedTransform)},`;
+                    const timeStr = formatter.format((startTime + time) * transformData.frameRate);
+                    const line = `${timeStr}: ${buildMatrix(composedTransform)},`;
                     writer.appendLine(line);
                 }
             }

src/engine-components/export/usdz/utils/animationutils.ts CHANGED Viewed

@@ -26,6 +26,7 @@
     const animationClips: { root: Object3D, clips: AnimationClip[] }[] = [];
     const animators = GameObject.getComponentsInChildren(root, Animator);
     const animationComponents = GameObject.getComponentsInChildren(root, Animation);
+    const animatorsWithPlayAtStart = new Array<Animator | Animation>();
     const constructedObjects = new Array<Object3D>();
@@ -39,6 +40,13 @@
             if (!activeState) continue;
             if (!activeState.motion || !activeState.motion.clip) continue;
             if (activeState.motion.clip.tracks?.length < 1) continue;
+            // We could skip if the current state has already ended playing
+            // but there's an edge case where we'd do this exactly in a transition,
+            // and also it's a bit weird when someone has watched the animation in the browser already
+            // and then it doesn't play in AR, so this is disabled for now.
+            // if (animator.getCurrentStateInfo()?.normalizedTime == 1) continue;
+            if (animatorsWithPlayAtStart.includes(animator)) continue;
             // Create a PlayAnimationOnClick component that will play the animation on start
             // This is a bit hacky right now (we're using the internal "start" trigger)
@@ -50,6 +58,8 @@
             const go = new Object3D();
             GameObject.addComponent(go, newComponent);
             constructedObjects.push(go);
+            animatorsWithPlayAtStart.push(animator);
             // the behaviour can be anywhere in the hierarchy
             root.add(go);
@@ -85,6 +95,7 @@
         for (const animationComponent of animationComponents) {
             if (!animationComponent || !animationComponent.clip ||!animationComponent.enabled) continue;
             if (!animationComponent.playAutomatically) continue;
+            if (animatorsWithPlayAtStart.includes(animationComponent)) continue;
             // Create a PlayAnimationOnClick component that will play the animation on start
             // This is a bit hacky right now (we're using the internal "start" trigger)
@@ -97,6 +108,8 @@
             GameObject.addComponent(go, newComponent);
             constructedObjects.push(go);
+            animatorsWithPlayAtStart.push(animationComponent);
             // the behaviour can be anywhere in the hierarchy
             root.add(go);
         }
@@ -130,6 +143,8 @@
 export function registerAudioSourcesImplictly(root: Object3D, _ext: AudioExtension): Array<Object3D> {
     const audioSources = GameObject.getComponentsInChildren(root, AudioSource);
     const playAudioOnClicks = GameObject.getComponentsInChildren(root, PlayAudioOnClick);
+    const audioWithPlayAtStart = new Array<AudioSource>();
     const constructedObjects = new Array<Object3D>();
@@ -144,6 +159,7 @@
     for (const audioSource of audioSources) {
         if (!audioSource || !audioSource.clip) continue;
         if (audioSource.volume <= 0) continue;
+        if (audioWithPlayAtStart.includes(audioSource)) continue;
         const newComponent = new PlayAudioOnClick();
         newComponent.target = audioSource;
@@ -153,6 +169,8 @@
         console.log("implicit PlayAudioOnStart", go, newComponent);
         constructedObjects.push(go);
+        audioWithPlayAtStart.push(audioSource);
         root.add(go);
     }

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

@@ -12,7 +12,7 @@
 import { Behaviour, GameObject } from "../../../../Component.js";
 import type { IPointerClickHandler, PointerEventData } from "../../../../ui/PointerEvents.js";
 import { ObjectRaycaster,Raycaster } from "../../../../ui/Raycaster.js";
-import { USDDocument, USDObject, USDZExporterContext } from "../../ThreeUSDZExporter.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";
@@ -297,6 +297,10 @@
         );
     }
+    private static getMaterialName(material: Material) {
+        return makeNameSafeForUSD(material.name || 'Material') + "_" + material.id;
+    }
     static variantSwitchIndex: number = 0;
     private createVariants() {
         if (!this.variantMaterial) return null;
@@ -304,8 +308,8 @@
         const variantModels: USDObject[] = [];
         for (const target of this.targetModels) {
             const variant = target.clone();
-            variant.name += " variant_" + this.variantMaterial.name + "_" + ChangeMaterialOnClick.variantSwitchIndex++;
-            variant.name = variant.name.replace(/\s/g, "_");
+            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.matrix = target.matrix;
@@ -811,14 +815,14 @@
             if (model.uuid === this.target?.uuid) {
                 const sequence = ActionBuilder.sequence();
-                if (this.animationSequence !== undefined)
+                if (this.animationSequence && this.animationSequence.length > 0)
                 {
                     for (const anim of this.animationSequence) {
                         sequence.addAction(getOrCacheAction(model, anim));
                     }
                 }
-                if (this.animationLoopAfterSequence !== undefined) {
+                if (this.animationLoopAfterSequence && this.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 this.animationLoopAfterSequence) {
@@ -829,7 +833,7 @@
                         sequence.addAction(loopSequence);
                 }
-                const playAnimationOnTap = new BehaviorModel("tap " + this.name + " for " + this.stateName + " on " + this.target?.name,
+                const playAnimationOnTap = new BehaviorModel("_tap_" + this.name + "_toPlayClip_" + this.stateName + "_on_" + this.target?.name,
                     this.trigger == "tap" ? TriggerBuilder.tapTrigger(this.selfModel) : TriggerBuilder.sceneStartTrigger(),
                     sequence
                 );
@@ -847,7 +851,7 @@
         this.stateAnimationModel = model;
-        if (this.animation && this.animation.clip) {
+        if (this.animation) {
             this.animationSequence = new Array<RegisteredAnimationInfo>();
             this.animationLoopAfterSequence = new Array<RegisteredAnimationInfo>();
             const anim = ext.registerAnimation(this.target, this.animation.clip);
@@ -920,6 +924,15 @@
             }
         }
+        // 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)) {
+            this.animationSequence = new Array<RegisteredAnimationInfo>();
+            const anim = ext.registerAnimation(this.target, null);
+            if (anim) this.animationSequence.push(anim);
+            return;
+        }
         // 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);
@@ -932,11 +945,7 @@
         const addStateToSequence = (state: State, sequence: Array<RegisteredAnimationInfo>) => {
             if (!this.target) return;
-            if (!state.motion?.clip) {
-                console.warn("No clip found for state " + state.name + " on " + this.animator?.name + ", can't export animation data");
-                return;
-            }
-            const anim = ext.registerAnimation(this.target, state.motion.clip);
+            const anim = ext.registerAnimation(this.target, state.motion.clip ?? null);
             if (anim) sequence.push(anim);
             else console.warn("Couldn't register animation for state " + state.name + " on " + this.animator?.name);
         };

src/engine/engine_lifecycle_functions_internal.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import { type Context,FrameEvent } from "./engine_context.js";
+import { type Context, FrameEvent } from "./engine_context.js";
 import type { ContextEvent } from "./engine_context_registry.js";
 import { safeInvoke } from "./engine_generic_utils.js";
@@ -45,10 +45,14 @@
     }
 }
+const bufferArray = new Array<LifecycleMethod>();
 function invoke(ctx: Context, methods: Array<LifecycleMethod>) {
-    for (let i = methods.length - 1; i >= 0; i--) {
-        const method = methods[i];
+    bufferArray.length = 0;
+    for (let i = 0; i < methods.length; i++) {
+        bufferArray.push(methods[i]);
+    }
+    for (let i = 0; i < bufferArray.length; i++) {
+        const method = bufferArray[i];
         safeInvoke(method, ctx);
     }
 }

src/engine/extensions/NEEDLE_animator_controller_model.ts CHANGED Viewed

@@ -75,6 +75,10 @@
     readonly speed: number;
     /** The current action playing. It can be used to modify the action */
     readonly action: AnimationAction | null;
+    /**
+     * If the state has any transitions
+     */
+    readonly hasTransitions: boolean;
     constructor(state: State, normalizedTime: number, length: number, speed: number) {
         this.name = state.name;
@@ -83,6 +87,7 @@
         this.length = length;
         this.speed = speed;
         this.action = state.motion.action || null;
+        this.hasTransitions = state.transitions?.length > 0 || false;
     }
 }

src/engine-components/export/usdz/ThreeUSDZExporter.ts CHANGED Viewed

@@ -1152,10 +1152,11 @@
 	return makeNameSafe(bone.name || 'bone_' + bone.uuid);
 }
-function getGeometryName(geometry: BufferGeometry, fallbackName: string) {
-	// TODO using object names here breaks instancing...
-	// Likely need to remove fallbackName again
-	return makeNameSafe(geometry.name || fallbackName || 'Geometry') + "_" + geometry.id;
+function getGeometryName(geometry: BufferGeometry, _fallbackName: string) {
+	// Using object names here breaks instancing...
+	// So we removed fallbackName again. Downside: geometries don't have nice names...
+	// A better workaround would be that we actually name them on glTF import (so the geometry has a name, not the object)
+	return makeNameSafe(geometry.name || 'Geometry') + "_" + geometry.id;
 }
 function getMaterialName(material: Material) {

src/engine-components/export/usdz/USDZExporter.ts CHANGED Viewed

@@ -222,9 +222,14 @@
             return null;
         }
+        if (!this.objectToExport) {
+            console.warn("No object to export", this);
+            return null;
+        }
         const blob = await this.export(this.objectToExport);
         if (!blob) {
-            console.warn("No object to export", this);
+            console.error("USDZ generation failed. Please report a bug", this);
             return null;
         }
@@ -255,6 +260,7 @@
         if (taskForThisObject) {
             return taskForThisObject;
         }
         // start the export
         const task = this.internalExport(objectToExport);
         // store the task
@@ -263,8 +269,9 @@
             return task.then((blob) => {
                 this._currentExportTasks.delete(objectToExport);
                 return blob;
-            }).catch((_) => {
+            }).catch((e) => {
                 this._currentExportTasks.delete(objectToExport);
+                console.error("Error during USDZ export – please report a bug!", e);
                 return null;
             });
         }