@needle-tools/engine 4.8.8-next.c758977 → 4.8.8-next.e80f4d7

package/src/engine/engine_camera.ts

@@ -25,7 +25,11 @@ export function setCameraController(cam: Camera, cameraController: ICameraContro
 
 const autofit = "needle:autofit";
 
-/** @internal */
+/** 
+ * Used by e.g. getBoundingBox via ContactShadows or OrbitControls when fitting the camera or shadow planes. Objects can be marked to be excluded from bounding box calculations via `setAutoFitEnabled(obj, <bool>)`
+ * @see setAutoFitEnabled
+ * @internal 
+ */
 export function useForAutoFit(obj: Object3D): boolean {
     // if autofit is not defined we assume it may be included
     if (obj[autofit] === undefined) return true;
@@ -34,7 +38,9 @@ export function useForAutoFit(obj: Object3D): boolean {
 }
 
 /**
- * Enable or disable autofitting for the given object
+ * Enable or disable autofitting for the given object. Objects that are 'disabled' will be excluded in getBoundingBox calculations.   
+ * This is used by ContactShadows or OrbitControls when fitting the shadow plane or camera to the given objects or scene.
+ * @see useForAutoFit
  */
 export function setAutoFitEnabled(obj: Object3D, enabled: boolean): void {
     obj[autofit] = enabled;
@@ -42,12 +48,18 @@ export function setAutoFitEnabled(obj: Object3D, enabled: boolean): void {
 
 
 
-
+export type FocusRectSettings = {
+    /** Lower values will result in faster alignment with the rect (value ~= seconds to reach target) 
+     * Minimum value is 0.
+     */
+    damping: number
+}
 export type FocusRect = DOMRect | Element | { x: number, y: number, width: number, height: number };
 
 let rendererRect: DOMRect | undefined = undefined;
 const overlapRect = { x: 0, y: 0, width: 0, height: 0 };
 
+/** Used internally by the Needle Engine context via 'setFocusRect(<rect>)'  */
 export function updateCameraFocusRect(focusRect: FocusRect, dt: number, camera: PerspectiveCamera, renderer: WebGLRenderer) {
 
     if (focusRect instanceof Element) {

package/src/engine/engine_context.ts

@@ -18,7 +18,7 @@ import { Addressables } from './engine_addressables.js';
 import { AnimationsRegistry } from './engine_animation.js';
 import { Application } from './engine_application.js';
 import { AssetDatabase } from './engine_assetdatabase.js';
-import { FocusRect, updateCameraFocusRect } from './engine_camera.js';
+import { FocusRect, FocusRectSettings, updateCameraFocusRect } from './engine_camera.js';
 import { VERSION } from './engine_constants.js';
 import { ContextEvent, ContextRegistry } from './engine_context_registry.js';
 import { WaitForPromise } from './engine_coroutine.js';
@@ -1378,11 +1378,26 @@ export class Context implements IContext {
 	 * Set a rect or dom element. The camera center will be moved to the center of the rect.  
 	 * This is useful if you have Needle Engine embedded in a HTML layout and while you want the webgl background to fill e.g. the whole screen you want to move the camera center to free space.  
 	 * For that you can simply pass in the rect or HMTL div that you want the camera to center on.
+	 * @param rect The focus rect or null to disable
+	 * @param settings Optional settings for the focus rect. These will override the `focusRectSettings` property
 	 */
-	public setCameraFocusRect(rect: FocusRect | null) {
+	public setCameraFocusRect(rect: FocusRect | null, settings?: Partial<FocusRectSettings>) {
 		this._focusRect = rect;
+		if (settings) {
+			Object.assign(this.focusRectSettings, settings);
+		}
 	}
 	get focusRect() { return this._focusRect; }
+	/** Settings when a focus rect is set. Use `setCameraFocusRect(...)` to do so.  
+	 * This can be used to offset the renderer center e.g. to a specific DOM element.
+	 */
+	readonly focusRectSettings: FocusRectSettings = {
+		/** Controls how fast the rect is centered. Smaller values mean the rect is centered faster.   
+		 * A minimum value of 0 means the rect is centered instantly.
+		 * @default .05
+		*/
+		damping: .05
+	};
 	private _focusRect: FocusRect | null = null;
 
 
@@ -1514,8 +1529,11 @@ export class Context implements IContext {
 		if (this.isVisibleToUser || this.runInBackground) {
 
 			if (this._focusRect) {
-				if (this.mainCamera instanceof PerspectiveCamera)
-					updateCameraFocusRect(this._focusRect, this.time.deltaTime / .05, this.mainCamera, this.renderer);
+				if (this.mainCamera instanceof PerspectiveCamera) {
+					const settings = this.focusRectSettings;
+					const dt = settings.damping > 0 ? this.time.deltaTime / settings.damping : 1;
+					updateCameraFocusRect(this._focusRect, dt, this.mainCamera, this.renderer);
+				}
 			}
 
 			this._currentFrameEvent = FrameEvent.OnBeforeRender;

package/src/engine/engine_create_objects.ts

@@ -42,13 +42,13 @@ export type ObjectOptions = {
     /**
      * The position of the object in local space
      */
-    position?: Vec3 | [number, number, number],
+    position?: Partial<Vec3> | [number, number, number],
     /** The rotation of the object in local space */
-    rotation?: Vec3 | [number, number, number],
+    rotation?: Partial<Vec3> | [number, number, number],
     /**
      * The scale of the object in local space
      */
-    scale?: Vec3 | number | [number, number, number],
+    scale?: Partial<Vec3> | number | [number, number, number],
     /**
      * If the object should receive shadows
      * @default true
@@ -251,14 +251,15 @@ export class ObjectUtils {
         if (opts?.position) {
             if (Array.isArray(opts.position))
                 obj.position.set(opts.position[0], opts.position[1], opts.position[2]);
-            else
-                obj.position.set(opts.position.x, opts.position.y, opts.position.z);
+            else {
+                obj.position.set(opts.position.x || 0, opts.position.y || 0, opts.position.z || 0);
+            }
         }
         if (opts?.rotation) {
             if (Array.isArray(opts.rotation))
                 obj.rotation.set(opts.rotation[0], opts.rotation[1], opts.rotation[2]);
             else
-                obj.rotation.set(opts.rotation.x, opts.rotation.y, opts.rotation.z);
+                obj.rotation.set(opts.rotation.x || 0, opts.rotation.y || 0, opts.rotation.z || 0);
         }
         if (opts?.scale) {
             if (typeof opts.scale === "number")
@@ -267,7 +268,7 @@ export class ObjectUtils {
                 obj.scale.set(opts.scale[0], opts.scale[1], opts.scale[2]);
             }
             else {
-                obj.scale.set(opts.scale.x, opts.scale.y, opts.scale.z);
+                obj.scale.set(opts.scale.x || 1, opts.scale.y || 1, opts.scale.z || 1);
 
             }
         }

package/src/engine/extensions/NEEDLE_lighting_settings.ts

@@ -169,8 +169,11 @@ export class SceneLightSettings extends Behaviour {
                 this._hemisphereLightObj.removeFromParent();
         }
 
-        if (this.sourceId)
-            this.context.sceneLighting.internalEnableReflection(this.sourceId);
+        if (this.sourceId) {
+            if (!this.context.domElement.getAttribute("environment-image")) {
+                this.context.sceneLighting.internalEnableReflection(this.sourceId);
+            }
+        }
     }
 
     onDisable() {

package/src/engine-components/OrbitControls.ts

@@ -1044,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);
@@ -1104,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) {
@@ -1116,9 +1115,6 @@ 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 direction = center.clone();
         if (options.fitDirection) {
             direction.sub(new Vector3().copy(options.fitDirection).multiplyScalar(1_000_000));