@needle-tools/engine 5.0.2 → 5.1.0-canary.525aa82

package/src/engine/engine_networking_instantiate.ts

@@ -11,7 +11,7 @@ import type { INetworkConnection } from "./engine_networking_types.js";
 import type { IModel } from "./engine_networking_types.js";
 import { SendQueue } from "./engine_networking_types.js";
 import { Context } from "./engine_setup.js"
-import type { IComponent as Component, IGameObject as GameObject } from "./engine_types.js"
+import type { IComponent as Component, IContext,IGameObject as GameObject } from "./engine_types.js"
 import type { UIDProvider } from "./engine_types.js";
 import * as utils from "./engine_utils.js"
 
@@ -154,13 +154,46 @@ export function sendDestroyed(guid: string, con: INetworkConnection, opts?: Sync
     con.send(InstantiateEvent.InstanceDestroyed, model, SendQueue.Queued);
 }
 
+declare type SyncDestroyCallback = (guid: string, object: Object3D) => void;
+const _onSyncDestroyCallbacks: SyncDestroyCallback[] = [];
+
+/**
+ * Register a callback that fires when a remote `syncDestroy` event is received.
+ * The callback receives the guid and the resolved Object3D (or null if not found in the scene).
+ * The callback fires **before** the object is destroyed, so you can still access its state.
+ * @param callback Called with the guid and the Object3D about to be destroyed
+ * @returns An unsubscribe function
+ * @category Networking
+ * @example
+ * ```ts
+ * const unsub = onSyncDestroy((guid, obj) => {
+ *   console.log("Remote object destroyed:", guid, obj?.name);
+ * });
+ * // later: unsub();
+ * ```
+ */
+export function onSyncDestroy(callback: SyncDestroyCallback): () => void {
+    _onSyncDestroyCallbacks.push(callback);
+    return () => {
+        const idx = _onSyncDestroyCallbacks.indexOf(callback);
+        if (idx >= 0) _onSyncDestroyCallbacks.splice(idx, 1);
+    };
+}
+
 export function beginListenDestroy(context: Context) {
     context.connection.beginListen(InstantiateEvent.InstanceDestroyed, (data: DestroyInstanceModel) => {
         if (debug)
             console.log("[Remote] Destroyed", context.scene, data);
         // TODO: create global lookup table for guids
         const obj = findByGuid(data.guid, context.scene);
-        if (obj) destroy(obj);
+        if (obj) {
+            // Notify listeners before destroying
+            for (const cb of _onSyncDestroyCallbacks) {
+                try { cb(data.guid, obj as Object3D); }
+                catch (err) { console.error("Error in onSyncDestroy callback", err); }
+            }
+            destroy(obj);
+        }
     });
 }
 
