@needle-tools/engine 4.8.8-next.7387ba3 → 4.8.8-next.937fc15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/engine",
-  "version": "4.8.8-next.7387ba3",
+  "version": "4.8.8-next.937fc15",
   "description": "Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.",
   "main": "dist/needle-engine.min.js",
   "exports": {

package/plugins/common/files.js

@@ -24,9 +24,12 @@ export function copyFilesSync(src, dest, override = true, ctx = undefined) {
         });
     }
     else if (override || !existsSync(dest)) {
-        if (ctx) {
-            ctx.count += 1;
+        if (exists) {
+            if (ctx) {
+                ctx.count += 1;
+            }
+            copyFileSync(src, dest);
         }
-        copyFileSync(src, dest);
+        else console.warn(`[needle-copy] - File at ${src} does not exist`);
     }
 };

package/plugins/vite/editor-connection.js

@@ -63,16 +63,16 @@ function createPlugin(isInstalled) {
         name: "needle-editor-connection",
         // Setup HMR port for connecting to the editor
         config(config) {
-            if (!isInstalled) {
+            if (isInstalled) {
                 if (!config.server) config.server = {};
                 if (!config.server.hmr) config.server.hmr = {};
                 if (config.server.hmr === false) {
-                    setTimeout(() => console.log("HMR is disabled, not initializing Needle Editor"));
+                    setTimeout(() => console.log("[needle-editor-sync] HMR is disabled, not initializing Needle Editor"));
                     return;
                 }
-                if (config.server.hmr.port !== 1107) {
+                if (config.server.hmr.port === undefined) {
                     config.server.hmr.port = 1107;
-                    setTimeout(() => console.log("Update HMR port to " + config.server.hmr.port));
+                    setTimeout(() => console.log("[needle-editor-sync] Update HMR port to " + config.server.hmr.port));
                 }
             }
 

package/src/engine/engine_loaders.callbacks.ts

@@ -98,6 +98,7 @@ export namespace NeedleEngineModelLoader {
      *     }
      *     return null;
      * });
+     * ```
      */
     export function onCreateCustomModelLoader(callback: CustomLoaderCallback, opts?: CustomLoaderOptions) {
         const entry = { name: opts?.name, priority: opts?.priority ?? 0, callback };

package/src/engine/webcomponents/needle-engine.ts

@@ -55,8 +55,8 @@ const observedAttributes = [
  * The needle engine web component creates and manages a needle engine context which is responsible for rendering a 3D scene using threejs.   
  * The needle engine context is created when the src attribute is set and disposed when the needle engine is removed from the document (you can prevent this by setting the keep-alive attribute to true).  
  * The needle engine context is accessible via the context property on the needle engine element (e.g. document.querySelector("needle-engine").context).
- * @link https://engine.needle.tools/docs/reference/needle-engine-attributes
- * 
+ * See {@link https://engine.needle.tools/docs/reference/needle-engine-attributes}
+ *
  * @example
  * <needle-engine src="https://example.com/scene.glb"></needle-engine>
  * @example
@@ -65,7 +65,7 @@ const observedAttributes = [
 export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngineComponent {
 
     static get observedAttributes() {
-        return observedAttributes
+        return observedAttributes;
     }
 
     public get loadingProgress01(): number { return this._loadingProgress01; }
@@ -95,7 +95,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
     /**
      * Get the current context for this web component instance. The context is created when the src attribute is set and the loading has finished.  
      * The context is disposed when the needle engine is removed from the document (you can prevent this by setting the keep-alive attribute to true).  
-     * @returns {Promise<Context>} a promise that resolves to the context when the loading has finished
+     * @returns a promise that resolves to the context when the loading has finished
      */
     public getContext(): Promise<Context> {
         return new Promise((res, _rej) => {
@@ -328,19 +328,12 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
                 break;
                 
             case "tonemapping":
-            case "tone-mapping": {
-                this.applyAttributes();
-                break;
-            }
-            case "tone-mapping-exposure": {
-                this.applyAttributes();
-                break;
-            }
-            case "background-blurriness": {
-                this.applyAttributes();
-                break;
-            }
-            case "environment-intensity": {
+            case "tone-mapping":
+            case "tone-mapping-exposure":
+            case "background-blurriness":
+            case "background-color":
+            case "environment-intensity":
+            {
                 this.applyAttributes();
                 break;
             }

package/src/engine-components/Camera.ts

@@ -10,6 +10,7 @@ import { getTempColor, getWorldPosition } from "../engine/engine_three_utils.js"
 import type { ICamera } from "../engine/engine_types.js"
 import { getParam } from "../engine/engine_utils.js";
 import { RGBAColor } from "../engine/js-extensions/index.js";
+import { NeedleXREventArgs } from "../engine/engine_xr.js";
 import { Behaviour, GameObject } from "./Component.js";
 import { OrbitControls } from "./OrbitControls.js";
 
@@ -446,6 +447,11 @@ export class Camera extends Behaviour implements ICamera {
         this.context.removeCamera(this);
     }
 
+    onLeaveXR(_args: NeedleXREventArgs): void {
+        // Restore previous FOV
+        this.fieldOfView = this._fov;
+    }
+
 
     /** @internal */
     onBeforeRender() {
@@ -553,7 +559,7 @@ export class Camera extends Behaviour implements ICamera {
         }
 
         // restore previous fov (e.g. when user was in VR or AR and the camera's fov has changed)
-        this.fieldOfView = this._fov;
+        this.fieldOfView = this.fieldOfView;
 
         if (debug) {
             const msg = `[Camera] Apply ClearFlags: ${ClearFlags[this._clearFlags]} - \"${this.name}\"`;

package/src/engine-components/DropListener.ts

@@ -399,10 +399,11 @@ export class DropListener extends Behaviour {
     private _abort: AbortController | null = null;
 
     /**
-     * Processes dropped files, loads them as 3D models, and handles networking if enabled
-     * Creates an abort controller to cancel previous uploads if new files are dropped
+     * Processes dropped files and loads them as 3D models.
+     * When enabled, it also handles network drops (sending files between clients).
+     * Automatically handles cancelling previous uploads if new files are dropped.
      * @param fileList Array of dropped files
-     * @param ctx Context information about where the drop occurred
+     * @param ctx Context information about where on the screen or in 3D space the drop occurred
      */
     private async addFromFiles(fileList: Array<File>, ctx: DropContext) {
         if (debug) console.log("Add files", fileList)

package/src/engine-components/OrbitControls.ts

@@ -889,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. 
@@ -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 - 
@@ -1078,9 +1081,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);
 
@@ -1107,9 +1119,13 @@ export class OrbitControls extends Behaviour implements ICameraController {
         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 +1134,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,7 +1180,7 @@ 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,
     /**
@@ -1166,14 +1192,41 @@ declare type FitCameraOptions = {
      */
     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",
 
-    fov?: number,
+    /**
+     * 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>,
 
-    /** Fit offset: A factor to multiply the distance to the objects by
-     * @default 1.1
+    /**
+     * Offset the camera target position in world space
      */
-    fitOffset?: number,
+    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/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,7 +51,8 @@ import "./CameraUtils.js"
 import "./AnimationUtils.js"
 import "./AnimationUtilsAutoplay.js"
 
-export { DragMode } from "./DragControls.js"
+export { DragMode } from "./DragControls.js";
+export { type FitCameraOptions } from "./OrbitControls.js";
 export type { DropListenerNetworkEventArguments, DropListenerOnDropArguments } from "./DropListener.js";
 export * from "./particlesystem/api.js"