@needle-tools/engine 4.4.0-ci.1 → 4.4.2

package/src/engine/engine_context.ts

@@ -278,26 +278,43 @@ export class Context implements IContext {
 		if (this.isInAR) return window.innerHeight;
 		return this.domElement.clientHeight;
 	}
-	/** the X position of the Needle Engine element on the website */
+	/** the X position of the `<needle-engine>` element on the website */
 	get domX(): number {
 		this.calculateBoundingClientRect();
 		return this._domX;
 	}
-	/** the Y position of the Needlee Engine element on the website */
+	/** the Y position of the `<needle-engine>` element on the website */
 	get domY(): number {
 		this.calculateBoundingClientRect();
 		return this._domY;
 	}
+	/**
+	 * Is a XR session currently active and presenting?
+	 * @returns true if the xr renderer is currently presenting
+	 */
 	get isInXR() { return this.renderer?.xr?.isPresenting || false; }
 	/** shorthand for `NeedleXRSession.active`  
 	 * Automatically set by NeedleXRSession when a XR session is active 
 	 * @returns the active XR session or null if no session is active
 	 * */
 	xr: NeedleXRSession | null = null;
+	/**
+	 * Shorthand for `this.xr?.mode`. AR or VR
+	 * @returns the current XR session mode (immersive-vr or immersive-ar)
+	 */
 	get xrSessionMode() { return this.xr?.mode; }
+	/** Shorthand for `this.xrSessionMode === "immersive-vr"` 
+	 * @returns true if a webxr VR session is currently active. 
+	 */
 	get isInVR() { return this.xrSessionMode === "immersive-vr"; }
+	/**
+	 * Shorthand for `this.xrSessionMode === "immersive-ar"`
+	 * @returns true if a webxr AR session is currently active.
+	 */
 	get isInAR() { return this.xrSessionMode === "immersive-ar"; }
-	/** If a XR session is active and in pass through mode (immersive-ar on e.g. Quest) */
+	/** If a XR session is active and in pass through mode (immersive-ar on e.g. Quest) 
+	 * @returns true if the XR session is in pass through mode
+	 */
 	get isInPassThrough() { return this.xr ? this.xr.isPassThrough : false; }
 	/** access the raw `XRSession` object (shorthand for `context.renderer.xr.getSession()`). For more control use `NeedleXRSession.active` */
 	get xrSession() { return this.renderer?.xr?.getSession(); }
