@needle-tools/engine 4.8.8-next.7387ba3 → 4.8.8-next.8add297

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/engine_gameobject.ts

@@ -166,9 +166,9 @@ export function destroy(instance: Object3D | Component, recursive: boolean = tru
         setDestroyed(obj, true);
         if (dispose) {
             disposeObjectResources(obj);
+            // This needs to be called after disposing because it removes the references to resources
+            __internalRemoveReferences(obj);
         }
-        // This needs to be called after disposing because it removes the references to resources
-        __internalRemoveReferences(obj);
     }
     destroyed_objects.length = 0;
     destroyed_components.length = 0;

package/src/engine/engine_gltf_builtin_components.ts

@@ -72,13 +72,13 @@ export async function createBuiltinComponents(context: Context, gltfId: SourceId
 
     if (gltf.scenes) {
         for (const scene of gltf.scenes) {
-            await onCreateBuiltinComponents(serializationContext, scene, deserializeQueue, lateResolve);
+            await onCreateBuiltinComponents(serializationContext, scene, deserializeQueue, lateResolve, 0);
         }
     }
     // TODO: when is the gltf here an object3d?
     if (gltf.children) {
         for (const ch of gltf.children) {
-            await onCreateBuiltinComponents(serializationContext, ch, deserializeQueue, lateResolve);
+            await onCreateBuiltinComponents(serializationContext, ch, deserializeQueue, lateResolve, 0);
         }
     }
 
@@ -202,7 +202,7 @@ const unknownComponentsBuffer: Array<string> = [];
 
 
 async function onCreateBuiltinComponents(context: SerializationContext, obj: Object3D,
-    deserialize: DeserializeData[], lateResolve: LateResolveCallback[]) {
+    deserialize: DeserializeData[], lateResolve: LateResolveCallback[], level: number) {
     if (!obj) return;
 
     // iterate injected data
@@ -267,20 +267,21 @@ async function onCreateBuiltinComponents(context: SerializationContext, obj: Obj
             }
             // console.debug("finished adding gltf builtin components", obj);
         }
-        if (unknownComponentsBuffer.length > 0) {
-            const unknown = unknownComponentsBuffer.join(", ");
-            console.warn("unknown components: " + unknown);
-            unknownComponentsBuffer.length = 0;
-            if (isLocalNetwork())
-                showBalloonMessage(`<strong>Unknown components in scene</strong>:\n\n${unknown}\n\nThis could mean you forgot to add a npmdef to your ExportInfo\n<a href="https://engine.needle.tools/docs/project_structure.html#creating-and-installing-a-npmdef" target="_blank">documentation</a>`, LogType.Warn);
-        }
     }
 
     if (obj.children) {
         for (const ch of obj.children) {
-            await onCreateBuiltinComponents(context, ch, deserialize, lateResolve);
+            await onCreateBuiltinComponents(context, ch, deserialize, lateResolve, level + 1);
         }
     }
+
+    if (unknownComponentsBuffer.length > 0 && level === 0) {
+        const unknown = unknownComponentsBuffer.join(", ");
+        console.warn(`Unknown components in scene: ${unknown}`);
+        unknownComponentsBuffer.length = 0;
+        if (isLocalNetwork())
+            showBalloonMessage(`<strong>Unknown components in scene</strong>:\n\n${unknown}\n\nThis could mean you forgot to add a npmdef to your ExportInfo\n<a href="https://engine.needle.tools/docs/project_structure.html#creating-and-installing-a-npmdef" target="_blank">documentation</a>`, LogType.Warn);
+    }
 }
 
 function handleDeserialization(data: DeserializeData, context: SerializationContext) {

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/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/extensions/NEEDLE_lightmaps.ts

@@ -70,7 +70,7 @@ export class NEEDLE_lightmaps implements GLTFLoaderPlugin {
                                 console.log(entry);
                             let res: Promise<any> | null = null;
                             // Check if the pointer is a json pointer:
-                            if (entry.pointer.startsWith("/textures/")) {
+                            if (entry.pointer.startsWith("/textures/") || /** legacy support e.g. SOC */entry.pointer.startsWith("textures/")) {
                                 if (debug) console.log("Load texture from gltf", entry.pointer);
                                 res = resolveReferences(this.parser, entry.pointer).then(res => this.resolveTexture(entry, res));
                             }

package/src/engine/js-extensions/Vector.ts

@@ -10,6 +10,12 @@ export function apply(object: Vector3) {
     }
 }
 
+// NOTE: keep in sync with method declarations below
+declare module 'three' {
+    export interface Vector3 {
+        slerp(end: Vector3, t: number): Vector3;
+    }
+}
 
 Vector3.prototype["slerp"] = function (end: Vector3, t: number) {
     return slerp(this, end, t);

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/ContactShadows.ts

@@ -1,4 +1,4 @@
-import { BackSide, CustomBlending, DoubleSide, FrontSide, Group, Material, Matrix4, MaxEquation, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshStandardMaterial, MinEquation, Object3D, OrthographicCamera, PlaneGeometry, RenderItem, ShaderMaterial, Vector3, WebGLRenderTarget } from "three";
+import { BackSide, CustomBlending, DoubleSide, FrontSide, Group, Material, Matrix4, MaxEquation, Mesh, MeshBasicMaterial, MeshDepthMaterial, MeshStandardMaterial, MinEquation, Object3D, OrthographicCamera, PlaneGeometry, RenderItem, ShaderMaterial, Vector3, Vector3Like, WebGLRenderTarget } from "three";
 import { HorizontalBlurShader } from 'three/examples/jsm/shaders/HorizontalBlurShader.js';
 import { VerticalBlurShader } from 'three/examples/jsm/shaders/VerticalBlurShader.js';
 
@@ -27,7 +27,14 @@ onStart(ctx => {
             shadows.darkness = intensity;
         }
     }
-})
+});
+
+
+type FitParameters = {
+    object?: Object3D | Object3D[];
+    positionOffset?: Partial<Vector3Like>;
+    scaleFactor?: Partial<Vector3Like>;
+}
 
 // Adapted from https://github.com/mrdoob/three.js/blob/master/examples/webgl_shadow_contact.html.
 
