@needle-tools/engine 4.8.6-next.f3ce848 → 4.8.7-next.1715881

package/src/engine-components/DropListener.ts

@@ -143,13 +143,6 @@ const blobKeyName = "blob";
  */
 export class DropListener extends Behaviour {
 
-    /**
-     * When enabled, the DropListener will automatically synchronize dropped files to other connected clients.
-     * When a file is dropped locally, it will be uploaded to blob storage and the URL will be shared with other clients.
-     */
-    @serializable()
-    useNetworking: boolean = true;
-
     /**
      * When assigned, the DropListener will only accept files that are dropped on this specific object.
      * This allows creating designated drop zones in your scene.
@@ -159,7 +152,10 @@ export class DropListener extends Behaviour {
 
     /**
      * When enabled, dropped objects will be automatically scaled to fit within the volume defined by fitVolumeSize.
-     * Useful for ensuring dropped models appear at an appropriate scale.
+     * Useful for ensuring dropped models appear at an appropriate scale.   
+     * 
+     * **Tip**: Use the handy `fitObjectIntoVolume` function (`import { fitObjectIntoVolume } from "@needle-tools/engine"`) for custom fitting needs.  
+     * 
      * @default false
      */
     @serializable()
@@ -180,6 +176,14 @@ export class DropListener extends Behaviour {
     @serializable()
     placeAtHitPosition: boolean = true;
 
+    /**
+     * When enabled, the DropListener will automatically synchronize dropped files to other connected clients.
+     * When a file is dropped locally, it will be uploaded to blob storage and the URL will be shared with other clients.
+     * @default false
+     */
+    @serializable()
+    useNetworking: boolean = false;
+
     /**
      * Event list that gets invoked after a file has been successfully added to the scene.
      * Receives {@link DropListenerOnDropArguments} containing the added object and related information.
@@ -193,6 +197,27 @@ export class DropListener extends Behaviour {
     @serializable(EventList)
     onDropped: EventList<DropListenerOnDropArguments> = new EventList();
 
+    /**
+     * Loads a file from the given URL and adds it to the scene.
+     * @returns A promise that resolves to the loaded object or null if loading failed.
+     */
+    loadFromURL(url: string, data?: { point?: Vec3, size?: Vec3 }): Promise<Object3D | null> {
+        return this.addFromUrl(url, { screenposition: new Vector2(), point: data?.point, size: data?.size, }, false);
+    }
+
+    /**
+     * Forgets all previously added objects.     
+     * The droplistener will then not be able to remove previously added objects.
+     */
+    forgetObjects() {
+        this.removePreviouslyAddedObjects(false);
+    }
+
+
+
+
+    // #region internals
+
     /** @internal */
     onEnable(): void {
         this.context.renderer.domElement.addEventListener("dragover", this.onDrag);
@@ -208,21 +233,6 @@ export class DropListener extends Behaviour {
         this.context.connection.stopListen("droplistener", this.onNetworkEvent);
     }
 
-    /**
-     * Loads a file from the given URL and adds it to the scene.
-     */
-    loadFromURL(url: string, data?: { point?: Vec3, size?: Vec3 }) {
-        this.addFromUrl(url, { screenposition: new Vector2(), point: data?.point, size: data?.size, }, true);
-    }
-
-    /**
-     * Forgets all previously added objects.     
-     * The droplistener will then not be able to remove previously added objects.
-     */
-    forgetObjects() {
-        this.removePreviouslyAddedObjects(false);
-    }
-
     /**
      * Handles network events received from other clients containing information about dropped objects
      * @param evt Network event data containing object information, position, and content URL
@@ -326,7 +336,7 @@ export class DropListener extends Behaviour {
             }
         }
         if (files.length > 0) {
-            await this.addDroppedFiles(files, ctx);
+            await this.addFromFiles(files, ctx);
         }
     }
 
@@ -359,6 +369,7 @@ export class DropListener extends Behaviour {
             // Ignore dropped images
             const lowercaseUrl = url.toLowerCase();
             if (lowercaseUrl.endsWith(".hdr") || lowercaseUrl.endsWith(".hdri") || lowercaseUrl.endsWith(".exr") || lowercaseUrl.endsWith(".png") || lowercaseUrl.endsWith(".jpg") || lowercaseUrl.endsWith(".jpeg")) {
+                console.warn(`Fileformat is not supported: ${lowercaseUrl}`);
                 return null;
             }
 
@@ -374,7 +385,7 @@ export class DropListener extends Behaviour {
             });
             if (res && this._addedObjects.length <= 0) {
                 ctx.url = url;
-                const obj = this.addObject(res, ctx, isRemote);
+                const obj = this.onObjectLoaded(res, ctx, isRemote);
                 return obj;
             }
         }
@@ -393,7 +404,7 @@ export class DropListener extends Behaviour {
      * @param fileList Array of dropped files
      * @param ctx Context information about where the drop occurred
      */
-    private async addDroppedFiles(fileList: Array<File>, ctx: DropContext) {
+    private async addFromFiles(fileList: Array<File>, ctx: DropContext) {
         if (debug) console.log("Add files", fileList)
         if (!Array.isArray(fileList)) return;
         if (!fileList.length) return;
@@ -427,7 +438,7 @@ export class DropListener extends Behaviour {
             if (res) {
                 this.dispatchEvent(new CustomEvent(DropListenerEvents.FileDropped, { detail: file }));
                 ctx.file = file;
-                const obj = this.addObject(res, ctx, false);
+                const obj = this.onObjectLoaded(res, ctx, false);
 
                 // handle uploading the dropped object and networking the event
                 if (obj && this.context.connection.isConnected && this.useNetworking) {
@@ -478,7 +489,7 @@ export class DropListener extends Behaviour {
      * @param isRemote Whether this object was shared from a remote client
      * @returns The added object or null if adding failed
      */
-    private addObject(data: { model: Model, contentMD5: string }, ctx: DropContext, isRemote: boolean): Object3D | null {
+    private onObjectLoaded(data: { model: Model, contentMD5: string }, ctx: DropContext, isRemote: boolean): Object3D | null {
 
         const { model, contentMD5 } = data;
 
@@ -522,9 +533,7 @@ export class DropListener extends Behaviour {
             }
         }
 
-        AnimationUtils.assignAnimationsFromFile(model, {
-            createAnimationComponent: obj => addComponent(obj, Animation)
-        });
+        AnimationUtils.autoplayAnimations(model);
 
         const evt = new DropListenerAddedEvent({
             sender: this,

package/src/engine-components/LookAtConstraint.ts

@@ -1,4 +1,4 @@
-import { Object3D } from "three";
+import { Object3D, Vector3 } from "three";
 
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Behaviour } from "./Component.js";
@@ -23,4 +23,12 @@ export class LookAtConstraint extends Behaviour {
      */
     @serializable(Object3D)
     sources: Object3D[] = [];
+
+    /**
+     * Set the position of the constraint.
+     */
+    setConstraintPosition(worldPosition: Vector3) {
+        const source = this.sources[0];
+        if (source) source.worldPosition = worldPosition;
+    }
 }

package/src/engine-components/OrbitControls.ts

@@ -649,12 +649,12 @@ export class OrbitControls extends Behaviour implements ICameraController {
             if (this._lookTargetLerpActive) {
                 this._lookTargetLerp01 += this.context.time.deltaTime / this._lookTargetLerpDuration;
                 if (this._lookTargetLerp01 >= 1) {
-                    this._controls.target.copy(this._lookTargetEndPosition);
+                    this.lerpLookTarget(this._lookTargetEndPosition, this._lookTargetEndPosition, 1);
                     this._lookTargetLerpActive = false;
                     this.dispatchEvent(new CameraTargetReachedEvent(this, "lookat"));
                 } else {
                     const t = Mathf.easeInOutCubic(this._lookTargetLerp01);
-                    this._controls.target.lerpVectors(this._lookTargetStartPosition, this._lookTargetEndPosition, t);
+                    this.lerpLookTarget(this._lookTargetStartPosition, this._lookTargetEndPosition, t);
                 }
             }
 
@@ -729,7 +729,9 @@ export class OrbitControls extends Behaviour implements ICameraController {
 
             // this._controls.zoomToCursor = this.zoomToCursor;
             if (!this.context.isInXR) {
-                if (!freeCam && this.lookAtConstraint?.locked) this.setLookTargetFromConstraint(0, this.lookAtConstraint01);
+                if (!freeCam && this.lookAtConstraint?.locked && !this._lookTargetLerpActive) {
+                    this.setLookTargetFromConstraint(0, this.lookAtConstraint01);
+                }
                 this._controls.update(this.context.time.deltaTime);
 
                 if (debug) {
@@ -910,7 +912,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
         }
 
         if (immediateOrDuration === true) {
-            this._controls.target.copy(this._lookTargetEndPosition);
+            this.lerpLookTarget(this._lookTargetEndPosition, this._lookTargetEndPosition, 1);
         }
         else {
             this._lookTargetLerpActive = true;
@@ -941,20 +943,18 @@ export class OrbitControls extends Behaviour implements ICameraController {
             const target = sources[index];
             if (target) {
                 target.getWorldPosition(this._lookTargetEndPosition);
-                this.lerpLookTarget(this._lookTargetEndPosition, t);
+                this.lerpLookTarget(this._controls.target, this._lookTargetEndPosition, t);
                 return true;
             }
         }
         return false;
     }
 
-    /** @deprecated use `controls.target.lerp(position, delta)` */
-    public lerpTarget(position: Vector3, delta: number) { return this.lerpLookTarget(position, delta); }
-
-    private lerpLookTarget(position: Vector3, delta: number) {
+    private lerpLookTarget(start: Vector3, position: Vector3, t: number) {
         if (!this._controls) return;
-        if (delta >= 1) this._controls.target.copy(position);
-        else this._controls.target.lerp(position, delta);
+        if (t >= 1) this._controls.target.copy(position);
+        else this._controls.target.lerpVectors(start, position, t);
+        if (this.lookAtConstraint) this.lookAtConstraint.setConstraintPosition(this._controls.target);
     }
 
     private setTargetFromRaycast(ray?: Ray, immediateOrDuration: number | boolean = false): boolean {
@@ -1063,7 +1063,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
             return;
         }
 
-        const verticalFov = options.fov || camera.fov;
+        const verticalFov = fov;
         const horizontalFov = 2 * Math.atan(Math.tan(verticalFov * Math.PI / 360 / 2) * camera.aspect) / Math.PI * 360;
         const fitHeightDistance = size.y / (2 * Math.atan(Math.PI * verticalFov / 360));
         const fitWidthDistance = size.x / (2 * Math.atan(Math.PI * horizontalFov / 360));
@@ -1161,16 +1161,19 @@ declare type FitCameraOptions = {
      * The objects to fit the camera to. If not provided the scene children will be used
      */
     objects?: Object3D[] | Object3D;
-    /** Fit offset: A factor to multiply the distance to the objects by
-     * @default 1.1
-     */
-    fitOffset?: number,
     /** If true the camera will move immediately to the new position, otherwise it will lerp 
      * @default false
      */
     immediate?: boolean,
+
     /** If set to "y" the camera will be centered in the y axis */
     centerCamera?: "none" | "y",
     cameraNearFar?: "keep" | "auto",
+
     fov?: number,
+
+    /** Fit offset: A factor to multiply the distance to the objects by
+     * @default 1.1
+     */
+    fitOffset?: number,
 }

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

@@ -21,5 +21,5 @@ export interface IUSDExporterExtension {
     onAfterBuildDocument?(context: USDZExporterContext);
     onExportObject?(object: Object3D, model: USDObject, context: USDZExporterContext);
     onAfterSerialize?(context: USDZExporterContext);
-    onAfterHierarchy?(context: USDZExporterContext, writer: USDWriter);
+    onAfterHierarchy?(context: USDZExporterContext, writer: USDWriter) : void | Promise<void>;
 }

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

@@ -1082,7 +1082,7 @@ async function parseDocument( context: USDZExporterContext, afterStageRoot: () =
 	Progress.end("export-usdz-xforms");
 
 	Progress.report("export-usdz", "invoke onAfterHierarchy");
-	invokeAll( context, 'onAfterHierarchy', writer );
+	await invokeAll( context, 'onAfterHierarchy', writer );
 
 	writer.closeBlock();
 	writer.closeBlock();

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

@@ -1,5 +1,5 @@
 import { NEEDLE_progressive } from "@needle-tools/gltf-progressive";
-import { Euler, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
+import { Euler, EventDispatcher, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "three";
 
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
 import { hasProLicense } from "../../../engine/engine_license.js";
@@ -29,6 +29,7 @@ import { USDZUIExtension } from "./extensions/USDZUI.js";
 import { USDZExporter as ThreeUSDZExporter } from "./ThreeUSDZExporter.js";
 import { disableObjectsAtStart, registerAnimatorsImplictly, registerAudioSourcesImplictly } from "./utils/animationutils.js";
 import { ensureQuicklookLinkIsCreated } from "./utils/quicklook.js";
+import { EventList } from "../../EventList.js";
 
 const debug = getParam("debugusdz");
 const debugUsdzPruning = getParam("debugusdzpruning");
@@ -71,6 +72,9 @@ export class CustomBranding {
  */
 export class USDZExporter extends Behaviour {
 
+    static readonly beforeExport = new EventList<{ exporter: USDZExporter }>();
+    static readonly afterExport = new EventList<{ exporter: USDZExporter }>();
+
     /**
      * Assign the object to export as USDZ file. If undefined or null, the whole scene will be exported.
      */
@@ -210,7 +214,7 @@ export class USDZExporter extends Behaviour {
      * 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 exportAndOpen() : Promise<Blob | null> {
+    async exportAndOpen(): Promise<Blob | null> {
 
         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
@@ -221,7 +225,7 @@ export class USDZExporter extends Behaviour {
         }
 
         if (!this.link) this.link = ensureQuicklookLinkIsCreated(this.context, DeviceUtilities.supportsQuickLookAR());
-        
+
         // 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)
@@ -234,14 +238,19 @@ export class USDZExporter extends Behaviour {
             return null;
         }
 
-        const blob = await this.export(this.objectToExport);
+        USDZExporter.beforeExport.invoke({ exporter: this });
+        const blob = await this.export(this.objectToExport)
+            .finally(() => {
+                USDZExporter.afterExport.invoke({ exporter: this });
+            });
+
         if (!blob) {
             console.error("USDZ generation failed. Please report a bug", this);
             return null;
         }
 
         if (debug) console.log("USDZ generation done. Downloading as " + name);
-        
+
         // TODO Potentially we have to detect QuickLook availability here,
         // and download the file instead. But browsers keep changing how they deal with non-user-initiated downloads...
         // https://webkit.org/blog/8421/viewing-augmented-reality-assets-in-safari-for-ios/#:~:text=inside%20the%20anchor.-,Feature%20Detection,-To%20detect%20support
@@ -364,7 +373,7 @@ export class USDZExporter extends Behaviour {
         if (this.interactive) {
             defaultExtensions.push(new BehaviorExtension());
             defaultExtensions.push(new AudioExtension());
-            
+
             // If physics are enabled, and there are any Rigidbody components in the scene,
             // add the PhysicsExtension to the default extensions.
             if (globalThis["NEEDLE_USE_RAPIER"]) {
@@ -632,13 +641,13 @@ export class USDZExporter extends Behaviour {
     private _rootPositionBeforeExport: Vector3 = new Vector3();
     private _rootRotationBeforeExport: Quaternion = new Quaternion();
     private _rootScaleBeforeExport: Vector3 = new Vector3();
-    
-    getARScaleAndTarget(): { scale: number, _invertForward: boolean, target: Object3D, sessionRoot: Object3D | null} {
-        if (!this.objectToExport) return { scale: 1, _invertForward: false, target: this.gameObject, sessionRoot: null};
+
+    getARScaleAndTarget(): { scale: number, _invertForward: boolean, target: Object3D, sessionRoot: Object3D | null } {
+        if (!this.objectToExport) return { scale: 1, _invertForward: false, target: this.gameObject, sessionRoot: null };
 
         const xr = GameObject.findObjectOfType(WebXR);
         let sessionRoot = GameObject.getComponentInParent(this.objectToExport, WebARSessionRoot);
-        if(!sessionRoot) sessionRoot = GameObject.getComponentInChildren(this.objectToExport, WebARSessionRoot);
+        if (!sessionRoot) sessionRoot = GameObject.getComponentInChildren(this.objectToExport, WebARSessionRoot);
 
         let arScale = 1;
         let _invertForward = false;
@@ -653,7 +662,7 @@ export class USDZExporter extends Behaviour {
             // eslint-disable-next-line deprecation/deprecation
             _invertForward = sessionRoot.invertForward;
         }
-        
+
         const scale = 1 / arScale;
         const result = { scale, _invertForward, target, sessionRoot: sessionRoot?.gameObject ?? null };
         return result;
@@ -699,7 +708,7 @@ export class USDZExporter extends Behaviour {
     private createQuicklookButton() {
         const buttoncontainer = WebXRButtonFactory.getOrCreate();
         const button = buttoncontainer.createQuicklookButton();
-        if(!button.parentNode) this.context.menu.appendChild(button);
+        if (!button.parentNode) this.context.menu.appendChild(button);
         return button;
     }
 }