@needle-tools/engine 5.1.0-alpha.1 → 5.1.0-canary.30cc545

package/plugins/dts-generator/manifest.types.js

@@ -0,0 +1,174 @@
+// @ts-check
+/**
+ * Type tables and components.needle.json manifest loader.
+ *
+ * Knows about primitive TS types, known Three.js types, known Needle Engine
+ * types, and how to resolve field types from the manifest.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** Primitive TS type strings that can safely appear in an ambient declaration. */
+export const PRIMITIVE_TYPES = new Set(["number", "string", "boolean"]);
+
+/**
+ * Known Three.js types → import("three").TypeName
+ * @type {Record<string, string>}
+ */
+export const THREE_TYPES = {
+    Color: `import("three").Color`,
+    ColorRepresentation: `import("three").ColorRepresentation`,
+    Euler: `import("three").Euler`,
+    Texture: `import("three").Texture`,
+    // Materials
+    Material: `import("three").Material`,
+    MeshStandardMaterial: `import("three").MeshStandardMaterial`,
+    // Objects
+    Object3D: `import("three").Object3D`,
+    Mesh: `import("three").Mesh`,
+    SkinnedMesh: `import("three").SkinnedMesh`,
+    // Other
+    Vector2: `import("three").Vector2`,
+    Vector3: `import("three").Vector3`,
+    Vector4: `import("three").Vector4`,
+    Matrix3: `import("three").Matrix3`,
+    Matrix4: `import("three").Matrix4`,
+    Quaternion: `import("three").Quaternion`,
+    // Animation
+    AnimationClip: `import("three").AnimationClip`,
+    AnimationMixer: `import("three").AnimationMixer`,
+};
+
+/**
+ * Known Needle Engine types → import("@needle-tools/engine").TypeName
+ * @type {Record<string, string>}
+ */
+export const NEEDLE_TYPES = {
+    AssetReference: `import("@needle-tools/engine").AssetReference`,
+    EventList: `import("@needle-tools/engine").EventList`,
+    GameObject: `import("@needle-tools/engine").GameObject`,
+    LookAtConstraint: `import("@needle-tools/engine").LookAtConstraint`,
+    RGBAColor: `import("@needle-tools/engine").RGBAColor`,
+    RenderTexture: `import("@needle-tools/engine").RenderTexture`,
+    Renderer: `import("@needle-tools/engine").Renderer`,
+    Rigidbody: `import("@needle-tools/engine").Rigidbody`,
+    Sprite: `import("@needle-tools/engine").Sprite`,
+    Vec2: `import("@needle-tools/engine").Vec2`,
+};
+
+/**
+ * Map a single non-array, non-primitive type token to its TS representation.
+ * Returns null if unknown.
+ * @param {string} token
+ * @returns {string | null}
+ */
+function mapKnownType(token) {
+    if (token in THREE_TYPES) return THREE_TYPES[token];
+    if (token in NEEDLE_TYPES) return NEEDLE_TYPES[token];
+    return null;
+}
+
+/**
+ * Convert a manifest type string to a safe ambient TS type.
+ * Primitives and known Three.js/Needle types are resolved precisely.
+ * For unknown types on a manifest component, falls back to
+ * `import("@needle-tools/engine").ComponentName["fieldName"]`.
+ * Truly unresolvable types → "unknown".
+ *
+ * @param {string} typeStr
+ * @param {string} [componentName]  The manifest component class name (enables indexed-access fallback)
+ * @param {string} [fieldName]      The field name on that component
+ * @returns {string}
+ */
+export function manifestTypeToTs(typeStr, componentName, fieldName) {
+    const parts = typeStr.split(" | ").map(p => p.trim());
+    const safeParts = parts.map(p => {
+        if (p === "undefined" || p === "null") return p;
+        const arrayMatch = p.match(/^(number|string|boolean)\[\]$/);
+        if (arrayMatch) return p;
+        if (PRIMITIVE_TYPES.has(p)) return p;
+        const arrayTypeMatch = p.match(/^(\w+)\[\]$/);
+        if (arrayTypeMatch) {
+            const base = arrayTypeMatch[1];
+            const mapped = mapKnownType(base);
+            if (mapped) return `${mapped}[]`;
+        }
+        const known = mapKnownType(p);
+        if (known) return known;
+        return null;
+    });
+    if (safeParts.every(p => p !== null)) {
+        return /** @type {string[]} */ (safeParts).join(" | ");
+    }
+    if (componentName && fieldName) {
+        return `import("@needle-tools/engine").${componentName}["${fieldName}"]`;
+    }
+    return "unknown";
+}
+
+/**
+ * Load components.needle.json and build a lookup:
+ *   componentName → Map<fieldName, tsType>
+ * Inherited fields are flattened (inheritedFrom chain is resolved).
+ *
+ * @returns {Map<string, Map<string, string>>}
+ */
+export function loadComponentsManifest() {
+    /** @type {Map<string, Map<string, string>>} */
+    const manifest = new Map();
+    const manifestPath = join(__dirname, "../../components.needle.json");
+    if (!existsSync(manifestPath)) return manifest;
+    try {
+        /** @type {Array<{name: string, inheritedFrom?: string, children?: Array<{name: string, kind: string, type: string}>}>} */
+        const entries = JSON.parse(readFileSync(manifestPath, "utf8"));
+
+        /** @type {Map<string, Map<string, string>>} */
+        const ownFields = new Map();
+        /** @type {Map<string, string>} */
+        const inheritedFrom = new Map();
+        for (const entry of entries) {
+            if (!entry.name) continue;
+            inheritedFrom.set(entry.name, entry.inheritedFrom || "");
+            /** @type {Map<string, string>} */
+            const fields = new Map();
+            if (Array.isArray(entry.children)) {
+                for (const child of entry.children) {
+                    if (child.kind === "property" && child.name && child.type) {
+                        fields.set(child.name, manifestTypeToTs(child.type, entry.name, child.name));
+                    }
+                }
+            }
+            ownFields.set(entry.name, fields);
+        }
+
+        /** @param {string} name @returns {Map<string, string>} */
+        function resolveFields(name) {
+            if (manifest.has(name)) return /** @type {Map<string, string>} */ (manifest.get(name));
+            const own = ownFields.get(name) ?? new Map();
+            const parent = inheritedFrom.get(name);
+            if (parent && ownFields.has(parent)) {
+                const parentFields = resolveFields(parent);
+                const merged = new Map([...parentFields, ...own]);
+                manifest.set(name, merged);
+                return merged;
+            }
+            manifest.set(name, own);
+            return own;
+        }
+
+        for (const name of ownFields.keys()) {
+            resolveFields(name);
+        }
+    } catch (e) {
+        console.warn("[needle:dts-generator] Failed to load components.needle.json:", (/** @type {any} */ (e))?.message ?? e);
+    }
+    return manifest;
+}
+
+/** @type {Map<string, Map<string, string>>} */
+export const componentsManifest = loadComponentsManifest();

