@needle-tools/engine 5.1.0-canary.30cc545 → 5.1.0-canary.40da791

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,
@@ -22,6 +23,7 @@ import { Application } from './engine_application.js';
 import { AssetDatabase } from './engine_assetdatabase.js';
 import { FocusRect, FocusRectSettings, updateCameraFocusRect } from './engine_camera.js';
 import { VERSION } from './engine_constants.js';
+import { EventBus } from './engine_context_eventbus.js';
 import { ContextEvent, ContextRegistry } from './engine_context_registry.js';
 import { WaitForPromise } from './engine_coroutine.js';
 import { ObjectUtils } from "./engine_create_objects.js";
@@ -36,9 +38,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';
@@ -151,7 +152,7 @@ export function registerComponent(script: IComponent, context?: Context) {
 }
 
 /**
- * The Needle Engine context is the main access point that holds all the data and state of a Needle Engine application. 
+ * The Needle Engine context is the main access point that holds all the data and state of a Needle Engine application.
  * It can be used to access the {@link Context.scene}, {@link Context.renderer}, {@link Context.mainCamera}, {@link Context.input}, {@link Context.physics}, {@link Context.time}, {@link Context.connection} (networking), and more.
  * 
  * The context is automatically created when using the `<needle-engine>` web component.  
@@ -478,13 +479,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.
 	 *
-	 * 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)`.
+	 * 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.
+	 *
+	 * @experimental This API may change in future versions.
 	 *
 	 * @example
 	 * // Toggle auto-rotate on the orbit camera
@@ -493,12 +495,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);
@@ -527,30 +523,59 @@ export class Context implements IContext {
 	private _fallbackCamera: PerspectiveCamera | null = null;
 
 	/** access application state (e.g. if all audio should be muted) */
-	application: Application;
+	get application(): Application { return this._application; }
+	private _application!: Application;
 	/** access animation mixer used by components in the scene */
-	animations: AnimationsRegistry;
+	get animations(): AnimationsRegistry { return this._animations; }
+	private _animations!: AnimationsRegistry;
 	/** access timings (current frame number, deltaTime, timeScale, ...) */
-	time: Time;
+	get time(): Time { return this._time; }
+	private _time!: Time;
 	/** access input data (e.g. click or touch events) */
-	input: Input;
+	get input(): Input { return this._input; }
+	private _input!: Input;
 	/** access physics related methods (e.g. raycasting). To access the phyiscs engine use `context.physics.engine` */
-	physics: Physics;
+	get physics(): Physics { return this._physics; }
+	private _physics!: Physics;
 	/** access postprocessing effects stack. Add/remove effects and configure adaptive performance settings */
-	postprocessing: PostProcessing;
+	get postprocessing(): PostProcessing { return this._postprocessing; }
+	private _postprocessing!: PostProcessing;
 	/** access networking methods (use it to send or listen to messages or join a networking backend) */
-	connection: NetworkConnection;
+	get connection(): NetworkConnection { return this._connection; }
+	private _connection!: NetworkConnection;
+	/** context-level event bus for decoupled component communication
+	 * @see {@link ContextEventMap} for known event types
+	 */
+	get events(): EventBus { return this._events; }
+	private _events = new EventBus();
 	/**  @deprecated AssetDatabase is deprecated */
 	assets: AssetDatabase;
