@needle-tools/engine 5.1.0-canary.deec6e4 → 5.1.0-canary.e7c2511

package/src/engine/engine_instantiate_resolve.ts

@@ -0,0 +1,407 @@
+import type { Color, Euler, Matrix2, Matrix3, Matrix4, Object3D, Quaternion, Vector2, Vector3, Vector4 } from "three";
+
+import { InstantiateIdProvider } from "./engine_networking_instantiate.js";
+import { isSerializable } from "./engine_serialization_core.js";
+import { type GuidsMap, type IComponent, type UIDProvider, isComponent } from "./engine_types.js";
+import { getParam } from "./engine_utils.js";
+
+const debug = getParam("debuginstantiate");
+
+// ————————————————————————————————————————————————————————
+// Types
+// ————————————————————————————————————————————————————————
+
+export type ObjectCloneReference = {
+    readonly original: object;
+    readonly clone: object;
+}
+
+/** Maps uuid/guid → { original, clone } for Object3D and Component instances */
+export type InstantiateReferenceMap = Record<string, ObjectCloneReference>;
+
+/**
+ * Provides access to the instantiated object map (used by EventList etc.)
+ */
+export type InstantiateContext = Readonly<InstantiateReferenceMap>;
+
+
+// ————————————————————————————————————————————————————————
+// ID Provider Cache (moved from engine_gltf_builtin_components.ts)
+// ————————————————————————————————————————————————————————
+
+/**
+ * Cache of id providers per component/object guid.
+ * Ensures deterministic guid generation regardless of scene order.
+ */
+const idProviderCache = new Map<string, InstantiateIdProvider>();
+
+/** Clear the id provider cache (e.g. when reloading a context) */
+export function clearIdProviderCache() {
+    idProviderCache.clear();
+}
+
+// ————————————————————————————————————————————————————————
+// Guid Generation (moved from engine_gltf_builtin_components.ts)
+// ————————————————————————————————————————————————————————
+
+export const originalComponentNameKey = Symbol("original-component-name");
+
+// #region hierarchy guids
+/**
+ * Recursively generates new deterministic guids for all objects and components in a hierarchy.
+ * Uses the idProviderCache so that the same source guid always produces the same output guid
+ * (needed for networking: all clients must agree on the guids of instantiated objects).
+ * Populates guidsMap (oldGuid → newGuid) so string references can be remapped afterwards.
+ */
+export function generateGuidsForHierarchy(
+    obj: Object3D,
+    idProvider: UIDProvider | null,
+    guidsMap: GuidsMap,
+): void {
+    if (idProvider === null) return;
+    if (!obj) return;
+    const prev = (obj as any).guid;
+
+    // Use a cached id provider per object to ensure stable guids regardless of hierarchy order
+    const idProviderKey = (obj as any).guid;
+    if (idProviderKey?.length) {
+        if (!idProviderCache.has(idProviderKey)) {
+            if (debug) console.log("Creating InstanceIdProvider with key \"" + idProviderKey + "\" for object " + obj.name);
+            idProviderCache.set(idProviderKey, new InstantiateIdProvider(idProviderKey));
+        }
+    }
+    const objectIdProvider = idProviderKey && idProviderCache.get(idProviderKey) || idProvider;
+
+    (obj as any).guid = objectIdProvider.generateUUID();
+    if (prev && prev !== "invalid")
+        guidsMap[prev] = (obj as any).guid;
+
+    if (obj && obj.userData && obj.userData.components) {
+        for (const comp of obj.userData.components) {
+            if (comp === null) continue;
+
+            const compIdProviderKey = comp.guid;
+            if (compIdProviderKey) {
+                if (!idProviderCache.has(compIdProviderKey)) {
+                    if (debug) console.log("Creating InstanceIdProvider with key \"" + compIdProviderKey + "\" for component " + comp[originalComponentNameKey]);
+                    idProviderCache.set(compIdProviderKey, new InstantiateIdProvider(compIdProviderKey));
+                }
+            }
+            else if (debug) console.warn("Can not create IdProvider: component " + comp[originalComponentNameKey] + " has no guid", comp.guid);
+            const componentIdProvider = idProviderCache.get(compIdProviderKey) || idProvider;
+
+            const compPrev = comp.guid;
+            comp.guid = componentIdProvider.generateUUID();
+            if (compPrev && compPrev !== "invalid")
+                guidsMap[compPrev] = comp.guid;
+        }
+    }
+    if (obj.children) {
+        for (const child of obj.children) {
+            generateGuidsForHierarchy(child as Object3D, idProvider, guidsMap);
+        }
+    }
+}
+
+// ————————————————————————————————————————————————————————
+// #region reference resolution
+// ————————————————————————————————————————————————————————
+
+/**
+ * The unified reference resolution function.
+ * Iterates all cloned components in the objectMap and remaps their properties
+ * to point at cloned counterparts where appropriate.
+ *
+ * Handles: Component, Object3D, Array, Map, Set, Record/plain objects,
+ * EventList, Vector/Color/Quaternion, and @serializable nested objects.
+ */
+export function resolveInstanceReferences(objectMap: InstantiateReferenceMap): void {
+    for (const key in objectMap) {
+        const val = objectMap[key];
+        const clone = val.clone as Object3D | null;
+        if (!clone?.isObject3D || !clone?.userData?.components) continue;
+
+        for (let i = 0; i < clone.userData.components.length; i++) {
+            const component = clone.userData.components[i];
+            const entries = Object.entries(component);
+            for (const [propKey, propValue] of entries) {
+                if (propValue === null || propValue === undefined) continue;
+                // Skip primitives that can't be remapped, but allow strings for guid resolution
+                if (typeof propValue !== "object" && typeof propValue !== "string") continue;
+                const resolved = resolveValue(propKey, propValue, objectMap);
+                if (resolved !== undefined) {
+                    component[propKey] = resolved;
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Resolves string-based guid references in all components of a hierarchy using a GuidsMap.
+ * Used by the glTF loading path where objects get new guids assigned and string references
+ * (e.g. PlayableDirector track.outputs) need to be updated.
+ */
+export function resolveStringGuidsInHierarchy(root: Object3D, guidsMap: GuidsMap): void {
+    resolveStringGuidsRecursive(root, guidsMap);
+}
+
+function resolveStringGuidsRecursive(obj: Object3D, guidsMap: GuidsMap): void {
+    if (obj.userData?.components) {
+        for (const component of obj.userData.components) {
+            if (component === null) continue;
+            resolveStringGuidsInObject(component, guidsMap);
+        }
+    }
+    if (obj.children) {
+        for (const child of obj.children) {
+            resolveStringGuidsRecursive(child as Object3D, guidsMap);
+        }
+    }
+}
+
+function resolveStringGuidsInObject(obj: any, guidsMap: GuidsMap, visited?: WeakSet<object>): void {
+    if (!visited) visited = new WeakSet();
+    if (visited.has(obj)) return;
+    visited.add(obj);
+
+    for (const key of Object.keys(obj)) {
+        const value = obj[key];
+        if (value === null || value === undefined) continue;
+        if (typeof value === "string") {
+            if (guidsMap[value]) {
+                obj[key] = guidsMap[value];
+            }
+        }
+        else if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++) {
+                if (typeof value[i] === "string" && guidsMap[value[i]]) {
+                    value[i] = guidsMap[value[i]];
+                }
+                else if (typeof value[i] === "object" && value[i] !== null) {
+                    resolveStringGuidsInObject(value[i], guidsMap, visited);
+                }
+            }
+        }
+        else if (typeof value === "object") {
+            // Skip known non-data objects
+            if (value.isObject3D || value.isComponent) continue;
+            resolveStringGuidsInObject(value, guidsMap, visited);
+        }
+    }
+}
+
+// #region resolveValue
+/**
+ * Resolve a single value, returning the remapped value or undefined if no remap needed.
+ * This is the core remapping logic called recursively for nested structures.
+ */
+export function resolveValue(key: string, value: unknown, objectMap: InstantiateReferenceMap): any | undefined {
+
+    // Handle null/undefined early to avoid unnecessary processing
+    if (value === undefined) return undefined;
+    if (value === null) return null;
+
+    // String guid resolution: if this string is a known guid/uuid in the objectMap,
+    // resolve it directly to the clone object. This handles e.g. PlayableDirector track.outputs.
+    if (typeof value === "string") {
+        const ref = objectMap[value];
+        if (ref) {
+            return ref.clone;
+        }
+        return undefined;
+    }
+
+    // Primitives: no remapping needed
+    if (typeof value !== "object") return undefined;
+
+    // 1. Component → find cloned counterpart by gameObject.uuid + component index
+    if (isComponent(value)) {
+        return resolveComponentReference(value, objectMap);
+    }
+
+    // 2. Object3D → uuid lookup, return clone if found (otherwise external, keep as-is)
+    if ((value as Object3D).isObject3D === true) {
+        if (key === "gameObject") return undefined;
+        const id = (value as Object3D).uuid;
+        const cloneRef = objectMap[id]?.clone;
+        if (cloneRef) {
+            if (debug) console.log(key, "old", value, "new", cloneRef);
+            return cloneRef;
+        }
+        return undefined;
+    }
+
+    // 3. Cloneable value types (Vector3, Quaternion, Euler, Color)
+    if (isCloneableValueType(value)) {
+        return value.clone();
+    }
+
+    // 4. Array → create new array, recursively resolve each element
+    if (Array.isArray(value)) {
+        return resolveArray(key, value, objectMap);
+    }
+
+    // 5. Map → create new Map, resolve keys and values
+    if (value instanceof Map) {
+        return resolveMap(value, objectMap);
+    }
+
+    // 6. Set → create new Set, resolve values
+    if (value instanceof Set) {
+        return resolveSet(value, objectMap);
+    }
+
+    // 7. WeakMap / WeakSet → NOT iterable, cannot remap. Keep as-is.
+    if (value instanceof WeakMap || value instanceof WeakSet) {
+        return undefined;
+    }
+
+    // 8. @serializable objects (incl. EventList, CallInfo) → shallow clone + recursively resolve $serializedTypes fields
+    if (isSerializable(value) && value.$serializedTypes) {
+        return resolveSerializableObject(value, objectMap);
+    }
+
+    // 9. Plain objects / Records → shallow clone, resolve each value
+    if (isPlainObject(value)) {
+        return resolvePlainObject(key, value, objectMap);
+    }
+
+    return undefined;
+}
+
+// ————————————————————————————————————————————————————————
+// Internal Helpers
+// ————————————————————————————————————————————————————————
+
+function resolveComponentReference(value: IComponent, objectMap: InstantiateReferenceMap): object | undefined {
+    const originalGameObject = value["gameObject"] as Object3D | undefined;
+    if (!originalGameObject) return undefined;
+
+    const id = originalGameObject.uuid;
+    const newGameObject = objectMap[id]?.clone as Object3D | undefined;
+    if (!newGameObject) {
+        // Reference points to an object not in the cloned hierarchy (external)
+        if (debug) console.log("Component reference did not change (external)", value);
+        return undefined;
+    }
+
+    const index = originalGameObject.userData.components.indexOf(value);
+    if (index >= 0 && newGameObject.isObject3D) {
+        if (debug) console.log("Resolved component", id, "at index", index);
+        return newGameObject.userData.components[index];
+    }
+    else {
+        console.warn("Could not find component at expected index", value);
+    }
+    return undefined;
+}
+
+function resolveArray(key: string, arr: unknown[], objectMap: InstantiateReferenceMap): unknown[] {
+    const result: unknown[] = [];
+    for (let i = 0; i < arr.length; i++) {
+        const entry = arr[i];
+        if (entry === null || entry === undefined) {
+            result.push(entry);
+            continue;
+        }
+        // Skip primitives that can't be remapped (numbers, booleans)
+        // but allow strings through for guid resolution
+        if (typeof entry !== "object" && typeof entry !== "string") {
+            result.push(entry);
+            continue;
+        }
+        const resolved = resolveValue(key, entry, objectMap);
+        result.push(resolved !== undefined ? resolved : entry);
+    }
+    return result;
+}
+
+function resolveMap(map: Map<unknown, unknown>, objectMap: InstantiateReferenceMap): Map<any, any> {
+    const result = new Map();
+    let didChange = false;
+    for (const [mapKey, mapValue] of map) {
+        let resolvedKey = mapKey;
+        let resolvedValue = mapValue;
+
+        if (typeof mapKey === "object" && mapKey !== null) {
+            const rk = resolveValue("", mapKey, objectMap);
+            if (rk !== undefined) { resolvedKey = rk; didChange = true; }
+        }
+        if (typeof mapValue === "object" && mapValue !== null) {
+            const rv = resolveValue("", mapValue, objectMap);
+            if (rv !== undefined) { resolvedValue = rv; didChange = true; }
+        }
+        result.set(resolvedKey, resolvedValue);
+    }
+    return didChange ? result : result; // always return new Map to prevent shared mutation
+}
+
+function resolveSet(set: Set<unknown>, objectMap: InstantiateReferenceMap): Set<any> {
+    const result = new Set();
+    for (const entry of set) {
+        if (typeof entry === "object" && entry !== null) {
+            const resolved = resolveValue("", entry, objectMap);
+            result.add(resolved !== undefined ? resolved : entry);
+        } else {
+            result.add(entry);
+        }
+    }
+    return result;
+}
+
+function resolveSerializableObject(value: unknown, objectMap: InstantiateReferenceMap): any | undefined {
+    // Clone the serializable object to avoid mutating the original (which may be shared with source)
+    const cloned = Object.assign(Object.create(Object.getPrototypeOf(value)), value);
+    let didChange = false;
+    for (const key in cloned.$serializedTypes) {
+        const val = cloned[key];
+        if (val === null || val === undefined) continue;
+        if (typeof val === "object") {
+            if (debug) console.log("Recursively resolve references for", key, val);
+            const resolved = resolveValue(key, val, objectMap);
+            if (resolved !== undefined) {
+                cloned[key] = resolved;
+                didChange = true;
+            }
+        }
+    }
+    return didChange ? cloned : undefined;
+}
+
+function resolvePlainObject(_parentKey: string, obj: Record<string, unknown>, objectMap: InstantiateReferenceMap): Record<string, unknown> | undefined {
+    let didChange = false;
+    const clone = { ...obj };
+    for (const key of Object.keys(clone)) {
+        const val = clone[key];
+        if (val === null || val === undefined) continue;
+        // Skip primitives that can't be remapped, but allow strings for guid resolution
+        if (typeof val !== "object" && typeof val !== "string") continue;
+        const resolved = resolveValue(key, val, objectMap);
+        if (resolved !== undefined) {
+            clone[key] = resolved;
+            didChange = true;
+        }
+    }
+    return didChange ? clone : undefined;
+}
+
+function isPlainObject(obj: unknown): obj is Record<string, unknown> {
+    if (typeof obj !== "object" || obj === null) return false;
+    const proto = Object.getPrototypeOf(obj);
+    return proto === Object.prototype || proto === null;
+}
+
+/** Returns true if the object is a three.js value type that should be cloned (not remapped) */
+function isCloneableValueType(value: object): value is { clone(): object } {
+    return (value as Vector2).isVector2 === true ||
+        (value as Vector3).isVector3 === true ||
+        (value as Vector4).isVector4 === true ||
+        (value as Quaternion).isQuaternion === true ||
+        (value as Euler).isEuler === true ||
+        (value as Color).isColor === true ||
+        (value as Matrix2).isMatrix2 === true ||
+        (value as Matrix3).isMatrix3 === true ||
+        (value as Matrix4).isMatrix4 === true;
+}
+

package/src/engine/engine_license.ts

@@ -3,9 +3,9 @@ import { ContextEvent, ContextRegistry } from "./engine_context_registry.js";
 import { onInitialized } from "./engine_lifecycle_api.js";
 import { isLocalNetwork } from "./engine_networking_utils.js";
 import { Context } from "./engine_setup.js";
+import { SSR } from "./engine_ssr.js";
 import type { IContext } from "./engine_types.js";
 import { getParam } from "./engine_utils.js";
-import { SSR } from "./engine_ssr.js";
 
 const debug = getParam("debuglicense");
 

package/src/engine/engine_mainloop_utils.ts

@@ -344,8 +344,11 @@ function updateIsActiveInHierarchyRecursiveRuntime(go: Object3D, activeInHierarc
         if (allowEventCall) {
             const components = go.userData?.components;
             if (components) {
-                for (let ci = components.length - 1, cl = -1; ci > cl; ci--) {
-                    const comp = components[ci];
+                // We need to iterate on components in the original order right now to work-around UI related initialization bugs where RectTransform must be initialized before e.g. Graphic components. https://linear.app/needle/issue/NE-6986
+                // In the future we can reverse iterate this once the UI system has been replaced (that being said it's probably expected that component enable in the order in which they're added to an object)
+                const componentsCopy = [...components];
+                for (let ci = 0; ci < componentsCopy.length; ci++) {
+                    const comp = componentsCopy[ci];
                     if (activeInHierarchy) {
                         if (comp?.enabled) {
                             try { comp.__internalAwake(); }

package/src/engine/engine_networking.ts

@@ -828,7 +828,9 @@ export class NetworkConnection implements INetworkConnection {
         this._ws = undefined;
         networkingServerUrl = undefined;
 
-        // Reset all state
+        // Reset all state synchronously so callers can rely on isConnected/isInRoom immediately
+        this.connected = false;
+        this._connectionId = null;
         this._currentRoomAllowEditing = true;
         this._currentRoomName = null;
         this._currentRoomViewId = null;

package/src/engine/engine_networking_blob.ts

@@ -3,7 +3,7 @@ import { FileLoader } from "three";
 import { showBalloonWarning } from "./debug/index.js";
 import { hasCommercialLicense } from "./engine_license.js";
 import { delay } from "./engine_utils.js";
-import { md5Hex, md5AsBytes, sha256Base64 } from "./engine_utils_hash.js";
+import { md5AsBytes, md5Hex, sha256Base64 } from "./engine_utils_hash.js";
 
 
 export namespace BlobStorage {

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.