@needle-tools/engine 4.9.2 → 4.9.3-next.0facab6

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;

package/src/engine/engine_physics.ts

@@ -592,7 +592,7 @@ namespace NEMeshBVH {
                 const timeSinceLastUpdate = now - skinnedMesh.staticGeometryLastUpdate!;
                 const interval = skinnedMesh.autoUpdateMeshBvhInterval ?? 100;
                 if (skinnedMeshBVHNeedsUpdate || timeSinceLastUpdate > interval) {
-                    if(debugPhysics) console.warn(`Physics: updating skinned mesh bvh for ${mesh.name} after ${timeSinceLastUpdate.toFixed(2)}ms`);
+                    if (debugPhysics) console.warn(`Physics: updating skinned mesh bvh for ${mesh.name} after ${timeSinceLastUpdate.toFixed(2)}ms`);
                     skinnedMesh.bvhNeedsUpdate = false;
                     skinnedMesh.staticGeometryLastUpdate = now;
                     skinnedMesh.staticGenerator?.generate(skinnedMesh.staticGeometry);
@@ -709,8 +709,11 @@ namespace NEMeshBVH {
             else {
                 if (debugPhysics) console.warn("No bounds tree found for mesh", mesh.name, { workerTask: geom[workerTaskSymbol], hasAcceleratedRaycast: _acceleratedRaycast != null });
                 if (options.allowSlowRaycastFallback === false) {
-                    if (debugPhysics) console.warn("Skipping raycast because no bounds tree is available and allowSlowRaycastFallback is false");
-                    return false;
+                    const vertices = geom.getAttribute("position")?.array?.length ?? 0;
+                    if (vertices > 2000) {
+                        if (debugPhysics) console.warn("Skipping raycast because no bounds tree is available and allowSlowRaycastFallback is false");
+                        return false;
+                    }
                 }
             }
             const prevFirstHitOnly = raycaster.firstHitOnly;

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

@@ -158,8 +158,18 @@ export class EngineLoadingView implements ILoadingViewHandler {
     private onDoneLoading() {
         if (this._loadingElement) {
             if (debug) console.log("Hiding loading element");
-            this._loadingElement.style.display = "none";
-            this._loadingElement.remove();
+            // animate alpha to 0
+            const element = this._loadingElement;
+            element.animate([
+                { opacity: 1 },
+                { opacity: 0 }
+            ], {
+                duration: 200,
+                easing: 'ease-in-out',
+            }).addEventListener('finish', () => {
+                element.style.display = "none";
+                element.remove();
+            });
         }
         if (this._progressLoop)
             clearInterval(this._progressLoop);
@@ -190,6 +200,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
                 loadingStyle = "light";
         }
 
+
         const hasLicense = hasProLicense();
         if (!existing) {
             this._loadingElement.style.position = "absolute";
@@ -197,6 +208,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
             this._loadingElement.style.height = "100%";
             this._loadingElement.style.left = "0";
             this._loadingElement.style.top = "0";
+            this._loadingElement.style.overflow = "hidden";
             const loadingBackgroundColor = this._element.getAttribute("loading-background");
             if (loadingBackgroundColor) {
                 this._loadingElement.style.background = loadingBackgroundColor;
@@ -227,24 +239,48 @@ export class EngineLoadingView implements ILoadingViewHandler {
         }
 
         const content = document.createElement("div");
+        content.style.cssText = `
+            position: relative;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            width: 100%;
+            height: 100%;
+            pointer-events: none;
+        `
         this._loadingElement.appendChild(content);
 
+        const poster = this._element.getAttribute("poster");
+        if (poster !== null && poster !== "0") {
+            const backgroundImage = document.createElement("div");
+            const backgroundBlur = poster?.length ? "0px" : "50px";
+            backgroundImage.style.cssText = `
+            position: absolute;
+            left: 0;
+            top: 0;
+            bottom: 0;
+            right: 0;
+            z-index: -1;
+            overflow: hidden;
+
+            margin: -${backgroundBlur};
+            background: url('${poster?.length ? poster : "/include/poster.webp"}') center center no-repeat;
+            background-size: cover;
+            filter: blur(${backgroundBlur});
+        `;
+            this._loadingElement.appendChild(backgroundImage);
+        }
+
         const logo = document.createElement("img");
-        const logoSize = 120;
-        logo.style.width = `${logoSize}px`;
-        logo.style.height = `${logoSize}px`;
-        logo.style.paddingTop = "20px";
-        logo.style.paddingBottom = "10px";
-        logo.style.margin = "0px";
+        const logoWidth = "80%";
+        const logoHeight = "15%";
+        const logoDelay = ".2s";
         logo.style.userSelect = "none";
         logo.style.objectFit = "contain";
-        logo.style.transition = "transform 1.5s ease-out, opacity .3s ease-in-out";
         logo.style.transform = "translateY(30px)";
-        logo.style.opacity = "0.05";
-        setTimeout(() => {
-            logo.style.opacity = "1";
-            logo.style.transform = "translateY(0px)";
-        }, 1);
+        logo.style.opacity = "0.0000001";
+        logo.style.transition = `transform 1s ease-out ${logoDelay}, opacity .3s ease-in-out ${logoDelay}`;
         logo.src = needleLogoOnlySVG;
         let isUsingCustomLogo = false;
         if (hasLicense && this._element) {
@@ -252,8 +288,15 @@ export class EngineLoadingView implements ILoadingViewHandler {
             if (customLogo) {
                 isUsingCustomLogo = true;
                 logo.src = customLogo;
+                setTimeout(() => {
+                    logo.style.opacity = "1";
+                    logo.style.transform = "translateY(0px)";
+                }, 1);
             }
         }
+
+        logo.style.width = `${logoWidth}`;
+        logo.style.height = `min(1000px, max(${logoHeight}, 50px))`;
         content.appendChild(logo);
 
         const details = document.createElement("div");
@@ -273,18 +316,14 @@ export class EngineLoadingView implements ILoadingViewHandler {
         const maxWidth = 100;
         loadingBarContainer.style.display = "flex";
         loadingBarContainer.style.width = maxWidth + "%";
-        loadingBarContainer.style.height = "3px";
+        loadingBarContainer.style.height = "5px";
         loadingBarContainer.style.position = "absolute";
         loadingBarContainer.style.left = "0";
-        loadingBarContainer.style.bottom = "0px";
+        loadingBarContainer.style.top = "0px";
         loadingBarContainer.style.opacity = "0";
-        loadingBarContainer.style.transition = "opacity 1s ease-in-out 2s";
+        loadingBarContainer.style.transition = "opacity 1s ease-in-out";
+        loadingBarContainer.style.backgroundColor = "rgba(240,240,240,.5)"
         setTimeout(() => { loadingBarContainer.style.opacity = "1"; }, 1);
-        if (loadingStyle === "light")
-            loadingBarContainer.style.backgroundColor = "rgba(0,0,0,.2)"
-        else
-            loadingBarContainer.style.backgroundColor = "rgba(255,255,255,.2)"
-        // loadingBarContainer.style.alignItems = "center";
 
         this._loadingElement.appendChild(loadingBarContainer);
 
@@ -294,9 +333,9 @@ export class EngineLoadingView implements ILoadingViewHandler {
         const getGradientPos = function (t: number): string {
             return Mathf.lerp(0, maxWidth, t) + "%";
         }
-        this._loadingBar.style.background = "#66A22F";
-            // `linear-gradient(90deg, #204f49 ${getGradientPos(0)}, #0BA398 ${getGradientPos(.3)}, #66A22F ${getGradientPos(.6)}, #D7DB0A ${getGradientPos(1)})`;
+        // `linear-gradient(90deg, #204f49 ${getGradientPos(0)}, #0BA398 ${getGradientPos(.3)}, #66A22F ${getGradientPos(.6)}, #D7DB0A ${getGradientPos(1)})`;
         this._loadingBar.style.backgroundAttachment = "fixed";
+        this._loadingBar.style.background = "#c4c4c4ab";
         this._loadingBar.style.width = "0%";
         this._loadingBar.style.height = "100%";
         if (hasLicense && this._element) {

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

@@ -85,12 +85,17 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
      * <needle-engine></needle-engine>
      * @returns {boolean | null} if the attribute is not set it returns null
      */
-    public get cameraControls(): boolean | null {
+    get cameraControls(): boolean | null {
         const attr = this.getAttribute("camera-controls") as NeedleEngineAttributes["camera-controls"] | ({} & string)
         if (attr == null) return null;
         if (attr === null || attr === "False" || attr === "false" || attr === "0" || attr === "none") return false;
         return true;
     }
+    set cameraControls(value: boolean | null) {
+        if (value === null) this.removeAttribute("camera-controls");
+        else this.setAttribute("camera-controls", value ? "true" : "false");
+    }
+    
 
     /**
      * Get the current context for this web component instance. The context is created when the src attribute is set and the loading has finished.  

package/src/engine/xr/NeedleXRSession.ts

@@ -1114,6 +1114,7 @@ export class NeedleXRSession implements INeedleXRSession {
         this.revertCustomForward();
         this._didStart = false;
         this._previousCameraParent = null;
+        this.requestedCameraNearPlane = null;
 
         unregisterFrameEventCallback(this.onBefore, FrameEvent.LateUpdate);
         const index = this.context.pre_render_callbacks.indexOf(this.onBeforeRender);
@@ -1412,8 +1413,14 @@ export class NeedleXRSession implements INeedleXRSession {
     }
 
     private onBeforeRender = () => {
-        if (this.context.mainCamera)
+        if (this.context.mainCamera) {
             this.updateFade(this.context.mainCamera);
+
+            if (this.requestedCameraNearPlane !== null && this.context.mainCamera instanceof PerspectiveCamera) {
+                this.context.mainCamera.near = this.requestedCameraNearPlane;
+                this.requestedCameraNearPlane = null;
+            }
+        }
     }
 
     private onAfterRender = () => {
@@ -1556,6 +1563,7 @@ export class NeedleXRSession implements INeedleXRSession {
     private _previousCameraParent!: Object3D | null;
     private readonly _customforward: boolean = true;
     private originalCameraNearPlane?: number;
+    private requestedCameraNearPlane: number | null = null;
     /** This is used to have the XR system camera look into threejs Z forward direction (instead of -z) */
     private applyCustomForward() {
         if (this.context.mainCamera && this._customforward) {
@@ -1567,15 +1575,22 @@ export class NeedleXRSession implements INeedleXRSession {
             this._cameraRenderParent.name = "XR Camera Render Parent";
             this._cameraRenderParent.add(this._camera);
 
-            let minNearPlane = .02;
-            if (this.rig) {
-                const rigWorldScale = getWorldScale(this.rig.gameObject);
-                minNearPlane *= rigWorldScale.x;
-            }
-            if (this._camera instanceof PerspectiveCamera && Math.abs(this._camera.near - minNearPlane) > .0001) {
-                this.originalCameraNearPlane = this._camera.near;
-                this._camera.near = minNearPlane;
-                if (debug) console.debug(`Setting camera near plane to ${minNearPlane} (was ${this.originalCameraNearPlane}) to account for XR rendering scale`);
+            {
+                let minNearPlane = .02;
+                const threshold = 0.001;
+                if (this.rig) {
+                    const rigWorldScale = getWorldScale(this.rig.gameObject);
+                    minNearPlane *= rigWorldScale.x;
+                }
+                if (this._camera instanceof PerspectiveCamera && Math.abs(this._camera.near - minNearPlane) > threshold) {
+                    // TODO: when we're in AR and update the near plane we do get glitchy rendering/sheered matrix transforms when scaling the scene (WebXRSessionRoot). As a workaround we defer AR near plane changes to before rendering but change VR near planes immediately.
+                    if (this.isAR)
+                        this.originalCameraNearPlane = this._camera.near;
+                    else {
+                        this._camera.near = minNearPlane;
+                    }
+                    if (debug) console.debug(`Setting camera near plane to ${minNearPlane} (was ${this.originalCameraNearPlane}) to account for XR rendering scale`);
+                }
             }
         }
     }

package/src/engine-components/AnimatorController.ts

@@ -276,7 +276,7 @@ export class AnimatorController {
      * @returns The found state or null if not found
      */
     FindState(name: string | number | undefined | null): State | null { return this.findState(name); }
-    
+
     /**
      * Finds an animation state by name or hash.
      * 
@@ -321,6 +321,25 @@ export class AnimatorController {
         return action;
     }
 
+    // addState(state: State, layerIndex: number = 0) {
+    //     if (!this.model) throw new Error("AnimatorController model is missing");
+    //     if (layerIndex < 0 || layerIndex >= this.model.layers.length) {
+    //         throw new Error(`Invalid layer index: ${layerIndex}`);
+    //     }
+    //     const layer = this.model.layers[layerIndex];
+    //     if (!layer.stateMachine) {
+    //         layer.stateMachine = { states: [], defaultState: 0 };
+    //     }
+    //     if (!layer.stateMachine.states) {
+    //         layer.stateMachine.states = [];
+    //     }
+    //     if (state.hash === undefined) {
+    //         state.hash = stringToHash(state.name || "state" + layer.stateMachine.states.length);
+    //     }
+
+    // }
+
+
     /**
      * The normalized time (0-1) to start playing the first state at.
      * This affects the initial state when the animator is first enabled.
@@ -331,7 +350,7 @@ export class AnimatorController {
      * The Animator component this controller is bound to.
      */
     animator?: Animator;
-    
+
     /**
      * The data model describing the animation states and transitions.
      */

package/src/engine-components/CameraUtils.ts

@@ -117,16 +117,15 @@ function createDefaultCameraControls(context: IContext, cam?: ICamera) {
     if (cameraObject) {
         const orbit = getOrAddComponent(cameraObject, OrbitControls) as OrbitControls;
         orbit.sourceId = cam?.sourceId ?? "unknown";
+        // /enable auto-rotate if the auto-rotate attribute is provided
         const autoRotate = context.domElement.getAttribute("auto-rotate");
-        orbit.autoRotate = autoRotate !== undefined && autoRotate !== null && (autoRotate != "0" && autoRotate?.toLowerCase() != "false");
-        orbit.autoRotateSpeed = 0.5;
-        orbit.autoFit = true;
-        if (orbit.autoRotate && autoRotate) {
-            const autoRotateValue = parseFloat(autoRotate);
-            if (!isNaN(autoRotateValue)) {
-                orbit.autoRotateSpeed = autoRotateValue;
-            }
-        }
+        orbit.autoRotate = autoRotate != "0" && autoRotate?.toLowerCase() != "false";
+        const autoRotateSpeed = Number.parseFloat(autoRotate || ".5");
+        orbit.autoRotateSpeed = !isNaN(autoRotateSpeed) ? autoRotateSpeed : .5;
+        console.log("Auto-rotate", orbit.autoRotate, "speed:", orbit.autoRotateSpeed);
+        const autoFit = context.domElement.getAttribute("auto-fit");
+        orbit.autoFit = autoFit !== "0" && autoFit?.toLowerCase() != "false";
+        orbit.autoTarget = true;
     }
     else {
         console.warn("Missing camera object, can not add orbit controls")

package/src/engine-components/OrbitControls.ts

@@ -2,18 +2,19 @@ import { Camera as Camera3, Object3D, PerspectiveCamera, Ray, Vector2, Vector3,
 import { OrbitControls as ThreeOrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
 
 import { isDevEnvironment } from "../engine/debug/index.js";
+import { fitCamera, FitCameraOptions } from "../engine/engine_camera.fit.js";
 import { setCameraController } from "../engine/engine_camera.js";
 import { Gizmos } from "../engine/engine_gizmos.js";
 import { InputEventQueue, NEPointerEvent } from "../engine/engine_input.js";
 import { Mathf } from "../engine/engine_math.js";
 import { IRaycastOptions, RaycastOptions } from "../engine/engine_physics.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
-import { getBoundingBox, getTempVector, getWorldPosition } from "../engine/engine_three_utils.js";
+import { getTempVector, getWorldPosition } from "../engine/engine_three_utils.js";
 import type { ICameraController } from "../engine/engine_types.js";
 import { DeviceUtilities, getParam } from "../engine/engine_utils.js";
+import { NeedleEngineWebComponent } from "../engine/webcomponents/needle-engine.js";
 import { Camera } from "./Camera.js";
 import { Behaviour, GameObject } from "./Component.js";
-import { GroundProjectedEnv } from "./GroundProjection.js";
 import { LookAtConstraint } from "./LookAtConstraint.js";
 import { SyncedTransform } from "./SyncedTransform.js";
 import { type AfterHandleInputEvent, EventSystem, EventSystemEvents } from "./ui/EventSystem.js";
@@ -354,6 +355,9 @@ export class OrbitControls extends Behaviour implements ICameraController {
         if (debug) console.debug("OrbitControls", this);
         this._didSetTarget = 0;
         this._startedListeningToKeyEvents = false;
+        if ((this.context.domElement as NeedleEngineWebComponent).cameraControls === false) {
+            this.enabled = false;
+        }
     }
 
     /** @internal */
@@ -490,10 +494,13 @@ export class OrbitControls extends Behaviour implements ICameraController {
                 this._lastTimeClickOnBackground = this.context.time.time;
                 if (this.clickBackgroundToFitScene <= 1 || dt < this.clickBackgroundToFitScene * .15) {
                     this._clickOnBackgroundCount += 1;
-                    if (this._clickOnBackgroundCount >= this.clickBackgroundToFitScene - 1)
-                        this.fitCamera(this.context.scene.children, {
-                            immediate: false
+                    if (this._clickOnBackgroundCount >= this.clickBackgroundToFitScene - 1) {
+                        this.autoRotate = false;
+                        this.fitCamera({
+                            objects: this.context.scene,
+                            immediate: false,
                         });
+                    }
                 }
                 else {
                     this._clickOnBackgroundCount = 0;
@@ -530,7 +537,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
     private _orbitStartAngle: number = 0;
     private _zoomStartDistance: number = 0;
     private onControlsChangeStarted = () => {
-        if(debug) console.debug("OrbitControls: Change started");
+        if (debug) console.debug("OrbitControls: Change started");
         if (this._controls) {
             this._orbitStartAngle = this._controls.getAzimuthalAngle() + this._controls.getPolarAngle();
             this._zoomStartDistance = this._controls.getDistance();
@@ -540,7 +547,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
         }
     }
     private onControlsChangeEnded = () => {
-        if(debug) console.debug("OrbitControls: Change ended", { autoTarget: this.autoTarget });
+        if (debug) console.debug("OrbitControls: Change ended", { autoTarget: this.autoTarget });
         if (this._controls) {
             if (this.autoTarget) {
                 const newAngle = this._controls.getAzimuthalAngle() + this._controls.getPolarAngle();
@@ -989,242 +996,26 @@ export class OrbitControls extends Behaviour implements ICameraController {
     /** 
      * Fits the camera to show the objects provided (defaults to the scene if no objects are passed in) 
     */
-    fitCamera(options?: FitCameraOptions);
-    fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<FitCameraOptions, "objects">);
-    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;
-        }
-
-        let objects: Object3D | Array<Object3D> | undefined = undefined;
-        // If the user passed in an array as first argument
-        if (Array.isArray(objectsOrOptions)) {
-            objects = objectsOrOptions;
-        }
-        // If the user passed in an object as first argument
-        else if (objectsOrOptions && "type" in objectsOrOptions) {
-            objects = objectsOrOptions;
-        }
-        // If the user passed in an object as first argument and options as second argument
-        else if (objectsOrOptions && typeof objectsOrOptions === "object") {
-            if (!(objectsOrOptions instanceof Object3D) && !Array.isArray(objectsOrOptions)) {
-                options = objectsOrOptions;
-                objects = options.objects;
-            }
-        }
-        // Ensure objects are setup correctly
-        if (objects && !Array.isArray(objects)) {
-            objects = [objects];
-        }
-        if (!Array.isArray(objects) || objects && objects.length <= 0) {
-            objects = this.context.scene.children;
-        }
-
-        // Make sure there's anything to fit to
-        if (!Array.isArray(objects) || objects.length <= 0) {
-            console.warn("No objects to fit camera to...");
-            return;
-        }
-
-        const camera = this._cameraObject as PerspectiveCamera;
-        const controls = this._controls as ThreeOrbitControls | null;
-
-        if (!camera || !controls) {
-            console.warn("No camera or controls found to fit camera to objects...");
-            return;
-        }
-        if (!options) 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 - 
-        // 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, this._camera?.threeCamera?.layers);
-        const boxCopy = box.clone();
-        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);
-        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, [...objects]);
-            return;
-        }
-        if (size.length() <= 0.0000000001) {
-            if (debugCameraFit) console.warn("Camera fit size is zero", box, [...objects]);
-            return;
-        }
-
-        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));
-
-        const distance = fitOffset * Math.max(fitHeightDistance, fitWidthDistance) + size.z / 2;
-
-        if (debugCameraFit) {
-            console.log("Fit camera to objects", { fitHeightDistance, fitWidthDistance, distance, verticalFov, horizontalFov });
-        }
-
-        this.maxZoom = distance * 10;
-        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);
-
-        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 = GameObject.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
-            camera.near = (distance / 100);
-            camera.far = boundsMax + distance * 10;
-            camera.updateProjectionMatrix();
-
-            // adjust maxZoom so that the ground projection radius is always inside
-            if (groundprojection) {
-                this.maxZoom = Math.max(Math.min(this.maxZoom, groundProjectionRadius * 0.5), distance);
-            }
-        }
-
-        // ensure we're not clipping out of the current zoom level just because we're fitting
-        const currentZoom = controls.getDistance();
-        if (currentZoom < this.minZoom) this.minZoom = currentZoom * 0.9;
-        if (currentZoom > this.maxZoom) this.maxZoom = 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 (debugCameraFit || options.debug) {
-            Gizmos.DrawWireBox3(box, 0xffff33, 10);
-            Gizmos.DrawWireBox3(boxCopy, 0x00ff00, 10);
-
-            if (!this._haveAttachedKeyboardEvents && debugCameraFit) {
-                this._haveAttachedKeyboardEvents = true;
-                document.body.addEventListener("keydown", (e) => {
-                    if (e.code === "KeyF") {
-                        // random fov for easier debugging of fov-based fitting
-                        let fov: number | undefined = undefined;
-                        if (this._cameraObject instanceof PerspectiveCamera) fov = (Math.random() * Math.random()) * 170 + 10;
-                        this.fitCamera({ objects, fitOffset, immediate: false, fov });
-                    }
-                    if (e.code === "KeyV") {
-                        if (this._cameraObject instanceof PerspectiveCamera) this._cameraObject.fov = 60;
-                    }
-                });
-            }
-        }
-
+    fitCamera(options?: OrbitFitCameraOptions): void {
+        const res = fitCamera({
+            ...options,
+            autoApply: false,
+            context: this.context,
+            camera: this._cameraObject as Camera3,
+            currentZoom: this._controls?.getDistance() || undefined,
+            minZoom: this.minZoom,
+            maxZoom: this.maxZoom,
+        });
+        if (!res) return;
+        this.setLookTargetPosition(res.lookAt, options?.immediate || false);
+        this.setCameraTargetPosition(res.position, options?.immediate || false);
+        this.setFieldOfView(options?.fov, options?.immediate || false);
         this.onBeforeRender();
-        // controls.update(); // this is not enough when calling fitCamera({immediate:true}) in an interval
     }
 
     private _haveAttachedKeyboardEvents: boolean = false;
 }
 
-
-/**
- * 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,
-    /**
-     * The objects to fit the camera to. If not provided the scene children will be used
-     */
-    objects?: Object3D[] | Object3D;
-    /** If true the camera will move immediately to the new position, otherwise it will lerp 
-     * @default false
-     */
+type OrbitFitCameraOptions = 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",
-
-    /**
-     * 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,
-}
+}