-	/** The main light in the scene */
-	mainLight: ILight | null = null;
+
+	/** 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
+	 */
+	get mainLight(): ILight | null {
+		let best: ILight | null = null;
+		for (const light of this.lights) {
+			if (light.type !== "directional") continue;
+			if (!best || light.intensity > best.intensity) best = light;
+		}
+		return best;
+	}
+
 	/** @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;
@@ -594,12 +619,12 @@ export class Context implements IContext {
 		else this.scene = new Scene();
 		if (args?.camera) this._mainCamera = args.camera;
 
-		this.application = new Application(this);
-		this.time = new Time();
-		this.input = new Input(this);
-		this.physics = new Physics(this);
-		this.postprocessing = new PostProcessing(this);
-		this.connection = new NetworkConnection(this);
+		this._application = new Application(this);
+		this._time = new Time();
+		this._input = new Input(this);
+		this._physics = new Physics(this);
+		this._postprocessing = new PostProcessing(this);
+		this._connection = new NetworkConnection(this);
 		// eslint-disable-next-line @typescript-eslint/no-deprecated
 		this.assets = new AssetDatabase();
 		this.sceneLighting = new SceneLighting(this);
@@ -608,7 +633,7 @@ export class Context implements IContext {
 		this.players = new PlayerViewManager(this);
 		this.menu = new NeedleMenu(this);
 		this.lodsManager = new LODsManager(this);
-		this.animations = new AnimationsRegistry(this);
+		this._animations = new AnimationsRegistry(this);
 		this.accessibility = new AccessibilityManager(this);
 
 
@@ -851,12 +876,16 @@ 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._events.clear();
+		this._events = new EventBus();
+
+		this.lights.length = 0;
 
 		if (!this.isManagedExternally) {
 			if (this.renderer) {
@@ -898,6 +927,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_context_eventbus.ts

@@ -0,0 +1,73 @@
+import type { Object3D } from "three";
+
+import type { IComponent } from "./engine_types.js";
+
+/** Typed event map for {@link Context.events}.
+ * Known events get full autocomplete; custom events can be typed at the call site via generic parameter.
+ */
+export interface ContextEventMap {
+	"scene-content-changed": {
+		/** The component that triggered the change (e.g. SceneSwitcher, DropListener) */
+		readonly source: IComponent;
+		/** The root object that was added/loaded */
+		readonly object: Object3D;
+	};
+}
+
+/** Options for {@link EventBus.on}. */
+export interface EventBusListenerOptions {
+	/** If true the listener is automatically removed after the first invocation. */
+	once?: boolean;
+}
+
+/** Typed event bus. Known {@link ContextEventMap} events get full autocomplete.
+ * Custom events can be typed at the call site via generic parameter.
+ * @example Known events
+ * ```ts
+ * context.events.on("scene-content-changed", e => e.object);
+ * ```
+ * @example Custom events — type at call site
+ * ```ts
+ * context.events.emit<{ pts: number }>("scored", { pts: 10 });
+ * context.events.on<{ pts: number }>("scored", e => e.pts);
+ * ```
+ * @example Once
+ * ```ts
+ * context.events.on("scene-content-changed", e => { ... }, { once: true });
+ * ```
+ */
+export class EventBus {
+	private _listeners = new Map<string, Function[]>();
+
+	/** Emit a known {@link ContextEventMap} event */
+	emit<K extends keyof ContextEventMap & string>(type: K, detail?: ContextEventMap[K]): void;
+	/** Emit a custom event with user-provided type */
+	emit<T>(type: string, detail?: T): void;
+	emit(type: string, detail?: unknown): void {
+		const arr = this._listeners.get(type);
+		if (arr) for (const cb of [...arr]) cb(detail);
+	}
+
+	/** Subscribe to a known {@link ContextEventMap} event. Returns an unsubscribe function. */
+	on<K extends keyof ContextEventMap & string>(type: K, callback: (args: ContextEventMap[K]) => void, options?: EventBusListenerOptions): () => void;
+	/** Subscribe to a custom event with user-provided type. Returns an unsubscribe function. */
+	on<T>(type: string, callback: (args: T) => void, options?: EventBusListenerOptions): () => void;
+	on(type: string, callback: Function, options?: EventBusListenerOptions): () => void {
+		let arr = this._listeners.get(type);
+		if (!arr) { arr = []; this._listeners.set(type, arr); }
+		const unsub = () => {
+			const i = arr.indexOf(wrapped);
+			if (i >= 0) arr.splice(i, 1);
+		};
+		const wrapped = options?.once
+			? (...args: unknown[]) => { unsub(); callback(...args); }
+			: callback;
+		arr.push(wrapped);
+		return unsub;
+	}
+
+	/** Remove all listeners. Called when the context is cleared or destroyed. */
+	clear(): void {
+		this._listeners.clear();
+	}
+}

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