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

package/src/engine/engine_input.ts

@@ -1,8 +1,8 @@
 import { Intersection, Matrix4, Object3D, Ray, Vector2, Vector3 } from 'three';
 
 import { showBalloonMessage, showBalloonWarning } from './debug/debug.js';
-import { PointerEventBase, KeyboardEventBase } from './engine_ssr.js';
 import { Context } from './engine_setup.js';
+import { KeyboardEventBase,PointerEventBase } from './engine_ssr.js';
 import { getTempVector, getWorldQuaternion } from './engine_three_utils.js';
 import type { ButtonName, CursorTypeName, IGameObject, IInput, MouseButtonName, Vec2 } from './engine_types.js';
 import { DeviceUtilities, type EnumToPrimitiveUnion, getParam } from './engine_utils.js';
@@ -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

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