@needle-tools/engine 5.1.0-alpha.2 → 5.1.0-alpha.3

package/plugins/vite/local-files-utils.d.ts

@@ -24,9 +24,11 @@ export function normalizeWebPath(path: string): string;
 export function ensureTrailingSlash(path: string): string;
 /**
  * @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: string): string;
+export function fixRelativeNewURL(src: string, base?: string): string;
 /**
  * @param {string} src
  * @returns {string}

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/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";
 

package/src/engine/debug/debug_spatial_console.ts

@@ -12,13 +12,16 @@ import { onError } from "./debug_overlay.js";
 
 let _isActive = false;
 
-// enable the spatial console if we receive an error while in dev session and in XR
-onError((...args: any[]) => {
-    if (isDevEnvironment() && ContextRegistry.Current?.isInXR) {
-        enableSpatialConsole(true);
-        onLog("error", ...args);
-    }
-})
+/** @internal */
+export function initSpatialConsole() {
+    // enable the spatial console if we receive an error while in dev session and in XR
+    onError((...args: any[]) => {
+        if (isDevEnvironment() && ContextRegistry.Current?.isInXR) {
+            enableSpatialConsole(true);
+            onLog("error", ...args);
+        }
+    });
+}
 
 
 /** Enable a spatial debug console that follows the camera */

package/src/engine/engine_addressables.ts

@@ -567,7 +567,6 @@ class AddressableSerializer extends TypeSerializer {
     }
 
 }
-new AddressableSerializer();
 
 
 
@@ -703,7 +702,6 @@ export class ImageReferenceSerializer extends TypeSerializer {
         return undefined;
     }
 }
-new ImageReferenceSerializer();
 
 
 
@@ -772,4 +770,9 @@ export class FileReferenceSerializer extends TypeSerializer {
         return undefined;
     }
 }
-new FileReferenceSerializer();
+/** @internal */
+export function initAddressableSerializers() {
+    new AddressableSerializer();
+    new ImageReferenceSerializer();
+    new FileReferenceSerializer();
+}

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';

package/src/engine/engine_gameobject.ts

@@ -212,8 +212,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;
     }

package/src/engine/engine_init.ts

@@ -1,20 +1,25 @@
 import { initAnimationAutoplay } from "../engine-components/AnimationUtilsAutoplay.js";
+import { initAnimatorControllerSerializer } from "../engine-components/AnimatorController.js";
 import { initCameraUtils } from "../engine-components/CameraUtils.js";
+import { initVolumeParameterSerializer } from "../engine-components/postprocessing/VolumeParameter.js";
 import { initSceneSwitcherAttributes } from "../engine-components/SceneSwitcher.js";
 import { initSkyboxAttributes } from "../engine-components/Skybox.js";
 import { initBuiltinTypes } from "./codegen/register_types.js";
+import { initSpatialConsole } from "./debug/debug_spatial_console.js";
+import { initAddressableSerializers } from "./engine_addressables.js";
 import { ensureAudioContextIsResumed } from "./engine_audio.js";
+import { initLicense } from "./engine_license.js";
 import { initNeedleLoader } from "./engine_loaders.js";
+import { initPhysics } from "./engine_physics_rapier.js";
+import { initBuiltinSerializers } from "./engine_serialization_builtin_serializer.js";
 import { initShims } from "./engine_shims.js";
+import { SSR } from "./engine_ssr.js";
 import { patchTonemapping } from "./engine_tonemapping.js";
 import { initCameraExtensions } from "./js-extensions/Camera.js";
 import { patchLayers } from "./js-extensions/Layers.js";
 import { initObject3DExtensions } from "./js-extensions/Object3D.js";
 import { initVectorExtensions } from "./js-extensions/Vector.js";
-import { SSR } from "./engine_ssr.js";
-import { initLicense } from "./engine_license.js";
 import { initWebComponents } from "./webcomponents/init.js";
-import { initPhysics } from "./engine_physics_rapier.js";
 import { initXR } from "./xr/init.js";
 
 let initialized = false;
@@ -35,6 +40,10 @@ export function initEngine() {
 
     initWebComponents();
     initShims();
+    initBuiltinSerializers();
+    initAddressableSerializers();
+    initAnimatorControllerSerializer();
+    initVolumeParameterSerializer();
     patchTonemapping();
     patchLayers();
     initCameraExtensions();
@@ -49,5 +58,6 @@ export function initEngine() {
     initSceneSwitcherAttributes();
     initPhysics();
     initXR();
+    initSpatialConsole();
     initLicense();
 }

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';

package/src/engine/engine_license.ts

@@ -3,9 +3,9 @@ import { ContextEvent, ContextRegistry } from "./engine_context_registry.js";
 import { onInitialized } from "./engine_lifecycle_api.js";
 import { isLocalNetwork } from "./engine_networking_utils.js";
 import { Context } from "./engine_setup.js";
+import { SSR } from "./engine_ssr.js";
 import type { IContext } from "./engine_types.js";
 import { getParam } from "./engine_utils.js";
-import { SSR } from "./engine_ssr.js";
 
 const debug = getParam("debuglicense");
 

package/src/engine/engine_mainloop_utils.ts

@@ -344,8 +344,11 @@ function updateIsActiveInHierarchyRecursiveRuntime(go: Object3D, activeInHierarc
         if (allowEventCall) {
             const components = go.userData?.components;
             if (components) {
-                for (let ci = components.length - 1, cl = -1; ci > cl; ci--) {
-                    const comp = components[ci];
+                // We need to iterate on components in the original order right now to work-around UI related initialization bugs where RectTransform must be initialized before e.g. Graphic components. https://linear.app/needle/issue/NE-6986
+                // In the future we can reverse iterate this once the UI system has been replaced (that being said it's probably expected that component enable in the order in which they're added to an object)
+                const componentsCopy = [...components];
+                for (let ci = 0; ci < componentsCopy.length; ci++) {
+                    const comp = componentsCopy[ci];
                     if (activeInHierarchy) {
                         if (comp?.enabled) {
                             try { comp.__internalAwake(); }

package/src/engine/engine_networking_blob.ts

@@ -3,7 +3,7 @@ import { FileLoader } from "three";
 import { showBalloonWarning } from "./debug/index.js";
 import { hasCommercialLicense } from "./engine_license.js";
 import { delay } from "./engine_utils.js";
-import { md5Hex, md5AsBytes, sha256Base64 } from "./engine_utils_hash.js";
+import { md5AsBytes, md5Hex, sha256Base64 } from "./engine_utils_hash.js";
 
 
 export namespace BlobStorage {

package/src/engine/engine_scenedata.ts

@@ -1,10 +1,10 @@
 import type { SceneData } from "needle-bindings";
 export type { SceneData };
-import type { IContext } from "./engine_types.js";
-import { getComponent } from "./engine_components.js";
-import { TypeStore } from "./engine_typestore.js";
 import { isDevEnvironment } from "./debug/index.js";
+import { getComponent } from "./engine_components.js";
 import { ContextRegistry } from "./engine_context_registry.js";
+import type { IContext } from "./engine_types.js";
+import { TypeStore } from "./engine_typestore.js";
 
 /**
  * Quick access to the current Needle Engine context from anywhere — no need to pass `ctx` around.
@@ -13,6 +13,8 @@ import { ContextRegistry } from "./engine_context_registry.js";
  * Safe to import at module level, including in SSR environments.
  * For pages with multiple `<needle-engine>` elements, use `ctx` directly instead.
  *
+ * @experimental This API may change in future releases.
+ *
  * @example
  * import { needle } from "@needle-tools/engine";
  * button.onclick = () => {