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

package/src/engine/engine_audio.ts

@@ -21,4 +21,188 @@ export function ensureAudioContextIsResumed() {
             }, 500);
         });
     });
+}
+
+
+/**
+ * Represents an audio clip that can be loaded and played independently.
+ * The AudioClip class encapsulates the URL of the audio resource and provides
+ * methods for playback control (play, pause, stop) and querying duration.
+ */
+export class AudioClip {
+
+    /**
+     * Creates a new AudioClip instance with the specified URL.
+     * @param url The URL of the audio resource to load. This can be a path to an audio file or a MediaStream URL.
+     */
+    constructor(public readonly url: string) {
+    }
+
+    /** Whether the clip is currently playing.
+     * @returns `true` if the clip is actively playing audio.
+     */
+    get isPlaying(): boolean {
+        return this._audioElement !== undefined
+            && !this._audioElement.paused
+            && !this._audioElement.ended;
+    }
+
+    /**
+     * The total duration of the audio clip in seconds.
+     * Loads the audio metadata if not already available.
+     * @returns A promise that resolves with the duration in seconds.
+     */
+    getDuration(): Promise<number> {
+        if (this._duration !== undefined) {
+            return Promise.resolve(this._duration);
+        }
+        return this.ensureAudioElement().then(audio => {
+            this._duration = audio.duration;
+            return audio.duration;
+        });
+    }
+
+    /**
+     * Plays the audio clip from the current position.
+     * @returns A promise that resolves when playback finishes, or rejects on error.
+     * If the clip is looping, the promise will never resolve on its own – call {@link stop} or {@link pause} to end playback.
+     */
+    // #region Play
+    play(): Promise<void> {
+        return this.ensureAudioElement().then(audio => {
+            return new Promise<void>((resolve, reject) => {
+                const onEnded = () => {
+                    cleanup();
+                    resolve();
+                };
+                const onError = () => {
+                    cleanup();
+                    reject(new Error(`Playback error for ${this.url}`));
+                };
+                const onPause = () => {
+                    // pause/stop also resolve the promise
+                    cleanup();
+                    resolve();
+                };
+                const cleanup = () => {
+                    audio.removeEventListener("ended", onEnded);
+                    audio.removeEventListener("error", onError);
+                    audio.removeEventListener("pause", onPause);
+                };
+                audio.addEventListener("ended", onEnded);
+                audio.addEventListener("error", onError);
+                audio.addEventListener("pause", onPause);
+                audio.play().catch(err => {
+                    cleanup();
+                    reject(err);
+                });
+            });
+        });
+    }
+
+    /**
+     * Pauses playback at the current position.
+     * Call {@link play} to resume.
+     */
+    // #region Pause/Stop
+    pause(): void {
+        this._audioElement?.pause();
+    }
+
+    /**
+     * Stops playback and resets the position to the beginning.
+     */
+    stop(): void {
+        if (this._audioElement) {
+            this._audioElement.pause();
+            this._audioElement.currentTime = 0;
+        }
+    }
+
+    /** Whether the clip should loop when reaching the end. */
+    get loop(): boolean { return this._loop; }
+    set loop(value: boolean) {
+        this._loop = value;
+        if (this._audioElement) this._audioElement.loop = value;
+    }
+
+    /** Playback volume from 0 (silent) to 1 (full). */
+    get volume(): number { return this._volume; }
+    set volume(value: number) {
+        this._volume = value;
+        if (this._audioElement) this._audioElement.volume = value;
+    }
+
+    /** Current playback position in seconds. */
+    get currentTime(): number { return this._audioElement?.currentTime ?? 0; }
+    set currentTime(value: number) {
+        if (this._audioElement) this._audioElement.currentTime = value;
+    }
+
+    /** Normalized playback progress from 0 to 1.
+     * @returns The current playback position as a value between 0 and 1, or 0 if the duration is unknown.
+     */
+    get progress(): number {
+        if (!this._audioElement || !this._duration) return 0;
+        return this._audioElement.currentTime / this._duration;
+    }
+
+    /**
+     * Seeks to a normalized position (0–1) in the clip.
+     * @param position A value between 0 (start) and 1 (end).
+     */
+    // #region Seek
+    seek(position: number): void {
+        if (this._audioElement && this._duration) {
+            this._audioElement.currentTime = Math.max(0, Math.min(1, position)) * this._duration;
+        }
+    }
+
+    /** The underlying HTMLAudioElement, or `undefined` if not yet created.
+     * Use this to connect the element to the Web Audio API via `createMediaElementSource()`.
+     * @returns The HTMLAudioElement if the clip has been loaded or played, otherwise `undefined`.
+     */
+    get audioElement(): HTMLAudioElement | undefined { return this._audioElement; }
+
+    private _audioElement?: HTMLAudioElement;
+    private _duration?: number;
+    private _loadPromise?: Promise<HTMLAudioElement>;
+    private _loop: boolean = false;
+    private _volume: number = 1;
+
+    /** Lazily creates and loads the shared HTMLAudioElement. */
+    private ensureAudioElement(): Promise<HTMLAudioElement> {
+        if (this._audioElement && this._loadPromise) {
+            return this._loadPromise;
+        }
+        const audio = this._audioElement ?? new Audio(this.url);
+        this._audioElement = audio;
+        audio.loop = this._loop;
+        audio.volume = this._volume;
+
+        if (audio.readyState >= HTMLMediaElement.HAVE_METADATA) {
+            this._duration = audio.duration;
+            this._loadPromise = Promise.resolve(audio);
+            return this._loadPromise;
+        }
+
+        this._loadPromise = new Promise<HTMLAudioElement>((resolve, reject) => {
+            const onLoaded = () => {
+                cleanup();
+                this._duration = audio.duration;
+                resolve(audio);
+            };
+            const onError = (e: Event) => {
+                cleanup();
+                reject(new Error(`Failed to load audio clip from ${this.url}: ${e}`));
+            };
+            const cleanup = () => {
+                audio.removeEventListener("loadedmetadata", onLoaded);
+                audio.removeEventListener("error", onError);
+            };
+            audio.addEventListener("loadedmetadata", onLoaded);
+            audio.addEventListener("error", onError);
+        });
+        return this._loadPromise;
+    }
 }

