@needle-tools/engine 4.7.0-next.4ec920e → 4.7.0-next.598a777

package/plugins/types/userconfig.d.ts

@@ -1,5 +1,4 @@
 import { License } from "./license";
-import { NeedlePWAOptions } from "./webmanifest.js";
 
 export type needleModules = {
     webpack: object | undefined
@@ -49,7 +48,7 @@ export type userSettings = {
     /** Custom configuration for facebook instant games. */
     facebookInstantGames?: {}
     /** Set to true to create an imports.log file that shows all module imports. The file is generated when stopping the server. */
-    logModuleImportChains?: boolean;
+    debugImportChains?: boolean;
 
     /** Set to true to disable generating the buildinfo.json file in your output directory */
     noBuildInfo?: boolean;
@@ -117,4 +116,9 @@ export type userSettings = {
      * @default undefined
      */
     openBrowser?: boolean;
+
+    /** Automatically import MaterialX for needle engine in 'main.ts' */
+    loadMaterialX?: boolean;
+
+    disableLogging?: boolean;
 }

package/plugins/vite/alias.js

@@ -3,14 +3,33 @@ import path from 'path';
 
 const projectDir = process.cwd() + "/";
 
+/**
+ * @typedef {"auto-resolve" | ((res: string, packageName: string, index: number, path: string) => string | null | void)} PackageResolveValue
+ */
+
 /** these are alias callbacks as in the vite.alias dictionary
  * the first argument is the already resoled absolute path (it is only invoked if the path was found in node_modules)
  * the 2,3,4 args are the same as in vite.alias (packageName, index, path);
  */
 /**
- * @type {Record<string, null | ((res: string, packageName: string, index: number, path: string) => string | null | void)>}
+ * @type {Record<string, PackageResolveValue>}
  */
 const packages_to_resolve = {
+    // We are currently overriding "three" resolution to ensure that all dependencies resolve to the same three.js version.
+    // This is hacky, but the alternative is potentially having conflicting three.js versions since some packages are 
+    // stubborn with their peer dependencies or just slow (slower as we) with updating.
+    // NOT adding this allows node.js to correctly resolve `exports` specified in three.js package.json;
+    // since we're overriding resolution here we need to manually resolve the subset of exports that we use.
+    'three/addons': (res, packageName, index, path) => {
+        return "three/examples/jsm";
+    },
+    'three/nodes': (res, packageName, index, path) => {
+        return "three/examples/jsm/nodes/Nodes.js";
+    },
+    'three': (res, packageName, index, _path) => {
+        return path.resolve(projectDir, 'node_modules', 'three');
+    },
+
     // Handle all previous imports where users did import using @needle-engine/src
     '@needle-tools/engine/src': (res, packageName, index, path) => {
         // resolve old engine/src imports UNLESS it's the asap plugin (the asap plugin currently only exists in the src folder)
@@ -23,21 +42,25 @@ const packages_to_resolve = {
     because this is automatically done by vite according to whatever we define in our package.json exports
     This did previously prevent us from declaring proper exports in package.json
     */
-    '@needle-tools/engine': (res, packageName, index, path) => {
+    '@needle-tools/engine': (res, packageName, index, _path) => {
         // Check if the import is something like @needle-tools/engine/engine/engine_utils
         // in which case we want to resolve into the lib directory
-        if (path.startsWith("@needle-tools/engine/engine")) {
+        if (_path.startsWith("@needle-tools/engine/engine")) {
             return res + "/lib";
         }
+        const node_modules_path = path.resolve(projectDir, 'node_modules', '@needle-tools/engine');
+        if (existsSync(node_modules_path)) {
+            return node_modules_path;
+        }
     },
 
-    /* 
-    Removed. Three.js is manually resolved below to ensure all dependencies resolve to the same three.js version.
-    'three': null,
-    */
-    'peerjs': null,
-    'websocket-ts': null,
-    'md5': null,
+    // Auto resolve to 'node_modules/<name>' or '@needle-tools/engine/node_modules/<name>'
+    'peerjs': "auto-resolve",
+    'websocket-ts': "auto-resolve",
+    'md5': "auto-resolve",
+    'three-mesh-bvh': "auto-resolve",
+    'postprocessing': "auto-resolve",
+    '@dimforge/rapier3d-compat': "auto-resolve",
 }
 
 /**
@@ -67,6 +90,7 @@ export const needleViteAlias = (command, config, userSettings) => {
     }
 
 
+    /** @type {import("vite").Plugin} */
     const aliasPlugin = {
         name: "needle-alias",
         config(config) {
@@ -75,11 +99,9 @@ export const needleViteAlias = (command, config, userSettings) => {
             if (!config.resolve.alias) config.resolve.alias = {};
             const aliasDict = config.resolve.alias;
 
-            addThreeJSResolvers(aliasDict);
-
             for (const name in packages_to_resolve) {
                 if (!aliasDict[name]) {
-                    addPathResolver(name, aliasDict, packages_to_resolve[name]);
+                    addPathResolver(name, aliasDict, packages_to_resolve[name], debug ?? false);
                 }
             }
 
@@ -127,43 +149,36 @@ export const needleViteAlias = (command, config, userSettings) => {
     if (debug) return [debuggingPlugin, aliasPlugin];
     return [aliasPlugin];
 
-    function addThreeJSResolvers(aliasDict) {
-        // We are currently overriding "three" resolution to ensure that all dependencies resolve to the same three.js version.
-        // This is hacky, but the alternative is potentially having conflicting three.js versions since some packages are 
-        // stubborn with their peer dependencies or just slow (slower as we) with updating.
-        // NOT adding this allows node.js to correctly resolve `exports` specified in three.js package.json;
-        // since we're overriding resolution here we need to manually resolve the subset of exports that we use.
-        aliasDict['three/addons'] = (res, packageName, index, path) => {
-            return "three/examples/jsm";
-        };
-        aliasDict['three/nodes'] = (res, packageName, index, path) => {
-            return "three/examples/jsm/nodes/Nodes.js";
-        };
-        aliasDict['three'] = (res, packageName, index, _path) => {
-            return path.resolve(projectDir, 'node_modules', 'three');
-        };
-    }
-
-    function addPathResolver(name, aliasDict, cb) {
+    /**
+     * Adds a path resolver to the alias dictionary.
+     * @param {string} name - The name of the package to resolve.
+     * @param {import("vite").AliasOptions} aliasDict - The alias dictionary to add the resolver to.
+     * @param {PackageResolveValue | null} value - A callback function to override the default resolution behavior.
+     * @param {boolean} debug - Whether to log debug information.
+     * @returns {void}
+     */
+    function addPathResolver(name, aliasDict, value, debug) {
         // If a package at the node_modules path exist we resolve the request there
         // introduced in 89a50718c38940abb99ee16c5e029065e41d7d65
-        const fullpath = path.resolve(projectDir, 'node_modules', name);
-        if (typeof cb !== "function") cb = null;
-        const isDevEnvironment = process.env.NODE_ENV === "development";
+        const callback = typeof value === "function" ? value : null;
+
+        let fullpath = path.resolve(projectDir, 'node_modules', name);
+        if (!existsSync(fullpath)) {
+            fullpath = path.resolve(projectDir, 'node_modules', "@needle-tools/engine", "node_modules", name);
+        }
 
         if (existsSync(fullpath)) {
             aliasDict[name] = (packageName, index, path) => {
-                if (cb !== null && !isDevEnvironment) {
-                    const overrideResult = cb(fullpath, packageName, index, path);
-                    if (overrideResult !== undefined)
+                if (callback !== null) {
+                    const overrideResult = callback(fullpath, packageName, index, path);
+                    if (typeof overrideResult === "string")
                         if (existsSync(overrideResult)) {
-                            console.warn(`[needle-alias] \"${path}\" was requested and resolved to \"${overrideResult}\"`);
+                            if (debug) console.warn(`[needle-alias] \"${path}\" was requested and resolved to \"${overrideResult}\"`);
                             return overrideResult;
                         }
                 }
 
-                if (path != packageName) {
-                    // TODO: we might want to check if the package.json exports contains the path to see if it's valid
+                if (debug && path != packageName) {
                     console.warn(`[needle-alias] \"${path}\" was requested and resolved to \"${fullpath}\"`);
                 }
 

package/plugins/vite/imports-logger.js

@@ -6,7 +6,7 @@ import fs from 'fs';
  */
 export const needleImportsLogger = (command, config, userSettings) => {
 
-    if (!userSettings.logModuleImportChains) return;
+    if (!userSettings.debugImportChains) return;
 
     const graph =  {
         allNodes: new Map(),

package/plugins/vite/index.js

@@ -66,6 +66,8 @@ export { needleBuildInfo } from "./buildinfo.js";
 import { needleServer } from "./server.js";
 import { needleNPM } from "./npm.js";
 import { needleTransformCode } from "./transform.js";
+import { needleMaterialXLoader } from "./materialx.js";
+import { needleLogger } from "./logger.js";
 export { needleServer } from "./server.js";
 
 
@@ -110,6 +112,7 @@ export const needlePlugins = async (command, config = undefined, userSettings =
     userSettings = { ...defaultUserSettings, ...userSettings };
 
     const array = [
+        needleLogger(command, config, userSettings),
         needleDefines(command, config, userSettings),
         needleLicense(command, config, userSettings),
         needleViteAlias(command, config, userSettings),
@@ -133,6 +136,7 @@ export const needlePlugins = async (command, config = undefined, userSettings =
         needlePWA(command, config, userSettings),
         needleServer(command, config, userSettings),
         needleNPM(command, config, userSettings),
+        needleMaterialXLoader(command, config, userSettings),
     ];
 
     const asap = await needleAsap(command, config, userSettings);

package/plugins/vite/logger.client.js

@@ -0,0 +1,262 @@
+
+/**
+ * Patches console methods to capture log messages and send them to the server.
+ * This is useful for debugging and logging in the client.
+ * @param {"log" | "warn" | "info" | "debug" | "error" | "internal"} level
+ * @param {any} message - The log message to capture.
+ */
+function sendLogToServer(level, ...message) {
+    if ("hot" in import.meta) {
+        message = stringifyLog(message);
+        // @ts-ignore
+        import.meta.hot.send("needle:client-log", { level, message: message });
+    }
+}
+
+// const obj = {
+//     hello: "world"
+// }
+// obj["test"] = obj;
+// sendLogToServer("internal", "Test circular reference", obj);
+
+if (import.meta && "hot" in import.meta) {
+
+    const originalLog = console.log;
+    const originalWarn = console.warn;
+    const originalInfo = console.info;
+    const originalDebug = console.debug;
+    const originalError = console.error;
+
+    console.log = (...args) => {
+        originalLog(...args);
+        sendLogToServer("log", ...args);
+    }
+    console.warn = (...args) => {
+        originalWarn(...args);
+        sendLogToServer("warn", ...args);
+    }
+    console.info = (...args) => {
+        originalInfo(...args);
+        sendLogToServer("info", ...args);
+    }
+    console.debug = (...args) => {
+        originalDebug(...args);
+        sendLogToServer("debug", ...args);
+    }
+    console.error = (...args) => {
+        originalError(...args);
+        sendLogToServer("error", ...args);
+    }
+
+    try {
+        sendLogToServer("internal", `Page loaded
+URL: ${window.location.href}
+UserAgent: ${navigator.userAgent}
+Screen: ${window.innerWidth} x ${window.innerHeight}px
+Device Pixel Ratio: ${window.devicePixelRatio}
+Device Memory: ${"deviceMemory" in navigator ? navigator.deviceMemory : "Not available"} GB
+Online: ${navigator.onLine}
+Language: ${navigator.language}
+Timezone: ${Intl.DateTimeFormat().resolvedOptions().timeZone}
+Connection: ${"connection" in navigator ? JSON.stringify(navigator.connection) : "Not available"}
+User Activation: ${"userActivation" in navigator ? JSON.stringify(navigator.userActivation) : "Not available"}
+`);
+
+        if ("gpu" in navigator) {
+
+            // @ts-ignore
+            navigator.gpu.requestAdapter()
+                .then(adapter => adapter ? adapter.requestDevice() : null)
+                .then(device => {
+                    if (device) {
+                        const adapterInfo = device.adapterInfo;
+                        if (adapterInfo) {
+                            sendLogToServer("internal", [`WebGPU adapter info`, {
+                                vendor: adapterInfo.vendor,
+                                architecture: adapterInfo.architecture,
+                                device: adapterInfo.device,
+                                description: adapterInfo.description,
+                                features: adapterInfo.features,
+                                limits: adapterInfo.limits
+                            }]);
+                        }
+                    }
+                });
+        }
+    }
+    catch (e) {
+        // silently fail
+        sendLogToServer("error", `Error during initial log: ${e.message}`);
+    }
+
+    window.addEventListener('error', (event) => {
+        const errorMessage = event.error ? event.error.stack || event.error.message : event.message;
+        sendLogToServer("error", errorMessage);
+    });
+    window.addEventListener('unhandledrejection', (event) => {
+        const reason = event.reason ? event.reason.stack || event.reason.message : "Unhandled rejection without reason";
+        sendLogToServer("error", `Unhandled promise rejection: ${reason}`);
+    });
+    window.addEventListener('beforeunload', () => {
+        sendLogToServer("internal", "Page is unloading");
+    });
+    document.addEventListener('visibilitychange', () => {
+        console.log("Visibility changed:", document.visibilityState);
+        if (document.visibilityState === 'hidden') {
+            sendLogToServer("internal", "Page is hidden");
+        }
+        else if (document.visibilityState === 'visible') {
+            sendLogToServer("internal", "Page is visible again");
+        }
+        else {
+            sendLogToServer("internal", `Page visibility changed to ${document.visibilityState}`);
+        }
+    });
+    window.addEventListener("focus", () => {
+        sendLogToServer("internal", "Page gained focus");
+    });
+    window.addEventListener("blur", () => {
+        sendLogToServer("internal", "Page lost focus");
+    });
+    window.addEventListener('load', () => {
+        sendLogToServer("internal", "Page fully loaded");
+    });
+    window.addEventListener('DOMContentLoaded', () => {
+        sendLogToServer("internal", "DOM fully loaded and parsed");
+    });
+    window.addEventListener('online', () => {
+        sendLogToServer("internal", "Browser is online");
+    });
+    window.addEventListener('offline', () => {
+        sendLogToServer("warn", "Browser is offline");
+    });
+    window.addEventListener('resize', () => {
+        sendLogToServer("internal", `Window resized to ${window.innerWidth}x${window.innerHeight}px`);
+    });
+    window.addEventListener('orientationchange', () => {
+        sendLogToServer("internal", `Orientation changed to ${screen.orientation.type}`);
+    });
+    window.addEventListener('fullscreenchange', () => {
+        if (document.fullscreenElement) {
+            sendLogToServer("internal", "Entered fullscreen mode");
+        } else {
+            sendLogToServer("internal", "Exited fullscreen mode");
+        }
+    });
+
+
+    // url change event
+    window.addEventListener('hashchange', () => {
+        sendLogToServer("internal", `URL hash changed to ${location.hash}`);
+    });
+    window.addEventListener('popstate', () => {
+        sendLogToServer("internal", `History state changed: ${JSON.stringify(history.state)}`);
+    });
+
+
+
+}
+
+
+
+
+
+// #region copied from common/logger.js
+
+
+/**
+ * Stringifies a log message, handling circular references and formatting.
+ * @param {any} log
+ * @param {Set<any>} [seen]
+ */
+function stringifyLog(log, seen = new Set(), depth = 0) {
+
+    const isServer = typeof window === "undefined";
+    const stringify_limits = {
+        string: isServer ? 100_000 : 2000,
+        object_keys: isServer ? 100 : 200,
+        array_items: isServer ? 2_000 : 100,
+    }
+
+    if (typeof log === "string") {
+        if (log.length > stringify_limits.string) log = `${log.slice(0, stringify_limits.string)}... <truncated ${log.length - stringify_limits.string} characters>`;
+        return log;
+    }
+    if (typeof log === "number" || typeof log === "boolean") {
+        return String(log);
+    }
+    if (log === null) {
+        return "null";
+    }
+    if (log === undefined) {
+        return "undefined";
+    }
+    if (typeof log === "function") {
+        return "<function>";
+    }
+
+    if (seen.has(log)) return "<circular>";
+
+    if (Array.isArray(log)) {
+        seen.add(log);
+        return stringifyArray(log);
+    }
+    if (typeof log === "object") {
+        seen.add(log);
+        // const str = JSON.stringify(log, (key, value) => {
+        //     if (typeof value === "function") return "<function>";
+        //     if (typeof value === "string") return stringifyLog(value, seen, depth + 1);
+        //     if (typeof value === "object") {
+        //         if (seen.has(value)) return "<circular>";
+        //         seen.add(value);
+        //     }
+        //     return value;
+        // });
+        // return str;
+        const keys = Object.keys(log);
+        let res = "{";
+        for (let i = 0; i < keys.length; i++) {
+            const key = keys[i];
+            let value = log[key];
+
+            if (typeof value === "number") {
+                // clamp precision for numbers
+                value = Number(value.toFixed(6));
+            }
+            let str = stringifyLog(value, seen, depth + 1);
+            if (typeof value === "object") {
+                if (Array.isArray(value)) {
+                    str = `[${str}]`;
+                }
+            }
+            else if (typeof value === "string") {
+                str = `"${str}"`;
+            }
+            if (i > 0) res += ", ";
+            res += `"${key}":${str}`;
+        }
+        res += "}";
+        return res;
+        // let entries = Object.entries(log).map(([key, value], index) => {
+        //     if (index > stringify_limits.object_keys) return `"${key}": <truncated>`;
+        //     return `"${key}": ${stringifyLog(value, seen, depth + 1)}`;
+        // });
+        // return `{ ${entries.join(", ")} }`;
+    }
+    return String(log);
+
+    function stringifyArray(arr) {
+        let res = "";
+        for (let i = 0; i < arr.length; i++) {
+            let entry = arr[i];
+            if (res && i > 0) res += ", ";
+            if (i > stringify_limits.array_items) {
+                res += "<truncated " + (arr.length - i) + ">";
+                break;
+            }
+            res += stringifyLog(entry, seen, depth + 1);
+        }
+        return res;
+    }
+}
+

package/plugins/vite/logger.js

@@ -0,0 +1,101 @@
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { captureLogMessage, patchConsoleLogs } from '../common/logger.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+
+/**
+ * write logs to local file
+ * @param {import('../types/userconfig.js').userSettings} userSettings
+ * @returns {import('vite').Plugin | null}
+ */
+export const needleLogger = (command, config, userSettings) => {
+
+    if (userSettings?.disableLogging === true) {
+        return null;
+    }
+
+    patchConsoleLogs();
+    captureLogMessage("server", "info", "Vite started with command \"" + command + "\" in " + __dirname, null);
+
+    return {
+        name: "needle:logger",
+        enforce: 'pre',
+        configureServer(server) {
+            logRequests(server);
+        },
+        configurePreviewServer(server) {
+            logRequests(server);
+        },
+        transformIndexHtml: {
+            order: 'pre',
+            handler(html, ctx) {
+                // inject client logger script during development
+                if (command === 'serve') {
+                    const file = path.join(__dirname, 'logger.client.js');
+                    if (existsSync(file)) {
+                        const scriptContent = readFileSync(file, 'utf8');
+                        return [
+                            {
+                                tag: 'script',
+                                attrs: {
+                                    type: 'module',
+                                },
+                                children: scriptContent,
+                                injectTo: 'head-prepend',
+                            },
+                        ];
+                    }
+                }
+            },
+        },
+    }
+}
+
+
+/**
+ * Logs HTTP requests to the console.
+ * This function is used in the Vite server to log incoming HTTP requests.
+ * @param {import('vite').PreviewServer | import('vite').ViteDevServer} server
+ */
+function logRequests(server, log_http_requests = false) {
+    /**
+     * Logs a message to the server console and captures it.
+     * @type {Map<import("vite").WebSocket, {id:string}>}
+     */
+    const connectedClients = new Map();
+    let index = 0;
+
+    if ("ws" in server) {
+        // Clent connections
+        server.ws.on('connection', (socket, request) => {
+            const clientId = String(index++);
+            connectedClients.set(socket, { id: clientId });
+            const ip = request.socket.remoteAddress || 'unknown';
+            captureLogMessage("server", "connection", `New websocket connection established ${clientId} from ${ip}`, clientId);
+            socket.on('close', () => {
+                captureLogMessage("server", "connection", `Websocket connection closed ${clientId}`, clientId);
+            });
+        });
+        // Client log messages via websocket
+        server.ws.on('needle:client-log', async (data, client) => {
+            if (!data || !data.level || !data.message) {
+                console.warn("Received empty log data, ignoring");
+                return;
+            }
+            const socket = client.socket;
+            const info = connectedClients.get(socket);
+            captureLogMessage("client", data.level, data.message, info ? info.id : null);
+        });
+    }
+    // Log HTTP requests
+    if (log_http_requests) {
+        server.middlewares.use((req, res, next) => {
+            captureLogMessage("client-http", "info", [req.method, req.url], null);
+            next();
+        });
+    }
+}

package/plugins/vite/materialx.js

@@ -0,0 +1,32 @@
+import { existsSync } from 'fs';
+
+const materialx_packagejson_path = "node_modules/@needle-tools/materialx/package.json";
+const materialx_import_chunk = `
+import { useNeedleMaterialX } from "@needle-tools/materialx/needle";
+useNeedleMaterialX();
+`
+
+/**
+ * Vite plugin to automatically setup the MaterialX loader for Needle Engine.
+ * @param {string} command 
+ * @param {object} config
+ * @param {import('../types/userconfig.js').userSettings} userSettings
+ * @returns {import('vite').Plugin}
+ */
+export const needleMaterialXLoader = (command, config, userSettings) => {
+
+    return {
+        name: 'needle-materialx-loader',
+        transform: (code, id) => {
+            if (id.endsWith("src/main.ts")) {
+                if (userSettings?.loadMaterialX !== false && existsSync(materialx_packagejson_path)) {
+                    if (!code.includes("@needle-tools/materialx")) {
+                        console.log("[needle-materialx-loader] Adding MaterialX import to main.ts");
+                        code = materialx_import_chunk + "\n" + code;
+                    }
+                }
+            }
+            return code;
+        }
+    }
+}

package/plugins/vite/transform.js

@@ -3,6 +3,7 @@
 
 /** 
  * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin[]}
  */
 export const needleTransformCode = (command, config, userSettings) => {