@needle-tools/engine 5.1.0-alpha.3 → 5.1.0-alpha.5

package/src/engine/engine_gameobject.ts

@@ -10,10 +10,11 @@ import { $isUsingInstancing, InstancingUtil } from "./engine_instancing.js";
 import { processNewScripts } from "./engine_mainloop_utils.js";
 import type { syncInstantiate } from "./engine_networking_instantiate.js";
 import { InstantiateIdProvider } from "./engine_networking_instantiate.js";
-import { assign, ISerializable } from "./engine_serialization_core.js";
+import { resolveInstanceReferences, type InstantiateReferenceMap, type InstantiateContext, type ObjectCloneReference } from "./engine_instantiate_resolve.js";
+import { assign } from "./engine_serialization_core.js";
 import { Context, registerComponent } from "./engine_setup.js";
 import { getTempQuaternion, logHierarchy, setWorldPosition, setWorldQuaternion } from "./engine_three_utils.js";
-import { type Constructor, type GuidsMap, type IComponent as Component, type IComponent, IEventList, type IGameObject as GameObject, type UIDProvider } from "./engine_types.js";
+import { type Constructor, type GuidsMap, type IComponent as Component, type IComponent, type IGameObject as GameObject, type UIDProvider, isComponent } from "./engine_types.js";
 import { deepClone, getParam, tryFindObject } from "./engine_utils.js";
 import { apply } from "./js-extensions/index.js";
 
@@ -324,19 +325,8 @@ function internalForEachComponent(instance: Object3D, cb: ForEachComponentCallba
 
 }
 