@@ -308,34 +325,79 @@ export class Context implements IContext {
 	/** @returns the current WebXR camera while the WebXRManager is active (shorthand for `context.renderer.xr.getCamera()`) */
 	get xrCamera(): WebXRArrayCamera | undefined { return this.renderer.xr.isPresenting ? this.renderer?.xr?.getCamera() : undefined }
 	private _xrFrame: XRFrame | null = null;
+	/**
+	 * The AR overlay element is used to display 2D HTML elements while a AR session is active.
+	 */
 	get arOverlayElement(): HTMLElement {
 		const el = this.domElement as any;
 		if (typeof el.getAROverlayContainer === "function")
 			return el.getAROverlayContainer();
 		return this.domElement;
 	}
-	/** Current event of the update cycle */
+	/** 
+	 * Current event of the update cycle (e.g. `FrameEvent.EarlyUpdate` or `FrameEvent.OnBeforeRender`)
+	 */
 	get currentFrameEvent(): FrameEvent {
 		return this._currentFrameEvent;
 	}
 	private _currentFrameEvent: FrameEvent = FrameEvent.Undefined;
 
+	/**
+	 * The scene contains all objects in the hierarchy and is automatically rendered by the context every frane.
+	 */
 	scene: Scene;
+	/**
+	 * The renderer is used to render the scene. It is automatically created when the context is created.
+	 */
 	renderer!: WebGLRenderer;
+	/**
+	 * The effect composer can be used to render postprocessing effects. If assigned then it will automatically render the scene every frame.
+	 */
 	composer: EffectComposer | ThreeEffectComposer | null = null;
 
-	// all scripts
+	/**
+	 * @internal All known components. Don't use directly
+	 */
 	readonly scripts: IComponent[] = [];
+	/**
+	 * @internal All paused components. Don't use directly
+	 */
 	readonly scripts_pausedChanged: IComponent[] = [];
-	// scripts with update event
+	/**
+	 * @internal All components that have a early update event. Don't use directly
+	 */
 	readonly scripts_earlyUpdate: IComponent[] = [];
+	/**
+	 * @internal All components that have a update event. Don't use directly
+	 */
 	readonly scripts_update: IComponent[] = [];
+	/**
+	 * @internal All components that have a late update event. Don't use directly
+	 */
 	readonly scripts_lateUpdate: IComponent[] = [];
+	/**
+	 * @internal All components that have a onBeforeRender event. Don't use directly
+	 */
 	readonly scripts_onBeforeRender: IComponent[] = [];
+	/**
+	 * @internal All components that have a onAfterRender event. Don't use directly
+	 */
 	readonly scripts_onAfterRender: IComponent[] = [];
+	/**
+	 * @internal All components that have coroutines. Don't use directly
+	 */
 	readonly scripts_WithCorroutines: IComponent[] = [];
+	/**
+	 * @internal Components with immersive-vr event methods. Don't use directly
+	 */
 	readonly scripts_immersive_vr: INeedleXRSessionEventReceiver[] = [];
+	/**
+	 * @internal Components with immersive-ar event methods. Don't use directly
+	 */
 	readonly scripts_immersive_ar: INeedleXRSessionEventReceiver[] = [];
+	/**
+	 * @internal Coroutine data
+	 */
 	readonly coroutines: { [FrameEvent: number]: Array<CoroutineData> } = {}
 
 	/** callbacks called once after the context has been created */
@@ -346,20 +408,30 @@ export class Context implements IContext {
 	readonly pre_render_callbacks: Array<(frame: XRFrame | null) => void> = [];
 	/** called every frame after rendering (after all component events) */
 	readonly post_render_callbacks: Function[] = [];
-
 	/** called every frame befroe update (this list is emptied every frame) */
 	readonly pre_update_oneshot_callbacks: Function[] = [];
 
+	/** @internal */
 	readonly new_scripts: IComponent[] = [];
+	/** @internal */
 	readonly new_script_start: IComponent[] = [];
+	/** @internal */
 	readonly new_scripts_pre_setup_callbacks: Function[] = [];
+	/** @internal */
 	readonly new_scripts_post_setup_callbacks: Function[] = [];
+	/** @internal */
 	readonly new_scripts_xr: INeedleXRSessionEventReceiver[] = [];
 
-	/** The main camera component of the scene - this camera is used for rendering */
+	/** 
+	 * The **main camera component** of the scene - this camera is used for rendering.  
+	 * Use `setCurrentCamera` for updating the main camera.
+	 */
 	mainCameraComponent: ICamera | undefined = undefined;
 
-	/** The main camera of the scene - this camera is used for rendering */
+	/** 
+	 * The main camera of the scene - this camera is used for rendering   
+	 * Use `setCurrentCamera` for updating the main camera.
+	 */
 	get mainCamera(): Camera {
 		if (this._mainCamera) {
 			return this._mainCamera;
@@ -382,11 +454,13 @@ export class Context implements IContext {
 	private _mainCamera: Camera | null = null;
 	private _fallbackCamera: PerspectiveCamera | null = null;
 
+	/** access application state (e.g. if all audio should be muted) */
 	application: Application;
 	/** access animation mixer used by components in the scene */
 	animations: AnimationsRegistry;
 	/** access timings (current frame number, deltaTime, timeScale, ...) */
 	time: Time;
+	/** access input data (e.g. click or touch events) */
 	input: Input;
 	/** access physics related methods (e.g. raycasting). To access the phyiscs engine use `context.physics.engine` */
 	physics: Physics;
@@ -396,6 +470,7 @@ export class Context implements IContext {
 	 * @deprecated AssetDataBase is deprecated
 	 */
 	assets: AssetDatabase;
+	/** The main light in the scene */
 	mainLight: ILight | null = null;
 	/** @deprecated Use sceneLighting */
 	get rendererData() { return this.sceneLighting }
@@ -404,11 +479,13 @@ export class Context implements IContext {
 	lightmaps: ILightDataRegistry;
 	players: PlayerViewManager;
 	readonly lodsManager: LODsManager;
+	/** Access the needle menu to add or remove buttons to the menu element */
 	readonly menu: NeedleMenu;
 
+	/** @returns true if the context is fully created and ready */
 	get isCreated() { return this._isCreated; }
 
-	private _sizeChanged: boolean = false;
+	private _needsUpdateSize: boolean = false;
 	private _isCreated: boolean = false;
 	private _isCreating: boolean = false;
 	private _isVisible: boolean = false;
@@ -446,11 +523,11 @@ export class Context implements IContext {
 		this.animations = new AnimationsRegistry(this);
 
 
-		const resizeCallback = () => this._sizeChanged = true;
+		const resizeCallback = () => this._needsUpdateSize = true;
 		window.addEventListener('resize', resizeCallback);
 		this._disposeCallbacks.push(() => window.removeEventListener('resize', resizeCallback));
 
-		const resizeObserver = new ResizeObserver(_ => this._sizeChanged = true);
+		const resizeObserver = new ResizeObserver(_ => this._needsUpdateSize = true);
 		resizeObserver.observe(this.domElement);
 		this._disposeCallbacks.push(() => resizeObserver.disconnect());
 
@@ -462,7 +539,12 @@ export class Context implements IContext {
 		ContextRegistry.register(this);
 	}
 
-	/** calling this function will dispose the current renderer and create a new one */
+	/** 
+	 * Calling this function will dispose the current renderer and create a new one which will then be assigned to the context. It can be used to create a new renderer with custom WebGLRendererParameters.   
+	 * **Note**: Instead you can also modify the static `Context.DefaultWebGlRendererParameters` before the context is created.  
+	 * **Note**: This method is recommended because it re-uses an potentially already existing canvas element. This is necessary to keep input event handlers from working (e.g. components like OrbitControls subscribe to input events on the canvas)
+	 * @returns {WebGLRenderer} the newly created renderer
+	 */
 	createNewRenderer(params?: WebGLRendererParameters) {
 		this.renderer?.dispose();
 
@@ -506,6 +588,8 @@ export class Context implements IContext {
 		this.lodsManager.setRenderer(this.renderer);
 
 		this.input.bindEvents();
+
+		return this.renderer;
 	}
 
 
@@ -519,15 +603,32 @@ export class Context implements IContext {
 
 
 	/** will request a renderer size update the next render call (will call updateSize the next update) */
-	requestSizeUpdate() { this._sizeChanged = true; }
+	requestSizeUpdate() { this._needsUpdateSize = true; }
 
 	/** Clamps the renderer max resolution. If undefined the max resolution is not clamped. Default is undefined */
 	maxRenderResolution?: Vec2;
 
-	/** update the renderer and canvas size */
+	/** Control the renderer devicePixelRatio.  
+	 * **Options**   
+	 * - `auto` - Needle Engine automatically sets the pixel ratio to the current window.devicePixelRatio.
+	 * - `manual` - Needle Engine will not change the renderer pixel ratio. You can set it manually.
+	 * - `number` - Needle Engine will set the pixel ratio to the given number. The change will be applied to the renderer and the composer (if used) at the end of the current frame.
+	 */
+	get devicePixelRatio() { return this._devicePixelRatio; }
+	set devicePixelRatio(val: "auto" | "manual" | number) {
+		if (val !== this._devicePixelRatio) {
+			this._devicePixelRatio = val;
+			this._needsUpdateSize = true;
+		}
+	}
+	private _devicePixelRatio: "auto" | "manual" | number = "auto";
+
+	/** 
+	 * Update the renderer and canvas size. This is also automatically called when a DOM size change is detected.
+	 */
 	updateSize(force: boolean = false) {
 		if (force || (!this.isManagedExternally && this.renderer.xr?.isPresenting === false)) {
-			this._sizeChanged = false;
+			this._needsUpdateSize = false;
 			const scaleFactor = this.resolutionScaleFactor;
 			let width = this.domWidth * scaleFactor;
 			let height = this.domHeight * scaleFactor;
@@ -540,20 +641,32 @@ export class Context implements IContext {
 			const camera = this.mainCamera as PerspectiveCamera;
 			this.updateAspect(camera);
 			this.renderer.setSize(width, height, true);
-			this.renderer.setPixelRatio(window.devicePixelRatio);
 			// avoid setting pixel values here since this can cause pingpong updates
 			// e.g. when system scale is set to 125%
 			// https://github.com/needle-tools/needle-engine-support/issues/69
 			this.renderer.domElement.style.width = "100%";
 			this.renderer.domElement.style.height = "100%";
+
+			const devicePixelRatio = typeof this.devicePixelRatio === "number"
+				? this.devicePixelRatio
+				: this.devicePixelRatio === "auto"
+					? window.devicePixelRatio
+					: undefined;
+			if (devicePixelRatio !== undefined) {
+				this.renderer.setPixelRatio(devicePixelRatio);
+			}
+
 			if (this.composer) {
 				this.composer.setSize?.call(this.composer, width, height);
-				if ("setPixelRatio" in this.composer && typeof this.composer.setPixelRatio === "function")
+				if (devicePixelRatio !== undefined && "setPixelRatio" in this.composer && typeof this.composer.setPixelRatio === "function")
 					this.composer.setPixelRatio?.call(this.composer, window.devicePixelRatio);
 			}
 		}
 	}
 
+	/**
+	 * Update the camera aspect ratio or orthorgraphic camera size. This is automatically called when a DOM size change is detected.
+	 */
 	updateAspect(camera: PerspectiveCamera | OrthographicCamera, width?: number, height?: number) {
 		if (!camera) return;
 		if (width === undefined)
@@ -601,6 +714,7 @@ export class Context implements IContext {
 	async onCreate(opts?: ContextCreateArgs) {
 		return this.create(opts);
 	}
+	/** @internal */
 	async create(opts?: ContextCreateArgs) {
 		try {
 			this._isCreating = true;
@@ -626,7 +740,11 @@ export class Context implements IContext {
 		this.domElement.dispatchEvent(new CustomEvent("error", { detail: error }));
 	}
 
-	/** Will destroy all scenes and objects in the scene
+	/** 
+	 * Clears the context and destroys all scenes and objects in the scene.   
+	 * The ContextCleared event is called at the end.   
+	 * This is automatically called when e.g. the `src` attribute changes on `<needle-engine>`   
+	 * or when the web component is removed from the DOM
 	 */
 	clear() {
 		ContextRegistry.dispatchCallback(ContextEvent.ContextClearing, this);
@@ -652,12 +770,16 @@ export class Context implements IContext {
 		ContextRegistry.dispatchCallback(ContextEvent.ContextCleared, this);
 	}
 
+	/**
+	 * Dispose all allocated resources and clears the scene. This is automatically called e.g. when the `<needle-engine>` component is removed from the DOM.
+	 */
 	dispose() {
 		this.internalOnDestroy();
 	}
 
 	/**@deprecated use dispose()  */
 	onDestroy() { this.internalOnDestroy(); }
+
 	private internalOnDestroy() {
 		Context.Current = this;
 		ContextRegistry.dispatchCallback(ContextEvent.ContextDestroying, this);
@@ -698,6 +820,7 @@ export class Context implements IContext {
 		}
 	}
 
+	/** @internal Automatically called by components when you call `startCoroutine`. Use `startCoroutine` instead  */
 	registerCoroutineUpdate(script: IComponent, coroutine: Generator, evt: FrameEvent): Generator {
 		if (typeof coroutine?.next !== "function") {
 			console.error("Registered invalid coroutine function from " + script.name + "\nCoroutine functions must be generators: \"*myCoroutine() {...}\"\nStart a coroutine from a component by calling \"this.startCoroutine(myCoroutine())\"")
@@ -708,12 +831,14 @@ export class Context implements IContext {
 		return coroutine;
 	}
 
+	/** @internal Automatically called by components. */
 	unregisterCoroutineUpdate(coroutine: Generator, evt: FrameEvent): void {
 		if (!this.coroutines[evt]) return;
 		const idx = this.coroutines[evt].findIndex(c => c.main === coroutine);
 		if (idx >= 0) this.coroutines[evt].splice(idx, 1);
 	}
 
+	/** @internal Automatically called */
 	stopAllCoroutinesFrom(script: IComponent) {
 		for (const evt in this.coroutines) {
 			const rout: CoroutineData[] = this.coroutines[evt];
@@ -728,6 +853,7 @@ export class Context implements IContext {
 
 	private _cameraStack: ICamera[] = [];
 
+	/** Change the main camera */
 	setCurrentCamera(cam: ICamera) {
 		if (!cam) return;
 		if (!cam.threeCamera) cam.buildCamera(); // < to build camera
@@ -745,6 +871,9 @@ export class Context implements IContext {
 		(this.mainCameraComponent as ICamera)?.applyClearFlagsIfIsActiveCamera();
 	}
 
+	/**
+	 * Remove the camera from the mainCamera stack (if it has been set before with `setCurrentCamera`)
+	 */
 	removeCamera(cam?: ICamera | null) {
 		if (!cam) return;
 		const index = this._cameraStack.indexOf(cam);
@@ -760,12 +889,12 @@ export class Context implements IContext {
 		}
 	}
 
-
-
 	private _onBeforeRenderListeners = new Map<string, OnRenderCallback[]>();
 	private _onAfterRenderListeners = new Map<string, OnRenderCallback[]>();
 
-	/** use this to subscribe to onBeforeRender events on threejs objects */
+	/** Use to subscribe to onBeforeRender events on threejs objects.
+	 * @link https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender
+	 */
 	addBeforeRenderListener(target: Object3D, callback: OnRenderCallback) {
 		if (!this._onBeforeRenderListeners.has(target.uuid)) {
 			this._onBeforeRenderListeners.set(target.uuid, []);
@@ -773,6 +902,9 @@ export class Context implements IContext {
 		}
 		this._onBeforeRenderListeners.get(target.uuid)!.push(callback);
 	}
+	/** Remove callback from three `onBeforeRender` event (if it has been added with `addBeforeRenderListener(...)`)
+	 * @link https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender
+	*/
 	removeBeforeRenderListener(target: Object3D, callback: OnRenderCallback) {
 		if (this._onBeforeRenderListeners.has(target.uuid)) {
 			const arr = this._onBeforeRenderListeners.get(target.uuid)!;
@@ -781,7 +913,10 @@ export class Context implements IContext {
 		}
 	}
 
-	/** use this to subscribe to onAfterRender events on threejs objects */
+	/** 
+	 * Subscribe to onAfterRender events on threejs objects 
+	 * @link https://threejs.org/docs/#api/en/core/Object3D.onAfterRender
+	*/
 	addAfterRenderListener(target: Object3D, callback: OnRenderCallback) {
 		if (!this._onAfterRenderListeners.has(target.uuid)) {
 			this._onAfterRenderListeners.set(target.uuid, []);
@@ -789,6 +924,10 @@ export class Context implements IContext {
 		}
 		this._onAfterRenderListeners.get(target.uuid)?.push(callback);
 	}
+	/** 
+	 * Remove from onAfterRender events on threejs objects 
+	 * @link https://threejs.org/docs/#api/en/core/Object3D.onAfterRender
+	*/
 	removeAfterRenderListener(target: Object3D, callback: OnRenderCallback) {
 		if (this._onAfterRenderListeners.has(target.uuid)) {
 			const arr = this._onAfterRenderListeners.get(target.uuid)!;
@@ -816,25 +955,23 @@ export class Context implements IContext {
 	private _renderTarget?: WebGLRenderTarget;
 	private _isRendering: boolean = false;
 
+	/** @returns true while the WebGL renderer is rendering (between onBeforeRender and onAfterRender events) */
 	get isRendering() { return this._isRendering; }
 
 	setRequireDepth(val: boolean) {
 		this._requireDepthTexture = val;
 	}
-
 	setRequireColor(val: boolean) {
 		this._requireColorTexture = val;
 	}
-
 	get depthTexture(): DepthTexture | null {
 		return this._renderTarget?.depthTexture || null;
 	}
-
 	get opaqueColorTexture(): Texture | null {
 		return this._renderTarget?.texture || null;
 	}
 
-	/** returns true if the dom element is visible on screen */
+	/** @returns true if the `<needle-engine>` DOM element is visible on screen (`context.domElement`) */
 	get isVisibleToUser() {
 		if (this.isInXR) return true;
 		if (!this._isVisible) return false;
@@ -842,7 +979,6 @@ export class Context implements IContext {
 		return style.visibility !== "hidden" && style.display !== "none" && style.opacity !== "0";
 	}
 
-
 	private _createId: number = 0;
 	private async internalOnCreate(opts?: ContextCreateArgs): Promise<boolean> {
 		const createId = ++this._createId;
@@ -1016,7 +1152,7 @@ export class Context implements IContext {
 			// this.composer.setSize(this.domWidth, this.domHeight);
 		}
 
-		this._sizeChanged = true;
+		this._needsUpdateSize = true;
 
 		if (this._stats) {
 			this._stats.showPanel(0);
@@ -1186,11 +1322,11 @@ export class Context implements IContext {
 		if (frame === undefined) frame = null;
 		if (isDevEnvironment() || debug || looputils.hasNewScripts()) {
 			try {
-				performance.mark('update.start');
+				//performance.mark('update.start');
 				this.internalStep(timestamp, frame);
 				this._renderlooperrors = 0;
-				performance.mark('update.end');
-				performance.measure('NE Frame', 'update.start', 'update.end');
+				//performance.mark('update.end');
+				//performance.measure('NE Frame', 'update.start', 'update.end');
 			}
 			catch (err) {
 				this._renderlooperrors += 1;
@@ -1361,7 +1497,7 @@ export class Context implements IContext {
 			this.executeCoroutines(FrameEvent.OnBeforeRender);
 			invokeLifecycleFunctions(this, FrameEvent.OnBeforeRender);
 
-			if (this._sizeChanged)
+			if (this._needsUpdateSize)
 				this.updateSize();
 
 			if (this.pre_render_callbacks) {

package/src/engine/engine_element.ts

@@ -12,6 +12,7 @@ import { NeedleLoader } from "./engine_scenetools.js";
 import { Context, ContextCreateArgs } from "./engine_setup.js";
 import { type INeedleEngineComponent, type LoadedModel } from "./engine_types.js";
 import { getParam } from "./engine_utils.js";
+import { RGBAColor } from "./js-extensions/RGBAColor.js";
 import { ensureFonts } from "./webcomponents/fonts.js";
 
 // 
@@ -177,6 +178,9 @@ export class NeedleEngineHTMLElement extends HTMLElement implements INeedleEngin
         -webkit-touch-callout: none;
         -webkit-user-drag: none;
         -webkit-user-modify: none;
+
+        left: 0;
+        top: 0;
     }
     :host .content {
         position: absolute;
@@ -517,7 +521,7 @@ export class NeedleEngineHTMLElement extends HTMLElement implements INeedleEngin
 
     private applyAttributes() {
         // set tonemapping if configured
-        if (this._context.renderer) {
+        if (this._context?.renderer) {
             const attribute = this.getAttribute("tonemapping") || this.getAttribute("tone-mapping") as TonemappingAttributeOptions | null | undefined;
             switch (attribute?.toLowerCase()) {
                 case "none":
@@ -555,15 +559,12 @@ export class NeedleEngineHTMLElement extends HTMLElement implements INeedleEngin
         }
 
         const backgroundColor = this.getAttribute("background-color");
-        if (this._context) {
+        if (this._context?.renderer) {
             if (typeof backgroundColor === "string" && backgroundColor.length > 0) {
-                const currentBackground = this._context.scene.background;
-                if (currentBackground instanceof Color) {
-                    currentBackground.set(backgroundColor);
-                }
-                else {
-                    this._context.scene.background = new Color(backgroundColor);
-                }
+                const rgbaColor = RGBAColor.fromColorRepresentation(backgroundColor);
+                if(debug) console.debug("<needle-engine> background-color changed, str:", backgroundColor, "→", rgbaColor)
+                this._context.renderer.setClearColor(rgbaColor, rgbaColor.alpha);
+                this.context.scene.background = null;
             }
         }
     }

package/src/engine/engine_gameobject.ts

@@ -1,5 +1,6 @@
 import { Bone, Object3D, Quaternion, SkinnedMesh, Vector3 } from "three";
 
+import { $shadowDomOwner } from "../engine-components/ui/Symbols.js";
 import { type AssetReference } from "./engine_addressables.js";
 import { __internalNotifyObjectDestroyed as __internalRemoveReferences, disposeObjectResources } from "./engine_assetdatabase.js";
 import { ComponentLifecycleEvents } from "./engine_components_internal.js";
@@ -380,6 +381,12 @@ function internalInstantiate(
 )
     : GameObject | Object3D | null {
     if (!instance) return null;
+
+    // Don't clone UI shadow objects
+    if (instance[$shadowDomOwner]) {
+        return null;
+    }
+    
     // prepare, remove things that dont work out of the box
     // e.g. user data we want to manually clone
     // also children throw errors (e.g. recursive toJson with nested meshes)