@needle-tools/engine 5.1.0-alpha.2 → 5.1.0-alpha.4

package/src/engine/engine_physics_rapier.ts

@@ -1,4 +1,4 @@
-import type { Ball, Collider, ColliderDesc, Cuboid, EventQueue, QueryFilterFlags, Ray, RigidBody, RigidBodyDesc, World } from '@dimforge/rapier3d-compat';
+import type { Ball, Collider, ColliderDesc, Cuboid, EventQueue, ImpulseJoint, QueryFilterFlags, Ray, RigidBody, RigidBodyDesc, World } from '@dimforge/rapier3d-compat';
 import { BufferAttribute, BufferGeometry, InterleavedBufferAttribute, LineBasicMaterial, LineSegments, Matrix4, Mesh, Object3D, Quaternion, Vector3, Vector4Like } from 'three'
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
 
@@ -690,12 +690,26 @@ export class RapierPhysics implements IPhysicsEngine {
         }
     }
 
-    clearCaches() {
+    /** Tears down the physics world and frees all WASM resources.
+     * After calling this, the world will be re-created on next use. */
+    dispose() {
         this._meshCache.clear();
-        if (this.eventQueue?.raw)
-            this.eventQueue?.free();
-        if (this.world?.bodies)
-            this.world?.free();
+        this.eventQueue?.free();
+        this._world?.free();
+        // Reset initialization state so the world can be recreated
+        this._world = undefined;
+        this.eventQueue = undefined;
+        this.collisionHandler = undefined;
+        this._isInitialized = false;
+        this._hasCreatedWorld = false;
+        this._initializePromise = undefined;
+        this.objects.length = 0;
+        this.bodies.length = 0;
+    }
+
+    /** @deprecated Use {@link dispose} instead. */
+    clearCaches() {
+        this.dispose();
     }
 
     async addBoxCollider(collider: ICollider, size: Vector3) {
@@ -981,13 +995,17 @@ export class RapierPhysics implements IPhysicsEngine {
             }
         }
 
-        // if we want to use explicit mass properties, we need to set the collider density to 0
-        // otherwise rapier will compute the mass properties based on the collider shape and density
+        // When using explicit mass (autoMass=false), set collider mass to near-zero
+        // so Rapier doesn't contribute mass from the collider shape.
+        // The actual mass is applied via setAdditionalMass on the rigidbody instead.
+        // Note: setMass overrides any prior setDensity call (they are mutually exclusive in Rapier)
         // https://rapier.rs/docs/user_guides/javascript/rigid_bodies#mass-properties
         if (collider.attachedRigidbody?.autoMass === false) {
-            desc.setDensity(.000001);
             desc.setMass(.000001);
         }
+        else if (collider.density != null) {
+            desc.setDensity(collider.density);
+        }
 
         try {
             const col = this.world.createCollider(desc, rigidBody);
@@ -1130,6 +1148,11 @@ export class RapierPhysics implements IPhysicsEngine {
                 break;
         }
 
+        // Update density if specified (setDensity auto-recomputes parent body mass)
+        if (col.density != null) {
+            collider.setDensity(col.density);
+        }
+
         if (sizeHasChanged) {
             const rb = col.attachedRigidbody;
             if (rb?.autoMass) {
@@ -1161,7 +1184,8 @@ export class RapierPhysics implements IPhysicsEngine {
             rigidbody.setAdditionalMass(0, false);
             for (let i = 0; i < rigidbody.numColliders(); i++) {
                 const col = rigidbody.collider(i);
-                col.setDensity(1);
+                const colliderComponent = col[$componentKey] as ICollider | null;
+                col.setDensity(colliderComponent?.density ?? 1);
             }
             rigidbody.recomputeMassPropertiesFromColliders();
         }
@@ -1477,16 +1501,21 @@ export class RapierPhysics implements IPhysicsEngine {
 
     private static centerConnectionPos = { x: 0, y: 0, z: 0 };
     private static centerConnectionRot = { x: 0, y: 0, z: 0, w: 1 };
+    private _jointTempMatrix = new Matrix4();
 
 
-
-    addFixedJoint(body1: IRigidbody, body2: IRigidbody) {
+    async addFixedJoint(body1: IRigidbody, body2: IRigidbody): Promise<ImpulseJoint | null> {
+        if (!this._isInitialized) await this.initialize();
         if (!this.world) {
             console.error("Physics world not initialized");
-            return;
+            return null;
         }
         const b1 = body1[$bodyKey] as RigidBody;
         const b2 = body2[$bodyKey] as RigidBody;
+        if (!b1 || !b2) {
+            console.error("Cannot create fixed joint: one or both physics bodies are not initialized");
+            return null;
+        }
 
         this.calculateJointRelativeMatrices(body1.gameObject, body2.gameObject, this._tempMatrix);
         this._tempMatrix.decompose(this._tempPosition, this._tempQuaternion, this._tempScale);
@@ -1498,41 +1527,67 @@ export class RapierPhysics implements IPhysicsEngine {
         const joint = this.world.createImpulseJoint(params, b1, b2, true);
         if (debugPhysics)
             console.log("ADD FIXED JOINT", joint)
+        return joint;
     }
 
 
     /** The joint prevents any relative movement between two rigid-bodies, except for relative rotations along one axis. This is typically used to simulate wheels, fans, etc. They are characterized by one local anchor as well as one local axis on each rigid-body. */
-    addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: { x: number, y: number, z: number }, axis: { x: number, y: number, z: number }) {
+    async addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: { x: number, y: number, z: number }, axis: { x: number, y: number, z: number }): Promise<ImpulseJoint | null> {
+        if (!this._isInitialized) await this.initialize();
         if (!this.world) {
             console.error("Physics world not initialized");
-            return;
+            return null;
         }
         const b1 = body1[$bodyKey] as RigidBody;
         const b2 = body2[$bodyKey] as RigidBody;
+        if (!b1 || !b2) {
+            console.error("Cannot create hinge joint: one or both physics bodies are not initialized");
+            return null;
+        }
 
         this.calculateJointRelativeMatrices(body1.gameObject, body2.gameObject, this._tempMatrix);
-        this._tempMatrix.decompose(this._tempPosition, this._tempQuaternion, this._tempScale);
+        // Transform anchor from body1's local space to body2's local space
+        const anchor2 = this._tempPosition.set(anchor.x, anchor.y, anchor.z).applyMatrix4(this._tempMatrix);
 
-        const params = MODULES.RAPIER_PHYSICS.MODULE.JointData.revolute(anchor, this._tempPosition, axis);
+        const params = MODULES.RAPIER_PHYSICS.MODULE.JointData.revolute(anchor, anchor2, axis);
         const joint = this.world.createImpulseJoint(params, b1, b2, true);
         if (debugPhysics)
             console.log("ADD HINGE JOINT", joint)
+        return joint;
     }
 
 
+    removeJoint(joint: ImpulseJoint) {
+        if (!this.world) return;
+        this.world.removeImpulseJoint(joint, true);
+    }
+
+
+    /** Compute the relative transform from body1's local space to body2's local space (W2⁻¹ * W1), ignoring scale. */
     private calculateJointRelativeMatrices(body1: IGameObject, body2: IGameObject, mat: Matrix4) {
         body1.updateWorldMatrix(true, false);
         body2.updateWorldMatrix(true, false);
-        const world1 = body1.matrixWorld;
-        const world2 = body2.matrixWorld;
-        // set scale to 1
-        world1.elements[0] = 1;
-        world1.elements[5] = 1;
-        world1.elements[10] = 1;
-        world2.elements[0] = 1;
-        world2.elements[5] = 1;
-        world2.elements[10] = 1;
-        mat.copy(world2).premultiply(world1.invert()).invert();
+
+        // Work on copies to avoid mutating the actual world matrices
+        mat.copy(body1.matrixWorld);
+        const w2 = this._jointTempMatrix.copy(body2.matrixWorld);
+
+        // Strip scale by normalizing each column of the upper 3x3
+        this.normalizeMatrixColumns(mat);
+        this.normalizeMatrixColumns(w2);
+
+        // mat = W2^-1 * W1 (body1's frame in body2's local space)
+        mat.premultiply(w2.invert());
+    }
+
+    private normalizeMatrixColumns(m: Matrix4) {
+        const e = m.elements;
+        let len = Math.sqrt(e[0] * e[0] + e[1] * e[1] + e[2] * e[2]);
+        if (len > 0) { e[0] /= len; e[1] /= len; e[2] /= len; }
+        len = Math.sqrt(e[4] * e[4] + e[5] * e[5] + e[6] * e[6]);
+        if (len > 0) { e[4] /= len; e[5] /= len; e[6] /= len; }
+        len = Math.sqrt(e[8] * e[8] + e[9] * e[9] + e[10] * e[10]);
+        if (len > 0) { e[8] /= len; e[9] /= len; e[10] /= len; }
     }
 }
 

package/src/engine/engine_scenedata.ts

@@ -1,10 +1,10 @@
 import type { SceneData } from "needle-bindings";
 export type { SceneData };
-import type { IContext } from "./engine_types.js";
-import { getComponent } from "./engine_components.js";
-import { TypeStore } from "./engine_typestore.js";
 import { isDevEnvironment } from "./debug/index.js";
+import { getComponent } from "./engine_components.js";
 import { ContextRegistry } from "./engine_context_registry.js";
+import type { IContext } from "./engine_types.js";
+import { TypeStore } from "./engine_typestore.js";
 
 /**
  * Quick access to the current Needle Engine context from anywhere — no need to pass `ctx` around.
@@ -13,6 +13,8 @@ import { ContextRegistry } from "./engine_context_registry.js";
  * Safe to import at module level, including in SSR environments.
  * For pages with multiple `<needle-engine>` elements, use `ctx` directly instead.
  *
+ * @experimental This API may change in future releases.
+ *
  * @example
  * import { needle } from "@needle-tools/engine";
  * button.onclick = () => {

package/src/engine/engine_serialization_builtin_serializer.ts

@@ -4,6 +4,7 @@ import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../eng
 import { Behaviour, Component, GameObject } from "../engine-components/Component.js";
 import { CallInfo, EventList } from "../engine-components/EventList.js";
 import { AssetReference } from "./engine_addressables.js";
+import { AudioClip } from "./engine_audio.js";
 import { debugExtension } from "./engine_default_parameters.js";
 import { SerializationContext, TypeSerializer } from "./engine_serialization_core.js";
 import { RenderTexture } from "./engine_texture.js";
@@ -11,25 +12,7 @@ import { IComponent } from "./engine_types.js";
 import { resolveUrl } from "./engine_utils.js";
 import { RGBAColor } from "./js-extensions/index.js";
 
-// export class SourcePath {
-//     src?:string
-// };
-
-// class SourcePathSerializer extends TypeSerializer{
-//     constructor(){
-//         super(SourcePath);
-//     }
-//     onDeserialize(data: any, _context: SerializationContext) {
-//         if(data.src && typeof data.src === "string"){
-//             return data.src;
-//         }
-//     }
-//     onSerialize(_data: any, _context: SerializationContext) {
-
-//     }
-// }
-// new SourcePathSerializer();
-
+// #region Color
 class ColorSerializer extends TypeSerializer {
     constructor() {
         super([Color, RGBAColor], "ColorSerializer")
@@ -52,7 +35,8 @@ class ColorSerializer extends TypeSerializer {
             return { r: data.r, g: data.g, b: data.b }
     }
 }
-export const colorSerializer = new ColorSerializer();
+
+// #region Euler
 
 class EulerSerializer extends TypeSerializer {
     constructor() {
@@ -72,12 +56,13 @@ class EulerSerializer extends TypeSerializer {
         return { x: data.x, y: data.y, z: data.z, order: data.order };
     }
 }
-export const euler = new EulerSerializer();
 
 declare type ObjectData = {
     node?: number;
     guid?: string;
 }
+
+// #region ObjectSerializer
 class ObjectSerializer extends TypeSerializer {
     constructor() {
         super(Object3D, "ObjectSerializer");
@@ -107,16 +92,6 @@ class ObjectSerializer extends TypeSerializer {
                 console.warn(`Wrong usage of @serializable detected in your script \"${scriptname}\"\n\nIt looks like you used @serializable(Object3D) or @serializable(GameObject) for a prefab or scene reference which is exported to a separate glTF file.\n\nTo fix this please change your code to:\n\n@serializable(AssetReference)\n${context.path}! : AssetReference;\n\0`);
             }
             // ACTUALLY: this is already handled by the extension_utils where we resolve json pointers recursively
-            // if(data.startsWith("/nodes/")){
-            //     const node = parseInt(data.substring("/nodes/".length));
-            //     if (context.nodeToObject) {
-            //         const res = context.nodeToObject[node];
-            //         if (debugExtension)
-            //             console.log("Deserialized object reference?", data, res, context?.nodeToObject);
-            //         if (!res) console.warn("Did not find node: " + data, context.nodeToObject, context.object);
-            //         return res;
-            //     }
-            // }
             return undefined;
         }
 
@@ -149,7 +124,7 @@ class ObjectSerializer extends TypeSerializer {
                 }
                 if (!res) {
                     if (isDevEnvironment() || debugExtension)
-                        console.warn("Could not resolve object reference", context.path, data, context.target, context.context.scene);
+                        console.warn(`Could not resolve object reference \"${context.path}\" (guid: ${data.guid}). The referenced object may have been deleted — check if the reference is still valid in your scene.`);
                     data["could_not_resolve"] = true;
                 }
                 else {
@@ -166,9 +141,8 @@ class ObjectSerializer extends TypeSerializer {
         return undefined;
     }
 }
-export const objectSerializer = new ObjectSerializer();
-
 
+// #region ComponentSerializer
 class ComponentSerializer extends TypeSerializer {
 
     constructor() {
@@ -241,7 +215,6 @@ class ComponentSerializer extends TypeSerializer {
         }
     }
 }
-export const componentSerializer = new ComponentSerializer();
 
 
 declare class EventListData {
@@ -258,6 +231,7 @@ declare type EventListCall = {
 
 const $eventListDebugInfo = Symbol("eventListDebugInfo");
 
+// #region EventListSerializer
 class EventListSerializer extends TypeSerializer {
     constructor() {
         super([EventList]);
@@ -360,11 +334,6 @@ class EventListSerializer extends TypeSerializer {
             if (debugExtension)
                 console.log(evt);
 
-            const eventListOwner = context.target;
-            if (eventListOwner !== undefined && context.path !== undefined) {
-                evt.setEventTarget(context.path, eventListOwner);
-            }
-
             return evt;
         }
         return undefined;
@@ -396,22 +365,14 @@ class EventListSerializer extends TypeSerializer {
     //     };
     // }
 }
-export const eventListSerializer = new EventListSerializer();
 
 
 /** Map<Clone, Original> texture. This is used for compressed textures (or when the GLTFLoader is cloning RenderTextures)
  * It's a weak map so we don't have to worry about memory leaks
  */
 const cloneOriginalMap = new WeakMap<Texture, Texture>();
-const textureClone = Texture.prototype.clone;
-Texture.prototype.clone = function () {
-    const clone = textureClone.call(this);
-    if (!cloneOriginalMap.has(clone)) {
-        cloneOriginalMap.set(clone, this);
-    }
-    return clone;
-}
 
+// #region RenderTextureSerializer
 export class RenderTextureSerializer extends TypeSerializer {
     constructor() {
         super([RenderTexture, WebGLRenderTarget]);
@@ -452,9 +413,8 @@ export class RenderTextureSerializer extends TypeSerializer {
         return undefined;
     }
 }
-new RenderTextureSerializer();
-
 
+// #region UriSerializer
 export class UriSerializer extends TypeSerializer {
     constructor() {
         super([URL]);
@@ -471,4 +431,56 @@ export class UriSerializer extends TypeSerializer {
         return undefined;
     }
 }
-new UriSerializer();
+
+// #region AudioClipSerializer
+class AudioClipSerializer extends TypeSerializer {
+    constructor() {
+        super([AudioClip]);
+    }
+
+    onSerialize(_data: AudioClip, _context: SerializationContext) {
+        return null;
+    }
+
+    onDeserialize(data: string, context: SerializationContext) {
+        if (typeof data === "string" && data.length > 0) {
+            const url = resolveUrl(context.gltfId, data);
+            if (url) return new AudioClip(url);
+        }
+        return undefined;
+    }
+}
+
+
+// #region Init serializer
+// Module-level references used by EventListSerializer internally
+export let colorSerializer: ColorSerializer;
+export let objectSerializer: ObjectSerializer;
+export let componentSerializer: ComponentSerializer;
+export let eventListSerializer: EventListSerializer;
+
+/** Register all builtin serializers and prototype patches.
+ * Must be called from {@link initEngine} so the registrations survive tree-shaking
+ * when the package declares `sideEffects: false`.
+ */
+export function initBuiltinSerializers() {
+    // Prototype patches
+    const textureClone = Texture.prototype.clone;
+    Texture.prototype.clone = function () {
+        const clone = textureClone.call(this);
+        if (!cloneOriginalMap.has(clone)) {
+            cloneOriginalMap.set(clone, this);
+        }
+        return clone;
+    }
+
+    // Register all serializers
+    colorSerializer = new ColorSerializer();
+    new EulerSerializer();
+    objectSerializer = new ObjectSerializer();
+    componentSerializer = new ComponentSerializer();
+    eventListSerializer = new EventListSerializer();
+    new RenderTextureSerializer();
+    new UriSerializer();
+    new AudioClipSerializer();
+}

package/src/engine/engine_serialization_core.ts

@@ -207,6 +207,15 @@ export interface ISerializable {
     onAfterDeserialize?(data: any, context: SerializationContext): void;
 };
 
+export function isSerializable(obj: any): obj is ISerializable {
+    return obj && typeof obj === "object" && (
+        typeof obj.$serializedTypes === "object" ||
+        typeof obj.onBeforeDeserialize === "function" ||
+        typeof obj.onBeforeDeserializeMember === "function" ||
+        typeof obj.onAfterDeserializeMember === "function" ||
+        typeof obj.onAfterDeserialize === "function"
+    )
+}
 
 export function serializeObject(obj: ISerializable, context: SerializationContext): object | null {
     const types = obj.$serializedTypes;

package/src/engine/engine_types.ts

@@ -5,7 +5,6 @@ import { type GLTF as THREE_GLTF } from "three/examples/jsm/loaders/GLTFLoader.j
 
 import type { Camera as CameraComponent } from "../engine-components/api.js";
 import type { Context } from "./engine_context.js";
-import { InstantiateContext } from "./engine_gameobject.js";
 import { CollisionDetectionMode, type PhysicsMaterial, RigidbodyConstraints } from "./engine_physics.types.js";
 import { CircularBuffer } from "./engine_utils.js";
 import type { NeedleXRSession } from "./engine_xr.js";
@@ -196,13 +195,11 @@ export interface IComponent extends IHasGuid {
     /** @internal */
     __internalStart();
     /** @internal */
-    __internalEnable(isAddingOrRemovingFromScene?: boolean);
+    __internalEnable(isHierarchyChange?: boolean);
     /** @internal */
-    __internalDisable(isAddingOrRemovingFromScene?: boolean);
+    __internalDisable(isHierarchyChange?: boolean);
     /** @internal */
     __internalDestroy();
-    /** @internal */
-    resolveGuids?(guidsMap: GuidsMap): void;
 
     /** experimental, called when the script is registered for the first time, this is called even if the component is not enabled. */
     registering?();
@@ -240,14 +237,14 @@ export interface IComponent extends IHasGuid {
 }
 
 export function isComponent(obj: any): obj is IComponent {
-    return obj && obj.isComponent;
+    return obj && typeof obj === "object" && obj.isComponent;
 }
 
 export type ICamera = CameraComponent;
 
 export type IAnimationComponent = Pick<IComponent, "gameObject"> & {
     isAnimationComponent: boolean;
-    addClip?(clip: AnimationClip);
+    addClip?(clip: AnimationClip): void;
 }
 
 /** Interface for a camera controller component that can be attached to a camera to control it */
@@ -274,7 +271,10 @@ export declare interface IRenderer extends IComponent {
 
 export declare interface IEventList {
     readonly isEventList: true;
-    __internalOnInstantiate(map: InstantiateContext): IEventList;
+}
+
+export declare interface ISignalReceiver {
+    readonly isSignalReceiver: true;
 }
 
 // export declare interface IPhysicsComponent extends IComponent {
@@ -302,12 +302,18 @@ export declare interface ICollider extends IComponent {
      * Default: [0]
     */
     membership?: number[];
-    /** The collider filter indicates what groups the collider can interact with (e.g. group 3 and 4)   
-     * An `undefined` array indicates that the collider can interact with all groups   
-     * Note: Make sure to call updateProperties after having changed this property  
+    /** The collider filter indicates what groups the collider can interact with (e.g. group 3 and 4)
+     * An `undefined` array indicates that the collider can interact with all groups
+     * Note: Make sure to call updateProperties after having changed this property
      * Default: undefined
     */
     filter?: number[];
+    /** The density of the collider used for automatic mass calculation.
+     * When the attached Rigidbody has `autoMass` enabled, the mass is computed as `density × volume`.
+     * Note: Make sure to call updateProperties after having changed this property
+     * Default: undefined (uses physics engine default of 1.0)
+    */
+    density?: number;
 }
 
 export declare interface ISphereCollider extends ICollider {
@@ -475,8 +481,10 @@ export interface IPhysicsEngine {
     postStep();
     /** Indicates whether the physics engine is currently updating */
     get isUpdating(): boolean;
-    /** Clears all cached data (e.g., mesh data when creating scaled mesh colliders) */
-    clearCaches();
+    /** Tears down the physics world and frees all resources. The world will be re-created on next use. */
+    dispose(): void;
+    /** @deprecated Use {@link dispose} instead. */
+    clearCaches(): void;
 
     /** Enables or disables the physics engine */
     enabled: boolean;
@@ -738,8 +746,9 @@ export interface IPhysicsEngine {
     getBody(obj: ICollider | IRigidbody): null | any;
 
     // Joints
-    addFixedJoint(body1: IRigidbody, body2: IRigidbody);
-    addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3);
+    addFixedJoint(body1: IRigidbody, body2: IRigidbody): Promise<any> | any;
+    addHingeJoint(body1: IRigidbody, body2: IRigidbody, anchor: Vec3, axis: Vec3): Promise<any> | any;
+    removeJoint(joint: any): void;
 
     /** Enable to render collider shapes */
     debugRenderColliders: boolean;

package/src/engine/engine_util_decorator.ts

@@ -79,8 +79,12 @@ function createPropertyWrapper(target: IComponent | any, _propertyKey: string |
                 return;
             }
 
-            // only build wrapper once per type
-            if (this[$prop] === undefined) {
+            // Only install the getter/setter once per instance.
+            // processStart may call __internalAwake again for components that were inactive
+            // during processNewScripts — the base Component.__internalAwake has a __didAwake guard
+            // but this decorator wrapper runs before reaching it, so we need our own idempotency check.
+            const desc = Object.getOwnPropertyDescriptor(this, propertyKey);
+            if (!desc || !desc.get) {
 
                 // make sure the field is initialized in a hidden property
                 this[$prop] = this[propertyKey];
@@ -99,6 +103,7 @@ function createPropertyWrapper(target: IComponent | any, _propertyKey: string |
                 }
 
                 Object.defineProperty(this, propertyKey, {
+                    configurable: true,
                     set: function (v) {
                         if (this[$isAssigningProperties] === true) {
                             this[$prop] = v;

package/src/engine/engine_utils.ts

@@ -279,24 +279,35 @@ declare type deepClonePredicate = (owner: any, propertyName: string, current: an
  *   return true;
  * });
  * */
-export function deepClone(obj: any, predicate?: deepClonePredicate): any {
+export function deepClone(obj: any, predicate?: deepClonePredicate, _visited?: WeakSet<object>): any {
     if (obj !== null && obj !== undefined && typeof obj === "object") {
+        if (!_visited) _visited = new WeakSet();
+        if (_visited.has(obj)) return obj;
+        _visited.add(obj);
+
         let clone;
         if (Array.isArray(obj)) clone = [];
         else {
-            clone = Object.create(obj);
-            Object.assign(clone, obj);
+            clone = Object.create(Object.getPrototypeOf(obj));
+            // Copy own properties, skipping getter-only properties that can't be set
+            const descriptors = Object.getOwnPropertyDescriptors(obj);
+            for (const key in descriptors) {
+                const desc = descriptors[key];
+                if (desc.set || desc.writable !== false) {
+                    try { clone[key] = obj[key]; }
+                    catch { /* skip read-only properties */ }
+                }
+            }
         }
         for (const key of Object.keys(obj)) {
             const val = obj[key];
             if (predicate && !predicate(obj, key, val)) {
-                // console.log("SKIP", val);
                 clone[key] = val;
             }
             else if (val?.clone !== undefined && typeof val.clone === "function")
                 clone[key] = val.clone();
             else
-                clone[key] = deepClone(val, predicate);
+                clone[key] = deepClone(val, predicate, _visited);
         }
         return clone;
     }

package/src/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js

@@ -35,7 +35,7 @@ export class GenerateMeshBVHWorker extends WorkerBase {
 
             worker.onerror = e => {
 
-                reject(new Error(`[GenerateMeshBVHWorker] ${e.message || "Unknown error. Please check the server console. If you're using vite try adding 'three-mesh-bvh' to 'optimizeDeps.exclude' in your vite.config.js"}`));
+                reject(new Error(`[GenerateMeshBVHWorker] ${e.message || "Could not load worker."}`));
             
 			};
 

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

@@ -1,8 +1,8 @@
 import { showBalloonMessage } from "../../debug/debug.js";
-import { HTMLElementBase } from "../../engine_ssr.js";
 import type { Context } from "../../engine_context.js";
 import { hasCommercialLicense, onLicenseCheckResultChanged, Telemetry } from "../../engine_license.js";
 import { isLocalNetwork } from "../../engine_networking_utils.js";
+import { HTMLElementBase } from "../../engine_ssr.js";
 import { DeviceUtilities, getParam } from "../../engine_utils.js";
 import { onXRSessionStart, XRSessionEventArgs } from "../../xr/events.js";
 import { ButtonsFactory } from "../buttons.js";

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

@@ -1,11 +1,11 @@
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
-import { HTMLElementBase } from "../engine_ssr.js";
 import { PUBLIC_KEY, VERSION } from "../engine_constants.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
 import { hasCommercialLicense } from "../engine_license.js";
 import { onStart } from "../engine_lifecycle_api.js";
 import { setDracoDecoderPath, setDracoDecoderType, setKtx2TranscoderPath } from "../engine_loaders.gltf.js";
 import { Context, ContextCreateArgs } from "../engine_setup.js";
+import { HTMLElementBase } from "../engine_ssr.js";
 import { nameToThreeTonemapping } from "../engine_tonemapping.js";
 import { type INeedleEngineComponent, type LoadedModel } from "../engine_types.js";
 import type { addAttributeChangeCallback } from "../engine_utils.js";
@@ -42,11 +42,17 @@ export interface NeedleEngineAttributes {
     'hash': string;
     /** Set to automatically add OrbitControls to the loaded scene. */
     'camera-controls': string;
-    /** Override the default draco decoder path location. */
+    /** Override the default Draco decoder/decompressor path. Can be a URL or a local path to a directory containing the Draco decoder files.
+     * @default "https://www.gstatic.com/draco/versioned/decoders/1.5.7/"
+     * @example <needle-engine dracoDecoderPath="./decoders/draco/"></needle-engine>
+     */
     'dracoDecoderPath': string;
-    /** Override the default draco library type. */
+    /** Override the default Draco decoder type. */
     'dracoDecoderType': 'wasm' | 'js';
-    /** Override the default KTX2 transcoder/decoder path. */
+    /** Override the default KTX2 transcoder/decoder path. Can be a URL or a local path to a directory containing the KTX2 transcoder files.
+     * @default "https://cdn.needle.tools/static/three/0.179.1/basis2/"
+     * @example <needle-engine ktx2DecoderPath="./decoders/ktx2/"></needle-engine>
+     */
     'ktx2DecoderPath': string;
     /** Prevent context from being disposed when element is removed from DOM. */
     'keep-alive': 'true' | 'false';