@needle-tools/engine 5.1.0-canary.c111c4f → 5.1.0-canary.cce79c8

package/src/engine/engine_context.ts

@@ -1,5 +1,6 @@
 import 'three/examples/jsm/renderers/webgl-legacy/nodes/WebGLNodes.js';
 
+import type { SceneData } from 'needle-bindings';
 import type { EffectComposer } from "postprocessing";
 import {
 	BufferGeometry, Camera, Color, DepthTexture, Group,
@@ -36,9 +37,8 @@ import * as looputils from './engine_mainloop_utils.js';
 import { NetworkConnection } from './engine_networking.js';
 import { Physics } from './engine_physics.js';
 import { PlayerViewManager } from './engine_playerview.js';
-import { RendererData as SceneLighting } from './engine_scenelighting.js';
 import { getSceneData } from './engine_scenedata.js';
-import type { SceneData } from 'needle-bindings';
+import { RendererData as SceneLighting } from './engine_scenelighting.js';
 import { getTempColor, logHierarchy } from './engine_three_utils.js';
 import { Time } from './engine_time.js';
 import { patchTonemapping } from './engine_tonemapping.js';
@@ -478,13 +478,14 @@ export class Context implements IContext {
 	 * Use `setCurrentCamera` for updating the main camera.
 	 */
 	/**
-	 * Typed proxy providing direct access to scene components by node and component name.
-	 * Types are auto-generated from your GLB assets by the `needle:dts-generator` Vite plugin
-	 * and written to `src/generated/needle-bindings.d.ts` on every dev-server start and GLB change.
+	 * Access your scene's full hierarchy, objects, and components directly by name — with full autocomplete.
+	 * Types are generated automatically from your GLB files when the dev server starts.
+	 *
+	 * You can store references to objects or components for later use.
+	 * Note that the scene hierarchy can change at runtime (e.g. when objects are added, removed, or re-parented),
+	 * in which case stored references may become stale.
 	 *
-	 * Each property access traverses the live scene graph on demand — no caching, always fresh.
-	 * This is a convenience shorthand for `getComponent` lookups; the same result can be
-	 * achieved manually via `scene.getObjectByName(name)` + `getComponent(node, Type)`.
+	 * @experimental This API may change in future versions.
 	 *
 	 * @example
 	 * // Toggle auto-rotate on the orbit camera
@@ -493,12 +494,6 @@ export class Context implements IContext {
 	 * @example
 	 * // Change the background color
 	 * ctx.sceneData.Camera.Camera.backgroundColor = new RGBAColor(1, 0, 0, 1);
-	 *
-	 * @example
-	 * // Equivalent manual approach (without sceneData)
-	 * const node = ctx.scene.getObjectByName("Camera");
-	 * const orbit = getComponent(node, OrbitControls);
-	 * if (orbit) orbit.autoRotate = true;
 	 */
 	get sceneData(): SceneData {
 		return getSceneData(this);
@@ -543,8 +538,10 @@ export class Context implements IContext {
 	/**  @deprecated AssetDatabase is deprecated */
 	assets: AssetDatabase;
 
-	/** All registered lights in the scene, maintained by the Light component */
-	readonly lights: Set<ILight> = new Set();
+	/** All registered lights in the scene, maintained by the Light component. 
+	 * @see mainLight for accessing the main directional light in the scene
+	 */
+	readonly lights = new Array<ILight>();
 
 	/** The brightest registered directional light, or null if none are registered
 	 * @see lights
@@ -559,12 +556,13 @@ export class Context implements IContext {
 	}
 
 	/** @deprecated Use sceneLighting */
-	get rendererData() { return this.sceneLighting }
+	private get rendererData() { return this.sceneLighting }
+
 	/** Access the scene lighting manager to control lighting settings in the context */
-	sceneLighting: SceneLighting;
-	addressables: Addressables;
-	lightmaps: ILightDataRegistry;
-	players: PlayerViewManager;
+	readonly sceneLighting: SceneLighting;
+	readonly addressables: Addressables;
+	readonly lightmaps: ILightDataRegistry;
+	readonly players: PlayerViewManager;
 
 	/** Access the LODs manager to control LOD behavior in the context */
 	readonly lodsManager: LODsManager;
@@ -865,14 +863,14 @@ export class Context implements IContext {
 		this.scene = new Scene();
 		this.addressables?.dispose();
 		this.lightmaps?.clear();
-		this.physics?.engine?.clearCaches();
+		this.physics?.engine?.dispose();
 		this.lodsManager.disable();
 		this.accessibility?.clear();
 
 		this._onBeforeRenderListeners.clear();
 		this._onAfterRenderListeners.clear();
 
-		this.lights.clear();
+		this.lights.length = 0;
 
 		if (!this.isManagedExternally) {
 			if (this.renderer) {
@@ -914,6 +912,7 @@ export class Context implements IContext {
 		this.scene = null!;
 		this.renderer = null!;
 		this.input.dispose();
+		this.connection.dispose();
 		this.menu.onDestroy();
 		this.animations.onDestroy();
 		for (const cb of this._disposeCallbacks) {

package/src/engine/engine_disposable.ts

@@ -0,0 +1,214 @@
+/** A function that performs cleanup when called */
+export type DisposeFn = () => void;
+
+/**
+ * Interface for objects that hold resources and can be disposed.
+ * Implement this interface on any object that needs deterministic cleanup.
+ *
+ * @example
+ * ```ts
+ * class MyResource implements IDisposable {
+ *     dispose() { /* release resources *\/ }
+ * }
+ * ```
+ *
+ * @category Utilities
+ * @group Lifecycle
+ */
+export interface IDisposable {
+    dispose(): void;
+}
+
+/**
+ * Type guard to check if an object implements {@link IDisposable}.
+ *
+ * @example
+ * ```ts
+ * if (isDisposable(obj)) {
+ *     obj.dispose(); // safe to call
+ * }
+ * ```
+ */
+export function isDisposable(value: unknown): value is IDisposable {
+    return value !== null
+        && typeof value === "object"
+        && "dispose" in (value as object)
+        && typeof (value as IDisposable).dispose === "function";
+}
+
+/**
+ * @experimental
+ * Subscribe to a DOM event on any {@link EventTarget} (window, document, HTML elements, etc.)
+ * and return an {@link IDisposable} that removes the listener when disposed.
+ *
+ * Provides full TypeScript event type inference — the callback parameter
+ * is automatically typed based on the event name (e.g. `"resize"` → `UIEvent`,
+ * `"click"` → `MouseEvent`).
+ *
+ * Use with {@link DisposableStore.add} for automatic lifecycle cleanup in components.
+ *
+ * @param target The EventTarget to listen on (window, document, an element, etc.)
+ * @param type The event name (e.g. `"resize"`, `"click"`, `"keydown"`)
+ * @param listener The event handler callback
+ * @param options Optional addEventListener options (passive, capture, once, signal)
+ * @returns An {@link IDisposable} that removes the event listener when disposed
+ *
+ * @example Standalone usage
+ * ```ts
+ * import { on } from "@needle-tools/engine";
+ *
+ * const sub = on(window, "resize", (ev) => {
+ *     // ev is typed as UIEvent
+ *     console.log("resized", ev.target);
+ * });
+ *
+ * // Later: clean up
+ * sub.dispose();
+ * ```
+ *
+ * @example With autoCleanup in a component
+ * ```ts
+ * import { Behaviour, on } from "@needle-tools/engine";
+ *
+ * export class MyComponent extends Behaviour {
+ *     onEnable() {
+ *         this.autoCleanup(on(window, "resize", (ev) => { /* UIEvent *\/ }));
+ *         this.autoCleanup(on(document, "keydown", (ev) => { /* KeyboardEvent *\/ }));
+ *         this.autoCleanup(on(this.context.domElement, "click", (ev) => { /* MouseEvent *\/ }));
+ *     }
+ *     // All listeners removed automatically on disable!
+ * }
+ * ```
+ *
+ * @category Utilities
+ * @group Lifecycle
+ */
+// #region on
+export function on<K extends keyof WindowEventMap>(target: Window, type: K, listener: (ev: WindowEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
+export function on<K extends keyof DocumentEventMap>(target: Document, type: K, listener: (ev: DocumentEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
+export function on<K extends keyof HTMLElementEventMap>(target: HTMLElement, type: K, listener: (ev: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
+export function on(target: EventTarget, type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): IDisposable;
+export function on(target: EventTarget, type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): IDisposable {
+    target.addEventListener(type, listener, options);
+    return {
+        dispose() {
+            target.removeEventListener(type, listener, options);
+        }
+    };
+}
+
+
+/**
+ * A store for managing disposable resources (event subscriptions, listeners, callbacks)
+ * that should be cleaned up together.
+ *
+ * DisposableStore collects disposables and disposes them all at once when
+ * {@link dispose} is called. After disposal, the store can be reused — new items
+ * can be added and a subsequent {@link dispose} call will clean those up.
+ *
+ * This is the same pattern used internally by VSCode for lifecycle-bound resource management.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { DisposableStore, on } from "@needle-tools/engine";
+ *
+ * const store = new DisposableStore();
+ *
+ * // Register a DOM event listener (typed!)
+ * store.add(on(window, "resize", (ev) => console.log(ev)));
+ *
+ * // Register the return value of EventList.on()
+ * store.add(myEventList.on(data => console.log(data)));
+ *
+ * // Register a raw cleanup function
+ * store.add(() => someSDK.off("event", handler));
+ *
+ * // Later: dispose everything at once
+ * store.dispose();
+ * ```
+ *
+ * @example Use with Needle Engine components
+ * ```ts
+ * import { Behaviour, serializable, EventList, on } from "@needle-tools/engine";
+ *
+ * export class MyComponent extends Behaviour {
+ *     @serializable(EventList)
+ *     onClick?: EventList;
+ *
+ *     onEnable() {
+ *         // DOM events — fully typed
+ *         this.autoCleanup(on(window, "resize", (ev) => this.onResize(ev)));
+ *
+ *         // EventList — .on() returns a function, autoCleanup accepts it
+ *         this.autoCleanup(this.onClick?.on(() => console.log("clicked!")));
+ *     }
+ *     // No onDisable needed — cleaned up automatically!
+ * }
+ * ```
+ *
+ * @category Utilities
+ * @group Lifecycle
+ */
+// #region DisposableStore
+export class DisposableStore implements IDisposable {
+
+    private _disposables: Array<DisposeFn> = [];
+
+    /** The number of registered disposables */
+    get size() { return this._disposables.length; }
+
+    /**
+     * Register a disposable resource. Accepts:
+     * - An {@link IDisposable} object (has a `dispose()` method) — e.g. from {@link on}
+     * - A cleanup function (e.g. return value of `EventList.on()`)
+     * - `null` or `undefined` (safe no-op for conditional subscriptions)
+     *
+     * When {@link dispose} is called, all registered resources are cleaned up.
+     *
+     * @param disposable The resource to register for disposal
+     *
+     * @example
+     * ```ts
+     * const store = new DisposableStore();
+     *
+     * // IDisposable object from on()
+     * store.add(on(window, "resize", handler));
+     *
+     * // Function returned by EventList.on()
+     * store.add(myEvent.on(handler));
+     *
+     * // Raw cleanup function
+     * store.add(() => connection.close());
+     *
+     * // Conditional — safe with undefined
+     * store.add(this.maybeEvent?.on(handler));
+     * ```
+     */
+    add(disposable: IDisposable | DisposeFn | Function | null | undefined): void {
+        if (!disposable) return;
+        if (typeof disposable === "function") {
+            this._disposables.push(disposable as DisposeFn);
+        }
+        else if (typeof disposable === "object" && "dispose" in disposable) {
+            this._disposables.push(() => disposable.dispose());
+        }
+    }
+
+    /**
+     * Dispose all registered resources. Each registered disposable is cleaned up,
+     * then the internal list is cleared. The store can be reused after disposal.
+     *
+     * Called automatically by the engine when a component's `onDisable` lifecycle fires.
+     */
+    dispose(): void {
+        for (let i = this._disposables.length - 1; i >= 0; i--) {
+            try {
+                this._disposables[i]();
+            }
+            catch (err) {
+                console.error("Error disposing resource", err);
+            }
+        }
+        this._disposables.length = 0;
+    }
+}

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";
 
@@ -212,8 +213,8 @@ function internalDestroy(instance: Object3D | Component, recursive: boolean = tr
         if (comp[$isDontDestroy]) return;
         destroyed_components.push(comp);
         const go = comp.gameObject;
-        comp.__internalDisable();
-        comp.__internalDestroy();
+        comp.__internalDisable?.();
+        comp.__internalDestroy?.();
         comp.gameObject = go;
         return;
     }
@@ -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