-declare type ObjectCloneReference = {
-    readonly original: object;
-    readonly clone: object;
-}
-
-
-declare type InstantiateReferenceMap = Record<string, ObjectCloneReference>;
-declare type NewObjectReferenceMap = Record<string, { target: object, key: string }>;
-
-/**
- * Provides access to the instantiated object and its clone
- */
-export declare type InstantiateContext = Readonly<InstantiateReferenceMap>;
+// Re-export types from the unified resolution module
+export type { InstantiateContext, InstantiateReferenceMap, ObjectCloneReference } from "./engine_instantiate_resolve.js";
 
 /**
  * Creates a copy (clone) of a GameObject or loads and instantiates an AssetReference.
@@ -410,7 +400,7 @@ export function instantiate(instance: AssetReference | GameObject | Object3D, op
     const clone = internalInstantiate(context, instance, options, components, referencemap, skinnedMeshes);
 
     if (clone) {
-        resolveReferences(clone, referencemap);
+        resolveInstanceReferences(referencemap);
         resolveAndBindSkinnedMeshBones(skinnedMeshes, referencemap);
     }
 
@@ -420,6 +410,18 @@ export function instantiate(instance: AssetReference | GameObject | Object3D, op
     }
 
     const guidsMap: GuidsMap = {};
+
+    // Cloned object guids
+    for (const ref in referencemap) {
+        const val = referencemap[ref];
+        const original = val.original;
+        const clone = val.clone;
+        if (original instanceof Object3D && clone instanceof Object3D) {
+            guidsMap[original.guid || original.uuid] = clone.guid || clone.uuid;
+        }
+    }
+
+    // Cloned component guids (generate new guids for components that dont have one and add them to the map)
     if (options?.components !== false) {
         for (const i in components) {
             const copy = components[i];
@@ -427,8 +429,7 @@ export function instantiate(instance: AssetReference | GameObject | Object3D, op
             if (options && options.idProvider) {
                 copy.guid = options.idProvider.generateUUID();
                 guidsMap[oldGuid] = copy.guid;
-                if (debug)
-                    console.log(copy.name, copy.guid)
+                if (debug) console.log(copy.name, copy.guid)
             }
             registerComponent(copy, context);
             if (copy.__internalNewInstanceCreated)
@@ -436,8 +437,6 @@ export function instantiate(instance: AssetReference | GameObject | Object3D, op
         }
         for (const i in components) {
             const copy = components[i];
-            if (copy.resolveGuids)
-                copy.resolveGuids(guidsMap);
             if (copy.enabled === false) continue;
             else copy.enabled = true;
         }
@@ -478,7 +477,12 @@ function internalInstantiate(
     instance.children = children;
 
     // make reference from old id to new object
-    objectsMap[instance.uuid] = { original: instance, clone: clone };
+    const ref: ObjectCloneReference = { original: instance, clone: clone };
+    objectsMap[instance.uuid] = ref;
+    // Also key by guid so string guid references (e.g. PlayableDirector track.outputs) can be resolved
+    if ((instance).guid && (instance).guid !== instance.uuid) {
+        objectsMap[(instance).guid] = ref;
+    }
     if (debugInstantiate) console.log("ADD", instance, clone)
 
     if (instance.type === "SkinnedMesh") {
@@ -612,32 +616,32 @@ function internalInstantiate(
 function onAssignComponent(source: any, target: any, _newObjectsMap: InstantiateReferenceMap) {
     assign(target, source, undefined, {
         // onAssigned: (target, key, _oldValue, value) => {
-            // if (value !== null && typeof value === "object") {
-            //     const serializable = target as ISerializable;
-            //     if (serializable?.$serializedTypes?.[key]) {
-            //         if (!(value instanceof Object3D)) {
-            //             // let clone = null;
-            //             // if ("clone" in value) {
-            //             //     if (canClone(value)) clone = (value as any).clone();
-            //             // }
-            //             // else {
-            //             //     clone = Object.assign(Object.create(Object.getPrototypeOf(value)), value);
-            //             // }
-            //             // if (clone) {
-            //             //     console.debug(key, { target, value, clone })
-            //             //     target[key] = clone;
-            //             //     findNestedReferences(clone, objectsMap);
-            //             // }
-            //             // else console.debug("Could not clone value for key", key, value);
-            //         }
-            //         else {
-            //             console.log("ASSIGNED", value)
-            //         }
-
-            //         recursiveAssign(target, target[key], newObjectsMap);
-            //     }
-
-            // }
+        // if (value !== null && typeof value === "object") {
+        //     const serializable = target as ISerializable;
+        //     if (serializable?.$serializedTypes?.[key]) {
+        //         if (!(value instanceof Object3D)) {
+        //             // let clone = null;
+        //             // if ("clone" in value) {
+        //             //     if (canClone(value)) clone = (value as any).clone();
+        //             // }
+        //             // else {
+        //             //     clone = Object.assign(Object.create(Object.getPrototypeOf(value)), value);
+        //             // }
+        //             // if (clone) {
+        //             //     console.debug(key, { target, value, clone })
+        //             //     target[key] = clone;
+        //             //     findNestedReferences(clone, objectsMap);
+        //             // }
+        //             // else console.debug("Could not clone value for key", key, value);
+        //         }
+        //         else {
+        //             console.log("ASSIGNED", value)
+        //         }
+
+        //         recursiveAssign(target, target[key], newObjectsMap);
+        //     }
+
+        // }
         // }
     });
 }
@@ -742,113 +746,4 @@ function resolveAndBindSkinnedMeshBones(
 
 // }
 
-function resolveReferences(_newInstance: Object3D, newObjectsMap: InstantiateReferenceMap) {
-    // for every object that is newly created we want to update references to their newly created counterparts
-    // e.g. a collider instance referencing a rigidbody instance should be updated so that 
-    // the cloned collider does not reference the cloned rigidbody (instead of the original rigidbody)
-    for (const key in newObjectsMap) {
-        const val = newObjectsMap[key];
-        const clone = val.clone as Object3D | null;
-        // resolve references
-        if (clone?.isObject3D && clone?.userData?.components) {
-            for (let i = 0; i < clone.userData.components.length; i++) {
-                const copy = clone.userData.components[i];
-                // find referenced within a cloned gameobject
-                const entries = Object.entries(copy);
-                // console.log(copy, entries);
-                for (const [key, value] of entries) {
-                    if (Array.isArray(value)) {
-                        const clonedArray: Array<any> = [];
-                        copy[key] = clonedArray;
-                        // console.log(copy, key, value, copy[key]);
-                        for (let i = 0; i < value.length; i++) {
-                            const entry = value[i];
-                            // push value types into new array
-                            if (typeof entry !== "object") {
-                                clonedArray.push(entry);
-                                continue;
-                            }
-                            const res: any = postProcessNewInstance(copy, key, entry, newObjectsMap);
-                            if (res !== undefined) {
-                                if (debugInstantiate) console.log("Found new instance for", key, entry, "->", res);
-                                clonedArray.push(res);
-                            }
-                            else {
-                                if (debugInstantiate) console.warn("Could not find new instance for", key, entry);
-                                clonedArray.push(entry);
-                            }
-                        }
-                        // console.log(copy[key])
-                    }
-                    else if (typeof value === "object") {
-                        const res = postProcessNewInstance(copy, key, value as IComponent | Object3D, newObjectsMap);
-                        if (res !== undefined) {
-                            copy[key] = res;
-                        }
-                        else {
-                            if (debugInstantiate) console.warn("Could not find new instance for", key, value);
-                        }
-                    }
-                }
-            }
-        }
-    }
-
-}
-
-function postProcessNewInstance(copy: Object3D, key: string, value: IComponent | Object3D | any, newObjectsMap: InstantiateReferenceMap) {
-    if (value === null || value === undefined) return;
-    if ((value as IComponent).isComponent === true) {
-        const originalGameObjectReference = value["gameObject"];
-        // console.log(key, value, originalGameObjectReference);
-        if (originalGameObjectReference) {
-            const id = originalGameObjectReference.uuid;
-            const newGameObject = newObjectsMap[id]?.clone;
-            if (!newGameObject) {
-                // reference has not changed!
-                if (debugInstantiate)
-                    console.log("reference did not change", key, copy, value);
-                return;
-            }
-            const index = originalGameObjectReference.userData.components.indexOf(value);
-            if (index >= 0 && (newGameObject as Object3D).isObject3D) {
-                if (debugInstantiate)
-                    console.log(key, id);
-                const found = (newGameObject as Object3D).userData.components[index];
-                return found;
-            }
-            else {
-                console.warn("could not find component", key, value);
-            }
-        }
-    } else if ((value as Object3D).isObject3D === true) {
-        // console.log(value);
-        if (key === "gameObject") return;
-        const originalGameObjectReference = value as Object3D;
-        if (originalGameObjectReference) {
-            const id = originalGameObjectReference.uuid;
-            const newGameObject = newObjectsMap[id]?.clone;
-            if (newGameObject) {
-                if (debugInstantiate)
-                    console.log(key, "old", value, "new", newGameObject);
-                return newGameObject;
-            }
-        }
-    }
-    else {
-        // create new instances for some types that we know should usually not be shared and can safely be cloned
-        if (value.isVector4 || value.isVector3 || value.isVector2 || value.isQuaternion || value.isEuler) {
-            return value.clone();
-        }
-        else if (value.isColor === true) {
-            return value.clone();
-        }
-        else if ((value as IEventList).isEventList === true) {
-            // create a new instance of the object
-            const copy = (value as IEventList).__internalOnInstantiate(newObjectsMap);
-            return copy;
-        }
-    }
-}
-
-// const canClone = (value: any) => value.isVector4 || value.isVector3 || value.isVector2 || value.isQuaternion || value.isEuler || value.isColor === true;
+// Reference resolution is now handled by the unified module: engine_instantiate_resolve.ts

package/src/engine/engine_gltf_builtin_components.ts

@@ -5,6 +5,7 @@ import { LogType, showBalloonMessage } from "./debug/index.js";
 import { addNewComponent } from "./engine_components.js";
 import { builtinComponentKeyName, editorGuidKeyName } from "./engine_constants.js";
 import { debugExtension } from "./engine_default_parameters.js";
+import { generateGuidsForHierarchy, resolveStringGuidsInHierarchy, originalComponentNameKey } from "./engine_instantiate_resolve.js";
 import { InstantiateIdProvider } from "./engine_networking_instantiate.js"
 import { isLocalNetwork } from "./engine_networking_utils.js";
 import { deserializeObject, serializeObject } from "./engine_serialization.js";
@@ -98,88 +99,18 @@ export async function createBuiltinComponents(context: Context, gltfId: SourceId
         // doing it here at the end of resolving of references should ensure that
         // and this should run before awake and onenable of newly created components
         if (idProvider) {
-            // TODO: should we do this after setup callbacks now?
             const guidsMap: GuidsMap = {};
-            const resolveGuids: IHasResolveGuids[] = [];
-            // TODO: when is the gltf here an object3d?
-            recursiveCreateGuids(gltf as any, idProvider, guidsMap, resolveGuids);
+            generateGuidsForHierarchy(gltf as any, idProvider, guidsMap);
             for (const scene of gltf.scenes)
-                recursiveCreateGuids(scene, idProvider, guidsMap, resolveGuids);
-            // make sure to resolve all guids AFTER new guids have been assigned
-            for (const res of resolveGuids) {
-                res.resolveGuids(guidsMap);
-            }
+                generateGuidsForHierarchy(scene, idProvider, guidsMap);
+            // Resolve string guid references in component fields (e.g. PlayableDirector track.outputs)
+            resolveStringGuidsInHierarchy(gltf as any, guidsMap);
+            for (const scene of gltf.scenes)
+                resolveStringGuidsInHierarchy(scene, guidsMap);
         }
     });
 }
 
-declare type IHasResolveGuids = {
-    resolveGuids: (guidsMap: GuidsMap) => void;
-}
-
-const originalComponentNameKey = Symbol("original-component-name");
-
-/** 
- * We want to create one id provider per component
- * If a component is used multiple times we want to create a new id provider for each instance
- * That way the order of components in the scene doesnt affect the result GUID
- */
-// TODO: clear this when re-loading the context
-const idProviderCache = new Map<string, InstantiateIdProvider>();
-
-function recursiveCreateGuids(obj: Object3D, idProvider: UIDProvider | null, guidsMap: GuidsMap, resolveGuids: IHasResolveGuids[]) {
-    if (idProvider === null) return;
-    if (!obj) return;
-    const prev = obj.guid;
-
-    // we also want to use the idproviderCache for objects because they might be removed or re-ordered in the scene hierarchy
-    // in which case we dont want to e.g. change the syncedInstantiate objects that get created because suddenly another object has that guid
-    const idProviderKey = obj.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.guid = objectIdProvider.generateUUID();
-    if (prev && prev !== "invalid")
-        guidsMap[prev] = obj.guid;
-
-    // console.log(obj);
-    if (obj && obj.userData && obj.userData.components) {
-        for (const comp of obj.userData.components) {
-            if (comp === null) continue;
-
-            // by default we use the component guid as a key - order of the components in the scene doesnt matter with this approach
-            // this is to prevent cases where multiple GLBs are loaded with the same component guid
-            const idProviderKey = comp.guid;
-            if (idProviderKey) {
-                if (!idProviderCache.has(idProviderKey)) {
-                    if (debug) console.log("Creating InstanceIdProvider with key \"" + idProviderKey + "\" for component " + comp[originalComponentNameKey]);
-                    idProviderCache.set(idProviderKey, new InstantiateIdProvider(idProviderKey));
-                }
-            }
-            else if (debug) console.warn("Can not create IdProvider: component " + comp[originalComponentNameKey] + " has no guid", comp.guid);
-            const componentIdProvider = idProviderCache.get(idProviderKey) || idProvider
-
-            const prev = comp.guid;
-            comp.guid = componentIdProvider.generateUUID();
-            if (prev && prev !== "invalid")
-                guidsMap[prev] = comp.guid;
-            if (comp.resolveGuids)
-                resolveGuids.push(comp);
-        }
-
-    }
-    if (obj.children) {
-        for (const child of obj.children) {
-            recursiveCreateGuids(child as IGameObject, idProvider, guidsMap, resolveGuids);
-        }
-    }
-}
-
 declare interface IGltfbuiltinComponent {
     name: string;
 }

