@needle-tools/engine 4.1.0-experimental.13 → 4.1.1

package/src/engine/engine_physics_rapier.ts

@@ -1,5 +1,4 @@
 import type { Ball, Collider, ColliderDesc, Cuboid, EventQueue, QueryFilterFlags, Ray, RigidBody, RigidBodyDesc, World } from '@dimforge/rapier3d-compat';
-
 import { BufferAttribute, BufferGeometry, InterleavedBufferAttribute, LineBasicMaterial, LineSegments, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from 'three'
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
 
@@ -10,6 +9,7 @@ import { ContextEvent, ContextRegistry } from './engine_context_registry.js';
 import { foreachComponent } from './engine_gameobject.js';
 import { Gizmos } from './engine_gizmos.js';
 import { Mathf } from './engine_math.js';
+import { MODULES } from './engine_modules.js';
 import { getWorldPosition, getWorldQuaternion, getWorldScale, setWorldPositionXYZ, setWorldQuaternionXYZW } from "./engine_three_utils.js"
 import type {
     IBoxCollider,
@@ -26,7 +26,6 @@ import type {
 import { Collision, ContactPoint } from './engine_types.js';
 import { SphereOverlapResult } from './engine_types.js';
 import { CircularBuffer, getParam } from "./engine_utils.js"
-import { MODULES } from './engine_modules.js';
 
 const debugPhysics = getParam("debugphysics");
 const debugColliderPlacement = getParam("debugcolliderplacement");
@@ -51,12 +50,8 @@ if (NEEDLE_USE_RAPIER) {
     ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, evt => {
         if (debugPhysics)
             console.log("Register rapier physics backend")
-        evt.context.physics.engine = new RapierPhysics();
-        // We want the physics engine to be initialized on start so when components start to enable and modify values they don't have delays
-        // TODO: should the promise be returned here to make the engine creation wait?
-        if (NEEDLE_USE_RAPIER) {
-            evt.context.physics.engine.initialize(evt.context);
-        }
+        evt.context.physics.engine = new RapierPhysics(evt.context);
+        // We do not initialize physics immediately to avoid loading the physics engine if it is not needed
     });
 }
 
@@ -238,12 +233,17 @@ export class RapierPhysics implements IPhysicsEngine {
         else console.warn("Rigidbody doesn't exist: can not set linear velocity (does your object with the Rigidbody have a collider?)");
     }
 
-    private context?: IContext;
+    private readonly context?: IContext;
     private _initializePromise?: Promise<boolean>;
     private _isInitialized: boolean = false;
 
-    async initialize(context: IContext) {
-        this.context = context;
+    constructor(ctx: IContext) {
+        this.context = ctx;
+    }
+
+    get isInitialized() { return this._isInitialized; }
+
+    async initialize() {
         if (!this._initializePromise)
             this._initializePromise = this.internalInitialization();
         return this._initializePromise;
@@ -270,7 +270,7 @@ export class RapierPhysics implements IPhysicsEngine {
         }
         this._hasCreatedWorld = true;
         if (MODULES.RAPIER_PHYSICS.MAYBEMODULE == undefined) {
-            if(debugPhysics) console.trace("Loading rapier physics engine");
+            if (debugPhysics) console.trace("Loading rapier physics engine");
             const module = await MODULES.RAPIER_PHYSICS.load();
             await module.init();
         }
@@ -317,6 +317,11 @@ export class RapierPhysics implements IPhysicsEngine {
     })
         : null | { point: Vector3, collider: ICollider } {
 
+        if (!this._isInitialized) {
+            console.log("Physics engine is not initialized");
+            return null;
+        }
+
         let maxDistance = options?.maxDistance;
         let solid = options?.solid;
 
@@ -363,6 +368,10 @@ export class RapierPhysics implements IPhysicsEngine {
     })
         : null | { point: Vector3, normal: Vector3, collider: ICollider } {
 
+        if (!this._isInitialized) {
+            return null;
+        }
+
         let maxDistance = options?.maxDistance;
         let solid = options?.solid;
 
@@ -449,7 +458,7 @@ export class RapierPhysics implements IPhysicsEngine {
 
 
     private rapierSphere: Ball | null = null;
-    private rapierColliderArray: Array<SphereOverlapResult> = [];
+    private readonly rapierColliderArray: Array<SphereOverlapResult> = [];
     private readonly rapierIdentityRotation = { x: 0, y: 0, z: 0, w: 1 };
     private readonly rapierForwardVector = { x: 0, y: 0, z: 1 };
     /** Precice sphere overlap detection using rapier against colliders
@@ -459,6 +468,9 @@ export class RapierPhysics implements IPhysicsEngine {
      */
     public sphereOverlap(point: Vector3, radius: number): Array<SphereOverlapResult> {
         this.rapierColliderArray.length = 0;
+        if (!this._isInitialized) {
+            return this.rapierColliderArray;
+        }
         if (!this.world) return this.rapierColliderArray;
         this.rapierSphere ??= new MODULES.RAPIER_PHYSICS.MODULE.Ball(radius);
         this.rapierSphere.radius = radius;
@@ -574,7 +586,7 @@ export class RapierPhysics implements IPhysicsEngine {
 
     async addBoxCollider(collider: ICollider, size: Vector3) {
         if (!this._isInitialized)
-            await this.initialize(collider.context);
+            await this.initialize();
         if (!collider.activeAndEnabled) return;
 
         if (!this.enabled) {
@@ -608,7 +620,7 @@ export class RapierPhysics implements IPhysicsEngine {
 
     async addSphereCollider(collider: ICollider) {
         if (!this._isInitialized)
-            await this.initialize(collider.context);
+            await this.initialize();
         if (!collider.activeAndEnabled) return;
         if (!this.enabled) {
             if (debugPhysics) console.warn("Physics are disabled");
@@ -621,7 +633,7 @@ export class RapierPhysics implements IPhysicsEngine {
 
     async addCapsuleCollider(collider: ICollider, height: number, radius: number) {
         if (!this._isInitialized)
-            await this.initialize(collider.context);
+            await this.initialize();
         if (!collider.activeAndEnabled) return;
         if (!this.enabled) {
             if (debugPhysics) console.warn("Physics are disabled");
@@ -640,14 +652,9 @@ export class RapierPhysics implements IPhysicsEngine {
         this.createCollider(collider, desc);
     }
 
-    async addMeshCollider(collider: ICollider, mesh: Mesh, convex: boolean, scale: Vector3) {
-        if (!this._isInitialized)
-            await this.initialize(collider.context);
-        if (!collider.activeAndEnabled) return;
-        if (!this.enabled) {
-            if (debugPhysics) console.warn("Physics are disabled");
-            return;
-        }
+    async addMeshCollider(collider: ICollider, mesh: Mesh, convex: boolean, extraScale?: Vector3) {
+        
+        // capture the geometry before waiting for phyiscs engine
         let geo = mesh.geometry;
         if (!geo) {
             if (debugPhysics) console.warn("Missing mesh geometry", mesh.name);
@@ -679,12 +686,25 @@ export class RapierPhysics implements IPhysicsEngine {
             positions = positionAttribute.array as Float32Array;
         }
 
+        await this.initialize();
+
+        if (!this.enabled) {
+            if (debugPhysics) console.warn("Physics are disabled");
+            return;
+        }
+
+        if (!collider.activeAndEnabled) return;
+        
+
         // let positions = geo.getAttribute("position").array as Float32Array;
         const indices = geo.index?.array as Uint32Array;
+        
+        const scale = collider.gameObject.worldScale.clone();
+        if(extraScale) scale.multiply(extraScale);
 
         // scaling seems not supported yet https://github.com/dimforge/rapier/issues/243
         if (Math.abs(scale.x - 1) > 0.0001 || Math.abs(scale.y - 1) > 0.0001 || Math.abs(scale.z - 1) > 0.0001) {
-            const key = geo.uuid + "_" + scale.x + "_" + scale.y + "_" + scale.z + "_" + convex;
+            const key = `${geo.uuid}_${scale.x}_${scale.y}_${scale.z}_${convex}`;
             if (this._meshCache.has(key)) {
                 if (debugPhysics) console.warn("Use cached mesh collider")
                 positions = this._meshCache.get(key)!;
@@ -701,7 +721,9 @@ export class RapierPhysics implements IPhysicsEngine {
                 this._meshCache.set(key, scaledPositions);
             }
         }
-        const desc = convex ? MODULES.RAPIER_PHYSICS.MODULE.ColliderDesc.convexHull(positions) : MODULES.RAPIER_PHYSICS.MODULE.ColliderDesc.trimesh(positions, indices);
+        const desc = convex
+            ? MODULES.RAPIER_PHYSICS.MODULE.ColliderDesc.convexHull(positions)
+            : MODULES.RAPIER_PHYSICS.MODULE.ColliderDesc.trimesh(positions, indices);
         if (desc) {
             this.createCollider(collider, desc);
             // col.setMassProperties(1, { x: 0, y: 0, z: 0 }, { x: 0, y: 0, z: 0 }, { x: 0, y: 0, z: 0, w: 1 });

package/src/engine/engine_scenetools.ts

@@ -183,10 +183,14 @@ export async function parseSync(context: Context, data: string | ArrayBuffer, pa
             // https://threejs.org/docs/#examples/en/loaders/GLTFLoader.parse
             // so we make sure that "path" is never a file path
             let gltfLoaderPath = path.split("?")[0].trimEnd();
-            if (gltfLoaderPath.endsWith(".glb") || gltfLoaderPath.endsWith(".gltf")) {
+            // This assumes that the path is a FILE path and not already a directory
+            // (it does not end with "/") – see https://linear.app/needle/issue/NE-6075
+            {
                 // strip file from path
                 const parts = gltfLoaderPath.split("/");
-                parts.pop();
+                // check if the last part is a /, otherwise remove it
+                if (parts.length > 0 && parts[parts.length - 1] !== "")
+                    parts.pop();
                 gltfLoaderPath = parts.join("/");
                 if (!gltfLoaderPath.endsWith("/")) gltfLoaderPath += "/";
             }

package/src/engine/engine_types.ts

@@ -90,6 +90,12 @@ export declare interface INeedleEngineComponent extends HTMLElement {
     onExitAR(session: XRSession);
 }
 
+export enum HideFlags {
+    None = 0,
+    /** When enabled the glTF exporter will omit this object and all children from being exported */
+    DontExport = 1 << 0,
+}
+
 export declare interface IGameObject extends Object3D {
 
     /** the object's unique identifier */
@@ -290,6 +296,7 @@ export declare interface IBoxCollider extends ICollider {
 }
 
 export declare interface IRigidbody extends IComponent {
+    get isRigidbody(): boolean;
     constraints: RigidbodyConstraints;
     isKinematic: boolean;
     /** When true the mass will automatically calculated by attached colliders */
@@ -435,7 +442,8 @@ export class SphereOverlapResult {
 
 
 export interface IPhysicsEngine {
-    initialize(ctx: IContext): Promise<boolean>;
+    initialize(): Promise<boolean>;
+    get isInitialized(): boolean;
     step(dt: number): void;
     postStep();
     get isUpdating(): boolean;
@@ -488,7 +496,7 @@ export interface IPhysicsEngine {
     addSphereCollider(collider: ICollider);
     addBoxCollider(collider: ICollider, size: Vector3);
     addCapsuleCollider(collider: ICollider, radius: number, height: number);
-    addMeshCollider(collider: ICollider, mesh: Mesh, convex: boolean, scale: Vector3);
+    addMeshCollider(collider: ICollider, mesh: Mesh, convex: boolean, scale?: Vector3 | undefined);
 
     updatePhysicsMaterial(collider: ICollider);
 

package/src/engine/export/gltf/Writers.ts

@@ -1,4 +1,3 @@
-
 import { Object3D, Texture } from 'three';
 import { GLTFExporterPlugin, GLTFWriter } from 'three/examples/jsm/exporters/GLTFExporter.js';
 

package/src/engine/export/gltf/index.ts

@@ -6,6 +6,7 @@ import { AnimationUtils } from "../../engine_animation.js";
 import type { Context } from "../../engine_setup.js";
 import { registerExportExtensions } from "../../extensions/index.js";
 import { __isExporting } from "../state.js";
+import { shouldExport_HideFlags } from "../utils.js";
 import { GizmoWriter as GLTFGizmoWriter, RenderTextureWriter as GLTFRenderTextureWriter } from "./Writers.js";
 
 declare type ExportOptions = {
@@ -49,8 +50,7 @@ export async function exportAsGLTF(_opts: ExportOptions): Promise<ArrayBuffer |
         animations: collectAnimations(context, opts.scene, []),
     }
     const state = new ExporterState();
-
-    console.log("Exporting GLTF", exporterOptions);
+    console.debug("Exporting GLTF", exporterOptions);
     state.onBeforeExport(opts);
     __isExporting(true);
     const res = await exporter.parseAsync(opts.scene, exporterOptions).catch((e) => {
@@ -108,7 +108,17 @@ class ExporterState {
                 }
             }
             mixer.update(0);
-        })
+        });
+
+        opts.context.scene.traverse(obj => {
+            if(!shouldExport_HideFlags(obj)) {
+                const parent = obj.parent;
+                if(parent) {
+                    obj.removeFromParent();
+                    this._undo.push(() => parent.add(obj));
+                }
+            }
+        });
     }
 
     onAfterExport(_opts: Required<ExportOptions>) {

package/src/engine/export/index.ts

@@ -1,2 +1,2 @@
 export * from "./gltf/index.js";
-export { isExporting } from "./state.js";
+export { isExporting } from "./state.js";

package/src/engine/export/utils.ts

@@ -0,0 +1,10 @@
+import { Object3D } from "three";
+
+import { HideFlags } from "../engine_types.js";
+
+
+export function shouldExport_HideFlags(obj: Object3D) {
+    const dontExport = HideFlags.DontExport;
+    if (obj.hideFlags & dontExport) return false;
+    return true;
+}

package/src/engine/extensions/NEEDLE_gameobject_data.ts

@@ -7,7 +7,6 @@ declare type GameObjectData = {
     layers: number,
     visible: boolean,
     tag: string,
-    hideFlags: number,
     static: boolean,
     activeSelf: boolean,
     guid: string
@@ -71,7 +70,7 @@ export class NEEDLE_gameobject_data implements GLTFLoaderPlugin {
 
         node.userData.tag = ext.tag ?? "none";
 
-        node.userData.hideFlags = ext.hideFlags ?? 0;
+        node.hideFlags = 0;
 
         node.userData.static = ext.static ?? false;
 

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

@@ -15,7 +15,7 @@ import {
     setWorldScale
 }
     from "../../engine/engine_three_utils.js";
-import type { ComponentInit, Constructor, ConstructorConcrete, IComponent as Component, IComponent } from "../../engine/engine_types.js";
+import type { ComponentInit, Constructor, ConstructorConcrete, HideFlags,IComponent as Component, IComponent } from "../../engine/engine_types.js";
 import { applyPrototypeExtensions, registerPrototypeExtensions } from "./ExtensionUtils.js";
 
 
@@ -26,6 +26,11 @@ declare module 'three' {
         get guid(): string | undefined;
         set guid(value: string | undefined);
 
+        /**
+         * Allows to control e.g. if an object should be exported
+         */
+        hideFlags: HideFlags;
+
         /**
          * Add a Needle Engine component to the {@link Object3D}.
          * @param comp The component instance or constructor to add.

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

@@ -1,7 +1,7 @@
 import type { Context } from "../../engine_context.js";
 import { hasCommercialLicense, onLicenseCheckResultChanged } from "../../engine_license.js";
 import { isLocalNetwork } from "../../engine_networking_utils.js";
-import { DeviceUtilities,getParam } from "../../engine_utils.js";
+import { DeviceUtilities, getParam } from "../../engine_utils.js";
 import { onXRSessionStart, XRSessionEventArgs } from "../../xr/events.js";
 import { ButtonsFactory } from "../buttons.js";
 import { ensureFonts, iconFontUrl, loadFont } from "../fonts.js";
@@ -256,7 +256,12 @@ export class NeedleMenuElement extends HTMLElement {
         if (!element && domElement.shadowRoot) {
             element = domElement.shadowRoot.querySelector(elementName);
         }
+        // if no needle-menu was found in the domelement then we search the document body
         if (!element) {
+            element = window.document.body.querySelector(elementName) as NeedleMenuElement | null;
+        }
+        if (!element) {
+            // OK no menu element exists yet anywhere
             element = NeedleMenuElement.create() as NeedleMenuElement;
             if (domElement.shadowRoot)
                 domElement.shadowRoot.appendChild(element);
@@ -682,14 +687,15 @@ export class NeedleMenuElement extends HTMLElement {
         });
 
         try {
-        // if the user has a license then we CAN hide the needle logo
-        onLicenseCheckResultChanged(res => {
-            if (res == true && hasCommercialLicense() && !debugNonCommercial) {
-                let visible = this._userRequestedLogoVisible;
-                if(visible === undefined) visible = false;
-                this.#onSetLogoVisible(visible);
-            }
-        });
+            // if the user has a license then we CAN hide the needle logo
+            // calling this method immediately will cause an issue with vite bundling tho
+            window.requestAnimationFrame(() => onLicenseCheckResultChanged(res => {
+                if (res == true && hasCommercialLicense() && !debugNonCommercial) {
+                    let visible = this._userRequestedLogoVisible;
+                    if (visible === undefined) visible = false;
+                    this.#onSetLogoVisible(visible);
+                }
+            }));
         } catch (e) {
             console.error("[Needle Menu] License check failed.", e);
         }
@@ -824,7 +830,7 @@ export class NeedleMenuElement extends HTMLElement {
         this.logoContainer.style.display = "";
         this.logoContainer.style.opacity = "1";
         this.logoContainer.style.visibility = "visible";
-        if(visible) { 
+        if (visible) {
             this.root.classList.remove("logo-hidden");
             this.root.classList.add("logo-visible");
         }

package/src/engine/xr/NeedleXRSession.ts

@@ -582,7 +582,7 @@ export class NeedleXRSession implements INeedleXRSession {
      * The XRSession interface's read-only interactionMode property describes the best space (according to the user agent) for the application to draw an interactive UI for the current session.
      * @link https://developer.mozilla.org/en-US/docs/Web/API/XRSession/interactionMode 
      */
-    get interactionMode(): "screen-space" | "world-space" { return this.session["interactionMode"]; }
+    get interactionMode(): "screen-space" | "world-space" { return this.session["interactionMode"]!; }
 
     /**
      * @link https://developer.mozilla.org/en-US/docs/Web/API/XRSession/visibilityState
@@ -712,8 +712,11 @@ export class NeedleXRSession implements INeedleXRSession {
     /** Sets a XRRig to be active which will parent the camera to this rig */
     setRigActive(rig: IXRRig) {
         const i = this._rigs.indexOf(rig);
+        const currentlyActive = this._rigs[0];
         this._rigs.splice(i, 1);
         this._rigs.unshift(rig);
+        // if there's another rig currently active we need to make sure we have at least the same priority
+        rig.priority = currentlyActive?.priority ?? 0;
         this.updateActiveXRRig();
     }
     /**

package/src/engine-components/AvatarLoader.ts

@@ -52,7 +52,7 @@ export class AvatarLoader {
             if (!root) {
                 const opts = new InstantiateOptions();
                 // opts.parent = context.scene.uuid;
-                root = GameObject.instantiate(utils.tryFindObject(avatarId, context.scene), opts);
+                root = GameObject.instantiate(utils.tryFindObject(avatarId, context.scene) as Object3D, opts);
             }
         }
         else root = avatarId;

package/src/engine-components/Camera.ts

@@ -51,7 +51,7 @@ export class Camera extends Behaviour implements ICamera {
             }
         }
     }
-    /** The camera's field of view in degrees if it is a perspective camera */
+    /** The camera's field of view in degrees if it is a perspective camera. Calls updateProjectionMatrix when set */
     get fieldOfView(): number | undefined {
         if (this._cam instanceof PerspectiveCamera) {
             return this._cam.fov;
@@ -74,7 +74,7 @@ export class Camera extends Behaviour implements ICamera {
         }
     }
 
-    /** The camera's near clipping plane */
+    /** The camera's near clipping plane. Calls updateProjectionMatrix when set */
     get nearClipPlane(): number { return this._nearClipPlane; }
     @serializable()
     set nearClipPlane(val) {
@@ -87,15 +87,7 @@ export class Camera extends Behaviour implements ICamera {
     }
     private _nearClipPlane: number = 0.1;
 
-    applyClippingPlane() {
-        if (this._cam) {
-            this._cam.near = this._nearClipPlane;
-            this._cam.far = this._farClipPlane;
-            this._cam.updateProjectionMatrix();
-        }
-    }
-
-    /** The camera's far clipping plane */
+    /** The camera's far clipping plane. Calls updateProjectionMatrix when set */
     get farClipPlane(): number { return this._farClipPlane; }
     @serializable()
     set farClipPlane(val) {
@@ -108,6 +100,17 @@ export class Camera extends Behaviour implements ICamera {
     }
     private _farClipPlane: number = 1000;
 
+    /**
+     * Applys both the camera's near and far plane and calls updateProjectionMatrix on the camera.
+     */
+    applyClippingPlane() {
+        if (this._cam) {
+            this._cam.near = this._nearClipPlane;
+            this._cam.far = this._farClipPlane;
+            this._cam.updateProjectionMatrix();
+        }
+    }
+
     /** The camera's clear flags - determines if the background is a skybox or a solid color or transparent */
     @serializable()
     public get clearFlags(): ClearFlags {

package/src/engine-components/Collider.ts

@@ -207,12 +207,12 @@ export class MeshCollider extends Collider {
         const LOD = 0;
 
         if (this.sharedMesh?.isMesh) {
-            this.context.physics.engine.addMeshCollider(this, this.sharedMesh, this.convex, getWorldScale(this.gameObject));
+            this.context.physics.engine.addMeshCollider(this, this.sharedMesh, this.convex);
             NEEDLE_progressive.assignMeshLOD(this.sharedMesh, LOD).then(res => {
                 if (res && this.activeAndEnabled && this.context.physics.engine && this.sharedMesh) {
                     this.context.physics.engine.removeBody(this);
                     this.sharedMesh.geometry = res;
-                    this.context.physics.engine.addMeshCollider(this, this.sharedMesh, this.convex, getWorldScale(this.gameObject));
+                    this.context.physics.engine.addMeshCollider(this, this.sharedMesh, this.convex);
                 }
             })
         }
@@ -224,7 +224,7 @@ export class MeshCollider extends Collider {
                 for (const ch in group.children) {
                     const child = group.children[ch] as Mesh;
                     if (child.isMesh) {
-                        this.context.physics.engine.addMeshCollider(this, child, this.convex, getWorldScale(this.gameObject));
+                        this.context.physics.engine.addMeshCollider(this, child, this.convex);
                         promises.push(NEEDLE_progressive.assignMeshLOD(child, LOD));
                     }
                 }
@@ -235,7 +235,7 @@ export class MeshCollider extends Collider {
                     for (const r of res) {
                         if (r && this.activeAndEnabled) {
                             mesh.geometry = r;
-                            this.context.physics.engine?.addMeshCollider(this, mesh, this.convex, getWorldScale(this.gameObject));
+                            this.context.physics.engine?.addMeshCollider(this, mesh, this.convex);
                         }
                     }
                 });

package/src/engine-components/Component.ts

@@ -1,9 +1,10 @@
 import { Euler, Object3D, Quaternion, Scene, Vector3 } from "three";
 
 import { isDevEnvironment } from "../engine/debug/index.js";
+import { type AssetReference } from "../engine/engine_addressables.js";
 import { addComponent, destroyComponentInstance, findObjectOfType, findObjectsOfType, getComponent, getComponentInChildren, getComponentInParent, getComponents, getComponentsInChildren, getComponentsInParent, getOrAddComponent, removeComponent } from "../engine/engine_components.js";
 import { activeInHierarchyFieldName } from "../engine/engine_constants.js";
-import { destroy, findByGuid, foreachComponent, HideFlags, type IInstantiateOptions, instantiate, isActiveInHierarchy, isActiveSelf, isDestroyed, isUsingInstancing, markAsInstancedRendered, setActive } from "../engine/engine_gameobject.js";
+import { destroy, findByGuid, foreachComponent, type IInstantiateOptions, instantiate, isActiveInHierarchy, isActiveSelf, isDestroyed, isUsingInstancing, markAsInstancedRendered, setActive } from "../engine/engine_gameobject.js";
 import * as main from "../engine/engine_mainloop_utils.js";
 import { syncDestroy, syncInstantiate, SyncInstantiateOptions } from "../engine/engine_networking_instantiate.js";
 import { Context, FrameEvent } from "../engine/engine_setup.js";
@@ -117,15 +118,20 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
      */
     public static instantiateSynced(instance: GameObject | Object3D | null, opts: SyncInstantiateOptions): GameObject | null {
         if (!instance) return null;
-        return syncInstantiate(instance as any, opts) as GameObject | null;
+        return syncInstantiate(instance, opts) as GameObject | null;
     }
 
     /** Creates a new instance of the provided object (like cloning it including all components and children) 
      * @param instance object to instantiate
      * @param opts options for the instantiation (e.g. with what parent, position, etc.)
     */
-    public static instantiate(instance: GameObject | Object3D, opts: IInstantiateOptions | null = null): GameObject {
-        return instantiate(instance, opts) as GameObject;
+    public static instantiate(instance: AssetReference, opts?: IInstantiateOptions | null | undefined): Promise<Object3D | null>
+    public static instantiate(instance: GameObject | Object3D, opts?: IInstantiateOptions | null | undefined): GameObject
+    public static instantiate(instance: AssetReference | GameObject | Object3D, opts: IInstantiateOptions | null | undefined = null): GameObject | Promise<Object3D | null> {
+        if ('isAssetReference' in instance) {
+            return instantiate(instance as AssetReference, opts);
+        }
+        return instantiate(instance as GameObject | Object3D, opts) as GameObject;
     }
 
     /** Destroys a object on all connected clients (if you are in a networked session) 
@@ -398,9 +404,9 @@ export abstract class Component implements IComponent, EventTarget,
             this.gameObject.userData.static = value;
         }
     }
-    get hideFlags(): HideFlags {
-        return this.gameObject?.userData.hideFlags;
-    }
+    // get hideFlags(): HideFlags {
+    //     return this.gameObject?.hideFlags;
+    // }
 
     /** @returns true if the object is enabled and active in the hierarchy */
     get activeAndEnabled(): boolean {

package/src/engine-components/ContactShadows.ts

@@ -9,7 +9,7 @@ import { Gizmos } from "../engine/engine_gizmos.js";
 import { onStart } from "../engine/engine_lifecycle_api.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { getBoundingBox, getVisibleInCustomShadowRendering } from "../engine/engine_three_utils.js";
-import { IGameObject, Vec3 } from "../engine/engine_types.js";
+import { HideFlags, IGameObject, Vec3 } from "../engine/engine_types.js";
 import { getParam } from "../engine/engine_utils.js"
 import { setCustomVisibility } from "../engine/js-extensions/Layers.js";
 import { Behaviour, GameObject } from "./Component.js";
@@ -37,7 +37,7 @@ onStart(ctx => {
  */
 export class ContactShadows extends Behaviour {
 
-    private static _instances: Map<Context, ContactShadows> = new Map();
+    private static readonly _instances: Map<Context, ContactShadows> = new Map();
     /**
      * Create contact shadows for the scene. Automatically fits the shadows to the scene.  
      * The instance of contact shadows will be created only once.  
@@ -162,10 +162,14 @@ export class ContactShadows extends Behaviour {
 
     /** @internal */
     awake() {
+        ContactShadows._instances.set(this.context, this);
+        this.shadowsRoot.hideFlags = HideFlags.DontExport;
+
         // ignore self for autofitting
         setAutoFitEnabled(this.shadowsRoot, false);
     }
 
+
     /** @internal */
     start(): void {
         if (debug) console.log("Create ContactShadows on " + this.gameObject.name, this)
@@ -280,6 +284,11 @@ export class ContactShadows extends Behaviour {
 
     /** @internal */
     onDestroy(): void {
+        const instance = ContactShadows._instances.get(this.context);
+        if (instance === this) {
+            ContactShadows._instances.delete(this.context);
+        }
+
         // dispose the render targets
         this.renderTarget?.dispose();
         this.renderTargetBlur?.dispose();