@needle-tools/engine 5.1.0-canary.db0c38f → 5.1.0-canary.e6680fa

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'
 
@@ -402,11 +402,16 @@ export class RapierPhysics implements IPhysicsEngine {
         filterGroups?: number,
         /** Return false to ignore this collider */
         filterPredicate?: (c: ICollider) => boolean,
-        /** When enabled the hit object's layer will be tested. If layer 2 is enabled the object will be ignored (Layer 2 == IgnoreRaycast) 
+        /** When enabled the hit object's layer will be tested. If layer 2 is enabled the object will be ignored (Layer 2 == IgnoreRaycast)
          * If not set the raycast will ignore objects in the IgnoreRaycast layer (default: true)
-         * @default undefined 
+         * @default undefined
         */
-        useIgnoreRaycastLayer?: boolean
+        useIgnoreRaycastLayer?: boolean,
+        /** When true, trigger/sensor colliders will be included in the raycast results.
+         * By default trigger colliders are skipped.
+         * @default false
+         */
+        includeTriggers?: boolean,
     })
         : null | { point: Vector3, collider: ICollider } {
 
@@ -428,6 +433,8 @@ export class RapierPhysics implements IPhysicsEngine {
 
         const hit = this.world?.castRay(ray, maxDistance, solid, options?.queryFilterFlags, options?.filterGroups, undefined, undefined, (c) => {
             const component = c[$componentKey];
+            // Skip trigger/sensor colliders unless explicitly included
+            if (options?.includeTriggers !== true && component?.isTrigger) return false;
             if (options?.filterPredicate) return options.filterPredicate(component);
             if (options?.useIgnoreRaycastLayer !== false) {
                 // ignore objects in the IgnoreRaycast=2 layer
@@ -453,11 +460,16 @@ export class RapierPhysics implements IPhysicsEngine {
         filterGroups?: number,
         /** Return false to ignore this collider */
         filterPredicate?: (c: ICollider) => boolean,
-        /** When enabled the hit object's layer will be tested. If layer 2 is enabled the object will be ignored (Layer 2 == IgnoreRaycast) 
+        /** When enabled the hit object's layer will be tested. If layer 2 is enabled the object will be ignored (Layer 2 == IgnoreRaycast)
          * If not set the raycast will ignore objects in the IgnoreRaycast layer (default: true)
-         * @default undefined 
+         * @default undefined
         */
-        useIgnoreRaycastLayer?: boolean
+        useIgnoreRaycastLayer?: boolean,
+        /** When true, trigger/sensor colliders will be included in the raycast results.
+         * By default trigger colliders are skipped.
+         * @default false
+         */
+        includeTriggers?: boolean,
     })
         : null | { point: Vector3, normal: Vector3, collider: ICollider } {
 
@@ -478,6 +490,8 @@ export class RapierPhysics implements IPhysicsEngine {
 
         const hit = this.world?.castRayAndGetNormal(ray, maxDistance, solid, options?.queryFilterFlags, options?.filterGroups, undefined, undefined, (c) => {
             const component = c[$componentKey];
+            // Skip trigger/sensor colliders unless explicitly included
+            if (options?.includeTriggers !== true && component?.isTrigger) return false;
             if (options?.filterPredicate) return options.filterPredicate(component);
             if (options?.useIgnoreRaycastLayer !== false) {
                 // ignore objects in the IgnoreRaycast=2 layer
@@ -690,12 +704,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 +1009,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 +1162,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 +1198,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 +1515,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 +1541,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_pmrem.ts

@@ -1,8 +1,8 @@
 import { createLoaders } from "@needle-tools/gltf-progressive";
 import { CubeUVReflectionMapping, EquirectangularRefractionMapping, SRGBColorSpace, Texture, TextureLoader, WebGLRenderer } from "three";
-import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader";
-import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader";
-import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader";
+import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader.js";
+import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader.js";
+import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader.js";
 
 const running: Map<string, Promise<Texture | null>> = new Map();
 
@@ -37,9 +37,59 @@ async function internalLoadPMREM(url: URL, renderer: WebGLRenderer) {
     const pathname = url.pathname;
     const isPMREM_URL: boolean = url.toString().toLowerCase().includes("pmrem") || url.searchParams.get("pmrem") != null;
 
-    const isEXR = pathname.endsWith(".exr");
-    const isHdr = pathname.endsWith(".hdr");
-    const isKtx2 = pathname.endsWith(".ktx2");
+    let isEXR = pathname.endsWith(".exr");
+    let isHdr = pathname.endsWith(".hdr");
+    let isKtx2 = pathname.endsWith(".ktx2");
+
+    // For URLs that don't carry a recognizable extension (e.g. `blob:` URLs
+    // from dropped local files, or signed CDN URLs that elide the filename),
+    // sniff Content-Type and a few magic bytes to pick the right loader.
+    // EXRLoader / RGBELoader / KTX2Loader vs TextureLoader is not interchangeable —
+    // routing EXR binary data through TextureLoader fails outright.
+    if (!isEXR && !isHdr && !isKtx2) {
+        try {
+            const probe = await fetch(url.toString(), {
+                method: "GET",
+                headers: { range: "bytes=0-15" },
+            });
+            const contentType = probe.headers.get("content-type")?.toLowerCase() ?? "";
+
+            // Content-Type wins when it's specific — skip reading the body.
+            if (contentType === "image/x-exr" || contentType === "image/aces") {
+                isEXR = true;
+            }
+            else if (contentType === "image/vnd.radiance" || contentType === "image/x-hdr") {
+                isHdr = true;
+            }
+            else if (contentType === "image/ktx2") {
+                isKtx2 = true;
+            }
+            // Otherwise fall back to magic-byte sniffing.
+            else {
+                const bytes = new Uint8Array(await probe.arrayBuffer());
+                if (bytes.length >= 4 && bytes[0] === 0x76 && bytes[1] === 0x2f && bytes[2] === 0x31 && bytes[3] === 0x01) {
+                    // EXR magic: 0x76 0x2f 0x31 0x01
+                    isEXR = true;
+                }
+                else if (bytes.length >= 12
+                    && bytes[0] === 0xAB && bytes[1] === 0x4B && bytes[2] === 0x54 && bytes[3] === 0x58
+                    && bytes[4] === 0x20 && bytes[5] === 0x32 && bytes[6] === 0x30 && bytes[7] === 0xBB) {
+                    // KTX2 magic: «KTX 20»\r\n\x1A\n
+                    isKtx2 = true;
+                }
+                else if (bytes.length >= 10
+                    && bytes[0] === 0x23 && bytes[1] === 0x3F   // "#?"
+                    && bytes[2] === 0x52 && bytes[3] === 0x41 && bytes[4] === 0x44 && bytes[5] === 0x49 // "RADI"
+                    && bytes[6] === 0x41 && bytes[7] === 0x4E && bytes[8] === 0x43 && bytes[9] === 0x45) { // "ANCE"
+                    // Radiance HDR header: "#?RADIANCE"
+                    isHdr = true;
+                }
+            }
+        }
+        catch (err) {
+            console.warn("loadPMREM: failed to probe URL for format detection", url, err);
+        }
+    }
 
     let loader: RGBELoader | EXRLoader | TextureLoader | KTX2Loader;
 

package/src/engine/engine_scenedata.ts

@@ -1,20 +1,19 @@
-import type { SceneData } from "needle:bindings";
-import type { IContext } from "./engine_types.js";
-import { getComponent } from "./engine_components.js";
-import { TypeStore } from "./engine_typestore.js";
+import type { SceneData } from "needle-bindings";
+export type { SceneData };
 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";
 
 /**
- * Global proxy for the primary Needle Engine context.
- * Resolves lazily on property access via `ContextRegistry.Current` —
- * safe to import at module level, including in SSR environments
- * (returns a silent error proxy when no context is active).
+ * Quick access to the current Needle Engine context from anywhere — no need to pass `ctx` around.
+ * Use it in React/Svelte/Vue components, button handlers, or plain JavaScript.
  *
- * Use this outside of Needle component lifecycle (e.g. in Svelte/React/Vue
- * components, button handlers, or vanilla JS) instead of threading `ctx` around.
+ * Safe to import at module level, including in SSR environments.
+ * For pages with multiple `<needle-engine>` elements, use `ctx` directly instead.
  *
- * For multiple `<needle-engine>` elements on the same page, use `ctx` directly.
+ * @experimental This API may change in future releases.
  *
  * @example
  * import { needle } from "@needle-tools/engine";
@@ -28,7 +27,7 @@ export const needle: IContext = new Proxy({} as IContext, {
         const ctx = ContextRegistry.Current;
         if (!ctx) {
             const fn = isDevEnvironment() ? console.error : console.warn;
-            fn(`[needle] needle.${prop} accessed before scene started`);
+            fn(`[needle] needle.${prop} was accessed before the scene started. Use "needle" inside event handlers or callbacks, not at module top-level. For setup code use: onStart(ctx => { ... })`);
             return makeErrorProxy(`needle not ready — scene hasn't started yet`);
         }
         const val = (ctx as any)[prop];
@@ -38,7 +37,7 @@ export const needle: IContext = new Proxy({} as IContext, {
         const ctx = ContextRegistry.Current;
         if (!ctx) {
             const fn = isDevEnvironment() ? console.error : console.warn;
-            fn(`[needle] needle.${prop} set before scene started`);
+            fn(`[needle] needle.${prop} was set before the scene started. Use "needle" inside event handlers or callbacks, not at module top-level. For setup code use: onStart(ctx => { ... })`);
             return true;
         }
         (ctx as any)[prop] = value;
@@ -70,36 +69,63 @@ function makeErrorProxy(message: string): object {
     return new Proxy({}, handler);
 }
 
+/**
+ * Returns a proxy for a scene node that exposes `$object`, `$components`,
+ * and child nodes as nested properties.
+ */
+function makeNodeProxy(ctx: IContext, node: import("three").Object3D): object {
+    return new Proxy({}, {
+        get(_t, prop: string) {
+            if (prop === "$object") return node;
+            if (prop === "$components") {
+                return new Proxy({}, {
+                    get(_t2, compName: string) {
+                        if (compName === "then") return undefined;
+                        const ctor = TypeStore.get(compName);
+                        if (!ctor) return makeErrorProxy(`Component type "${compName}" not registered (node "${node.name}")`);
+                        const comp = getComponent(node, ctor);
+                        if (!comp) return makeErrorProxy(`Component "${compName}" not found on node "${node.name}"`);
+                        return comp;
+                    }
+                });
+            }
+            if (prop === "then") return undefined; // not a Promise
+            // Child node lookup by name
+            const child = node.children.find(c => c.name === prop) ?? null;
+            if (!child) {
+                const fn = isDevEnvironment() ? console.error : console.warn;
+                fn(`[SceneData] "${prop}" is not a child of "${node.name}". Use .$object to get the Three.js object or .$components.Name to access a component.`);
+                return makeErrorProxy(`"${prop}" not found on node "${node.name}"`);
+            }
+            return makeNodeProxy(ctx, child);
+        }
+    });
+}
+
 /**
  * Returns a lazily-resolved proxy typed as {@link SceneData}.
  * The proxy is cached per context — each context gets exactly one instance.
  *
- * Accessing a property traverses the scene graph on demand:
- * - First level  → find Object3D by node name
- * - Second level → getComponent by component name (via TypeStore)
- * - Third level  → read/write a field on the real component instance
- *
- * If a node or component is not found, property accesses log a warning
- * instead of throwing, so chained access never crashes.
+ * Shape mirrors the generated `needle-bindings.gen.d.ts`:
+ *   ctx.sceneData.MyGlb.Camera.$components.OrbitControls.autoRotate = true;
+ *   ctx.sceneData.MyGlb.Camera.$object  // → THREE.Camera
+ *   ctx.sceneData.MyGlb.UI.Button.$components.Button  // → Needle Button component
  *
- * @example
- * ctx.sceneData.Camera.OrbitControls.autoRotate = true;
+ * GLB name is ignored at runtime (scene is already loaded).
+ * Node lookup starts at the scene root.
  */
 export function getSceneData(ctx: IContext): SceneData {
     let proxy = cache.get(ctx);
     if (!proxy) {
         proxy = new Proxy({} as SceneData, {
-            get(_target, nodeName: string) {
+            get(_target, _glbName: string) {
+                // GLB name level — ignored at runtime, return node-name proxy
                 return new Proxy({}, {
-                    get(_target, compName: string) {
+                    get(_target, nodeName: string) {
+                        if (nodeName === "then") return undefined;
                         const node = ctx.scene.getObjectByName(nodeName) ?? null;
                         if (!node) return makeErrorProxy(`Node "${nodeName}" not found in scene`);
-                        if (compName === "$node") return node;
-                        const ctor = TypeStore.get(compName);
-                        if (!ctor) return makeErrorProxy(`Component type "${compName}" not registered (node "${nodeName}")`);
-                        const comp = getComponent(node, ctor);
-                        if (!comp) return makeErrorProxy(`Component "${compName}" not found on node "${nodeName}"`);
-                        return comp;
+                        return makeNodeProxy(ctx, node);
                     }
                 });
             }

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();
+}