package/src/engine/engine_input.ts

@@ -343,14 +343,33 @@ export class Input implements IInput {
     private readonly _eventListeners: Record<string, RegisteredEventListenerValue> = {};
 
     /** Adds an event listener for the specified event type. The callback will be called when the event is triggered.
+     *
+     * Returns an unsubscribe function — call it to remove the listener.
+     * Pass it to {@link Behaviour.autoCleanup} for automatic lifecycle management.
+     *
      * @param type The event type to listen for
      * @param callback The callback to call when the event is triggered
      * @param options The options for adding the event listener.
-     * @example Basic usage
+     * @returns A function that removes the event listener when called.
+     *
+     * @example With autoCleanup (recommended)
      * ```ts
-     * input.addEventListener("pointerdown", (evt) => {
+     * export class MyComponent extends Behaviour {
+     *   onEnable() {
+     *     this.autoCleanup(this.context.input.addEventListener("pointerdown", (evt) => {
+     *       console.log("Pointer down", evt.pointerId, evt.pointerType);
+     *     }));
+     *   }
+     *   // Listener is automatically removed on disable — no manual cleanup needed!
+     * }
+     * ```
+     * @example Manual unsubscribe
+     * ```ts
+     * const off = input.addEventListener("pointerdown", (evt) => {
      *   console.log("Pointer down", evt.pointerId, evt.pointerType);
      * });
+     * // later
+     * off();
      * ```
      * @example Adding a listener that is called after all other listeners
      * By using a higher value for the queue the listener will be called after other listeners (default queue is 0).
@@ -366,14 +385,14 @@ export class Input implements IInput {
      * }, { once: true });
      * ```
      */
-    addEventListener(type: PointerEventNames, callback: PointerEventListener, options?: EventListenerOptions);
-    addEventListener(type: KeyboardEventNames, callback: KeyboardEventListener, options?: EventListenerOptions);
-    addEventListener(type: InputEvents | InputEventNames, callback: InputEventListener, options?: EventListenerOptions): void {
+    addEventListener(type: PointerEventNames, callback: PointerEventListener, options?: EventListenerOptions): () => void;
+    addEventListener(type: KeyboardEventNames, callback: KeyboardEventListener, options?: EventListenerOptions): () => void;
+    addEventListener(type: InputEvents | InputEventNames, callback: InputEventListener, options?: EventListenerOptions): () => void {
         if (!this._eventListeners[type]) this._eventListeners[type] = [];
 
         if (!callback || typeof callback !== "function") {
             console.error("Invalid call to addEventListener: callback is required and must be a function!");
-            return;
+            return () => {};
         }
 
         if (!options) options = {};
@@ -392,6 +411,8 @@ export class Input implements IInput {
         } else {
             queueListeners.listeners.push({ callback, options });
         }
+
+        return () => this.removeEventListener(type as any, callback as any, options);
     }
     /** Removes the event listener from the specified event type. If no queue is specified the listener will be removed from all queues.
      * @param type The event type to remove the listener from