package/src/engine/engine_camera.fit.ts

@@ -257,12 +257,23 @@ export function fitCamera(options?: FitCameraOptions): null | FitCameraReturnTyp
     else {
         direction.sub(camera.worldPosition);
     }
-    if (centerCamera === "y")
-        direction.y = 0;
+    if (centerCamera === "y") {
+        // Preserve the camera's current elevation angle when it's already above the center,
+        // but clamp to a minimum elevation to prevent the camera from ending up at or below
+        // the scene center (which causes a "looking up from below" effect).
+        // direction points FROM camera TO center, so negative Y = camera is above center.
+        const horizontalLen = Math.sqrt(direction.x * direction.x + direction.z * direction.z);
+        if (horizontalLen > 0.0001) {
+            const minY = -horizontalLen * verticalOffset * 4;
+            if (direction.y > minY) direction.y = minY;
+        }
+        else {
+            // Camera is directly above/below center — pick a default slight angle from +Z
+            direction.set(0, -verticalOffset * 4, 1);
+        }
+    }
     direction.normalize();
     direction.multiplyScalar(distance);
-    if (centerCamera === "y")
-        direction.y += -verticalOffset * 4 * distance;
 
     let cameraLocalPosition = center.clone().sub(direction);
     if (options.cameraOffset) {

package/src/engine/engine_components.ts

@@ -8,9 +8,9 @@ import { InstantiateIdProvider } from "./engine_networking_instantiate.js";
 import { Context, registerComponent } from "./engine_setup.js";
 import type { ComponentInit, Constructor, ConstructorConcrete, IComponent, IGameObject } from "./engine_types.js";
 import { $componentName } from "./engine_types.js";
+import { TypeStore } from "./engine_typestore.js";
 import { getParam } from "./engine_utils.js";
 import { apply } from "./js-extensions/index.js";
-import { TypeStore } from "./engine_typestore.js";
 
 const COMPONENT_GUID_NAMESPACE = 'eff8ba80-635d-11ec-90d6-0242ac120003';
 

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.
+	 *
+	 * 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 +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);
@@ -516,6 +512,13 @@ export class Context implements IContext {
 		}
 		if (!this._fallbackCamera) {
 			this._fallbackCamera = new PerspectiveCamera(75, this.domWidth / this.domHeight, 0.1, 1000);
+			// Put the fallback into the scene graph. Without this, callers who
+			// do `ctx.mainCamera.add(child)` end up parenting children to an
+			// orphan camera that the renderer never traverses (since
+			// `renderer.render(scene, camera)` walks `scene`, not `camera`).
+			// Safe because this branch only runs before a real main camera
+			// component exists, and the fallback is replaced once one does.
+			this.scene.add(this._fallbackCamera);
 		}
 		return this._fallbackCamera;
 	}
@@ -527,30 +530,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 +626,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 +640,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 +883,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 +934,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) {
@@ -1778,6 +1815,7 @@ export class Context implements IContext {
 					? (`${((window.performance as any).memory.usedJSHeapSize / 1024 / 1024).toFixed(2)} MB`)
 					: "n/a";
 
+				const gl = this.renderer.getContext();
 				console.log(this.renderer.info.render.calls + " DrawCalls", "\nRender:",
 					{
 						shaders: this.renderer.info.programs?.length,
@@ -1787,7 +1825,16 @@ export class Context implements IContext {
 					{
 						usedMemory: usedJSHeapSize,
 						...this.renderer.info.memory
-					}, "\nTarget Framerate: " + this.targetFrameRate);
+					},
+					"\nRenderer:",
+					{
+						dpr: this.renderer.getPixelRatio(),
+						windowDpr: window.devicePixelRatio,
+						antialias: gl.getContextAttributes()?.antialias,
+						samples: gl.getParameter(gl.SAMPLES),
+						resolution: `${this.renderer.domElement.width}x${this.renderer.domElement.height}`,
+					},
+					"\nTarget Framerate: " + this.targetFrameRate);
 			}
 		}
 

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