@needle-tools/engine 4.16.5-next.c1731f4 → 4.16.6

package/plugins/vite/drop.js

@@ -42,14 +42,16 @@ export function needleDrop(command, config, userSettings) {
                 ];
             },
         },
-        configureServer(/** @type {import('vite').ViteDevServer} */ server) {
-            const hot = server.hot ?? server.ws;
+        configureServer(/** @type {{ ws: { on(event: string, cb: (...args: unknown[]) => void): void, send(type: string, data?: unknown): void } }} */ server) {
 
-            hot.on('needle:drop-file', async (/** @type {unknown} */ data, /** @type {unknown} */ client) => {
-                hot.send('needle-editor:drop-file', data);
+            server.ws.on('needle:drop-file', async (/** @type {unknown} */ data, /** @type {unknown} */ client) => {
+                server.ws.send('needle-editor:drop-file', data);
             });
+            // TODO: not sure how we can receive it with the normal vite server
+            // server.ws.on("custom", (data, client) => {
+            //     console.log(data);
+            // })
 
-            // Raw WebSocket access for editor messages
             server.ws.on('connection', (/** @type {{ on(event: string, cb: (...args: unknown[]) => void): void }} */ socket, /** @type {unknown} */ request) => {
                 socket.on('message', async (/** @type {Buffer | string} */ bytes) => {
                     try {
@@ -57,7 +59,7 @@ export function needleDrop(command, config, userSettings) {
                         if (message && message.startsWith("{")) {
                             const obj = /** @type {{ type: string, data: unknown }} */ (JSON.parse(message));
                             if (obj.type === "needle-editor:exported-file") {
-                                hot.send(obj.type, obj.data);
+                                server.ws.send(obj.type, obj.data);
                             }
                         }
                     }

package/plugins/vite/editor-connection.js

@@ -86,9 +86,8 @@ function createPlugin(isInstalled) {
         },
 
         configureServer(server) {
-            try
+            try 
             {
-                // Raw WebSocket access needed for direct socket communication
                 server.ws.on('connection', (socket, _request) => {
     
                     // console.log("Send editor sync status: " + isInstalled);

package/plugins/vite/poster.js

@@ -24,8 +24,7 @@ export function needlePoster(command, config, userSettings) {
     return {
         name: 'needle:poster',
         configureServer(server) {
-            const hot = server.hot ?? server.ws;
-            hot.on('needle:screenshot', async (data, client) => {
+            server.ws.on('needle:screenshot', async (data, client) => {
                 if (userSettings.noPoster) return;
                 if (!data?.data) {
                     console.warn("Received empty screenshot data, ignoring");

package/plugins/vite/reload.js

@@ -112,15 +112,10 @@ const posterPath = getPosterPath();
 let reloadIsScheduled = false;
 const lockFileName = "needle.lock";
 
-/** @param {import('vite').ViteDevServer} server */
-function getHot(server) {
-    return server.hot ?? server.ws;
-}
-
 /** @param {import('vite').ViteDevServer} server @param {string} [file] */
 function notifyClientWillReload(server, file) {
     console.log("Send reload notification");
-    getHot(server).send('needle:reload', { type: 'will-reload', file: file });
+    server.ws.send('needle:reload', { type: 'will-reload', file: file });
 }
 
 /**
@@ -241,7 +236,7 @@ async function scheduleReload(server, level = 0) {
     lastReloadTime = Date.now();
     const readableTime = new Date(lastReloadTime).toLocaleTimeString();
     console.log("< Reloading... " + readableTime)
-    getHot(server).send({
+    server.ws.send({
         type: 'full-reload',
         path: '*'
     });

package/plugins/vite/transform-codegen.js

@@ -43,12 +43,8 @@ export function needleTransformCodegen(command, config, userSettings) {
                         // }
 
                         console.log(`[needle-transform-files] - Transform codegen paths \"${configuredAssetsDirectory}\" → \"${assetsDir}\"`)
-                        // replace codegen paths, but only in non-import lines
-                        // (import lines use filesystem-relative paths for bundler awareness)
-                        src = src.split('\n').map(line => {
-                            if (line.trimStart().startsWith('import ')) return line;
-                            return line.replaceAll(configuredAssetsDirectory, assetsDir);
-                        }).join('\n');
+                        // replace codegen paths
+                        src = src.replaceAll(configuredAssetsDirectory, assetsDir);
                         return {
                             code: src,
                             map: null

package/src/engine/engine_application.ts

@@ -1,16 +1,6 @@
 import { isDevEnvironment } from "./debug/index.js";
 import { Context } from "./engine_setup.js";
 
-declare global {
-    interface UserActivation {
-        readonly hasBeenActive: boolean;
-        readonly isActive: boolean;
-    }
-    interface Navigator {
-        readonly userActivation: UserActivation;
-    }
-}
-
 export enum ApplicationEvents {
     Visible = "application-visible",
     Hidden = "application-hidden",

package/src/engine/engine_feature_flags.ts

@@ -1,4 +1,8 @@
 
-export const NEEDLE_ENGINE_FEATURE_FLAGS = {
-    experimentalSmartHierarchyUpdate: false,
-};
+
+export namespace NEEDLE_ENGINE_FEATURE_FLAGS {
+
+    // eslint-disable-next-line prefer-const
+    export let experimentalSmartHierarchyUpdate = false;
+
+}

package/src/engine/engine_modules.ts

@@ -1,46 +1,108 @@
 
-function createModule<T>(loader: () => Promise<T>) {
-    const callbacks: Array<(module: T) => void> = [];
-    const mod = {
-        MODULE: undefined as unknown as T,
-        MAYBEMODULE: null as T | null,
+/**
+ * External dependencies that are loaded on demand either by the engine automatically when needed or they can be loaded manually by calling the `load` function.  
+ * 
+ * Use the `ready` function to wait for the module to be loaded if you do not wand to trigger a load.
+ * 
+ * If a module is already loaded it's also available in the `MODULE` variable.
+ */
+export namespace MODULES {
+
+    export namespace MaterialX {
+        export type TYPE = typeof import("@needle-tools/materialx");
+        export let MODULE: TYPE;
+        export let MAYBEMODULE: TYPE | null = null;
+
+        const callbacks: Array<(module: TYPE) => void> = [];
         /** Wait for the module to be loaded (doesn't trigger a load) */
-        ready(): Promise<T> {
-            if (mod.MODULE) return Promise.resolve(mod.MODULE);
-            return new Promise(resolve => { callbacks.push(resolve); });
-        },
+        export function ready(): Promise<TYPE> {
+            if (MODULE) return Promise.resolve(MODULE);
+            return new Promise((resolve) => { callbacks.push(resolve); });
+        };
         /** Load the module */
-        async load(): Promise<T> {
-            if (mod.MODULE) return mod.MODULE;
-            const module = await loader();
-            mod.MODULE = module;
-            mod.MAYBEMODULE = module;
-            for (const cb of callbacks) cb(module);
+        export async function load(): Promise<TYPE> {
+            if (MODULE) return MODULE;
+            const module = await import("@needle-tools/materialx");
+            MODULE = module;
+            MAYBEMODULE = module;
+            callbacks.forEach((callback) => callback(module));
             callbacks.length = 0;
             return module;
         }
-    };
-    return mod;
-}
 
-/**
- * External dependencies that are loaded on demand either by the engine automatically when needed or they can be loaded manually by calling the `load` function.
- *
- * Use the `ready` function to wait for the module to be loaded if you do not wand to trigger a load.
- *
- * If a module is already loaded it's also available in the `MODULE` variable.
- */
-export const MODULES = {
-    MaterialX: createModule<typeof import("@needle-tools/materialx")>(
-        () => import("@needle-tools/materialx")
-    ),
-    RAPIER_PHYSICS: createModule<typeof import("@dimforge/rapier3d-compat")>(
-        () => import("@dimforge/rapier3d-compat")
-    ),
-    POSTPROCESSING: createModule<typeof import("postprocessing")>(
-        () => import("postprocessing")
-    ),
-    POSTPROCESSING_AO: createModule<typeof import("n8ao")>(
-        () => import("n8ao")
-    ),
-};
+    }
+
+    export namespace RAPIER_PHYSICS {
+        export type TYPE = typeof import("@dimforge/rapier3d-compat");
+        export let MODULE: TYPE;
+        export let MAYBEMODULE: TYPE | null = null;
+
+        const callbacks: Array<(module: TYPE) => void> = [];
+        /** Wait for the module to be loaded (doesn't trigger a load) */
+        export function ready(): Promise<TYPE> {
+            if (MODULE) return Promise.resolve(MODULE);
+            return new Promise((resolve) => { callbacks.push(resolve); });
+        };
+        /** Load the module */
+        export async function load(): Promise<TYPE> {
+            if (MODULE) return MODULE;
+            const module = await import("@dimforge/rapier3d-compat");
+            MODULE = module;
+            MAYBEMODULE = module;
+            callbacks.forEach((callback) => callback(module));
+            callbacks.length = 0;
+            return module;
+        }
+
+    }
+
+    export namespace POSTPROCESSING {
+
+        export type TYPE = typeof import("postprocessing");
+        export let MODULE: TYPE;
+        export let MAYBEMODULE: TYPE | null = null;
+
+        const callbacks: Array<(module: TYPE) => void> = [];
+        /** Wait for the module to be loaded (doesn't trigger a load) */
+        export function ready(): Promise<TYPE> {
+            if (MODULE) return Promise.resolve(MODULE);
+            return new Promise((resolve) => { callbacks.push(resolve); });
+        };
+
+        /** Load the module */
+        export async function load(): Promise<TYPE> {
+            if (MODULE) return MODULE;
+            const module = await import("postprocessing");
+            MODULE = module;
+            MAYBEMODULE = module;
+            callbacks.forEach((callback) => callback(module));
+            callbacks.length = 0;
+            return module;
+        }
+    }
+
+    export namespace POSTPROCESSING_AO {
+
+        export type TYPE = typeof import("n8ao");
+        export let MODULE: TYPE;
+        export let MAYBEMODULE: TYPE | null = null;
+
+        const callbacks: Array<(module: TYPE) => void> = [];
+        /** Wait for the module to be loaded (doesn't trigger a load) */
+        export function ready(): Promise<TYPE> {
+            if (MODULE) return Promise.resolve(MODULE);
+            return new Promise((resolve) => { callbacks.push(resolve); });
+        };
+
+        /** Load the module */
+        export async function load(): Promise<TYPE> {
+            if (MODULE) return MODULE;
+            const module = await import("n8ao");
+            MODULE = module;
+            MAYBEMODULE = module;
+            callbacks.forEach((callback) => callback(module));
+            callbacks.length = 0;
+            return module;
+        }
+    }
+}

package/src/engine/webcomponents/needle-engine.ts

@@ -38,58 +38,6 @@ const desktopSessionActiveClassName = "desktop-session-active";
 
 type TonemappingAttributeOptions = "none" | "linear" | "neutral" | "agx";
 
-/** Supported attributes for the `<needle-engine>` web component. */
-export interface NeedleEngineAttributes {
-    /** Change which model gets loaded. */
-    'src': string;
-    /** String attached to the context for caching/identification. */
-    'hash': string;
-    /** Set to automatically add OrbitControls to the loaded scene. */
-    'camera-controls': string;
-    /** Override the default draco decoder path location. */
-    'dracoDecoderPath': string;
-    /** Override the default draco library type. */
-    'dracoDecoderType': 'wasm' | 'js';
-    /** Override the default KTX2 transcoder/decoder path. */
-    'ktx2DecoderPath': string;
-    /** Prevent context from being disposed when element is removed from DOM. */
-    'keep-alive': 'true' | 'false';
-    /** Loading overlay style. */
-    'loading-style': 'dark' | 'light' | 'auto';
-    /** URL to .exr, .hdr, .png, .jpg to be used as skybox. */
-    'background-image': string;
-    /** Rotation of the background image in degrees. */
-    'background-rotation': string | number;
-    /** URL to .exr, .hdr, .png, .jpg to be used for lighting. */
-    'environment-image': string;
-    /** Intensity multiplier for environment lighting. */
-    'environment-intensity': string;
-    /** Blurs the background image. 0 (sharp) to 1 (fully blurred). */
-    'background-blurriness': string;
-    /** Intensity multiplier for the background image. */
-    'background-intensity': string;
-    /** CSS background color if no skybox/background image is provided. */
-    'background-color': string;
-    /** Enable/disable renderer canvas transparency. */
-    'transparent': 'true' | 'false';
-    /** Enable/disable contact shadows. */
-    'contact-shadows': 'true' | 'false';
-    /** Tonemapping mode. */
-    'tone-mapping': TonemappingAttributeOptions;
-    /** Exposure multiplier for tonemapping. */
-    'tone-mapping-exposure': string;
-    /** CSS selector or HTMLElement for camera focus. */
-    'focus-rect': string | HTMLElement;
-    /** Allow pointer events to pass through transparent parts. */
-    'clickthrough': 'true' | 'false';
-    /** Automatically fit model into camera view on load. */
-    'auto-fit': 'true' | 'false';
-    /** Auto-rotate model until user interacts. */
-    'auto-rotate': 'true' | 'false';
-    /** Play animations automatically on scene load. */
-    'autoplay': 'true' | 'false';
-}
-
 // #region Observables
 
 /** Keep in sync with the overloads and docs here:
@@ -958,18 +906,200 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
 
     // #region setAttribute
 
-    /** Set a known Needle Engine attribute. See {@link NeedleEngineAttributes} for available attributes. */
-    setAttribute<K extends keyof NeedleEngineAttributes>(name: K, value: NeedleEngineAttributes[K]): void;
-    setAttribute(qualifiedName: string, value: string): void;
+    // MainAttributes
+    /** Change which model gets loaded. This will trigger a reload of the scene. 
+     * @example src="path/to/scene.glb"
+     * @example src="[./path/scene1.glb, myOtherScene.gltf]"
+     * */
+    setAttribute(name: 'src', value: string): void;
+    /** Optional. String attached to the context for caching/identification. */
+    setAttribute(name: 'hash', value: string): void;
+    /** Set to automatically add {@link OrbitControls} to the loaded scene */
+    setAttribute(name: 'camera-controls', value: string): void;
+    /** Override the default draco decoder path location. */
+    setAttribute(name: 'dracoDecoderPath', value: string): void;
+    /** Override the default draco library type. */
+    setAttribute(name: 'dracoDecoderType', value: 'wasm' | 'js'): void;
+    /** Override the default KTX2 transcoder/decoder path */
+    setAttribute(name: 'ktx2DecoderPath', value: string): void;
+    /** Prevent Needle Engine context from being disposed when the element is removed from the DOM */
+    setAttribute(name: 'keep-alive', value: 'true' | 'false'): void;
+
+    /** @private Public key used for licensing and feature gating. */
+    setAttribute(name: 'public-key', value: string): void;
+    /** @private Engine version string — usually set by the build/runtime. */
+    setAttribute(name: 'version', value: string): void;
+
+    // LoadingAttributes
+    // ...
+
+    // SkyboxAttributes
+    /** URL to .exr, .hdr, .png, .jpg to be used as skybox */
+    setAttribute(name: 'background-image', value: string): void;
+    /** @private Rotation of the background image in degrees. */
+    setAttribute(name: 'background-rotation', value: string | number): void;
+    /** @deprecated Use 'environment-image' instead. */
+    setAttribute(name: 'skybox-image', value: string): void;
+    /** URL to .exr, .hdr, .png, .jpg to be used for lighting */
+    setAttribute(name: 'environment-image', value: string): void;
+    /** Intensity multiplier for environment lighting. */
+    setAttribute(name: 'environment-intensity', value: string): void;
+    /** Blurs the background image. Strength between 0 (sharp) and 1 (fully blurred). */
+    setAttribute(name: 'background-blurriness', value: string): void;
+    /** Intensity multiplier for the background image. */
+    setAttribute(name: 'background-intensity', value: string): void;
+    /**
+     * CSS background color value to be used if no skybox or background image is provided.
+     * @example "background-color='#ff0000'" will set the background color to red.
+     */
+    setAttribute(name: 'background-color', value: string): void;
+
+    // RenderingAttributes
+    /** Enable/disable renderer canvas transparency. */
+    setAttribute(name: 'transparent', value: 'true' | 'false'): void;
+    /** Enable/disable contact shadows in the rendered scene */
+    setAttribute(name: 'contact-shadows', value: 'true' | 'false'): void;
+    /** Tonemapping mode. */
+    setAttribute(name: 'tone-mapping', value: TonemappingAttributeOptions): void;
+    /** Exposure multiplier for tonemapping. */
+    setAttribute(name: 'tone-mapping-exposure', value: string): void;
+
+    /** Defines a CSS selector or HTMLElement where the camera should be focused on. Content will be fit into this element. */
+    setAttribute(name: 'focus-rect', value: string | HTMLElement): void;
+    /** Allow pointer events to pass through transparent parts of the content to the underlying DOM elements. */
+    setAttribute(name: 'clickthrough', value: 'true' | 'false'): void;
+    /** Automatically fits the model into the camera view on load. */
+    setAttribute(name: 'auto-fit', value: 'true' | 'false'): void;
+    /** Automatically rotates the model until a user interacts with the scene. */
+    setAttribute(name: 'auto-rotate', value: 'true' | 'false'): void;
+    /** Play animations automatically on scene load */
+    setAttribute(name: "autoplay", value: 'true' | 'false'): void;
+    /** @private Used for switching the scene in SceneSwitcher */
+    setAttribute(name: 'scene', value: string): void;
+
+    // setAttribute(name: 'loadstart', value: string): void;
+
+    /** @private Experimental.*/
+    setAttribute(name: 'loading-blur', value: 'true' | 'false'): void;
+    /** @private */
+    setAttribute(name: 'alias', value: string): void;
+    /** @private */
+    setAttribute(name: 'hide-loading-overlay', value: 'true' | 'false'): void;
+    /** @private */
+    setAttribute(name: 'no-telemetry', value: 'true' | 'false'): void;
+
+    /** Generic typed setter for known Needle Engine attributes */
+    // Comment out to see errors inside NE for undocumented attributes
+    // setAttribute<T extends keyof NeedleEngineAttributes>(qualifiedName: T, value: NeedleEngineAttributes[T]): void;
+
+    setAttribute(qualifiedName: ({} & string), value: string): void;
+
+    // The ones we're using internally:
+    /*
+    setAttribute(name: "tabindex", value: string): void;
+    */
     setAttribute(qualifiedName: string, value: string): void {
-        super.setAttribute(qualifiedName, typeof value === "string" ? value : String(value));
+        super.setAttribute(qualifiedName, value);
     }
 
     // #region getAttribute
 
-    /** Get a known Needle Engine attribute. See {@link NeedleEngineAttributes} for available attributes. */
-    getAttribute<K extends keyof NeedleEngineAttributes>(qualifiedName: K): string | null;
-    getAttribute(qualifiedName: string): string | null;
+    // MainAttributes
+    /** Change which model gets loaded. This will trigger a reload of the scene. 
+     * @example src="path/to/scene.glb"
+     * @example src="[./path/scene1.glb, myOtherScene.gltf]"
+     * */
+    getAttribute(name: 'src'): string | null;
+    /** Optional. String attached to the context for caching/identification. */
+    getAttribute(name: 'hash'): string | null;
+    /** Set to automatically add {@link OrbitControls} to the loaded scene */
+    getAttribute(name: 'camera-controls'): "true" | "false" | "none" | null;
+    /** Override the default draco decoder path location. */
+    getAttribute(name: 'dracoDecoderPath'): string | null;
+    /** Override the default draco library type. */
+    getAttribute(name: 'dracoDecoderType'): "wasm" | "js" | null;
+    /** Override the default KTX2 transcoder/decoder path */
+    getAttribute(name: 'ktx2DecoderPath'): string | null;
+    /** Prevent Needle Engine context from being disposed when the element is removed from the DOM */
+    getAttribute(name: 'keep-alive'): string | null;
+
+    /** @private Public key used for licensing and feature gating. */
+    getAttribute(name: 'public-key'): string | null;
+    /** @private Engine version string — usually set by the build/runtime. */
+    getAttribute(name: 'version'): string | null;
+
+    // LoadingAttributes
+    // ...
+
+    // SkyboxAttributes
+    /** URL to .exr, .hdr, .png, .jpg to be used as skybox */
+    getAttribute(name: 'background-image'): string | null;
+    /** @private Rotation of the background image in degrees. */
+    getAttribute(name: 'background-rotation'): string | null;
+    /** URL to .exr, .hdr, .png, .jpg to be used for lighting */
+    getAttribute(name: 'environment-image'): string | null;
+    /** Intensity multiplier for environment lighting. */
+    getAttribute(name: 'environment-intensity'): string | null;
+    /** Blurs the background image. Strength between 0 (sharp) and 1 (fully blurred). */
+    getAttribute(name: 'background-blurriness'): string | null;
+    /** Intensity multiplier for the background image. */
+    getAttribute(name: 'background-intensity'): string | null;
+    /**
+     * CSS background color value to be used if no skybox or background image is provided.
+     * @example "background-color='#ff0000'" will set the background color to red.
+     */
+    getAttribute(name: 'background-color'): string | null;
+
+    // RenderingAttributes
+    /** Enable/disable renderer canvas transparency. */
+    getAttribute(name: 'transparent'): string | null;
+    /** Enable/disable contact shadows in the rendered scene */
+    getAttribute(name: 'contact-shadows'): string | null;
+    /** @deprecated Use 'contact-shadows' instead. */
+    getAttribute(name: 'contactshadows'): string | null;
+    /** Tonemapping mode. */
+    getAttribute(name: 'tone-mapping'): TonemappingAttributeOptions | null;
+    /** @deprecated Use 'tone-mapping' instead. */
+    getAttribute(name: 'tonemapping'): TonemappingAttributeOptions | null;
+    /** Exposure multiplier for tonemapping. */
+    getAttribute(name: 'tone-mapping-exposure'): string | null;
+
+    /** Defines a CSS selector or HTMLElement where the camera should be focused on. Content will be fit into this element. */
+    getAttribute(name: 'focus-rect'): string | null;
+    /** Allow pointer events to pass through transparent parts of the content to the underlying DOM elements. */
+    getAttribute(name: 'clickthrough'): string | null;
+    /** Automatically fits the model into the camera view on load. */
+    getAttribute(name: 'auto-fit'): string | null;
+    /** @deprecated Use 'auto-fit' instead. */
+    getAttribute(name: 'autofit'): string | null;
+    /** Automatically rotates the model until a user interacts with the scene. */
+    getAttribute(name: 'auto-rotate'): string | null;
+    /** Play animations automatically on scene load */
+    getAttribute(name: "autoplay"): string | null;
+    /** @private Used for switching the scene in SceneSwitcher */
+    getAttribute(name: 'scene'): string | null;
+    // getAttribute(name: 'loadstart'): string | null;
+
+    /** @private Experimental.*/
+    getAttribute(name: 'loading-blur'): string | null;
+    /** @private */
+    getAttribute(name: 'alias'): string | null;
+    /** @private */
+    getAttribute(name: 'hide-loading-overlay'): string | null;
+    /** @private */
+    getAttribute(name: 'no-telemetry'): string | null;
+
+    // Comment these out to get development errors for undocumented NE attributes
+    /** Typed getter for known NeedleEngine attribute names; returns the typed shape declared in NeedleEngineAttributes or null. */
+    // getAttribute<T extends keyof NeedleEngineAttributes>(qualifiedName: T): NeedleEngineAttributes[T] | null;
+    getAttribute(qualifiedName: ({} & string)): string | null;
+
+    // The ones we're using interally:
+    /*
+    getAttribute(name: "autostart"): string | null;
+    getAttribute(name: "tabindex"): string | null;
+    */
+
     getAttribute(qualifiedName: string): string | null {
         return super.getAttribute(qualifiedName);
     }

package/src/engine-components/postprocessing/PostProcessingHandler.ts

@@ -56,7 +56,7 @@ export class PostProcessingHandler {
     }
 
     apply(components: PostProcessingEffect[]): Promise<void> {
-        if ("env" in import.meta && (import.meta as any /* webpack support */ ).env.VITE_NEEDLE_USE_POSTPROCESSING === "false") {
+        if ("env" in import.meta && import.meta.env.VITE_NEEDLE_USE_POSTPROCESSING === "false") {
             if (debug) console.warn("Postprocessing is disabled via vite env setting");
             else console.debug("Postprocessing is disabled via vite env setting");
             return Promise.resolve();