@needle-tools/engine 4.9.3 → 4.10.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/engine",
-  "version": "4.9.3",
+  "version": "4.10.0-beta.1",
   "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/vite/alias.js

@@ -113,12 +113,14 @@ export const needleViteAlias = (command, config, userSettings) => {
 
             // is needle engine a local package?
             // This will cause local changes to not be reflected anymore...
-            const localEnginePath = path.resolve(projectDir, 'node_modules/', '@needle-tools/engine', 'node_modules');
+            const localEnginePath = path.resolve(projectDir, 'node_modules/', '@needle-tools/engine', 'node_modules', '.package-lock.json');
             if (existsSync(localEnginePath)) {
                 config.optimizeDeps ??= {};
                 config.optimizeDeps.exclude ??= [];
-                config.optimizeDeps.exclude.push('@needle-tools/engine');
-                log("[needle-alias] Detected local @needle-tools/engine package: will exclude it from optimization");
+                if (!config.optimizeDeps.include?.includes('@needle-tools/engine')) {
+                    config.optimizeDeps.exclude.push('@needle-tools/engine');
+                    log("[needle-alias] Detected local @needle-tools/engine package → will exclude it from optimization");
+                }
             }
 
 

package/plugins/vite/poster-client.js

@@ -10,32 +10,33 @@ async function generatePoster() {
         const height = 1080;
 
         return new Promise(res => {
-            onStart(async context => {
+            /** @ts-ignore */
+            onStart(async (context) => {
 
                 if (context.lodsManager.manager) {
                     await context.lodsManager.manager.awaitLoading({ frames: 5, maxPromisesPerObject: 2, waitForFirstCapture: true });
                 }
 
-                const mimeType = "image/webp";
-
-                // We're reading back as a blob here because that's async, and doesn't seem
-                // to stress the GPU so much on memory-constrained devices.
-                const blob = await screenshot2({ context, width, height, mimeType, type: "blob" });
-
-                // We can only send a DataURL, so we need to convert it back here.
-                const dataUrl = await new Promise((resolve, reject) => {
-                    const reader = new FileReader();
-                    reader.onload = function () {
-                        resolve(reader.result);
-                    };
-                    reader.onloadend = function () {
-                        resolve(null);
-                    };
-                    reader.readAsDataURL(blob);
-                });
-
-
-                res(dataUrl);
+                onStart(() => {
+                    const mimeType = "image/webp";
+                    // We're reading back as a blob here because that's async, and doesn't seem
+                    // to stress the GPU so much on memory-constrained devices.
+                    screenshot2({ context, width, height, mimeType, type: "blob" })
+                        // @ts-ignore
+                        .then(blob => {
+                            const reader = new FileReader();
+                            reader.onload = function () {
+                                res(reader.result);
+                            };
+                            reader.onloadend = function () {
+                                res(null);
+                            };
+                            reader.readAsDataURL(blob);
+
+                        })
+
+
+                }, { once: true });
 
 
             }, { once: true });

package/src/engine/api.ts

@@ -24,7 +24,8 @@ export * from "./engine_addressables.js";
 export { AnimationUtils } from "./engine_animation.js";
 export { Application } from "./engine_application.js";
 export * from "./engine_assetdatabase.js";
-export { getCameraController, setAutoFitEnabled, setCameraController, useForAutoFit } from "./engine_camera.js"
+export * from "./engine_camera.fit.js";
+export { getCameraController, setAutoFitEnabled, setCameraController, useForAutoFit } from "./engine_camera.js";
 export * from "./engine_components.js";
 export * from "./engine_components_internal.js";
 export * from "./engine_components_internal.js";

package/src/engine/codegen/register_types.ts

@@ -108,6 +108,7 @@ import { PlayableDirector } from "../../engine-components/timeline/PlayableDirec
 import { SignalReceiver } from "../../engine-components/timeline/SignalAsset.js";
 import { AnimationTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
 import { AudioTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
+import { MarkerTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
 import { SignalTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
 import { ControlTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
 import { TransformGizmo } from "../../engine-components/TransformGizmo.js";
@@ -139,7 +140,9 @@ import { VideoPlayer } from "../../engine-components/VideoPlayer.js";
 import { Voip } from "../../engine-components/Voip.js";
 import { ClickThrough } from "../../engine-components/web/Clickthrough.js";
 import { CursorFollow } from "../../engine-components/web/CursorFollow.js";
+import { HoverAnimation } from "../../engine-components/web/HoverAnimation.js";
 import { ScrollFollow } from "../../engine-components/web/ScrollFollow.js";
+import { ViewBox } from "../../engine-components/web/ViewBox.js";
 import { Avatar } from "../../engine-components/webxr/Avatar.js";
 import { XRControllerFollow } from "../../engine-components/webxr/controllers/XRControllerFollow.js";
 import { XRControllerModel } from "../../engine-components/webxr/controllers/XRControllerModel.js";
@@ -264,6 +267,7 @@ TypeStore.add("PlayableDirector", PlayableDirector);
 TypeStore.add("SignalReceiver", SignalReceiver);
 TypeStore.add("AnimationTrackHandler", AnimationTrackHandler);
 TypeStore.add("AudioTrackHandler", AudioTrackHandler);
+TypeStore.add("MarkerTrackHandler", MarkerTrackHandler);
 TypeStore.add("SignalTrackHandler", SignalTrackHandler);
 TypeStore.add("ControlTrackHandler", ControlTrackHandler);
 TypeStore.add("TransformGizmo", TransformGizmo);
@@ -295,7 +299,9 @@ TypeStore.add("VideoPlayer", VideoPlayer);
 TypeStore.add("Voip", Voip);
 TypeStore.add("ClickThrough", ClickThrough);
 TypeStore.add("CursorFollow", CursorFollow);
+TypeStore.add("HoverAnimation", HoverAnimation);
 TypeStore.add("ScrollFollow", ScrollFollow);
+TypeStore.add("ViewBox", ViewBox);
 TypeStore.add("Avatar", Avatar);
 TypeStore.add("XRControllerFollow", XRControllerFollow);
 TypeStore.add("XRControllerModel", XRControllerModel);

package/src/engine/engine_animation.ts

@@ -1,4 +1,4 @@
-import { AnimationAction, AnimationClip, AnimationMixer, Object3D, PropertyBinding } from "three";
+import { AnimationAction, AnimationClip, AnimationMixer, KeyframeTrack, Object3D, PropertyBinding, Vector3Like } from "three";
 
 import type { Context } from "./engine_context.js";
 import { GLTF, IAnimationComponent, Model } from "./engine_types.js";
@@ -151,4 +151,72 @@ export class AnimationUtils {
             return findAnimationComponentInParent(obj.parent);
         }
     }
+
+
+    static emptyClip(): AnimationClip {
+        return new AnimationClip("empty", 0, []);
+    }
+
+    static createScaleClip(options?: ScaleClipOptions): AnimationClip {
+        const duration = options?.duration ?? 0.3;
+
+        let baseScale: Vector3Like = { x: 1, y: 1, z: 1 };
+        if (options?.scale !== undefined) {
+            if (typeof options.scale === "number") {
+                baseScale = { x: options.scale, y: options.scale, z: options.scale };
+            }
+            else {
+                baseScale = options.scale;
+            }
+        }
+        const type = options?.type ?? "linear";
+        const scale = options?.scaleFactor ?? 1.2;
+
+        const times = new Array<number>();
+        const values = new Array<number>();
+        switch (type) {
+            case "linear":
+                times.push(0, duration);
+                values.push(
+                    baseScale.x, baseScale.y, baseScale.z,
+                    baseScale.x * scale, baseScale.y * scale, baseScale.z * scale
+                );
+                break;
+
+            case "spring":
+                times.push(0, duration * 0.3, duration * 0.5, duration * 0.7, duration * 0.9, duration);
+                values.push(
+                    baseScale.x, baseScale.y, baseScale.z,
+                    baseScale.x * scale, baseScale.y * scale, baseScale.z * scale,
+                    baseScale.x * 0.9, baseScale.y * 0.9, baseScale.z * 0.9,
+                    baseScale.x * 1.05, baseScale.y * 1.05, baseScale.z * 1.05,
+                    baseScale.x * 0.98, baseScale.y * 0.98, baseScale.z * 0.98,
+                    baseScale.x, baseScale.y, baseScale.z
+                );
+                break;
+
+        }
+
+        const track = new KeyframeTrack(".scale", times, values);
+        return new AnimationClip("scale", times[times.length - 1], [track]);
+    }
+}
+
+/**
+ * Type of scale animation to create.  
+ * - "linear": Simple linear scale up animation.  
+ * - "spring": Spring-like scale animation with overshoot and settling.  
+ */
+export type ScaleClipType = "linear"  | "spring";
+
+type ScaleClipOptions = {
+    /**
+     * Type of scale animation to create.
+     * - "linear": Simple linear scale up animation.
+     * - "spring": Spring-like scale animation with overshoot and settling.
+     */
+    type?: ScaleClipType,
+    duration?: number,
+    scale?: number | Vector3Like,
+    scaleFactor?: number
 }

package/src/engine/engine_camera.fit.ts

@@ -0,0 +1,258 @@
+import { Camera, Object3D, PerspectiveCamera, Vector3, Vector3Like } from "three";
+
+import { GroundProjectedEnv } from "../engine-components/GroundProjection.js";
+import { findObjectOfType } from "./engine_components.js";
+import { Context } from "./engine_context.js";
+import { Gizmos } from "./engine_gizmos.js";
+import { getBoundingBox } from "./engine_three_utils.js";
+import { NeedleXRSession } from "./xr/NeedleXRSession.js";
+
+
+/**
+ * Options for fitting the camera to the scene. Used in {@link OrbitControls.fitCamera}
+ */
+export type FitCameraOptions = {
+    /** When enabled debug rendering will be shown */
+    debug?: boolean,
+
+    /**
+     * If true the camera position and target will be applied immediately
+     * @default true
+     */
+    autoApply?: boolean,
+
+    /**
+     * The context to use. If not provided the current context will be used
+     */
+    context?: Context,
+
+    /**
+     * The camera to fit. If not provided the current camera will be used
+     */
+    camera?: Camera,
+
+    currentZoom?: number,
+    minZoom?: number,
+    maxZoom?: number,
+
+    /**
+     * 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,
+
+    /** 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,
+}
+
+export type FitCameraReturnType = {
+    camera: Camera,
+    position: Vector3,
+    lookAt: Vector3,
+    fov: number | undefined
+}
+
+
+export function fitCamera(options?: FitCameraOptions): null | FitCameraReturnType {
+
+    if (NeedleXRSession.active) {
+        // camera fitting in XR is not supported
+        console.warn('[OrbitControls] Can not fit camera while XR session is active');
+        return null;
+    }
+
+    const context = Context.Current;
+    if (!context) {
+        console.warn('[OrbitControls] No context found');
+        return null;
+    }
+    const camera = options?.camera || context.mainCamera;
+
+    // const controls = this._controls as ThreeOrbitControls | null;
+
+    if (!camera) {
+        console.warn("No camera or controls found to fit camera to objects...");
+        return null;
+    }
+
+    if (!options) options = {}
+    options.autoApply = options.autoApply !== false; // default to true
+    options.minZoom ||= 0;
+    options.maxZoom ||= Infinity;
+
+    const {
+        centerCamera,
+        cameraNearFar = "auto",
+        fitOffset = 1.1,
+        fov = camera instanceof PerspectiveCamera ? camera?.fov : -1
+    } = options;
+
+    const size = new Vector3();
+    const center = new Vector3();
+    const aspect = camera instanceof PerspectiveCamera ? camera.aspect : 1;
+    const objects = options.objects || context.scene;
+    // TODO would be much better to calculate the bounds in camera space instead of world space - 
+    // we would get proper view-dependant fit.
+    // Right now it's independent from where the camera is actually looking from,
+    // and thus we're just getting some maximum that will work for sure.
+    const box = getBoundingBox(objects, undefined, camera?.layers);
+    const boxCopy = box.clone();
+    box.getCenter(center);
+
+    const box_size = new Vector3();
+    box.getSize(box_size);
+
+    // project this box into camera space
+    if (camera instanceof PerspectiveCamera) camera.updateProjectionMatrix();
+    camera.updateMatrixWorld();
+    box.applyMatrix4(camera.matrixWorldInverse);
+
+    box.getSize(size);
+    box.setFromCenterAndSize(center, size);
+    if (Number.isNaN(size.x) || Number.isNaN(size.y) || Number.isNaN(size.z)) {
+        console.warn("Camera fit size resultet in NaN", camera, box);
+        return null;
+    }
+    if (size.length() <= 0.0000000001) {
+        console.warn("Camera fit size is zero", box);
+        return null;
+    }
+
+    const verticalFov = fov;
+    const horizontalFov = 2 * Math.atan(Math.tan(verticalFov * Math.PI / 360 / 2) * 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));
+
+    const distance = fitOffset * Math.max(fitHeightDistance, fitWidthDistance) + size.z / 2;
+    options.maxZoom = distance * 10;
+    options.minZoom = distance * 0.01;
+
+    if (options.debug === true) {
+        console.log("Fit camera to objects", { fitHeightDistance, fitWidthDistance, distance, verticalFov, horizontalFov });
+    }
+
+    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);
+
+    if (cameraNearFar == undefined || cameraNearFar == "auto") {
+        // Check if the scene has a GroundProjectedEnv and include the scale to the far plane so that it doesnt cut off
+        const groundprojection = findObjectOfType(GroundProjectedEnv);
+        const groundProjectionRadius = groundprojection ? groundprojection.radius : 0;
+        const boundsMax = Math.max(box_size.x, box_size.y, box_size.z, groundProjectionRadius);
+        // TODO: this doesnt take the Camera component nearClipPlane into account
+        if (camera instanceof PerspectiveCamera) {
+            camera.near = (distance / 100);
+            camera.far = boundsMax + distance * 10;
+            camera.updateProjectionMatrix();
+        }
+
+        // adjust maxZoom so that the ground projection radius is always inside
+        if (groundprojection) {
+            options.maxZoom = Math.max(Math.min(options.maxZoom, groundProjectionRadius * 0.5), distance);
+        }
+    }
+
+    // ensure we're not clipping out of the current zoom level just because we're fitting
+    if (options.currentZoom !== undefined) {
+        if (options.currentZoom < options.minZoom) options.minZoom = options.currentZoom * 0.9;
+        if (options.currentZoom > options.maxZoom) options.maxZoom = options.currentZoom * 1.1;
+    }
+
+    const direction = center.clone();
+    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();
+    direction.multiplyScalar(distance);
+    if (centerCamera === "y")
+        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);
+    }
+    // this.setCameraTargetPosition(cameraLocalPosition, immediate);
+
+    if (options.debug) {
+        Gizmos.DrawWireBox3(box, 0xffff33, 10);
+        Gizmos.DrawWireBox3(boxCopy, 0x00ff00, 10);
+    }
+
+    if (options.autoApply) {
+        camera.position.copy(cameraLocalPosition);
+        camera.lookAt(lookAt);
+        if (fov > 0 && camera instanceof PerspectiveCamera) {
+            camera.fov = fov;
+            camera.updateProjectionMatrix();
+        }
+    }
+
+    return {
+        camera: camera,
+        position: cameraLocalPosition,
+        lookAt: lookAt,
+        fov: options.fov,
+    }
+}

package/src/engine/engine_camera.ts

@@ -52,15 +52,23 @@ export type FocusRectSettings = {
     /** Lower values will result in faster alignment with the rect (value ~= seconds to reach target) 
      * Minimum value is 0.
      */
-    damping: number
+    damping: number,
+
+    /** X offset in camera coordinates. Used by ViewBox component */
+    offsetX: number,
+    /** Y offset in camera coordinates. Used by ViewBox component */
+    offsetY: number,
+    /** Zoom factor. Used by ViewBox component */
+    zoom: 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 };
+let _testTime = 1;
 
 /** Used internally by the Needle Engine context via 'setFocusRect(<rect>)'  */
-export function updateCameraFocusRect(focusRect: FocusRect, dt: number, camera: PerspectiveCamera, renderer: WebGLRenderer) {
+export function updateCameraFocusRect(focusRect: FocusRect, settings: FocusRectSettings, dt: number, camera: PerspectiveCamera, renderer: WebGLRenderer) {
 
     if (focusRect instanceof Element) {
         focusRect = focusRect.getBoundingClientRect();
@@ -76,16 +84,62 @@ export function updateCameraFocusRect(focusRect: FocusRect, dt: number, camera:
     rect.x -= rendererRect.x;
     rect.y -= rendererRect.y;
 
-    const targetX = rect.width / -2 - (rect.x - (rendererRect.width / 2));
-    const targetY = rect.height / -2 - (rect.y - (rendererRect.height / 2));
+    const sourceWidth = rendererRect.width;
+    const sourceHeight = rendererRect.height;
 
-    const view = camera.view;
+    const view = camera.view as PerspectiveCamera["view"];
 
+    // Apply zoom
+    let zoom = settings.zoom;
     let offsetX = view?.offsetX || 0;
     let offsetY = view?.offsetY || 0;
-    offsetX = Mathf.lerp(offsetX, targetX, dt);
-    offsetY = Mathf.lerp(offsetY, targetY, dt);
 
-    camera.setViewOffset(rendererRect.width, rendererRect.height, offsetX, offsetY, rendererRect.width, rendererRect.height);
+    let width = rendererRect.width;
+    let height = rendererRect.height;
+    width /= zoom;
+    height /= zoom;
+    offsetX = width * (zoom - 1) * .5;
+    offsetY = height * (zoom - 1) * .5;
+
+    const focusRectCenterX = rect.x + rect.width * .5;
+    const focusRectCenterY = rect.y + rect.height * .5;
+    const rendererCenterX = rendererRect.width * .5;
+    const rendererCenterY = rendererRect.height * .5;
+
+    const diffx = focusRectCenterX - rendererCenterX;
+    const diffy = focusRectCenterY - rendererCenterY;
+    offsetX -= diffx / zoom;
+    offsetY -= diffy / zoom;
+    if (settings.offsetX !== undefined) {
+        offsetX += settings.offsetX * (rendererRect.width * .5);
+    }
+    if (settings.offsetY !== undefined) {
+        offsetY -= settings.offsetY * (rendererRect.height * .5);
+    }
+
+
+    const currentOffsetX = view?.offsetX || offsetX;
+    const currentOffsetY = view?.offsetY || offsetY;
+    offsetX = Mathf.lerp(currentOffsetX, offsetX, dt);
+    offsetY = Mathf.lerp(currentOffsetY, offsetY, dt);
+    const currentWidth = view?.width || sourceWidth;
+    const currentHeight = view?.height || sourceHeight;
+    width = Mathf.lerp(currentWidth, width, dt);
+    height = Mathf.lerp(currentHeight, height, dt);
+
+    camera.setViewOffset(sourceWidth, sourceHeight, offsetX, offsetY, width, height);
     camera.updateProjectionMatrix();
+
+    if (settings.damping > 0) {
+        settings.damping *= (1.0 - dt);
+        if (settings.damping < 0.01) settings.damping = 0;
+        settings.damping = Math.max(0, settings.damping);
+    }
+}
+
+
+function fit(width1: number, height1: number, width2: number, height2: number) {
+    const scaleX = width2 / width1;
+    const scaleY = height2 / height1;
+    return Math.max(scaleX, scaleY);
 }

package/src/engine/engine_context.ts

@@ -1382,21 +1382,61 @@ export class Context implements IContext {
 	 * @param settings Optional settings for the focus rect. These will override the `focusRectSettings` property
 	 */
 	public setCameraFocusRect(rect: FocusRect | null, settings?: Partial<FocusRectSettings>) {
+		const oldRect = this._focusRect;
 		this._focusRect = rect;
 		if (settings) {
 			Object.assign(this.focusRectSettings, settings);
 		}
+		if (settings?.damping === undefined) {
+			// if the new rect is on screen then set damping
+			if (oldRect) {
+				let domRect = oldRect as DOMRect;
+				if (oldRect instanceof HTMLElement) {
+					domRect = oldRect.getBoundingClientRect();
+				}
+				if (domRect && "top" in domRect) {
+					const allowedDistance = 100;
+					const isVisible = domRect.bottom >= -allowedDistance && domRect.right >= -allowedDistance && domRect.top <= window.innerHeight + allowedDistance && domRect.left <= window.innerWidth + allowedDistance;
+					if (isVisible) this.focusRectSettings.damping = .2;
+				}
+			}
+		}
+
 	}
 	get focusRect() { return this._focusRect; }
+	get focusRectSize(): null | { x: number, y: number, width: number, height: number } {
+		const rect = this._focusRect;
+		if (rect && (rect instanceof DOMRect || ("width" in rect && "height" in rect && "x" in rect && "y" in rect))) {
+			return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+		}
+		else if (rect instanceof HTMLElement) {
+			const r = rect.getBoundingClientRect();
+			return { x: r.x, y: r.y, width: r.width, height: r.height };
+		}
+		return null;
+	}
 	/** 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
+		 * @default 0
 		*/
-		damping: .05
+		damping: 0,
+
+		/**
+		 * Zoom factor when a focus rect is set.
+		 */
+		zoom: 1,
+		/**
+		 * Additional offset in pixels from the center of the rect
+		 */
+		offsetX: 0,
+		/**
+		 * Additional offset in pixels from the center of the rect
+		 */
+		offsetY: 0,
 	};
 	private _focusRect: FocusRect | null = null;
 
@@ -1528,14 +1568,6 @@ export class Context implements IContext {
 
 		if (this.isVisibleToUser || this.runInBackground) {
 
-			if (this._focusRect) {
-				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;
 
 			// should we move these callbacks in the regular three onBeforeRender events?
@@ -1552,6 +1584,14 @@ export class Context implements IContext {
 			this.executeCoroutines(FrameEvent.OnBeforeRender);
 			invokeLifecycleFunctions(this, FrameEvent.OnBeforeRender);
 
+			if (this._focusRect) {
+				if (this.mainCamera instanceof PerspectiveCamera) {
+					const settings = this.focusRectSettings;
+					const dt = settings.damping > 0 ? this.time.deltaTime / settings.damping : 1;
+					updateCameraFocusRect(this._focusRect, this.focusRectSettings, dt, this.mainCamera, this.renderer);
+				}
+			}
+
 			if (this._needsUpdateSize)
 				this.updateSize();
 

package/src/engine/engine_gizmos.ts

@@ -230,8 +230,8 @@ export class Gizmos {
      * Draw a 3D wiremesh box gizmo in the scene
      * @param box the box in world space
      * @param color the color of the box
-     * @param duration the duration in seconds the box will be rendered. If 0 it will be rendered for one frame
-     * @param depthTest if true the box will be rendered with depth test
+     * @param duration the duration in seconds the box will be rendered. If 0 it will be rendered for one frame. Default: 0
+     * @param depthTest if true the box will be rendered with depth test. Default: true
      */
     static DrawWireBox3(box: Box3, color: ColorRepresentation = defaultColor, duration: number = 0, depthTest: boolean = true) {
         if (!Gizmos.enabled) return;