package/plugins/types/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./needleConfig.js";
 export * from './userconfig.js';
-export * from "./webmanifest.js";
+export * from "./webmanifest.js";
+export * from "./needle-bindings.js";

package/plugins/types/needle-bindings.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Ambient module declaration for `needle:bindings`.
+ *
+ * The `SceneData` interface is empty by default.
+ * When the `needle:dts-generator` Vite plugin is active it writes
+ * `src/generated/needle-bindings.d.ts` into the user's project, which
+ * augments this interface with the actual component bindings extracted
+ * from the project's GLB files at build time.
+ *
+ * @example
+ * import type { SceneData } from "@needle-tools/engine";
+ * type MyBallData = SceneData["RedBall"]["MyBall"];
+ */
+declare module "needle:bindings" {
+    interface SceneData {
+        /** Fallback for nodes not present in the generated bindings — no type info, but no crash. */
+        [nodeName: string]: Record<string, unknown> | undefined;
+    }
+}

package/plugins/types/userconfig.d.ts

@@ -26,10 +26,17 @@ export type userSettings = {
     noCopy?: boolean;
     /** When enabled the needle-engine include directory will be copied */
     copyIncludesFromEngine?: boolean;
-    /** set to false to tree-shake rapier physics engine to the reduce bundle size */
+
+
+    /** Set to `false` to prevent the Rapier physics engine from loading.  
+     * NOTE: by default Needle Engine uses dynamic loading of the Rapier physics engine. This means that the Rapier code is only loaded when a physics component is used in the scene.
+     */
     useRapier?: boolean;
-    /** experimental */
+    /** Set to `false` to prevent postprocessing effects from loading.  
+     * NOTE: by default Needle Engine uses dynamic loading of postprocessing modules. This means that the postprocessing code is only loaded when a postprocessing effect is used in the scene.
+     */
     usePostprocessing?: boolean;
+
     noDependencyWatcher?: boolean;
     /** set to false to suppress editor-sync package installation and connection */
     dontInstallEditor?: boolean;

package/plugins/vite/dts-generator.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @param {"build" | "serve"} _command  Vite command (unused — runs in both modes)
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} _config
+ * @param {import('../types').userSettings} [_userSettings]
+ * @returns {import('vite').Plugin}
+ */
+export function needleDtsGenerator(_command: "build" | "serve", _config: import("../types/needleConfig").needleMeta | null | undefined, _userSettings?: import("../types").userSettings): import("vite").Plugin;