@@ -50,7 +57,7 @@ export class ContactShadows extends Behaviour {
      * @param context The context to create the contact shadows in.
      * @returns The instance of the contact shadows.
      */
-    static auto(context?: Context): ContactShadows {
+    static auto(context?: Context, params?: FitParameters): ContactShadows {
         if (!context) context = Context.Current;
         if (!context) {
             throw new Error("No context provided and no current context set.");
@@ -65,12 +72,13 @@ export class ContactShadows extends Behaviour {
             this._instances.set(context, instance);
         }
         context.scene.add(instance.gameObject);
-        instance.fitShadows();
+        instance.fitShadows(params);
         return instance;
     }
 
     /**
      * When enabled the contact shadows component will be created to fit the whole scene.
+     * @default false
      */
     @serializable()
     autoFit: boolean = false;
@@ -107,12 +115,14 @@ export class ContactShadows extends Behaviour {
 
     /**
      * The minimum size of the shadows box
+     * @default undefined
      */
     minSize?: Partial<Vec3>;
 
     /**
      * When enabled the shadows will not be updated automatically. Use `needsUpdate()` to update the shadows manually.
      * This is useful when you want to update the shadows only when the scene changes.
+     * @default false
      */
     manualUpdate: boolean = false;
     /**
@@ -150,10 +160,11 @@ export class ContactShadows extends Behaviour {
     /**
      * Call to fit the shadows to the scene.
      */
-    fitShadows() {
+    fitShadows(params: FitParameters = {}) {
         if (debug) console.warn("Fitting shadows to scene");
         setAutoFitEnabled(this.shadowsRoot, false);
-        const box = getBoundingBox(this.context.scene.children, [this.shadowsRoot]);
+        const objectToFit = params.object || this.context.scene;
+        const box = getBoundingBox(objectToFit, [this.shadowsRoot]);
         // expand box in all directions (except below ground)
         // 0.75 expands by 75% in each direction
         // The "32" is pretty much heuristically determined – adjusting the value until we don't get a visible border anymore.
@@ -175,6 +186,16 @@ export class ContactShadows extends Behaviour {
         // We can't move GroundProjection down because of immersive-ar mesh/plane tracking where occlusion would otherwise hide GroundProjection
         this.shadowsRoot.position.set((min.x + box.max.x) / 2, min.y - offset, (min.z + box.max.z) / 2);
         this.shadowsRoot.scale.set(box.max.x - min.x, box.max.y - min.y, box.max.z - min.z);
+        if (params.positionOffset) {
+            if (params.positionOffset.x !== undefined) this.shadowsRoot.position.x += params.positionOffset.x;
+            if (params.positionOffset.y !== undefined) this.shadowsRoot.position.y += params.positionOffset.y;
+            if (params.positionOffset.z !== undefined) this.shadowsRoot.position.z += params.positionOffset.z;
+        }
+        if (params.scaleFactor) {
+            if (params.scaleFactor.x !== undefined) this.shadowsRoot.scale.x *= params.scaleFactor.x;
+            if (params.scaleFactor.y !== undefined) this.shadowsRoot.scale.y *= params.scaleFactor.y;
+            if (params.scaleFactor.z !== undefined) this.shadowsRoot.scale.z *= params.scaleFactor.z;
+        }
         this.applyMinSize();
         this.shadowsRoot.matrixWorldNeedsUpdate = true;
         if (debug) console.log("Fitted shadows to scene", this.shadowsRoot.scale.clone());

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/NestedGltf.ts

@@ -4,6 +4,7 @@ import { InstantiateIdProvider } from "../engine/engine_networking_instantiate.j
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { getParam } from "../engine/engine_utils.js";
 import { Behaviour } from "../engine-components/Component.js";
+import { EventList } from "./EventList.js";
 
 const debug = getParam("debugnestedgltf");
 
@@ -11,17 +12,21 @@ const debug = getParam("debugnestedgltf");
  * It will load the gltf file and instantiate it as a child of the parent of the GameObject that has this component
  */
 export class NestedGltf extends Behaviour {
-    /**
-     * A reference to the gltf file that should be loaded
-     */
+
+    /**  A reference to the gltf file that should be loaded */
     @serializable(AssetReference)
     filePath?: AssetReference;
 
+    /** Invoked when the nested glTF file has been instantiated */
+    @serializable(EventList)
+    loaded: EventList<{ component: NestedGltf, instance: any, asset: AssetReference }> = new EventList();
+
     /**
      * EXPERIMENTAL for cloud asset loading
      */
     loadAssetInParent = true;
 
+
     private _isLoadingOrDoneLoading: boolean = false;
 
     /** Register a callback that will be called when the progress of the loading changes */
@@ -31,7 +36,7 @@ export class NestedGltf extends Behaviour {
 
     /** Begin loading the referenced gltf file in filePath */
     preload() {
-        this.filePath?.preload();
+        return this.filePath?.preload() || null;
     }
 
     /** @internal */
@@ -41,27 +46,31 @@ export class NestedGltf extends Behaviour {
 
         const parent = this.gameObject.parent;
         if (parent) {
-            this._isLoadingOrDoneLoading = true;
-            const opts = new InstantiateOptions();
-            // we need to provide stable guids for creating nested gltfs
-            opts.idProvider = new InstantiateIdProvider(this.hash(this.guid));
-            opts.parent = this.loadAssetInParent !== false ? parent : this.gameObject;
-            this.gameObject.updateMatrix();
-            const matrix = this.gameObject.matrix;
-            if (debug) console.log("Load nested:", this.filePath?.url ?? this.filePath, this.gameObject.position);
-            const res = await this.filePath?.instantiate?.call(this.filePath, opts);
-            if (debug) console.log("Nested loaded:", this.filePath?.url ?? this.filePath, res);
-            if (res && this.loadAssetInParent !== false) {
-                res.matrixAutoUpdate = false;
-                res.matrix.identity();
-                res.applyMatrix4(matrix);
-                res.matrixAutoUpdate = true;
-                res.layers.disableAll();
-                res.layers.set(this.layer);
-
-                this.dispatchEvent(new CustomEvent("loaded", { detail: { instance: res, assetReference: this.filePath } }));
+
+            if (this.filePath) {
+
+                this._isLoadingOrDoneLoading = true;
+                const opts = new InstantiateOptions();
+                // we need to provide stable guids for creating nested gltfs
+                opts.idProvider = new InstantiateIdProvider(this.hash(this.guid));
+                opts.parent = this.loadAssetInParent !== false ? parent : this.gameObject;
+                this.gameObject.updateMatrix();
+                const matrix = this.gameObject.matrix;
+                if (debug) console.log("Load nested:", this.filePath?.url ?? this.filePath, this.gameObject.position);
+                const res = await this.filePath?.instantiate?.call(this.filePath, opts);
+                if (debug) console.log("Nested loaded:", this.filePath?.url ?? this.filePath, res);
+                if (res && this.loadAssetInParent !== false) {
+                    res.matrixAutoUpdate = false;
+                    res.matrix.identity();
+                    res.applyMatrix4(matrix);
+                    res.matrixAutoUpdate = true;
+                    res.layers.disableAll();
+                    res.layers.set(this.layer);
+                    this.loaded.invoke({ component: this, instance: res, asset: this.filePath });
+                }
+                if (debug) console.log("Nested loading done:", this.filePath?.url ?? this.filePath, res);
             }
-            if (debug) console.log("Nested loading done:", this.filePath?.url ?? this.filePath, res);
+
         }
     }
 

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 - 
@@ -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);
@@ -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,7 +1176,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 +1188,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/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