@needle-tools/engine 4.8.8-next.5cb3196 → 4.8.8-next.68a4ed9

package/src/engine/engine_animation.ts

@@ -120,7 +120,7 @@ export class AnimationUtils {
                     }
                 }
 
-                let animationComponent = findAnimationGameObjectInParent(obj) || findAnimationGameObjectInParent(scene);
+                let animationComponent = findAnimationComponentInParent(obj) || findAnimationComponentInParent(scene);
                 if (!animationComponent) {
                     const anim = TypeStore.get("Animation");
                     animationComponent = scene.addComponent(anim);
@@ -137,18 +137,18 @@ export class AnimationUtils {
         }
         return animationComponents;
 
-        function findAnimationGameObjectInParent(obj): IAnimationComponent | null {
+        function findAnimationComponentInParent(obj): IAnimationComponent | null {
             if (!obj) return null;
             const components = obj.userData?.components;
             if (components && components.length > 0) {
                 for (let i = 0; i < components.length; i++) {
                     const component = components[i] as IAnimationComponent;
                     if (component.isAnimationComponent === true) {
-                        return obj;
+                        return component;
                     }
                 }
             }
-            return findAnimationGameObjectInParent(obj.parent);
+            return findAnimationComponentInParent(obj.parent);
         }
     }
 }

package/src/engine/engine_assetdatabase.ts

@@ -61,7 +61,7 @@ export function disposeObjectResources(obj: object | null | undefined) {
         return;
     }
 
-    if(typeof obj === "object") {
+    if (typeof obj === "object") {
         obj[$disposed] = true;
     }
 
@@ -79,8 +79,8 @@ export function disposeObjectResources(obj: object | null | undefined) {
         disposeObjectResources(obj.bindMatrixInverse);
         disposeObjectResources(obj.customDepthMaterial);
         disposeObjectResources(obj.customDistanceMaterial);
-        obj.geometry = null;
-        obj.material = null;
+        obj.geometry = {};
+        obj.material = {};
         obj.visible = false;
     }
     else if (obj instanceof Mesh) {
@@ -88,8 +88,8 @@ export function disposeObjectResources(obj: object | null | undefined) {
         disposeObjectResources(obj.material);
         disposeObjectResources(obj.customDepthMaterial);
         disposeObjectResources(obj.customDistanceMaterial);
-        obj.geometry = null;
-        obj.material = null;
+        obj.geometry = {};
+        obj.material = {};
         obj.visible = false;
     }
     else if (obj instanceof BufferGeometry) {
@@ -175,8 +175,8 @@ function free(obj: any) {
 
 export function __internalNotifyObjectDestroyed(obj: Object3D) {
     if (obj instanceof Mesh || obj instanceof SkinnedMesh) {
-        obj.material = null;
-        obj.geometry = null;
+        obj.material = {};
+        obj.geometry = {};
     }
 }
 

package/src/engine/engine_camera.ts

@@ -42,7 +42,9 @@ export function setAutoFitEnabled(obj: Object3D, enabled: boolean): void {
 
 
 
-
+export type FocusRectSettings = {
+    damping: number
+}
 export type FocusRect = DOMRect | Element | { x: number, y: number, width: number, height: number };
 
 let rendererRect: DOMRect | undefined = undefined;

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/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/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-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/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/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