package/plugins/vite/dts-generator.js

@@ -0,0 +1,157 @@
+// @ts-check
+/**
+ * Vite plugin: needle:dts-generator
+ *
+ * Thin wrapper around plugins/dts-generator/index.js.
+ * Regenerates `needle-bindings.d.ts` on startup and whenever a .glb / .gltf
+ * file changes in the assets directory.
+ *
+ * The generated file is written to `{codegenDirectory}/needle-bindings.d.ts`
+ * (falls back to `src/generated/needle-bindings.d.ts`).
+ *
+ * Usage — the plugin is already wired into needlePlugins(). To use standalone:
+ *
+ *   import { needleDtsGenerator } from "@needle-tools/engine/plugins/vite/dts-generator.js";
+ *   // in vite.config.js plugins array:
+ *   needleDtsGenerator(command, needleConfig, userSettings)
+ */
+
+import { join, resolve } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { tryLoadProjectConfig } from './config.js';
+import { generateBindingsDts } from '../dts-generator/index.js';
+import { needleLog } from './logging.js';
+
+/**
+ * Ensure `.vscode/settings.json` references the generated `needle-html-data.json`
+ * so VS Code provides `data-bind-needle` completions in HTML files automatically.
+ * Only adds the entry if it isn't already present — never overwrites other settings.
+ *
+ * @param {string} projectRoot
+ * @param {string} htmlDataPath  Absolute path to the generated needle-html-data.json
+ */
+function ensureVscodeHtmlCustomData(projectRoot, htmlDataPath) {
+    const vscodeDir = join(projectRoot, ".vscode");
+    const settingsPath = join(vscodeDir, "settings.json");
+
+    // Relative path from project root for portability
+    const relPath = htmlDataPath.replace(projectRoot + "/", "").replace(projectRoot + "\\", "");
+
+    /** @type {Record<string, unknown>} */
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+        } catch (_e) { /* malformed JSON — leave settings empty, will add key */ }
+    }
+
+    const key = "html.customData";
+    const existing = Array.isArray(settings[key]) ? /** @type {string[]} */ (settings[key]) : [];
+    if (existing.includes(relPath)) return; // already registered
+
+    settings[key] = [...existing, relPath];
+
+    mkdirSync(vscodeDir, { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+    needleLog("needle:dts-generator", `registered HTML completions in .vscode/settings.json`);
+}
+
+/**
+ * @param {"build" | "serve"} _command  Vite command (unused — runs in both modes)
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} _config
+ * @param {import('../types').userSettings} [_userSettings]
+ * @returns {import('vite').Plugin}
+ */
+export function needleDtsGenerator(_command, _config, _userSettings) {
+    let projectRoot = process.cwd();
+
+    function resolveCodegenDir() {
+        const projectConfig = tryLoadProjectConfig();
+        return projectConfig?.codegenDirectory
+            ? resolve(projectRoot, projectConfig.codegenDirectory)
+            : join(projectRoot, "src", "generated");
+    }
+
+    function resolveOutputPath() {
+        return join(resolveCodegenDir(), "needle-bindings.d.ts");
+    }
+
+    function resolveAssetsDir() {
+        const projectConfig = tryLoadProjectConfig();
+        return projectConfig?.assetsDirectory
+            ? resolve(projectRoot, projectConfig.assetsDirectory)
+            : join(projectRoot, "assets");
+    }
+
+    /** @type {import('vite').ViteDevServer | undefined} */
+    let devServer;
+
+    async function run() {
+        try {
+            const assetsDir = resolveAssetsDir();
+            const outputPath = resolveOutputPath();
+            const codegenDir = resolveCodegenDir();
+            const count = await generateBindingsDts({ assetsDir, outputPath, projectRoot, codegenDir });
+            // Always register HTML custom data — the file is written on every run
+            const htmlDataPath = join(codegenDir, "needle-html-data.json");
+            ensureVscodeHtmlCustomData(projectRoot, htmlDataPath);
+            if (count !== false) {
+                needleLog("needle:dts-generator", `${count} binding(s) → ${outputPath.replace(process.cwd(), ".")}`);
+                if (devServer) {
+                    const hot = devServer.hot ?? devServer.ws;
+                    hot.send({ type: "full-reload", path: "*" });
+                }
+            } else {
+                needleLog("needle:dts-generator", `up-to-date`);
+            }
+        } catch (err) {
+            needleLog("needle:dts-generator", "Failed: " + (/** @type {any} */ (err)?.message ?? err));
+        }
+    }
+
+    return {
+        name: "needle:dts-generator",
+
+        /** @param {import('vite').ResolvedConfig} config */
+        configResolved(config) {
+            projectRoot = config.root ?? process.cwd();
+        },
+
+        buildStart() {
+            return run();
+        },
+
+        /** @param {import('vite').ViteDevServer} server */
+        configureServer(server) {
+            devServer = server;
+
+            // Watch assets directory for GLB/glTF changes and regenerate
+            const assetsDir = resolveAssetsDir();
+            server.watcher.add(assetsDir);
+
+            // Also watch files that determine which GLBs are entrypoints
+            const indexHtmlPath = join(projectRoot, "index.html");
+            const genJsPath = join(resolveCodegenDir(), "gen.js");
+            server.watcher.add(indexHtmlPath);
+            server.watcher.add(genJsPath);
+
+            server.watcher.on("change", (file) => {
+                if (
+                    (/\.(glb|gltf)$/i.test(file) && file.startsWith(assetsDir)) ||
+                    file === indexHtmlPath ||
+                    file === genJsPath
+                ) {
+                    run();
+                }
+            });
+            server.watcher.on("add", (file) => {
+                if (/\.(glb|gltf)$/i.test(file) && file.startsWith(assetsDir)) {
+                    run();
+                }
+            });
+
+            // Return post-hook so Vite awaits the initial run before printing "ready"
+            return () => run();
+        },
+    };
+}

package/plugins/vite/index.d.ts

@@ -26,6 +26,7 @@
  */
 export function needlePlugins(command: "build" | "serve", config?: import("../types/needleConfig").needleMeta | null | undefined, userSettings?: import("../types/index.js").userSettings): Promise<import("vite").Plugin[]>;
 export { needleAI } from "./ai.js";
+export { needleDtsGenerator } from "./dts-generator.js";
 export { needleAsap } from "./asap.js";
 export { needleDefines } from "./defines.js";
 export { needleBuildPipeline } from "./build-pipeline.js";

package/plugins/vite/index.js

@@ -1,6 +1,9 @@
 import { needleAI } from "./ai.js";
 export { needleAI } from "./ai.js";
 
+import { needleDtsGenerator } from "./dts-generator.js";
+export { needleDtsGenerator } from "./dts-generator.js";
+
 import { needleAsap } from "./asap.js";
 export { needleAsap } from "./asap.js";
 
@@ -126,6 +129,7 @@ export async function needlePlugins(command, config = undefined, userSettings =
     userSettings = { ...defaultUserSettings, ...userSettings };
 
     const array = [
+        needleDtsGenerator(command, config, userSettings),
         needleAI(command, config, userSettings),
         needleLogger(command, config, userSettings),
         needleDefines(command, config, userSettings),

package/plugins/vite/logging.js

@@ -97,8 +97,8 @@ export function needleLog(pluginName, message, level = 'log', options = undefine
             ? (dimBody ? leveledBody.split('\n').map(l => colors.dim(l)).join('\n') : leveledBody)
             : "";
         const payloadCore = emitHeader
-            ? (body.length > 0 ? `${header}\n${body}\n` : `${header}\n`)
-            : (body.length > 0 ? `${body}\n` : "");
+            ? (body.length > 0 ? `${header}\n${body}` : `${header}`)
+            : (body.length > 0 ? `${body}` : "");
         const payload = leadingNewline ? `\n${payloadCore}` : payloadCore;
         log(payload);
         return;

package/plugins/vite/reload.js

@@ -172,8 +172,9 @@ async function handleReload({ file, server, modules: _modules, read, buildDirect
     // Check if codegen files actually changed their content
     // this will return false if its the first update
     // 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) {
+    if (shouldCheckIfContentChanged && !file.endsWith(".d.ts") && !file.endsWith("needle-html-data.json")) {
         if (reloadIsScheduled) {
             return [];
         }

package/src/engine/api.ts

@@ -336,6 +336,9 @@ export { loadPMREM } from "./engine_pmrem.js";
 /** Scene lighting data and environment configuration */
 export * from "./engine_scenelighting.js";
 
+/** Typed scene data proxy — maps SceneData interface to live component instances */
+export { getSceneData, needle } from "./engine_scenedata.js";
+
 
 // ============================================================================
 // SERIALIZATION
@@ -436,4 +439,15 @@ export * from "./webcomponents/needle-engine.loading.js";
  * XR API: NeedleXRSession, NeedleXRController, XRRig.
  * @see {@link https://engine.needle.tools/docs/xr.html | XR Documentation}
  */
-export * from "./xr/api.js"
+export * from "./xr/api.js"
+
+/**
+ * HTML ↔ 3D component binding types, similar to Svelte's `PageData`.
+ * `SceneData` is a nested interface augmented per-project by the `needle:dts-generator`
+ * Vite plugin — it maps scene node names to their components and typed fields.
+ *
+ * @example
+ * import type { SceneData } from "@needle-tools/engine";
+ * type OrbitSettings = SceneData["Camera"]["OrbitControls"];
+ */
+export type { SceneData } from "needle:bindings";

package/src/engine/debug/debug_environment.ts

@@ -15,7 +15,7 @@ export function isDevEnvironment(): boolean {
     let res = isLocalNetwork();
     if (!res) {
         // is stackblitz?
-        res = window.location.hostname.endsWith(".local-credentialless.webcontainer.io");
+        res = typeof window !== "undefined" && window.location.hostname.endsWith(".local-credentialless.webcontainer.io");
     }
     _cachedDevEnvironment = res;
     return res;

package/src/engine/engine_application.ts

@@ -31,12 +31,14 @@ export function internalOnUserInputRegistered() {
     userInteractionCallbacks.length = 0;
     copy.forEach(cb => cb());
 }
-document.addEventListener('mousedown', internalOnUserInputRegistered);
-document.addEventListener('pointerup', internalOnUserInputRegistered);
-document.addEventListener('click', internalOnUserInputRegistered);
-document.addEventListener('dragstart', internalOnUserInputRegistered);
-document.addEventListener('touchend', internalOnUserInputRegistered);
-document.addEventListener('keydown', internalOnUserInputRegistered);
+if (typeof document !== "undefined") {
+    document.addEventListener('mousedown', internalOnUserInputRegistered);
+    document.addEventListener('pointerup', internalOnUserInputRegistered);
+    document.addEventListener('click', internalOnUserInputRegistered);
+    document.addEventListener('dragstart', internalOnUserInputRegistered);
+    document.addEventListener('touchend', internalOnUserInputRegistered);
+    document.addEventListener('keydown', internalOnUserInputRegistered);
+}
 
 
 // User Activation should be available across browsers since November 2023 https://developer.mozilla.org/en-US/docs/Web/API/UserActivation

package/src/engine/engine_constants.ts

@@ -1,6 +1,8 @@
 import { getParam } from "../engine/engine_utils.js";
 const debug = getParam("debugdefines");
 
+// #region global defines
+
 // We jump through hoops like this to support 3 cases:
 // 1) Vanilla js or angular js where global defines are not guaranteed to be made
 // 2) Vite where global defines are made, vite defines are also automatically set to globalThis
@@ -11,11 +13,6 @@ tryEval(`if(!globalThis["NEEDLE_ENGINE_GENERATOR"]) globalThis["NEEDLE_ENGINE_GE
 tryEval(`if(!globalThis["NEEDLE_PROJECT_BUILD_TIME"]) globalThis["NEEDLE_PROJECT_BUILD_TIME"] = "unknown";`);
 tryEval(`if(!globalThis["NEEDLE_PUBLIC_KEY"]) globalThis["NEEDLE_PUBLIC_KEY"] = "unknown";`);
 
-declare const NEEDLE_ENGINE_VERSION: string
-declare const NEEDLE_ENGINE_GENERATOR: string;
-declare const NEEDLE_PROJECT_BUILD_TIME: string;
-declare const NEEDLE_PUBLIC_KEY: string;
-
 // Make sure to wrap the new global this define in underscores to prevent the bundler from replacing it with the actual value
 tryEval(`globalThis["__NEEDLE_ENGINE_VERSION__"] = "` + NEEDLE_ENGINE_VERSION + `";`);
 tryEval(`globalThis["__NEEDLE_ENGINE_GENERATOR__"] = "` + NEEDLE_ENGINE_GENERATOR + `";`);
@@ -50,4 +47,12 @@ function tryEval(str: string) {
         if (debug)
             console.error(err);
     }
-}
+}
+
+
+
+// #region treeshake flags
+// globalThis fallbacks for vanilla JS environments (no bundler define)
+globalThis["NEEDLE_USE_RAPIER"] = globalThis["NEEDLE_USE_RAPIER"] !== undefined ? globalThis["NEEDLE_USE_RAPIER"] : true;
+globalThis["NEEDLE_USE_POSTPROCESSING"] = globalThis["NEEDLE_USE_POSTPROCESSING"] !== undefined ? globalThis["NEEDLE_USE_POSTPROCESSING"] : true;
+// #endregion treeshake flags

package/src/engine/engine_context.ts

@@ -37,6 +37,8 @@ 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 { getTempColor, logHierarchy } from './engine_three_utils.js';
 import { Time } from './engine_time.js';
 import { patchTonemapping } from './engine_tonemapping.js';
@@ -475,6 +477,33 @@ export class Context implements IContext {
 	 * The main camera of the scene - this camera is used for rendering   
 	 * Use `setCurrentCamera` for updating the main camera.
 	 */
+	/**
+	 * Typed proxy providing direct access to scene components by node and component name.
+	 * Types are auto-generated from your GLB assets by the `needle:dts-generator` Vite plugin
+	 * and written to `src/generated/needle-bindings.d.ts` on every dev-server start and GLB change.
+	 *
+	 * Each property access traverses the live scene graph on demand — no caching, always fresh.
+	 * This is a convenience shorthand for `getComponent` lookups; the same result can be
+	 * achieved manually via `scene.getObjectByName(name)` + `getComponent(node, Type)`.
+	 *
+	 * @example
+	 * // Toggle auto-rotate on the orbit camera
+	 * ctx.sceneData.Camera.OrbitControls.autoRotate = true;
+	 *
+	 * @example
+	 * // Change the background color
+	 * ctx.sceneData.Camera.Camera.backgroundColor = new RGBAColor(1, 0, 0, 1);
+	 *
+	 * @example
+	 * // Equivalent manual approach (without sceneData)
+	 * const node = ctx.scene.getObjectByName("Camera");
+	 * const orbit = getComponent(node, OrbitControls);
+	 * if (orbit) orbit.autoRotate = true;
+	 */
+	get sceneData(): SceneData {
+		return getSceneData(this);
+	}
+
 	get mainCamera(): Camera {
 		if (this._mainCamera) {
 			return this._mainCamera;

package/src/engine/engine_context_registry.ts

@@ -1,6 +1,6 @@
 import { type IComponent, type IContext, type LoadedModel } from "./engine_types.js";
 
-const debug = typeof window !== undefined ? window.location.search.includes("debugcontext") : false;
+const debug = typeof window !== "undefined" ? window.location.search.includes("debugcontext") : false;
 
 /** The various events that can be dispatched by a Needle Engine {@link IContext} instance
  */

package/src/engine/engine_input.ts

@@ -1,6 +1,7 @@
 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 { getTempVector, getWorldQuaternion } from './engine_three_utils.js';
 import type { ButtonName, CursorTypeName, IGameObject, IInput, MouseButtonName, Vec2 } from './engine_types.js';
@@ -116,7 +117,7 @@ export declare type NEPointerEventIntersection = Intersection & { event?: NEPoin
  * @see {@link Input} for the input management system
  * @see {@link PointerType} for available pointer types
  */
-export class NEPointerEvent extends PointerEvent {
+export class NEPointerEvent extends PointerEventBase {
 
     /**
      * Spatial input data
@@ -242,7 +243,7 @@ export class NEPointerEvent extends PointerEvent {
         if (debug) console.warn("Stop propagation...", this.pointerId, this.pointerType)
     }
 }
-export class NEKeyboardEvent extends KeyboardEvent {
+export class NEKeyboardEvent extends KeyboardEventBase {
     source?: Event
     constructor(type: InputEvents, source: Event, init: KeyboardEventInit) {
         super(type, init)

package/src/engine/engine_license.ts

@@ -77,16 +77,18 @@ function invokeLicenseCheckResultChanged(result: boolean) {
 // #region Telemetry
 export namespace Telemetry {
 
-    window.addEventListener("error", (event: ErrorEvent) => {
-        sendError(Context.Current, "unhandled_error", event);
-    });
-    window.addEventListener("unhandledrejection", (event: PromiseRejectionEvent) => {
-        sendError(Context.Current, "unhandled_promise_rejection", {
-            message: event.reason?.message,
-            stack: event.reason?.stack,
-            timestamp: Date.now(),
+    if (typeof window !== "undefined") {
+        window.addEventListener("error", (event: ErrorEvent) => {
+            sendError(Context.Current, "unhandled_error", event);
         });
-    });
+        window.addEventListener("unhandledrejection", (event: PromiseRejectionEvent) => {
+            sendError(Context.Current, "unhandled_promise_rejection", {
+                message: event.reason?.message,
+                stack: event.reason?.stack,
+                timestamp: Date.now(),
+            });
+        });
+    }
 
     onInitialized((ctx => sendPageViewEvent(ctx)), { once: true });