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

package/plugins/vite/dts-generator.js

@@ -16,12 +16,24 @@
  *   needleDtsGenerator(command, needleConfig, userSettings)
  */
 
-import { join, resolve } from 'path';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync } from 'fs';
 import { tryLoadProjectConfig } from './config.js';
 import { generateBindingsDts } from '../dts-generator/index.js';
 import { needleLog } from './logging.js';
 
+// Two dirs up from plugins/vite/ → package root.
+// Use fileURLToPath so %7E and other URL-encoded characters in the path are decoded correctly.
+// realpathSync follows symlinks so the path is stable even in npm link / monorepo setups.
+import { fileURLToPath } from 'url';
+let _packageRoot = /** @type {string | null} */ (null);
+try {
+    _packageRoot = realpathSync(join(dirname(fileURLToPath(import.meta.url)), '..', '..'));
+} catch (_e) {
+    // If we can't resolve the package root (e.g. unusual install layout), the plugin
+    // will silently skip generation rather than crashing the dev server.
+}
+
 /**
  * Ensure `.vscode/settings.json` references the generated `needle-html-data.json`
  * so VS Code provides `data-bind-needle` completions in HTML files automatically.
@@ -60,9 +72,14 @@ function ensureVscodeHtmlCustomData(projectRoot, htmlDataPath) {
  * @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}
+ * @returns {import('vite').Plugin | null}
  */
 export function needleDtsGenerator(_command, _config, _userSettings) {
+
+    if(_userSettings?.dts?.enabled === false) {
+        return null;
+    }
+
     let projectRoot = process.cwd();
 
     function resolveCodegenDir() {
@@ -73,7 +90,11 @@ export function needleDtsGenerator(_command, _config, _userSettings) {
     }
 
     function resolveOutputPath() {
-        return join(resolveCodegenDir(), "needle-bindings.d.ts");
+        // Write to a .needle dotfolder at the package root.
+        // Not in the `files` allowlist → never npm-published.
+        // ../../.needle/ from plugins/types/ resolves correctly for both
+        // symlinked (js/package~/) and published (node_modules/@needle-tools/engine/) layouts.
+        return join(/** @type {string} */ (_packageRoot), ".needle", "generated", "needle-bindings.gen.d.ts");
     }
 
     function resolveAssetsDir() {
@@ -86,14 +107,24 @@ export function needleDtsGenerator(_command, _config, _userSettings) {
     /** @type {import('vite').ViteDevServer | undefined} */
     let devServer;
 
-    async function run() {
+    /** @type {Promise<void> | null} */
+    let _runInFlight = null;
+
+    function run() {
+        if (_runInFlight) return _runInFlight;
+        _runInFlight = _doRun().finally(() => { _runInFlight = null; });
+        return _runInFlight;
+    }
+
+    async function _doRun() {
         try {
+            if (!_packageRoot) return;
             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");
+            // HTML custom data sits next to the generated dts in .needle/generated/
+            const htmlDataPath = join(/** @type {string} */ (_packageRoot), ".needle", "generated", "needle-html-data.json");
             ensureVscodeHtmlCustomData(projectRoot, htmlDataPath);
             if (count !== false) {
                 needleLog("needle:dts-generator", `${count} binding(s) → ${outputPath.replace(process.cwd(), ".")}`);
@@ -102,7 +133,7 @@ export function needleDtsGenerator(_command, _config, _userSettings) {
                     hot.send({ type: "full-reload", path: "*" });
                 }
             } else {
-                needleLog("needle:dts-generator", `up-to-date`);
+                needleLog("needle:dts-generator", `up-to-date → ${outputPath.replace(process.cwd(), ".")}`);
             }
         } catch (err) {
             needleLog("needle:dts-generator", "Failed: " + (/** @type {any} */ (err)?.message ?? err));
@@ -118,7 +149,10 @@ export function needleDtsGenerator(_command, _config, _userSettings) {
         },
 
         buildStart() {
-            return run();
+            // In serve mode, the configureServer post-hook runs instead.
+            // Only run here for actual builds (no devServer).
+            if (!devServer) return run();
+            return undefined;
         },
 
         /** @param {import('vite').ViteDevServer} server */

package/plugins/vite/index.d.ts

@@ -19,12 +19,18 @@
  *        ],
  *    }
  * ```
- * @param {"build" | "serve"} command
- * @param {import('../types/needleConfig').needleMeta | null | undefined} config
+ * When used without arguments (e.g. in a SvelteKit `defineConfig({})` plain object),
+ * the command is resolved automatically from Vite's `configResolved` hook.
+ * ```js
+ * // SvelteKit — no command needed:
+ * export default defineConfig({ plugins: [sveltekit(), needlePlugins()] });
+ * ```
+ * @param {"build" | "serve" | undefined} [command]
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} [config]
  * @param {import('../types/index.js').userSettings} [userSettings]
  * @returns {Promise<import('vite').Plugin[]>}
  */
-export function needlePlugins(command: "build" | "serve", config?: import("../types/needleConfig").needleMeta | null | undefined, userSettings?: import("../types/index.js").userSettings): Promise<import("vite").Plugin[]>;
+export function needlePlugins(command?: "build" | "serve" | undefined, 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";

package/plugins/vite/index.js

@@ -116,12 +116,18 @@ const defaultUserSettings = {
  *        ],
  *    }
  * ```
- * @param {"build" | "serve"} command
- * @param {import('../types/needleConfig').needleMeta | null | undefined} config
+ * When used without arguments (e.g. in a SvelteKit `defineConfig({})` plain object),
+ * the command is resolved automatically from Vite's `configResolved` hook.
+ * ```js
+ * // SvelteKit — no command needed:
+ * export default defineConfig({ plugins: [sveltekit(), needlePlugins()] });
+ * ```
+ * @param {"build" | "serve" | undefined} [command]
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} [config]
  * @param {import('../types/index.js').userSettings} [userSettings]
  * @returns {Promise<import('vite').Plugin[]>}
  */
-export async function needlePlugins(command, config = undefined, userSettings = {}) {
+export async function needlePlugins(command = undefined, config = undefined, userSettings = {}) {
 
     if (!config) config = {}
 
@@ -168,14 +174,21 @@ export async function needlePlugins(command, config = undefined, userSettings =
     array.push(await editorConnection(command, config, userSettings, array));
     array.push(needleDependencyWatcher(command, config, userSettings));
 
-    // Ensure the process exits on SIGINT (Ctrl+C) since plugin timers/sockets can keep the event loop alive
-    if (command === "serve") {
+    // Ensure the process exits on SIGINT (Ctrl+C) since plugin timers/sockets can keep the event loop alive.
+    // If command is unknown at call time (e.g. SvelteKit plain defineConfig), defer to configResolved.
+    const registerSigint = () => {
         process.on('SIGINT', () => {
-            // Wait a moment to allow plugins to clean up if needed, then exit
-            setTimeout(() => {
-                console.debug('\nGoodbye!');
-                process.exit();
-            }, 1000);
+            setTimeout(() => { console.debug('\nGoodbye!'); process.exit(); }, 1000);
+        });
+    };
+    if (command === "serve") {
+        registerSigint();
+    } else if (command === undefined) {
+        array.push({
+            name: "needle:sigint",
+            configResolved(config) {
+                if (config.command === "serve") registerSigint();
+            }
         });
     }
 

package/plugins/vite/meta.js

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

package/plugins/vite/poster.d.ts

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

package/plugins/vite/poster.js

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

package/plugins/vite/reload.d.ts

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

package/plugins/vite/reload.js

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

package/src/engine/api.ts

@@ -450,4 +450,4 @@ export * from "./xr/api.js"
  * import type { SceneData } from "@needle-tools/engine";
  * type OrbitSettings = SceneData["Camera"]["OrbitControls"];
  */
-export type { SceneData } from "needle:bindings";
+export type { SceneData } from "needle-bindings";

package/src/engine/debug/debug_spatial_console.ts

@@ -12,13 +12,16 @@ import { onError } from "./debug_overlay.js";
 
 let _isActive = false;
 
-// enable the spatial console if we receive an error while in dev session and in XR
-onError((...args: any[]) => {
-    if (isDevEnvironment() && ContextRegistry.Current?.isInXR) {
-        enableSpatialConsole(true);
-        onLog("error", ...args);
-    }
-})
+/** @internal */
+export function initSpatialConsole() {
+    // enable the spatial console if we receive an error while in dev session and in XR
+    onError((...args: any[]) => {
+        if (isDevEnvironment() && ContextRegistry.Current?.isInXR) {
+            enableSpatialConsole(true);
+            onLog("error", ...args);
+        }
+    });
+}
 
 
 /** Enable a spatial debug console that follows the camera */

package/src/engine/engine_addressables.ts

@@ -567,7 +567,6 @@ class AddressableSerializer extends TypeSerializer {
     }
 
 }
-new AddressableSerializer();
 
 
 
@@ -703,7 +702,6 @@ export class ImageReferenceSerializer extends TypeSerializer {
         return undefined;
     }
 }
-new ImageReferenceSerializer();
 
 
 
@@ -772,4 +770,9 @@ export class FileReferenceSerializer extends TypeSerializer {
         return undefined;
     }
 }
-new FileReferenceSerializer();
+/** @internal */
+export function initAddressableSerializers() {
+    new AddressableSerializer();
+    new ImageReferenceSerializer();
+    new FileReferenceSerializer();
+}

package/src/engine/engine_context.ts

@@ -38,7 +38,7 @@ 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 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';
@@ -478,13 +478,14 @@ export class Context implements IContext {
 	 * 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.
+	 * Access your scene's full hierarchy, objects, and components directly by name — with full autocomplete.
+	 * Types are generated automatically from your GLB files when the dev server starts.
 	 *
-	 * 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)`.
+	 * You can store references to objects or components for later use.
+	 * Note that the scene hierarchy can change at runtime (e.g. when objects are added, removed, or re-parented),
+	 * in which case stored references may become stale.
+	 *
+	 * @experimental This API may change in future versions.
 	 *
 	 * @example
 	 * // Toggle auto-rotate on the orbit camera
@@ -493,12 +494,6 @@ export class Context implements IContext {
 	 * @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);
@@ -542,15 +537,32 @@ export class Context implements IContext {
 	connection: NetworkConnection;
 	/**  @deprecated AssetDatabase is deprecated */
 	assets: AssetDatabase;
-	/** The main light in the scene */
-	mainLight: ILight | null = null;
+
+	/** All registered lights in the scene, maintained by the Light component. 
+	 * @see mainLight for accessing the main directional light in the scene
+	 */
+	readonly lights = new Array<ILight>();
+
+	/** The brightest registered directional light, or null if none are registered
+	 * @see lights
+	 */
+	get mainLight(): ILight | null {
+		let best: ILight | null = null;
+		for (const light of this.lights) {
+			if (light.type !== "directional") continue;
+			if (!best || light.intensity > best.intensity) best = light;
+		}
+		return best;
+	}
+
 	/** @deprecated Use sceneLighting */
-	get rendererData() { return this.sceneLighting }
+	private get rendererData() { return this.sceneLighting }
+
 	/** Access the scene lighting manager to control lighting settings in the context */
-	sceneLighting: SceneLighting;
-	addressables: Addressables;
-	lightmaps: ILightDataRegistry;
-	players: PlayerViewManager;
+	readonly sceneLighting: SceneLighting;
+	readonly addressables: Addressables;
+	readonly lightmaps: ILightDataRegistry;
+	readonly players: PlayerViewManager;
 
 	/** Access the LODs manager to control LOD behavior in the context */
 	readonly lodsManager: LODsManager;
@@ -858,6 +870,8 @@ export class Context implements IContext {
 		this._onBeforeRenderListeners.clear();
 		this._onAfterRenderListeners.clear();
 
+		this.lights.length = 0;
+
 		if (!this.isManagedExternally) {
 			if (this.renderer) {
 				this.renderer.renderLists.dispose();

package/src/engine/engine_init.ts

@@ -1,18 +1,25 @@
+import { initAnimatorControllerSerializer } from "../engine-components/AnimatorController.js";
 import { initAnimationAutoplay } from "../engine-components/AnimationUtilsAutoplay.js";
 import { initCameraUtils } from "../engine-components/CameraUtils.js";
+import { initVolumeParameterSerializer } from "../engine-components/postprocessing/VolumeParameter.js";
 import { initSceneSwitcherAttributes } from "../engine-components/SceneSwitcher.js";
 import { initSkyboxAttributes } from "../engine-components/Skybox.js";
+import { initAddressableSerializers } from "./engine_addressables.js";
 import { initBuiltinTypes } from "./codegen/register_types.js";
 import { ensureAudioContextIsResumed } from "./engine_audio.js";
 import { initNeedleLoader } from "./engine_loaders.js";
+import { initBuiltinSerializers } from "./engine_serialization_builtin_serializer.js";
 import { initShims } from "./engine_shims.js";
 import { patchTonemapping } from "./engine_tonemapping.js";
 import { initCameraExtensions } from "./js-extensions/Camera.js";
 import { patchLayers } from "./js-extensions/Layers.js";
 import { initObject3DExtensions } from "./js-extensions/Object3D.js";
 import { initVectorExtensions } from "./js-extensions/Vector.js";
+import { SSR } from "./engine_ssr.js";
+import { initLicense } from "./engine_license.js";
 import { initWebComponents } from "./webcomponents/init.js";
 import { initPhysics } from "./engine_physics_rapier.js";
+import { initSpatialConsole } from "./debug/debug_spatial_console.js";
 import { initXR } from "./xr/init.js";
 
 let initialized = false;
@@ -28,10 +35,15 @@ let initialized = false;
  */
 export function initEngine() {
     if (initialized) return;
+    if (SSR) return;
     initialized = true;
 
     initWebComponents();
     initShims();
+    initBuiltinSerializers();
+    initAddressableSerializers();
+    initAnimatorControllerSerializer();
+    initVolumeParameterSerializer();
     patchTonemapping();
     patchLayers();
     initCameraExtensions();
@@ -46,4 +58,6 @@ export function initEngine() {
     initSceneSwitcherAttributes();
     initPhysics();
     initXR();
+    initSpatialConsole();
+    initLicense();
 }