@needle-tools/engine 4.17.0-next.36dcae2 → 4.17.0-next.4989636

package/src/engine/engine_audio.ts

@@ -21,5 +21,4 @@ export function ensureAudioContextIsResumed() {
             }, 500);
         });
     });
-}
-setTimeout(ensureAudioContextIsResumed, 1000);
+}

package/src/engine/engine_components.ts

@@ -44,7 +44,10 @@ export function getOrAddComponent<T extends IComponent>(go: Object3D, typeName:
     return addComponent(go, typeName, init);
 }
 
-const idProvider = new InstantiateIdProvider("addComponentIdProvider");
+let idProvider: InstantiateIdProvider;
+function getIdProvider() {
+    return idProvider ??= new InstantiateIdProvider("addComponentIdProvider");
+}
 
 export function addNewComponent<T extends IComponent>(obj: Object3D, componentInstance: T, callAwake = true): T {
     if (!obj) {
@@ -56,7 +59,7 @@ export function addNewComponent<T extends IComponent>(obj: Object3D, componentIn
     componentInstance.gameObject = obj as IGameObject;
     // TODO: currently add component does not ensure a new component instance has a guid
     if (componentInstance.guid === undefined || componentInstance.guid === "invalid") {
-        componentInstance.guid = idProvider.generateUUID();
+        componentInstance.guid = getIdProvider().generateUUID();
     }
     apply(obj);
     // register the component - make sure to provide the component instance context (if assigned)
@@ -106,7 +109,7 @@ export function addComponent<T extends IComponent>(obj: Object3D, componentInsta
     // componentInstance.__internalEnable();
     // componentInstance.transform = obj;
     if (componentInstance.guid === undefined || componentInstance.guid === "invalid") {
-        componentInstance.guid = idProvider.generateUUID();
+        componentInstance.guid = getIdProvider().generateUUID();
     }
     if(init) componentInstance._internalInit(init);
     // Register the component - make sure to provide the component instance context (if assigned)

package/src/engine/engine_gltf_builtin_components.ts

@@ -1,5 +1,3 @@
-import "./codegen/register_types.js";
-
 import { Object3D } from "three";
 import { type GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
 
@@ -214,9 +212,10 @@ async function onCreateBuiltinComponents(context: SerializationContext, obj: Obj
             for (const compData of components) {
                 try {
                     if (compData === null) continue;
-                    const type = TypeStore.get(compData.name);
-                    // console.log(compData, compData.name, type, TypeStore);
-                    if (type !== undefined && type !== null) {
+                    let type = TypeStore.get(compData.name);
+                    // If not eagerly registered, try lazy/async loading
+                    if (!type) type = await TypeStore.getAsync(compData.name);
+                    if (type) {
                         const instance: IComponent = new type() as IComponent;
                         instance.sourceId = context.gltfId;
 

package/src/engine/engine_init.ts

@@ -0,0 +1,45 @@
+import { initAnimationAutoplay } from "../engine-components/AnimationUtilsAutoplay.js";
+import { initCameraUtils } from "../engine-components/CameraUtils.js";
+import { initSceneSwitcherAttributes } from "../engine-components/SceneSwitcher.js";
+import { initSkyboxAttributes } from "../engine-components/Skybox.js";
+import { initBuiltinTypes } from "./codegen/register_types.js";
+import { ensureAudioContextIsResumed } from "./engine_audio.js";
+import { initNeedleLoader } from "./engine_loaders.js";
+import { initShims } from "./engine_shims.js";
+import { patchTonemapping } from "./engine_tonemapping.js";
+import { initCameraExtensions } from "./js-extensions/Camera.js";
+import { patchLayers } from "./js-extensions/Layers.js";
+import { initObject3DExtensions } from "./js-extensions/Object3D.js";
+import { initVectorExtensions } from "./js-extensions/Vector.js";
+import { initWebComponents } from "./webcomponents/init.js";
+
+let initialized = false;
+
+/**
+ * Initialize all engine subsystems. Called once from the entry point.
+ *
+ * Every subsystem (prototype patches, type registrations, loader setup, etc.)
+ * is wrapped in an explicit init function instead of running at module scope.
+ * This creates an unbroken call chain from the entry point that bundlers can
+ * trace, so the package can declare `sideEffects: false` and tree-shake
+ * correctly — without maintaining a fragile list of side-effect files.
+ */
+export function initEngine() {
+    if (initialized) return;
+    initialized = true;
+
+    initWebComponents();
+    initShims();
+    patchTonemapping();
+    patchLayers();
+    initCameraExtensions();
+    initObject3DExtensions();
+    initVectorExtensions();
+    initBuiltinTypes();
+    initNeedleLoader();
+    setTimeout(ensureAudioContextIsResumed, 1000);
+    initCameraUtils();
+    initAnimationAutoplay();
+    initSkyboxAttributes();
+    initSceneSwitcherAttributes();
+}

package/src/engine/engine_loaders.ts

@@ -35,7 +35,8 @@ export class NeedleLoader implements INeedleGltfLoader {
         return loadSync(context, url, sourceId, seed, prog);
     }
 }
-registerLoader(NeedleLoader); // Register the loader
+/** Initialize the default NeedleLoader. Called from engine_init.ts */
+export function initNeedleLoader() { registerLoader(NeedleLoader); }
 
 
 const printGltf = utils.getParam("printGltf") || utils.getParam("printgltf");

package/src/engine/engine_modules.ts

@@ -43,4 +43,7 @@ export const MODULES = {
     POSTPROCESSING_AO: createModule<typeof import("n8ao")>(
         () => import("n8ao")
     ),
+    PEERJS: createModule<typeof import("peerjs")>(
+        () => import("peerjs")
+    ),
 };

package/src/engine/engine_networking.ts

@@ -118,6 +118,7 @@ declare type OwnershipResponse = {
 
 declare type WebsocketSendType = IModel | object | boolean | null | string | number;
 
+// #region OwnershipModel
 /**
  * Manages ownership of networked objects or components.
  *
@@ -368,6 +369,8 @@ export class OwnershipModel {
 }
 
 
+// #region Networking
+
 export declare type BinaryCallback = {
     (data: any | flatbuffers.ByteBuffer): void;
 }
@@ -411,6 +414,7 @@ export declare type BinaryCallback = {
  * @see {@link RoomEvents} for room lifecycle events
  * @see {@link OwnershipModel} for object ownership
  * @link https://engine.needle.tools/docs/how-to-guides/networking/
+ * @category Networking
  */
 export class NetworkConnection implements INetworkConnection {
 
@@ -560,7 +564,7 @@ export class NetworkConnection implements INetworkConnection {
         return true;
     }
 
-    /** Send a message to the networking backend - it will broadcasted to all connected users in the same room by default */
+    /** Send a message to the networking backend - it will be broadcasted to all connected users (except yourself) in the same room by default */
     public send<T extends WebsocketSendType>(key: string | OwnershipEvent, data: T | null = null, queue: SendQueue = SendQueue.Queued) {
 
         //@ts-ignore

package/src/engine/engine_networking_blob.ts

@@ -1,6 +1,6 @@
-// workaround for this is not a function when deployed
-// see https://github.com/pvorb/node-md5/issues/52
-import md5 from "md5";
+import * as _md5 from "md5";
+// CJS interop: md5 may appear as { default: fn } or fn depending on bundler
+const md5 = typeof _md5 === "function" ? _md5 : (_md5 as any).default;
 import { FileLoader } from "three";
 
 import { showBalloonWarning } from "./debug/index.js";

package/src/engine/engine_networking_peer.ts

@@ -1,6 +1,7 @@
 import type { DataConnection, PeerJSOption } from "peerjs";
-import Peer, { type PeerConnectOption } from "peerjs";
+import type Peer from "peerjs";
 
+import { MODULES } from "./engine_modules.js";
 import { type ConstructorConcrete } from "./engine_types.js";
 
 let peerOptions: PeerJSOption | undefined = undefined;
@@ -11,22 +12,23 @@ export function getPeerOptions() {
 export function setPeerOptions(opts: PeerJSOption) {
     peerOptions = opts;
 }
-export function getPeerjsInstance(id?: string, opts?: PeerJSOption): Peer {
+export async function getPeerjsInstance(id?: string, opts?: PeerJSOption): Promise<Peer> {
+    const peerjs = await MODULES.PEERJS.load();
+    const PeerConstructor = peerjs.default;
     if (!opts) opts = {}
     opts = {
         ...peerOptions,
         ...opts,
     }
     if (id)
-        return new Peer(id, opts);
-    return new Peer(opts);
+        return new PeerConstructor(id, opts);
+    return new PeerConstructor(opts);
 }
 
 
 
 async function importPeer(): Promise<ConstructorConcrete<Peer>> {
-    const pkg = await import("peerjs");
-    console.log(pkg);
+    const pkg = await MODULES.PEERJS.load();
     if (pkg.default === undefined) return pkg as any;
     return pkg.default;
 }

package/src/engine/engine_networking_streams.ts

@@ -1,4 +1,5 @@
-import Peer, { CallOption, MediaConnection } from "peerjs"
+import type Peer from "peerjs";
+import type { CallOption, MediaConnection } from "peerjs";
 import { EventDispatcher } from "three";
 
 import { RoomEvents } from "../engine/engine_networking.js";
@@ -285,14 +286,14 @@ export class PeerHandle extends EventDispatcher<any> {
     // private onUserJoinedOrLeftRoom(_: UserJoinedOrLeftRoomModel): void {
     // };
 
-    private setupPeer() {
+    private async setupPeer() {
         if (!this.context.connection.connectionId) return;
         if (this._enabledPeer) return;
         this._enabledPeer = true;
         if (!this._peer) {
             const peerId = this.getMyPeerId();
             if (peerId)
-                this._peer = getPeerjsInstance(peerId);
+                this._peer = await getPeerjsInstance(peerId);
             else console.error("Failed to setup peerjs because we dont have a connection id", this.context.connection.connectionId);
         }
         if (this._enabled)

package/src/engine/engine_physics_rapier.ts

@@ -203,6 +203,14 @@ export class RapierPhysics implements IPhysicsEngine {
         }
     }
 
+    setColliderEnabled(collider: ICollider, enabled: boolean): boolean {
+        const rapierCollider = collider[$bodyKey] as Collider;
+        if (!rapierCollider) return false;
+        rapierCollider.setEnabled(enabled);
+        if (debugPhysics) console.log("SET COLLIDER ENABLED", collider.name, enabled);
+        return true;
+    }
+
     updateBody(comp: ICollider | IRigidbody, translation: boolean, rotation: boolean) {
         this.validate();
         if (!this.enabled) return;
@@ -1188,6 +1196,7 @@ export class RapierPhysics implements IPhysicsEngine {
 
     // private _lastStepTime: number | undefined = 0;
     private lines?: LineSegments;
+    private disabledLines?: LineSegments;
 
     public step(dt?: number) {
         if (!this.world) return;
@@ -1238,29 +1247,53 @@ export class RapierPhysics implements IPhysicsEngine {
                 const material = new LineBasicMaterial({
                     color: 0x77dd77,
                     fog: false,
-                    // vertexColors: VertexColors
                 });
                 const geometry = new BufferGeometry();
                 this.lines = new LineSegments(geometry, material);
                 this.lines.layers.disableAll();
                 this.lines.layers.enable(2);
             }
+            if (!this.disabledLines) {
+                const material = new LineBasicMaterial({
+                    color: 0xdd7777,
+                    fog: false,
+                });
+                const geometry = new BufferGeometry();
+                this.disabledLines = new LineSegments(geometry, material);
+                this.disabledLines.layers.disableAll();
+                this.disabledLines.layers.enable(2);
+            }
             if (this.lines.parent !== this.context?.scene)
                 this.context?.scene.add(this.lines);
-            const buffers = world.debugRender();
-            this.lines.geometry.setAttribute('position', new BufferAttribute(buffers.vertices, 3));
-            this.lines.geometry.setAttribute('color', new BufferAttribute(buffers.colors, 4));
+            if (this.disabledLines.parent !== this.context?.scene)
+                this.context?.scene.add(this.disabledLines);
+
+            // Render enabled colliders in green
+            const enabledBuffers = world.debugRender(undefined, col => col.isEnabled());
+            this.lines.geometry.setAttribute('position', new BufferAttribute(enabledBuffers.vertices, 3));
+            this.lines.geometry.setAttribute('color', new BufferAttribute(enabledBuffers.colors, 4));
+
+            // Render disabled colliders in red
+            const disabledBuffers = world.debugRender(undefined, col => !col.isEnabled());
+            this.disabledLines.geometry.setAttribute('position', new BufferAttribute(disabledBuffers.vertices, 3));
+            this.disabledLines.geometry.setAttribute('color', new BufferAttribute(disabledBuffers.colors, 4));
+            this.disabledLines.visible = disabledBuffers.vertices.length > 0;
+
             // If a scene has no colliders at all at the start of the scene
             // the bounding sphere radius will be 0 and the lines will not be rendered
             // so we need to update the bounding sphere (perhaps it's enough to do this once...)
             if (this.context!.time.frame % 30 === 0 || this.lines.geometry.boundingSphere?.radius === 0) {
                 this.lines.geometry.computeBoundingSphere();
+                this.disabledLines.geometry.computeBoundingSphere();
             }
         }
         else {
             if (this.lines) {
                 this.context?.scene.remove(this.lines);
             }
+            if (this.disabledLines) {
+                this.context?.scene.remove(this.disabledLines);
+            }
         }
     }
 

package/src/engine/engine_shims.ts

@@ -10,24 +10,26 @@ export declare type OffscreenCanvasExt = OffscreenCanvas & {
 
 // REMOVE once usage of browsers that don't support OffscreenCanvas is low
 // Shim for missing OffscreenCanvas in iOS 16.x
-if (typeof globalThis !== undefined && !('OffscreenCanvas' in globalThis)) {
-	// @ts-ignore
-	globalThis['OffscreenCanvas'] = class OffscreenCanvas  {
-		canvas: HTMLCanvasElement;
-	    constructor(width, height) {
-			this.canvas = document.createElement("canvas");
-			this.canvas.width = width;
-			this.canvas.height = height;
-	
-			// @ts-ignore
-			this.canvas.convertToBlob = (type?: string, quality?: any) => {
-				return new Promise(resolve => {
-					this.canvas.toBlob(resolve, type, quality);
-				});
-			};
-	
-			// @ts-ignore
-			return this.canvas;
-		}
-	};
+export function initShims() {
+	if (typeof globalThis !== undefined && !('OffscreenCanvas' in globalThis)) {
+		// @ts-ignore
+		globalThis['OffscreenCanvas'] = class OffscreenCanvas  {
+			canvas: HTMLCanvasElement;
+			constructor(width, height) {
+				this.canvas = document.createElement("canvas");
+				this.canvas.width = width;
+				this.canvas.height = height;
+
+				// @ts-ignore
+				this.canvas.convertToBlob = (type?: string, quality?: any) => {
+					return new Promise(resolve => {
+						this.canvas.toBlob(resolve, type, quality);
+					});
+				};
+
+				// @ts-ignore
+				return this.canvas;
+			}
+		};
+	}
 }

package/src/engine/engine_tonemapping.ts

@@ -10,7 +10,6 @@ export function patchTonemapping(_ctx?: Context) {
     patchNeutral();
     patchAGX();
 }
-patchTonemapping();
 
 function patchNeutral() {
     // From https://github.com/google/model-viewer/pull/4495

package/src/engine/engine_types.ts

@@ -719,6 +719,15 @@ export interface IPhysicsEngine {
      */
     removeBody(body: IComponent);
 
+    /**
+     * Enables or disables a collider in the physics world without destroying it.
+     * Uses Rapier's `setEnabled()` for efficient toggling instead of removing and recreating the collider.
+     * @param collider The collider component to enable or disable
+     * @param enabled Whether the collider should be enabled
+     * @returns True if the collider was found and its state was changed, false otherwise
+     */
+    setColliderEnabled(collider: ICollider, enabled: boolean): boolean;
+
     /**
      * Gets the physics body for a component
      * @param obj The collider or rigidbody component

package/src/engine/engine_typestore.ts

@@ -8,6 +8,7 @@ class _TypeStore {
 
     private _types: Map<string, Type> = new Map();
     private _reverseTypes: Map<Type, string> = new Map();
+    private _lazyLoaders: Map<string, () => Promise<Type>> = new Map();
 
     constructor() {
         if (debug) console.warn("TypeStore: Created", this);
@@ -32,6 +33,16 @@ class _TypeStore {
         }
     }
 
+    /**
+     * Register a lazy-loadable type. The loader is called on first use via {@link getAsync}.
+     * Once resolved, the type is cached for synchronous access via {@link get}.
+     */
+    public addLazy(key: string, loader: () => Promise<Type>) {
+        if (!this._types.has(key)) {
+            this._lazyLoaders.set(key, loader);
+        }
+    }
+
     /**
      * @returns the type for the given key if registered
      */
@@ -39,6 +50,24 @@ class _TypeStore {
         return this._types.get(key) || null;
     }
 
+    /**
+     * Async version of {@link get} that also resolves lazy-registered types.
+     * After resolving, the type is cached for future synchronous access.
+     */
+    public async getAsync(key: string): Promise<Type | null> {
+        const existing = this._types.get(key);
+        if (existing) return existing;
+        const loader = this._lazyLoaders.get(key);
+        if (loader) {
+            if (debug) console.warn("LAZY LOAD TYPE", key);
+            const type = await loader();
+            this.add(key, type);
+            this._lazyLoaders.delete(key);
+            return type;
+        }
+        return null;
+    }
+
     /**
      * @returns the key/name for the given type if registered
      */

package/src/engine/extensions/NEEDLE_animator_controller_model.ts

@@ -1,7 +1,7 @@
 import { AnimationAction, AnimationClip, MathUtils, Object3D } from "three"
 
 import { InstantiateIdProvider } from "../../engine/engine_networking_instantiate.js";
-import { Animator } from "../../engine-components/Animator.js";
+import type { Animator } from "../../engine-components/Animator.js";
 import { Context } from "../engine_setup.js";
 
 

package/src/engine/js-extensions/Camera.ts

@@ -1,38 +1,45 @@
 import { PerspectiveCamera } from "three";
 
+let initialized = false;
+
 // Wrap camera FOV to allow animation of fov
-Object.defineProperty(PerspectiveCamera.prototype, "fov", {
-    get: function () {
-        return this._fov;;
-    },
-    set: function (val) {
-        const changed = val !== this._fov;
-        this._fov = val;
-        if (changed && this.view !== undefined) this.updateProjectionMatrix();
-    },
-    configurable: true
-});
+export function initCameraExtensions() {
+    if (initialized) return;
+    initialized = true;
+
+    Object.defineProperty(PerspectiveCamera.prototype, "fov", {
+        get: function () {
+            return this._fov;;
+        },
+        set: function (val) {
+            const changed = val !== this._fov;
+            this._fov = val;
+            if (changed && this.view !== undefined) this.updateProjectionMatrix();
+        },
+        configurable: true
+    });
 
-Object.defineProperty(PerspectiveCamera.prototype, "near", {
-    get: function () {
-        return this._near;
-    },
-    set: function (val) {
-        const changed = val !== this._near;
-        this._near = val;
-        if (changed && this.view !== undefined) this.updateProjectionMatrix();
-    },
-    configurable: true
-});
+    Object.defineProperty(PerspectiveCamera.prototype, "near", {
+        get: function () {
+            return this._near;
+        },
+        set: function (val) {
+            const changed = val !== this._near;
+            this._near = val;
+            if (changed && this.view !== undefined) this.updateProjectionMatrix();
+        },
+        configurable: true
+    });
 
-Object.defineProperty(PerspectiveCamera.prototype, "far", {
-    get: function () {
-        return this._far;
-    },
-    set: function (val) {
-        const changed = val !== this._far;
-        this._far = val;
-        if (changed && this.view !== undefined) this.updateProjectionMatrix();
-    },
-    configurable: true
-});
+    Object.defineProperty(PerspectiveCamera.prototype, "far", {
+        get: function () {
+            return this._far;
+        },
+        set: function (val) {
+            const changed = val !== this._far;
+            this._far = val;
+            if (changed && this.view !== undefined) this.updateProjectionMatrix();
+        },
+        configurable: true
+    });
+}

package/src/engine/js-extensions/Layers.ts

@@ -20,5 +20,4 @@ export function patchLayers() {
         if(this[$customVisibilityFlag] === false) return false;
         return origTest.call(this, layer);
     };
-}
-patchLayers();
+}