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

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

@@ -291,7 +291,7 @@ export function needleMakeFilesLocal(command, _config, userSettings) {
                     failedDownloads,
                     localizationStats,
                 }, activeHandlers);
-                src = fixRelativeNewURL(src);
+                src = fixRelativeNewURL(src, viteConfig?.base);
             }
             catch (err) {
                 needleLog("needle:local-files", "Error in transform: " + getErrMessage(err), "error");
@@ -303,7 +303,7 @@ export function needleMakeFilesLocal(command, _config, userSettings) {
         },
         renderChunk(code, chunk) {
             if (!chunk.fileName?.endsWith(".js")) return null;
-            const fixed = fixRelativeNewURL(code);
+            const fixed = fixRelativeNewURL(code, viteConfig?.base);
             if (fixed === code) return null;
             return {
                 code: fixed,
@@ -314,7 +314,7 @@ export function needleMakeFilesLocal(command, _config, userSettings) {
             for (const output of Object.values(bundle)) {
                 if (output.type !== "chunk") continue;
                 if (!output.fileName?.endsWith(".js")) continue;
-                const fixed = fixRelativeNewURL(output.code);
+                const fixed = fixRelativeNewURL(output.code, viteConfig?.base);
                 if (fixed !== output.code) output.code = fixed;
             }
         },

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/plugins/vite/meta.js

@@ -13,8 +13,7 @@ import { needleGreenBold, needleLog } from './logging.js';
  */
 export function needleMeta(command, config, userSettings) {
 
-    // we can check if this is a build
-    const isBuild = command === 'build';
+    let isBuild = command === 'build';
 
     async function updateConfig() {
         config = await loadConfig();
@@ -25,6 +24,9 @@ export function needleMeta(command, config, userSettings) {
     return {
         // replace meta tags
         name: 'needle:meta',
+        configResolved(resolvedConfig) {
+            isBuild = resolvedConfig.command === 'build';
+        },
         transformIndexHtml: {
             order: 'pre',
             handler(/** @type {string} */ html, /** @type {unknown} */ _ctx) {

package/plugins/vite/poster.d.ts

@@ -1,8 +1,8 @@
 export function getPosterPath(): string;
 /**
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {import('../types/needleConfig').needleMeta | null | undefined} config
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin | undefined}
  */
-export function needlePoster(command: "build" | "serve", config: import("../types/needleConfig").needleMeta | null | undefined, userSettings: import("../types").userSettings): import("vite").Plugin | undefined;
+export function needlePoster(_command: "build" | "serve" | undefined, config: import("../types/needleConfig").needleMeta | null | undefined, userSettings: import("../types").userSettings): import("vite").Plugin | undefined;

package/plugins/vite/poster.js

@@ -10,19 +10,17 @@ export function getPosterPath() {
 }
 
 /**
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {import('../types/needleConfig').needleMeta | null | undefined} config
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin | undefined}
  */
-export function needlePoster(command, config, userSettings) {
-    // only relevant for local development
-    if (command === 'build') return [];
-
+export function needlePoster(_command, config, userSettings) {
     if (userSettings.noPoster) return;
 
     return {
         name: 'needle:poster',
+        apply: 'serve',
         configureServer(server) {
             const hot = server.hot ?? server.ws;
             hot.on('needle:screenshot', async (data, client) => {

package/plugins/vite/reload.d.ts

@@ -1,7 +1,7 @@
 /**
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {import('../types/needleConfig').needleMeta | null} config
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin | undefined}
  */
-export function needleReload(command: "build" | "serve", config: import("../types/needleConfig").needleMeta | null, userSettings: import("../types").userSettings): import("vite").Plugin | undefined;
+export function needleReload(_command: "build" | "serve" | undefined, config: import("../types/needleConfig").needleMeta | null, userSettings: import("../types").userSettings): import("vite").Plugin | undefined;

package/plugins/vite/reload.js

@@ -7,6 +7,7 @@ import { existsSync, readFileSync, statSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { needleLog } from './logging.js';
 
+const pluginName = "needle-reload";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
@@ -15,14 +16,12 @@ const filesUsingHotReload = new Set();
 let assetsDirectory = "";
 
 /**
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {import('../types/needleConfig').needleMeta | null} config
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin | undefined}
  */
-export function needleReload(command, config, userSettings) {
-    if (command === "build") return undefined;
-
+export function needleReload(_command, config, userSettings) {
     if (userSettings?.noReload === true) return undefined;
 
 
@@ -41,7 +40,7 @@ export function needleReload(command, config, userSettings) {
     const buildDirectory = projectConfig?.buildDirectory?.length ? process.cwd().replaceAll("\\", "/") + "/" + projectConfig?.buildDirectory : "";
     if (buildDirectory?.length) {
         const relativeBuildDirectory = path.relative(process.cwd(), buildDirectory).replaceAll("\\", "/") || ".";
-        setTimeout(() => needleLog("needle-reload", "Build directory: " + relativeBuildDirectory), 100);
+        setTimeout(() => needleLog(pluginName, "Build directory: " + relativeBuildDirectory), 100);
     }
 
     // These ignore patterns will be injected into user config to better control vite reloading
@@ -51,6 +50,7 @@ export function needleReload(command, config, userSettings) {
 
     return {
         name: 'needle:reload',
+        apply: 'serve',
         /** @param {import('vite').UserConfig} config */
         config(config) {
             if (!config.server) config.server = { watch: { ignored: [] } };
@@ -60,7 +60,7 @@ export function needleReload(command, config, userSettings) {
                 // @ts-ignore - watch.ignored is guaranteed to be string[] by the guards above
                 config.server.watch.ignored.push(pattern);
             if (userSettings?.debug === true)
-                setTimeout(() => needleLog("needle-reload", "Updated server ignore patterns: " + JSON.stringify(config.server?.watch?.ignored)), 100);
+                setTimeout(() => needleLog(pluginName, "Updated server ignore patterns: " + JSON.stringify(config.server?.watch?.ignored)), 100);
         },
         /** @param {import('vite').HmrContext & {buildDirectory?: string}} args */
         handleHotUpdate(args) {
@@ -119,7 +119,7 @@ function getHot(server) {
 
 /** @param {import('vite').ViteDevServer} server @param {string} [file] */
 function notifyClientWillReload(server, file) {
-    console.log("Send reload notification");
+    needleLog(pluginName, "Send reload notification");
     getHot(server).send('needle:reload', { type: 'will-reload', file: file });
 }
 
@@ -135,7 +135,7 @@ async function handleReload({ file, server, modules: _modules, read, buildDirect
 
     // Dont reload the whole server when a file that is using hot reload changes
     if (filesUsingHotReload.has(file)) {
-        console.log("File is using hot reload: " + file);
+        needleLog(pluginName, "File is using hot reload: " + file);
         return null;
     }
 
@@ -154,7 +154,7 @@ async function handleReload({ file, server, modules: _modules, read, buildDirect
     // instead of relying on the vite server watch ignore array
     // we could here also match paths that we know we dont want to track
     if (ignorePatterns.length > 0 && ignoreRegex.test(file)) {
-        console.log("Ignore change in file: " + getFileNameLog(file));
+        needleLog(pluginName, "Ignore change in file: " + getFileNameLog(file));
         return [];
     }
 
@@ -164,7 +164,7 @@ async function handleReload({ file, server, modules: _modules, read, buildDirect
     if (buildDirectory?.length) {
         const dir = path.dirname(file).replaceAll("\\", "/");
         if (dir.startsWith(buildDirectory)) {
-            console.log("Ignore change in build directory: " + getFileNameLog(file));
+            needleLog(pluginName, "Ignore change in build directory: " + getFileNameLog(file));
             return [];
         }
     }
@@ -174,18 +174,18 @@ async function handleReload({ file, server, modules: _modules, read, buildDirect
     // meaning if its the first export after the server starts those will not trigger a reload
     // Ignore d.ts
     const shouldCheckIfContentChanged = file.includes("/codegen/") || file.includes("/generated/") || file.endsWith("gen.js");// || file.endsWith(".glb") || file.endsWith(".gltf") || file.endsWith(".bin");
-    if (shouldCheckIfContentChanged && !file.endsWith(".d.ts") && !file.endsWith("needle-html-data.json")) {
+    if (!file.includes("/.svelte-kit/") && !file.endsWith(".d.ts") && !file.endsWith("needle-html-data.json") && shouldCheckIfContentChanged) {
         if (reloadIsScheduled) {
             return [];
         }
         if (await testIfFileContentChanged(file, read) === false) {
-            console.log("File content didnt change: " + getFileNameLog(file));
+            needleLog(pluginName, "File content didnt change: " + getFileNameLog(file));
             return [];
         }
     }
 
     // these are known file types we export from integrations
-    const knownExportFileTypes = [ ".glb", ".gltf", ".bin", "exr", ".ktx2", ".mp3", ".ogg", ".mp4", ".webm" ];
+    const knownExportFileTypes = [".glb", ".gltf", ".bin", "exr", ".ktx2", ".mp3", ".ogg", ".mp4", ".webm"];
     if (!knownExportFileTypes.some((type) => file.endsWith(type)))
         return null;
 
@@ -209,7 +209,7 @@ async function handleReload({ file, server, modules: _modules, read, buildDirect
         }
     }
 
-    console.log("> Detected file change: ", getFileNameLog(file) + " (" + ((fileSize / (1024 * 1024)).toFixed(1)) + " MB)");
+    needleLog(pluginName, "> Detected file change: " + getFileNameLog(file) + " (" + ((fileSize / (1024 * 1024)).toFixed(1)) + " MB)");
     notifyClientWillReload(server);
     scheduleReload(server);
     return [];
@@ -224,8 +224,8 @@ async function scheduleReload(server, level = 0) {
     const lockFile = path.join(process.cwd(), lockFileName);
     if (existsSync(lockFile)) {
         if (level === 0)
-            console.log("Lock file exists, waiting for export to finish...");
-        setTimeout(() => scheduleReload(server, level += 1), 300);
+            needleLog(pluginName, "Lock file exists, waiting for export to finish...");
+        setTimeout(() => scheduleReload(server, level += 1), 300).unref();
         return;
     }
 
@@ -235,13 +235,13 @@ async function scheduleReload(server, level = 0) {
     if (timeDiff < 1000) {
         // Sometimes file changes happen immediately after triggering a reload 
         // we dont want to reload again in that case
-        console.log("Ignoring reload, last reload was too recent", timeDiff);
+        needleLog(pluginName, "Ignoring reload, last reload was too recent" + timeDiff + "ms ago");
         return;
     }
 
     lastReloadTime = Date.now();
     const readableTime = new Date(lastReloadTime).toLocaleTimeString();
-    console.log("< Reloading... " + readableTime)
+    needleLog(pluginName, "< Reloading... " + readableTime);
     getHot(server).send({
         type: 'full-reload',
         path: '*'
@@ -300,10 +300,10 @@ function removeVersionQueryArgument(content) {
 function insertScriptRegisterHotReloadCode(src, filePath) {
 
     // We only want to inject the hot reload code in the needle-engine root file
-    if(!filePath.includes("/src/needle-engine.ts")) {
+    if (!filePath.includes("/src/needle-engine.ts")) {
         return src;
     }
-    console.log("[Needle HMR] Hot reload is enabled");
+    needleLog(pluginName, "[Needle HMR] Hot reload is enabled");
     // this code let's the engine know that we are in hot reload mode
     const code = `
 globalThis.NEEDLE_HOT_RELOAD_ENABLED = true;
@@ -339,12 +339,12 @@ function insertScriptHotReloadCode(src, filePath) {
             return undefined;
         // make import path from engine package
         const fullPathToHotReload = process.cwd() + "/node_modules/@needle-tools/engine/src/engine/engine_hot_reload.ts";
-        // console.log(fullPathToHotReload);
+        // needleLog(pluginName, fullPathToHotReload);
         const fileDirectory = path.dirname(filePath);
-        // console.log("DIR", fileDirectory)
+        // needleLog(pluginName, "DIR", fileDirectory)
         const relativePath = path.relative(fileDirectory, fullPathToHotReload);
         importPath = relativePath.replace(/\\/g, "/");
-        // console.log("importPath: ", importPath);
+        // needleLog(pluginName, "importPath: ", importPath);
     }
 
     // console.log(importPath, ">", filePath);

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";
 
@@ -164,6 +167,9 @@ export * from "./engine_constants.js";
  */
 export * from "./engine_context.js";
 
+/** Typed event bus for decoupled component communication via {@link Context.events} */
+export * from "./engine_context_eventbus.js";
+
 /** Registry for managing multiple engine contexts */
 export * from "./engine_context_registry.js";
 
@@ -173,6 +179,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";
 
@@ -220,7 +230,7 @@ export * from "./engine_input.js";
 export { InstancingUtil } from "./engine_instancing.js";
 
 /** License checking utilities */
-export { hasCommercialLicense, hasIndieLicense, hasProLicense } from "./engine_license.js";
+export { __gGoBKfJa, __CYjiNy, $TXm } from "./engine_license.js";
 
 
 // ============================================================================
@@ -450,4 +460,4 @@ export * from "./xr/api.js"
  * import type { SceneData } from "@needle-tools/engine";
  * type OrbitSettings = SceneData["Camera"]["OrbitControls"];
  */
-export type { SceneData } from "needle:bindings";
+export type { SceneData } from "needle-bindings";

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";
@@ -106,11 +101,12 @@ import { TestRunner } from "../../engine-components/TestRunner.js";
 import { TestSimulateUserData } from "../../engine-components/TestRunner.js";
 import { PlayableDirector } from "../../engine-components/timeline/PlayableDirector.js";
 import { SignalReceiver } from "../../engine-components/timeline/SignalAsset.js";
-import { AnimationTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
-import { AudioTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
-import { MarkerTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineAnimationTrack } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineAudioTrack } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineMarkerTrack } from "../../engine-components/timeline/TimelineTracks.js";
 import { SignalTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
-import { ControlTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineActivationTrack } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineControlTrack } from "../../engine-components/timeline/TimelineTracks.js";
 import { TransformGizmo } from "../../engine-components/TransformGizmo.js";
 import { BaseUIComponent } from "../../engine-components/ui/BaseUIComponent.js";
 import { UIRootComponent } 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);
@@ -266,11 +257,12 @@ export function initBuiltinTypes() {
 	TypeStore.add("TestSimulateUserData", TestSimulateUserData);
 	TypeStore.add("PlayableDirector", PlayableDirector);
 	TypeStore.add("SignalReceiver", SignalReceiver);
-	TypeStore.add("AnimationTrackHandler", AnimationTrackHandler);
-	TypeStore.add("AudioTrackHandler", AudioTrackHandler);
-	TypeStore.add("MarkerTrackHandler", MarkerTrackHandler);
+	TypeStore.add("TimelineAnimationTrack", TimelineAnimationTrack);
+	TypeStore.add("TimelineAudioTrack", TimelineAudioTrack);
+	TypeStore.add("TimelineMarkerTrack", TimelineMarkerTrack);
 	TypeStore.add("SignalTrackHandler", SignalTrackHandler);
-	TypeStore.add("ControlTrackHandler", ControlTrackHandler);
+	TypeStore.add("TimelineActivationTrack", TimelineActivationTrack);
+	TypeStore.add("TimelineControlTrack", TimelineControlTrack);
 	TypeStore.add("TransformGizmo", TransformGizmo);
 	TypeStore.add("BaseUIComponent", BaseUIComponent);
 	TypeStore.add("UIRootComponent", UIRootComponent);

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