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

package/plugins/vite/local-files-utils.js

@@ -113,25 +113,49 @@ export function ensureTrailingSlash(path) {
 
 /**
  * @param {string} src
+ * @param {string} [base] - Vite base path (e.g. "/" or "/app/"). When provided,
+ *   ext/ paths are made absolute so they resolve correctly under SPA routing.
  * @returns {string}
  */
-export function fixRelativeNewURL(src) {
+export function fixRelativeNewURL(src, base) {
+    /** @param {string} path */
+    function makeAbsolute(path) {
+        // Strip any leading ./ ../ or / prefix to get the clean ext/... path
+        const clean = path.replace(/^(?:\.\.?\/)+/, '').replace(/^\//, '');
+        if (base) return base.replace(/\/+$/, '') + '/' + clean;
+        return clean;
+    }
+
     src = src.replace(
         /(?<==\s*)(["'])((?:(?:\.{1,2}\/)|\/)?ext\/[^"']*\/)\1/g,
         (/** @type {string} */ _match, /** @type {string} */ quote, /** @type {string} */ path) => {
-            const runtimePath = path.startsWith("/ext/") ? path.substring(1) : path;
-            return `new URL(${quote}${runtimePath}${quote}, self.location?.href || ${quote}${quote}).href`;
+            const resolved = makeAbsolute(path);
+            return `new URL(${quote}${resolved}${quote}, self.location?.href || ${quote}${quote}).href`;
         }
     );
 
     src = src.replace(
         /new\s+URL\s*\(\s*(["'`])((?:(?:\.{1,2}\/)|\/)?ext\/[^"'`]+)\1\s*\)/g,
         (/** @type {string} */ _match, /** @type {string} */ quote, /** @type {string} */ path) => {
-            const runtimePath = path.startsWith("/ext/") ? path.substring(1) : path;
-            return `new URL(${quote}${runtimePath}${quote}, self.location?.href)`;
+            const resolved = makeAbsolute(path);
+            return `new URL(${quote}${resolved}${quote}, self.location?.href)`;
         }
     );
 
+    // Make remaining ext/ string literals absolute (e.g. font paths passed as
+    // function arguments like addVariant("normal","normal","ext/fonts/...")).
+    // The regexes above already consumed paths inside new URL() calls and
+    // assignment-based patterns, so this only catches leftover bare strings.
+    if (base) {
+        src = src.replace(
+            /(["'`])((?:\.{1,2}\/)?ext\/[^"'`]+)\1/g,
+            (/** @type {string} */ _match, /** @type {string} */ quote, /** @type {string} */ path) => {
+                const resolved = makeAbsolute(path);
+                return `${quote}${resolved}${quote}`;
+            }
+        );
+    }
+
     return src;
 }
 

package/plugins/vite/reload.js

@@ -225,7 +225,7 @@ async function scheduleReload(server, level = 0) {
     if (existsSync(lockFile)) {
         if (level === 0)
             needleLog(pluginName, "Lock file exists, waiting for export to finish...");
-        setTimeout(() => scheduleReload(server, level += 1), 300);
+        setTimeout(() => scheduleReload(server, level += 1), 300).unref();
         return;
     }
 

package/plugins/vite/server.js

@@ -60,7 +60,8 @@ export function needleServer(command, config, userSettings) {
                             })
                             .catch((err) => console.error("ERR: [needle:server] 'open' package not found - please make sure to install 'open' in your package.json\n", err));
                     }
-                }, 100)
+                }, 100);
+                i.unref();
             }
         },
     }

package/src/engine/api.ts

@@ -114,6 +114,9 @@ export * from "./engine_addressables.js";
 /** Animation playback and control utilities */
 export { AnimationUtils } from "./engine_animation.js";
 
+/** Standalone audio clip for playback control */
+export { AudioClip } from "./engine_audio.js";
+
 /** Application-level state and utilities */
 export { Application } from "./engine_application.js";
 
@@ -173,6 +176,10 @@ export * from "./engine_context_registry.js";
  */
 export * from "./engine_coroutine.js"
 
+/** DisposableStore for managing lifecycle-bound cleanup in components */
+export { DisposableStore, on, isDisposable } from "./engine_disposable.js";
+export type { DisposeFn, IDisposable } from "./engine_disposable.js";
+
 /** Factory functions for creating primitives and objects */
 export * from "./engine_create_objects.js";
 

package/src/engine/codegen/register_types.ts

@@ -7,11 +7,6 @@ import { Animation } from "../../engine-components/Animation.js";
 import { Animator } from "../../engine-components/Animator.js";
 import { AudioListener } from "../../engine-components/AudioListener.js";
 import { AudioSource } from "../../engine-components/AudioSource.js";
-import { Avatar_Brain_LookAt } from "../../engine-components/avatar/Avatar_Brain_LookAt.js";
-import { Avatar_MouthShapes } from "../../engine-components/avatar/Avatar_MouthShapes.js";
-import { Avatar_MustacheShake } from "../../engine-components/avatar/Avatar_MustacheShake.js";
-import { AvatarBlink_Simple } from "../../engine-components/avatar/AvatarBlink_Simple.js";
-import { AvatarEyeLook_Rotation } from "../../engine-components/avatar/AvatarEyeLook_Rotation.js";
 import { AxesHelper } from "../../engine-components/AxesHelper.js";
 import { BasicIKConstraint } from "../../engine-components/BasicIKConstraint.js";
 import { BoxHelperComponent } from "../../engine-components/BoxHelperComponent.js";
@@ -110,6 +105,7 @@ import { AnimationTrackHandler } from "../../engine-components/timeline/Timeline
 import { AudioTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
 import { MarkerTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
 import { SignalTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
+import { ActivationTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
 import { ControlTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
 import { TransformGizmo } from "../../engine-components/TransformGizmo.js";
 import { BaseUIComponent } from "../../engine-components/ui/BaseUIComponent.js";
@@ -167,11 +163,6 @@ export function initBuiltinTypes() {
 	TypeStore.add("Animator", Animator);
 	TypeStore.add("AudioListener", AudioListener);
 	TypeStore.add("AudioSource", AudioSource);
-	TypeStore.add("Avatar_Brain_LookAt", Avatar_Brain_LookAt);
-	TypeStore.add("Avatar_MouthShapes", Avatar_MouthShapes);
-	TypeStore.add("Avatar_MustacheShake", Avatar_MustacheShake);
-	TypeStore.add("AvatarBlink_Simple", AvatarBlink_Simple);
-	TypeStore.add("AvatarEyeLook_Rotation", AvatarEyeLook_Rotation);
 	TypeStore.add("AxesHelper", AxesHelper);
 	TypeStore.add("BasicIKConstraint", BasicIKConstraint);
 	TypeStore.add("BoxHelperComponent", BoxHelperComponent);
@@ -270,6 +261,7 @@ export function initBuiltinTypes() {
 	TypeStore.add("AudioTrackHandler", AudioTrackHandler);
 	TypeStore.add("MarkerTrackHandler", MarkerTrackHandler);
 	TypeStore.add("SignalTrackHandler", SignalTrackHandler);
+	TypeStore.add("ActivationTrackHandler", ActivationTrackHandler);
 	TypeStore.add("ControlTrackHandler", ControlTrackHandler);
 	TypeStore.add("TransformGizmo", TransformGizmo);
 	TypeStore.add("BaseUIComponent", BaseUIComponent);

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_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,
@@ -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';
@@ -863,7 +863,7 @@ 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();
 

package/src/engine/engine_disposable.ts

@@ -0,0 +1,213 @@
+/** 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";
+}
+
+/**
+ * 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;
+    }
+}