@@ -215,27 +248,125 @@ export class NewInstanceModel implements IModel {
 
 /**
  * Instantiation options for {@link syncInstantiate}
+ * @category Networking
+ * @see {@link syncInstantiate} - Instantiate objects across the network
  */
 export type SyncInstantiateOptions = IInstantiateOptions & Pick<IModel, "deleteOnDisconnect">;
 
 // #region Sync Instantiate
+
+/**
+ * Callback type for {@link onSyncInstantiate}
+ * @param instance The instantiated object
+ * @param model The network model data sent with the instantiate event
+ * @param context The network context in which the instantiate event was received
+ * @category Networking
+ */
+declare type SyncInstantiateCallback = (instance: GameObject, model: NewInstanceModel, context: IContext) => void;
+/** Registered callbacks for remote instantiation events */
+const _onSyncInstantiateCallbacks: SyncInstantiateCallback[] = [];
+
 /**
- * Instantiate an object across the network. See also {@link syncDestroy}.
+ * Register a callback that fires when a remote `syncInstantiate` object is created on this client.
+ * Use this to get references to objects spawned by other users.
+ * @param callback Called with the instantiated Object3D, the network model data, and the Needle Engine context in which the instantiate event was received
+ * @returns An unsubscribe function
  * @category Networking
+ * @example
+ * ```ts
+ * const unsub = onSyncInstantiate((instance, model, context) => {
+ *   console.log("Remote object created:", instance.name, model.originalGuid, context);
+ * });
+ * // later: unsub();
+ * ```
+ * @see {@link syncInstantiate} - Instantiate objects across the network
+ * @see {@link syncDestroy} - Destroy objects across the network
+ */
+export function onSyncInstantiate(callback: SyncInstantiateCallback): () => void {
+    _onSyncInstantiateCallbacks.push(callback);
+    return () => {
+        const idx = _onSyncInstantiateCallbacks.indexOf(callback);
+        if (idx >= 0) _onSyncInstantiateCallbacks.splice(idx, 1);
+    };
+}
+
+/**
+ * Instantiate an object across the network. The object is cloned locally and a network message
+ * is sent so all connected clients create the same clone. Late joiners receive the message
+ * via room state replay (unless `deleteOnDisconnect` is set or `save` is false).
+ *
+ * ## How it works internally
+ * 1. The prefab is cloned locally using a seeded {@link InstantiateIdProvider}
+ * 2. The seed ensures all clients generate **identical deterministic guids** for the clone
+ *    and all its children — no need to send individual guids over the network
+ * 3. A {@link NewInstanceModel} message is sent containing the prefab's `originalGuid`,
+ *    the clone's `guid`, the `seed`, and transform data
+ * 4. On receiving clients, the prefab is resolved via {@link registerPrefabProvider} or
+ *    by searching the scene for an object with matching guid, then cloned with the same seed
+ *
+ * ## Runtime-created prefabs (no GLB)
+ * If the object has a `guid` but no prefab provider is registered for it, `syncInstantiate`
+ * will **auto-register** the object as a prefab provider. This means for code-only prefabs
+ * you just need to set a `guid` — no manual `registerPrefabProvider` call needed, as long as
+ * all clients run the same setup code that creates the same prefab with the same guid.
+ *
+ * @param object The object to instantiate. Must have a `guid` property (set one for runtime objects).
+ * @param opts Options for the instantiation, including the network context to send the instantiate event to
+ * @param hostData Optional data about a file to download when this object is instantiated (e.g. when instantiated via file drop)
+ * @param save When false, the state of this instance will not be saved in the networking backend. Default is true.
+ * @returns The instantiated object, or null if instantiation failed (e.g. missing guid or network context)
+ * @see {@link syncDestroy} - Destroy objects across the network
+ * @see {@link onSyncInstantiate} - Register a callback to get references to remotely instantiated objects
+ * @see {@link registerPrefabProvider} - Manually register a prefab provider (auto-registered by syncInstantiate)
+ * @see {@link unregisterPrefabProvider} - Remove a registered prefab provider
+ * @category Networking
+ *
+ * @example Basic usage with a runtime-created prefab
+ * ```ts
+ * const cookie = ObjectUtils.createPrimitive("Cube", { color: 0xff8c00 });
+ * cookie.guid = "cookie-prefab";
+ * // No need to call registerPrefabProvider — syncInstantiate auto-registers it
+ * syncInstantiate(cookie, { parent: ctx.scene, deleteOnDisconnect: false });
+ * ```
+ *
+ * @example With deterministic seed (advanced)
+ * ```ts
+ * const idProvider = new InstantiateIdProvider("my-seed");
+ * const instance = syncInstantiate(prefab, { context, idProvider });
+ * ```
+ * The seed generates deterministic guids via UUID v5, so all clients produce identical
+ * identifiers for the clone and its children without sending them over the network.
  */
 export function syncInstantiate(object: GameObject | Object3D, opts: SyncInstantiateOptions, hostData?: HostData, save?: boolean): GameObject | null {
 
     const obj: GameObject = object as GameObject;
 
     if (!obj.guid) {
-        console.warn("Can not instantiate: No guid", obj);
-        return null;
+        // Auto-assign guid from object name if available.
+        // The name must be the same on all clients (which it is when both run the same setup code).
+        if (obj.name) {
+            obj.guid = obj.name;
+        }
+        else {
+            console.error("[syncInstantiate] Can not instantiate: a 'guid' is required. For runtime-created objects, either set a name (`obj.name = 'my-prefab'`) or a guid (`obj.guid = 'my-prefab-id'`). The identifier must be the same on all clients.", obj);
+            return null;
+        }
     }
 
-    if (!opts.context) opts.context = Context.Current;
+    // Auto-register the prefab provider if none exists for this guid.
+    // This allows runtime-created objects to work with syncInstantiate without
+    // manual Prefabs.register calls, as long as all clients create the
+    // same prefab with the same guid in their setup code.
+    if (!Prefabs.has(obj.guid)) {
+        Prefabs.register(obj.guid, async () => obj);
+    }
 
     if (!opts.context) {
-        console.error("Missing network instantiate options / reference to network connection in sync instantiate");
+        opts.context = Context.Current;
+    }
+
+    if (!opts.context) {
+        console.error("[syncInstantiate] Missing network instantiate options / reference to network connection in sync instantiate. Please pass in the Needle Engine context.");
         return null;
     }
 
@@ -318,7 +449,6 @@ const syncedInstantiated = new Array<WeakRef<Object3D>>();
 
 export function beginListenInstantiate(context: Context) {
 
-
     const cb1 = context.connection.beginListen(InstantiateEvent.NewInstanceCreated, async (model: NewInstanceModel) => {
         const obj: GameObject | null = await tryResolvePrefab(model.originalGuid, context.scene) as GameObject;
         if (model.preventCreation === true) {
@@ -350,6 +480,11 @@ export function beginListenInstantiate(context: Context) {
                 context.scene.add(inst);
             if (debug)
                 console.log("[Remote] new instance", "gameobject:", inst?.guid, obj);
+            // Notify listeners about the remote instantiation
+            for (const cb of _onSyncInstantiateCallbacks) {
+                try { cb(inst, model, context); }
+                catch (err) { console.error("Error in onSyncInstantiate callback", err); }
+            }
         }
     });
     const cb2 = context.connection.beginListen("left-room", () => {
@@ -377,21 +512,28 @@ function instantiateSeeded(obj: GameObject, opts: IInstantiateOptions | null): {
     return { seed: seed, instance: instance };
 }
 
-export declare type PrefabProviderCallback = (guid: string) => Promise<Object3D | null>;
+export { type PrefabProviderCallback,Prefabs } from "./engine_networking_prefabs.js";
+import { Prefabs } from "./engine_networking_prefabs.js";
 
-const registeredPrefabProviders: { [key: string]: PrefabProviderCallback } = {};
+/**
+ * Register a prefab provider. Forwards to {@link Prefabs.register}.
+ * @category Networking
+ */
+export function registerPrefabProvider(key: string, fn: (guid: string) => Promise<Object3D | null>) {
+    Prefabs.register(key, fn);
+}
 
-//** e.g. provide a function that can return a instantiated object when instantiation event is received */
-export function registerPrefabProvider(key: string, fn: PrefabProviderCallback) {
-    registeredPrefabProviders[key] = fn;
+/**
+ * Unregister a prefab provider. Forwards to {@link Prefabs.unregister}.
+ * @category Networking
+ */
+export function unregisterPrefabProvider(key: string) {
+    Prefabs.unregister(key);
 }
 
 async function tryResolvePrefab(guid: string, obj: Object3D): Promise<Object3D | null> {
-    const prov = registeredPrefabProviders[guid];
-    if (prov !== null && prov !== undefined) {
-        const res = await prov(guid);
-        if (res) return res;
-    }
+    const res = await Prefabs.resolve(guid);
+    if (res) return res;
     return tryFindObjectByGuid(guid, obj) as Object3D;
 }
 

package/src/engine/engine_networking_prefabs.ts

@@ -0,0 +1,80 @@
+import { Object3D } from "three";
+
+/**
+ * Callback type for prefab providers.
+ * @param guid The guid of the prefab to resolve
+ * @returns The prefab Object3D, or null if not found
+ */
+export declare type PrefabProviderCallback = (guid: string) => Promise<Object3D | null>;
+
+const registeredProviders: { [key: string]: PrefabProviderCallback } = {};
+
+/**
+ * Prefab registry for networked instantiation.
+ *
+ * When a remote {@link syncInstantiate} event is received, the engine looks up the prefab
+ * by its guid using this registry. Both GLB-loaded objects and runtime-created objects
+ * can be registered here.
+ *
+ * Note: {@link syncInstantiate} auto-registers prefabs if no provider exists for their guid,
+ * so manual registration is only needed for custom resolution logic.
+ *
+ * @example
+ * ```ts
+ * import { Prefabs, ObjectUtils } from "@needle-tools/engine";
+ *
+ * const cookie = ObjectUtils.createPrimitive("Cube", { color: 0xff8c00 });
+ * cookie.guid = "cookie-prefab";
+ * Prefabs.register("cookie-prefab", async () => cookie);
+ *
+ * console.log(Prefabs.list()); // ["cookie-prefab"]
+ * Prefabs.unregister("cookie-prefab");
+ * ```
+ *
+ * @category Networking
+ */
+export const Prefabs = {
+
+    /**
+     * Register a prefab provider that resolves objects by guid for networked instantiation.
+     * When a remote `syncInstantiate` event is received, the engine uses this to find the prefab
+     * to clone on the receiving client.
+     *
+     * @param key The guid to register the provider for
+     * @param fn Callback that returns the prefab Object3D for the given guid
+     */
+    register(key: string, fn: PrefabProviderCallback) {
+        registeredProviders[key] = fn;
+    },
+
+    /**
+     * Unregister a previously registered prefab provider.
+     * @param key The guid to unregister
+     */
+    unregister(key: string) {
+        delete registeredProviders[key];
+    },
+
+    /**
+     * Returns a list of all registered prefab provider keys (guids).
+     * Useful for debugging to see which prefabs are available for networked instantiation.
+     */
+    list(): string[] {
+        return Object.keys(registeredProviders);
+    },
+
+    /**
+     * Check if a prefab provider is registered for the given guid.
+     * @param key The guid to check
+     */
+    has(key: string): boolean {
+        return key in registeredProviders;
+    },
+
+    /** @internal Resolve a prefab by guid. Used by the networking system. */
+    async resolve(guid: string): Promise<Object3D | null> {
+        const prov = registeredProviders[guid];
+        if (prov) return prov(guid);
+        return null;
+    },
+} as const;

package/src/engine/engine_physics_rapier.ts

@@ -46,16 +46,21 @@ const $colliderRigidbody = Symbol("rigidbody");
 
 declare const NEEDLE_USE_RAPIER: boolean;
 globalThis["NEEDLE_USE_RAPIER"] = globalThis["NEEDLE_USE_RAPIER"] !== undefined ? globalThis["NEEDLE_USE_RAPIER"] : true;
-if (debugPhysics)
-    console.log("Use Rapier", NEEDLE_USE_RAPIER, globalThis["NEEDLE_USE_RAPIER"])
 
-if (NEEDLE_USE_RAPIER) {
-    ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, evt => {
-        if (debugPhysics)
-            console.log("Register rapier physics backend")
-        evt.context.physics.engine = new RapierPhysics(evt.context);
-        // We do not initialize physics immediately to avoid loading the physics engine if it is not needed
-    });
+/** Register the Rapier physics backend. Called from {@link initEngine}
+ * to ensure it runs regardless of tree-shaking. */
+export function initPhysics() {
+    if (debugPhysics)
+        console.log("Use Rapier", NEEDLE_USE_RAPIER, globalThis["NEEDLE_USE_RAPIER"])
+
+    if (NEEDLE_USE_RAPIER) {
+        ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, evt => {
+            if (debugPhysics)
+                console.log("Register rapier physics backend")
+            evt.context.physics.engine = new RapierPhysics(evt.context);
+            // We do not initialize physics immediately to avoid loading the physics engine if it is not needed
+        });
+    }
 }
 
 

package/src/engine/postprocessing/api.ts

@@ -0,0 +1,2 @@
+export { PostProcessing } from "./index.js";
+export type { IPostProcessingEffect, IPostProcessingHandler, ITonemappingEffect } from "./types.js";

package/src/engine/postprocessing/index.ts

@@ -0,0 +1,2 @@
+export { PostProcessing } from "./postprocessing.js";
+export type { IPostProcessingEffect, IPostProcessingHandler, ITonemappingEffect } from "./types.js";