@needle-tools/engine 5.1.0-alpha.3 → 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_serialization_builtin_serializer.ts

@@ -124,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 {
@@ -334,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;

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-components/Animator.ts

@@ -89,6 +89,15 @@ export class Animator extends Behaviour implements IAnimationComponent {
         return true;
     }
 
+    /**
+     * The current animator mixer, used for low-level control of animations. Owned by the AnimatorController
+     * @returns The current AnimationMixer, or null if no controller is assigned
+     * @see AnimatorController.mixer
+     */
+    get mixer() {
+        return this._animatorController?.mixer || null;
+    }
+
     /**
      * When enabled, animation will affect the root transform position and rotation
      */
@@ -401,17 +410,15 @@ export class Animator extends Behaviour implements IAnimationComponent {
     initializeRuntimeAnimatorController(force: boolean = false) {
         const shouldRun = (force || this.runtimeAnimatorController !== this._initializeWithRuntimeAnimatorController);
         if (this.runtimeAnimatorController && shouldRun) {
-            const clone = this.runtimeAnimatorController.clone();
-            this._initializeWithRuntimeAnimatorController = clone;
-            if (clone) {
-                console.assert(this.runtimeAnimatorController !== clone);
-                this.runtimeAnimatorController = clone;
-                console.assert(this.runtimeAnimatorController === clone);
-                this.runtimeAnimatorController.bind(this);
-                this.runtimeAnimatorController.setSpeed(this._speed);
-                this.runtimeAnimatorController.normalizedStartOffset = this._normalizedStartOffset;
-            }
-            else console.warn("Could not clone animator controller", this.runtimeAnimatorController);
+            // Create a fresh controller from the (possibly remapped) model.
+            // The constructor deep-clones the model, preserving Object3D refs that
+            // the resolve system has already remapped to cloned objects.
+            const controller = new AnimatorController(this.runtimeAnimatorController.model);
+            this.runtimeAnimatorController = controller;
+            this._initializeWithRuntimeAnimatorController = controller;
+            controller.bind(this);
+            controller.setSpeed(this._speed);
+            controller.normalizedStartOffset = this._normalizedStartOffset;
         }
     }