@needle-tools/engine 4.8.7 → 4.8.8-next.4b53212

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) {
@@ -887,6 +889,8 @@ export class OrbitControls extends Behaviour implements ICameraController {
             }
             else this._fovLerpDuration = this.targetLerpDuration;
         }
+
+        // if (this.context.mainCameraComponent) this.context.mainCameraComponent.fieldOfView = fov;
     }
 
     /** Moves the camera look-at target to a position smoothly. 
@@ -910,7 +914,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 +945,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 {
@@ -984,10 +986,11 @@ export class OrbitControls extends Behaviour implements ICameraController {
     */
     fitCamera(options?: FitCameraOptions);
     fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<FitCameraOptions, "objects">);
-    fitCamera(objectsOrOptions?: Object3D | Array<Object3D> | FitCameraOptions, options?: FitCameraOptions) {
+    fitCamera(objectsOrOptions?: Object3D | Array<Object3D> | FitCameraOptions, options?: FitCameraOptions): void {
 
         if (this.context.isInXR) {
             // camera fitting in XR is not supported
+            console.warn('[OrbitControls] Can not fit camera while XR session is active');
             return;
         }
 
@@ -1032,7 +1035,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
             return;
         }
         if (!options) options = {}
-        const { immediate = false, centerCamera = "y", cameraNearFar = "auto", fitOffset = 1.1, fov = camera?.fov } = options;
+        const { immediate = false, centerCamera, cameraNearFar = "auto", fitOffset = 1.1, fov = camera?.fov } = options;
         const size = new Vector3();
         const center = new Vector3();
         // TODO would be much better to calculate the bounds in camera space instead of world space - 
@@ -1041,15 +1044,13 @@ export class OrbitControls extends Behaviour implements ICameraController {
         // and thus we're just getting some maximum that will work for sure.
         const box = getBoundingBox(objects, undefined, this._camera?.threeCamera?.layers);
         const boxCopy = box.clone();
-
-        camera.updateMatrixWorld();
-        camera.updateProjectionMatrix();
         box.getCenter(center);
 
         const box_size = new Vector3();
         box.getSize(box_size);
 
         // project this box into camera space
+        camera.updateMatrixWorld();
         box.applyMatrix4(camera.matrixWorldInverse);
 
         box.getSize(size);
@@ -1063,7 +1064,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));
@@ -1078,9 +1079,18 @@ export class OrbitControls extends Behaviour implements ICameraController {
         this.minZoom = distance * 0.01;
 
         const verticalOffset = 0.05;
-
         const lookAt = center.clone();
         lookAt.y -= size.y * verticalOffset;
+        if (options.targetOffset) {
+            if (options.targetOffset.x !== undefined) lookAt.x += options.targetOffset.x;
+            if (options.targetOffset.y !== undefined) lookAt.y += options.targetOffset.y;
+            if (options.targetOffset.z !== undefined) lookAt.z += options.targetOffset.z;
+        }
+        if (options.relativeTargetOffset) {
+            if (options.relativeTargetOffset.x !== undefined) lookAt.x += options.relativeTargetOffset.x * size.x;
+            if (options.relativeTargetOffset.y !== undefined) lookAt.y += options.relativeTargetOffset.y * size.y;
+            if (options.relativeTargetOffset.z !== undefined) lookAt.z += options.relativeTargetOffset.z * size.z;
+        }
         this.setLookTargetPosition(lookAt, immediate);
         this.setFieldOfView(options.fov, immediate);
 
@@ -1092,6 +1102,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
             // TODO: this doesnt take the Camera component nearClipPlane into account
             camera.near = (distance / 100);
             camera.far = boundsMax + distance * 10;
+            camera.updateProjectionMatrix();
 
             // adjust maxZoom so that the ground projection radius is always inside
             if (groundprojection) {
@@ -1104,12 +1115,13 @@ export class OrbitControls extends Behaviour implements ICameraController {
         if (currentZoom < this.minZoom) this.minZoom = currentZoom * 0.9;
         if (currentZoom > this.maxZoom) this.maxZoom = currentZoom * 1.1;
 
-        camera.updateMatrixWorld();
-        camera.updateProjectionMatrix();
-
-        const cameraWp = getWorldPosition(camera);
         const direction = center.clone();
-        direction.sub(cameraWp);
+        if (options.fitDirection) {
+            direction.sub(new Vector3().copy(options.fitDirection).multiplyScalar(1_000_000));
+        }
+        else {
+            direction.sub(camera.worldPosition);
+        }
         if (centerCamera === "y")
             direction.y = 0;
         direction.normalize();
@@ -1118,6 +1130,16 @@ export class OrbitControls extends Behaviour implements ICameraController {
             direction.y += -verticalOffset * 4 * distance;
 
         let cameraLocalPosition = center.clone().sub(direction);
+        if (options.cameraOffset) {
+            if (options.cameraOffset.x !== undefined) cameraLocalPosition.x += options.cameraOffset.x;
+            if (options.cameraOffset.y !== undefined) cameraLocalPosition.y += options.cameraOffset.y;
+            if (options.cameraOffset.z !== undefined) cameraLocalPosition.z += options.cameraOffset.z;
+        }
+        if (options.relativeCameraOffset) {
+            if (options.relativeCameraOffset.x !== undefined) cameraLocalPosition.x += options.relativeCameraOffset.x * size.x;
+            if (options.relativeCameraOffset.y !== undefined) cameraLocalPosition.y += options.relativeCameraOffset.y * size.y;
+            if (options.relativeCameraOffset.z !== undefined) cameraLocalPosition.z += options.relativeCameraOffset.z * size.z;
+        }
         if (camera.parent) {
             cameraLocalPosition = camera.parent.worldToLocal(cameraLocalPosition);
         }
@@ -1154,23 +1176,53 @@ export class OrbitControls extends Behaviour implements ICameraController {
 /**
  * Options for fitting the camera to the scene. Used in {@link OrbitControls.fitCamera}
  */
-declare type FitCameraOptions = {
+export type FitCameraOptions = {
     /** When enabled debug rendering will be shown */
     debug?: boolean,
     /**
      * 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,
+
+    /** Fit offset: A factor to multiply the distance to the objects by
+     * @default 1.1
+     */
+    fitOffset?: number,
+
+    /** The direction from which the camera should be fitted in worldspace. If not defined the current camera's position will be used */
+    fitDirection?: Vector3Like,
+
     /** If set to "y" the camera will be centered in the y axis */
     centerCamera?: "none" | "y",
+    /** Set to 'auto' to update the camera near or far plane based on the fitted-objects bounds */
     cameraNearFar?: "keep" | "auto",
+
+    /**
+     * Offset the camera position in world space
+     */
+    cameraOffset?: Partial<Vector3Like>,
+    /**
+     * Offset the camera position relative to the size of the objects being focused on (e.g. x: 0.5).  
+     * Value range: -1 to 1
+     */
+    relativeCameraOffset?: Partial<Vector3Like>,
+
+    /**
+     * Offset the camera target position in world space
+     */
+    targetOffset?: Partial<Vector3Like>,
+    /**
+     * Offset the camera target position relative to the size of the objects being focused on.  
+     * Value range: -1 to 1
+     */
+    relativeTargetOffset?: Partial<Vector3Like>,
+
+    /**
+     * Field of view (FOV) for the camera
+     */
     fov?: number,
 }

package/src/engine-components/Renderer.ts

@@ -706,7 +706,8 @@ export class Renderer extends Behaviour implements IRenderer {
         }
 
         if (this.reflectionProbeUsage !== ReflectionProbeUsage.Off && this._reflectionProbe) {
-            this._reflectionProbe.onSet(this);
+            if (!this._lightmaps?.length) // Currently reflectionprobes cant be used with lightmaps
+                this._reflectionProbe.onSet(this);
         }
         // since three 163 we need to set the envMap to the scene envMap if it is not set
         // otherwise the envmapIntensity has no effect: https://github.com/mrdoob/three.js/pull/27903

package/src/engine-components/Skybox.ts

@@ -48,21 +48,20 @@ function createRemoteSkyboxComponent(context: IContext, url: string, skybox: boo
 const promises = new Array<Promise<any>>();
 ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, (args) => {
     const context = args.context;
-    const skyboxImage = context.domElement.getAttribute("background-image");
+    const backgroundImage = context.domElement.getAttribute("background-image");
     const environmentImage = context.domElement.getAttribute("environment-image");
-    const envAndSkyboxAreSame = skyboxImage === environmentImage;
-
-    if (skyboxImage && !envAndSkyboxAreSame) {
-        if (debug) console.log("Creating remote skybox to load " + skyboxImage);
+    
+    if (backgroundImage) {
+        if (debug) console.log("Creating RemoteSkybox to load background " + backgroundImage);
         // if the user is loading a GLB without a camera then the CameraUtils (which creates the default camera)
         // checks if we have this attribute set and then sets the skybox clearflags accordingly
         // if the user has a GLB with a camera but set to solid color then the skybox image is not visible -> we will just warn then and not override the camera settings
-        const promise = createRemoteSkyboxComponent(context, skyboxImage, true, false, "background-image");
+        const promise = createRemoteSkyboxComponent(context, backgroundImage, true, false, "background-image");
         if (promise) promises.push(promise);
     }
     if (environmentImage) {
-        if (debug) console.log("Creating remote environment to load " + environmentImage);
-        const promise = createRemoteSkyboxComponent(context, environmentImage, envAndSkyboxAreSame, true, "environment-image");
+        if (debug) console.log("Creating RemoteSkybox to load environment " + environmentImage);
+        const promise = createRemoteSkyboxComponent(context, environmentImage, false, true, "environment-image");
         if (promise) promises.push(promise);
     }
 });
@@ -200,7 +199,7 @@ export class RemoteSkybox extends Behaviour {
             console.warn("Potentially invalid skybox URL: \"" + name + "\" on " + (this.name || this.gameObject?.name || "context"));
         }
 
-        if (debug) console.log("Set remote skybox url: " + url);
+        if (debug) console.log("Set RemoteSkybox url: " + url);
 
         if (this._prevUrl === url && this._prevLoadedEnvironment) {
             this.apply();
@@ -258,7 +257,7 @@ export class RemoteSkybox extends Behaviour {
             this._prevBackground = this.context.scene.background;
         if (this.context.scene.environment !== envMap)
             this._prevEnvironment = this.context.scene.environment;
-        if (debug) console.log("Set remote skybox", this.url, !Camera.backgroundShouldBeTransparent(this.context));
+        if (debug) console.log("Set RemoteSkybox (" + ((this.environment && this.background) ? "environment and background" : this.environment ? "environment" : this.background ? "background" : "none") + ")", this.url, !Camera.backgroundShouldBeTransparent(this.context));
         if (this.environment)
             this.context.scene.environment = envMap;
         if (this.background && !Camera.backgroundShouldBeTransparent(this.context))

package/src/engine-components/api.ts

@@ -51,8 +51,9 @@ import "./CameraUtils.js"
 import "./AnimationUtils.js"
 import "./AnimationUtilsAutoplay.js"
 
-export { DragMode } from "./DragControls.js"
+export { DragMode } from "./DragControls.js";
 export type { DropListenerNetworkEventArguments, DropListenerOnDropArguments } from "./DropListener.js";
+export { type FitCameraOptions } from "./OrbitControls.js";
 export * from "./particlesystem/api.js"
 
 // for correct type resolution in JSDoc

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";
@@ -12,6 +12,7 @@ import { InstancingHandler } from "../../../engine-components/RendererInstancing
 import { Collider } from "../../Collider.js";
 import { Behaviour, GameObject } from "../../Component.js";
 import { ContactShadows } from "../../ContactShadows.js";
+import { EventList } from "../../EventList.js";
 import { GroundProjectedEnv } from "../../GroundProjection.js";
 import { Renderer } from "../../Renderer.js"
 import { Rigidbody } from "../../RigidBody.js";
@@ -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;
     }
 }