@needle-tools/engine 5.1.0-alpha → 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/logger.client.js

@@ -99,8 +99,9 @@ if (import.meta && "hot" in import.meta) {
         //     unpatch();
         // }, 10_000);
 
+        const isMobile = /Android|iPhone|iPad|iPod/i.test(navigator.userAgent);
         const threshold = 100;
-        const devToolsArePotentiallyOpen = window.outerHeight - window.innerHeight > threshold || window.outerWidth - window.innerWidth > threshold;
+        const devToolsArePotentiallyOpen = !isMobile && (window.outerHeight - window.innerHeight > threshold || window.outerWidth - window.innerWidth > threshold);
         if (devToolsArePotentiallyOpen) {
             sendLogToServer("internal", "Console logging is disabled (devtools are open)");
         }
@@ -240,8 +241,8 @@ function stringifyLog(log, seen = /** @type {Set<unknown>} */ (new Set()), depth
     const isServer = typeof window === "undefined";
     const stringify_limits = {
         string: isServer ? 100_000 : 1_000,
-        object_keys: isServer ? 300 : 200,
-        object_depth: isServer ? 10 : 3,
+        object_keys: isServer ? 10 : 10,
+        object_depth: isServer ? 3 : 3,
         array_items: isServer ? 2_000 : 100,
     }
 

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_components.ts

@@ -10,6 +10,7 @@ import type { ComponentInit, Constructor, ConstructorConcrete, IComponent, IGame
 import { $componentName } from "./engine_types.js";
 import { getParam } from "./engine_utils.js";
 import { apply } from "./js-extensions/index.js";
+import { TypeStore } from "./engine_typestore.js";
 
 const COMPONENT_GUID_NAMESPACE = 'eff8ba80-635d-11ec-90d6-0242ac120003';
 
@@ -137,7 +138,7 @@ export function addComponent<T extends IComponent>(obj: Object3D, componentInsta
     if (componentInstance.guid === undefined || componentInstance.guid === "invalid") {
         componentInstance.guid = generateDeterministicComponentGuid(obj, componentInstance);
     }
-    if(init) componentInstance._internalInit(init);
+    if (init) componentInstance._internalInit(init);
     // Register the component - make sure to provide the component instance context (if assigned)
     registerComponent(componentInstance, componentInstance.context);
     return componentInstance;
@@ -170,10 +171,12 @@ function onGetComponent<T>(obj: Object3D | null | undefined, componentType: Cons
     }
     if (!(obj?.userData?.components)) return null;
     if (typeof componentType === "string") {
-        if (!didWarnAboutComponentAccess) {
+        const type = TypeStore.get(componentType);
+        if (!didWarnAboutComponentAccess && !type) {
             didWarnAboutComponentAccess = true;
             console.warn(`Accessing components by name is not supported.\nPlease use the component type instead. This may keep working in local development but it will fail when bundling your application.\n\nYou can import other modules your main module to get access to types\nor if you use npmdefs you can make types available globally using globalThis:\nhttps://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis`, componentType);
         }
+        if (type) componentType = type as Constructor<T>;
     }
 
     if (debugEnabled())
@@ -248,7 +251,7 @@ export function getComponents<T extends IComponent>(obj: Object3D, componentType
  * ```
  */
 export function getComponentInChildren<T extends IComponent>(obj: Object3D, componentType: Constructor<T>, includeInactive: boolean = false): T | null {
-    if (includeInactive === false && obj[activeInHierarchyFieldName] === false) return null; 
+    if (includeInactive === false && obj[activeInHierarchyFieldName] === false) return null;
     const res = getComponent(obj, componentType) as IComponent | null;
     if (includeInactive === false && (res?.enabled === false || res?.activeAndEnabled === false)) return null;
     if (res) return res as T;
@@ -361,7 +364,7 @@ export function findObjectOfType<T extends IComponent>(type: Constructor<T>, con
     if (!scene) return null;
 
     const res = getComponentInChildren(scene, type, includeInactive);
-    if(res) return res;
+    if (res) return res;
     return null;
 }
 

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
  */