@needle-tools/engine 5.0.3 → 5.1.0-alpha.1

package/plugins/vite/ai.js

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { dirname, join } from "path";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync, writeFileSync } from "fs";
+import { dirname, join, relative } from "path";
 import { fileURLToPath } from "url";
 import { needleLog } from "./logging.js";
 
@@ -8,20 +8,49 @@ const __dirname = dirname(__filename);
 
 const pluginName = "needle-ai";
 
+/**
+ * Supported AI coding agents.
+ * Each entry defines how to detect the agent and how to write its skill file.
+ * `detect` is the directory that must exist in the project root.
+ * `write(cwd, canonicalDir, content)` installs the skill in the agent's native format.
+ *
+ * The `.agents/` entry is special: it is the canonical location where SKILL.md
+ * and downloaded reference files are written directly. All other agents symlink
+ * their skill directory to `.agents/skills/needle-engine/`.
+ */
+const agents = [
+    {
+        name: "Claude Code",
+        detect: ".claude",
+        write: (cwd, canonicalDir, content) => symlinkSkillDir(join(cwd, ".claude"), canonicalDir),
+    },
+    {
+        name: "GitHub Copilot",
+        detect: ".github",
+        write: (cwd, canonicalDir, content) => symlinkSkillDir(join(cwd, ".github"), canonicalDir),
+    },
+    {
+        name: "Cursor",
+        detect: ".cursor",
+        write: (cwd, canonicalDir, content) => writeCursorRule(cwd, canonicalDir, content),
+    },
+];
+
 /**
  * Needle Engine AI skill installer.
  *
- * Writes a Needle Engine skill to `<dir>/skills/needle-engine/SKILL.md`
- * for each supported AI agent directory (`.claude/`, `.github/`, `.agents/`).
- * Both Claude Code and GitHub Copilot auto-load skills based on their
- * description frontmatter, so the AI agent will automatically have Needle
- * Engine context when working in the project.
+ * Auto-detects AI coding agents by checking for their config directories
+ * in the project root, then writes the Needle Engine skill in each agent's
+ * native format.
+ *
+ * Supported agents: Claude Code, GitHub Copilot, Cursor, Codex / universal.
  *
- * The skill is only written if at least one of the supported directories
- * already exists in the project root (i.e. the developer is already using
- * an AI coding agent).
- * Old skill files are always overwritten so the skill stays up to date with
- * the engine version.
+ * `.agents/skills/needle-engine/` is always created as the canonical skill
+ * location. SKILL.md and downloaded reference files live there. Other agents
+ * symlink to it to avoid duplication.
+ *
+ * Remote reference files (API docs, templates, etc.) linked from SKILL.md are
+ * downloaded at install time and stored locally with relative paths.
  *
  * @param {"build" | "serve"} command
  * @param {{} | undefined | null} config
@@ -32,34 +61,279 @@ export function needleAI(command, config, userSettings) {
     return {
         name: pluginName,
         enforce: "pre",
-        buildStart() {
-            installClaudeSkill();
+        async buildStart() {
+            await installSkills();
         },
-        configureServer() {
-            installClaudeSkill();
+        async configureServer() {
+            await installSkills();
         },
     };
 }
 
-function writeSkill(claudeDir) {
-    const skillDir = join(claudeDir, "skills", "needle-engine");
-    if (!existsSync(skillDir)) {
-        mkdirSync(skillDir, { recursive: true });
-    }
-    const skillPath = join(skillDir, "SKILL.md");
+/** Read the SKILL.md template shipped with the engine. */
+function getSkillContent() {
     const templatePath = join(__dirname, "../../SKILL.md");
-    const content = readFileSync(templatePath, "utf8");
-    writeFileSync(skillPath, content, "utf8");
-    return skillPath;
+    return readFileSync(templatePath, "utf8");
+}
+
+/**
+ * Extract the body of a SKILL.md file (everything after the YAML frontmatter).
+ * Returns the full content if no frontmatter is found.
+ */
+function stripFrontmatter(content) {
+    const match = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n([\s\S]*)$/);
+    return match ? match[1].trimStart() : content;
+}
+
+// ---------------------------------------------------------------------------
+// Remote reference downloading
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract markdown links to raw.githubusercontent.com files from content.
+ * Returns an array of { fullMatch, linkText, url, subdir, filename, localRelPath }.
+ */
+function extractRemoteRefs(content) {
+    const pattern = /\[([^\]]*)\]\((https:\/\/raw\.githubusercontent\.com\/[^)]+)\)/g;
+    const refs = [];
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        const url = match[2];
+        const urlPath = new URL(url).pathname;
+        const segments = urlPath.split("/").filter(Boolean);
+        const filename = segments[segments.length - 1];
+        const subdir = segments[segments.length - 2] || "";
+        refs.push({
+            fullMatch: match[0],
+            linkText: match[1],
+            url,
+            subdir,
+            filename,
+            localRelPath: `./${subdir}/${filename}`,
+        });
+    }
+    return refs;
 }
 
-function installClaudeSkill() {
+/**
+ * Download a single remote file. Returns text on success, null on failure.
+ * @param {{ fullMatch: string, linkText: string, url: string, subdir: string, filename: string, localRelPath: string }} ref
+ * @param {number} timeoutMs
+ * @returns {Promise<string | null>}
+ */
+async function downloadRef(ref, timeoutMs = 5000) {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        const response = await fetch(ref.url, { signal: controller.signal });
+        clearTimeout(timer);
+        if (!response.ok) return null;
+        return await response.text();
+    }
+    catch {
+        return null;
+    }
+}
+
+/**
+ * Download all remote references found in content. Returns rewritten content
+ * (absolute URLs → relative paths) and the downloaded file data.
+ * Failed downloads keep their original absolute URL.
+ */
+async function downloadAndRewriteRefs(content) {
+    const refs = extractRemoteRefs(content);
+    if (refs.length === 0) return { rewrittenContent: content, downloadedFiles: [] };
+
+    if (typeof globalThis.fetch !== "function") {
+        return { rewrittenContent: content, downloadedFiles: [] };
+    }
+
+    const results = await Promise.allSettled(
+        refs.map(async ref => {
+            const data = await downloadRef(ref);
+            return { ref, data };
+        })
+    );
+
+    let rewrittenContent = content;
+    const downloadedFiles = [];
+
+    for (const result of results) {
+        if (result.status === "fulfilled" && result.value.data !== null) {
+            const { ref, data } = result.value;
+            const newLink = `[${ref.linkText}](${ref.localRelPath})`;
+            rewrittenContent = rewrittenContent.replace(ref.fullMatch, newLink);
+            downloadedFiles.push({
+                subdir: ref.subdir,
+                filename: ref.filename,
+                data,
+            });
+        }
+    }
+
+    return { rewrittenContent, downloadedFiles };
+}
+
+// ---------------------------------------------------------------------------
+// Canonical skill directory (.agents/)
+// ---------------------------------------------------------------------------
+
+/**
+ * Write SKILL.md and downloaded reference files into the canonical location
+ * at `.agents/skills/needle-engine/`. This directory is always created and
+ * serves as the symlink target for all other agents.
+ * @returns {string} The absolute path to the canonical skill directory.
+ */
+function writeCanonicalSkillDir(cwd, content, downloadedFiles) {
+    const canonicalDir = join(cwd, ".agents", "skills", "needle-engine");
+    if (!existsSync(canonicalDir)) {
+        mkdirSync(canonicalDir, { recursive: true });
+    }
+
+    writeFileSync(join(canonicalDir, "SKILL.md"), content, "utf8");
+
+    for (const file of downloadedFiles) {
+        const fileDir = join(canonicalDir, file.subdir);
+        if (!existsSync(fileDir)) {
+            mkdirSync(fileDir, { recursive: true });
+        }
+        writeFileSync(join(fileDir, file.filename), file.data, "utf8");
+    }
+
+    return canonicalDir;
+}
+
+// ---------------------------------------------------------------------------
+// Agent writers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a symlink at `<agentDir>/skills/needle-engine` → canonical skill dir.
+ * If the target already exists (file, dir, or stale symlink), it is replaced.
+ */
+function symlinkSkillDir(agentDir, canonicalDir) {
+    const skillsDir = join(agentDir, "skills");
+    const linkPath = join(skillsDir, "needle-engine");
+
+    if (!existsSync(skillsDir)) {
+        mkdirSync(skillsDir, { recursive: true });
+    }
+
+    const target = relative(skillsDir, canonicalDir);
+
+    // Remove existing entry (file, dir, or stale symlink)
+    try {
+        if (existsSync(linkPath) || lstatSync(linkPath).isSymbolicLink()) {
+            rmSync(linkPath, { recursive: true, force: true });
+        }
+    }
+    catch { /* nothing to remove */ }
+
+    try {
+        symlinkSync(target, linkPath, "junction");
+        return linkPath;
+    }
+    catch {
+        // Fallback: copy if symlink fails (e.g. Windows without privileges)
+        if (!existsSync(linkPath)) {
+            mkdirSync(linkPath, { recursive: true });
+        }
+        copyDirSync(canonicalDir, linkPath);
+        return linkPath;
+    }
+}
+
+/**
+ * Write a Cursor rule file at `.cursor/rules/needle-engine.mdc` and symlink
+ * the reference files directory at `.cursor/rules/needle-engine/`.
+ * Cursor uses its own frontmatter format (description, globs, alwaysApply).
+ */
+function writeCursorRule(cwd, canonicalDir, content) {
+    const rulesDir = join(cwd, ".cursor", "rules");
+    if (!existsSync(rulesDir)) {
+        mkdirSync(rulesDir, { recursive: true });
+    }
+
+    // Symlink .cursor/rules/needle-engine/ → canonical dir (for reference files)
+    const linkPath = join(rulesDir, "needle-engine");
+    const target = relative(rulesDir, canonicalDir);
+    try {
+        if (existsSync(linkPath) || lstatSync(linkPath).isSymbolicLink()) {
+            rmSync(linkPath, { recursive: true, force: true });
+        }
+    }
+    catch { /* nothing to remove */ }
+
+    try {
+        symlinkSync(target, linkPath, "junction");
+    }
+    catch {
+        // Fallback: copy directly
+        if (!existsSync(linkPath)) {
+            mkdirSync(linkPath, { recursive: true });
+        }
+        copyDirSync(canonicalDir, linkPath);
+    }
+
+    // Write the .mdc file with adjusted relative paths
+    // SKILL.md uses ./references/api.md but the .mdc sits at .cursor/rules/needle-engine.mdc
+    // so we need ./needle-engine/references/api.md
+    let body = stripFrontmatter(content);
+    body = body.replace(/\]\(\.\/(references|templates)\//g, "](./needle-engine/$1/");
+
+    const rulePath = join(rulesDir, "needle-engine.mdc");
+    const cursorContent = `---
+description: Needle Engine context — use when editing TypeScript components, Vite config, GLB assets, or anything related to @needle-tools/engine.
+globs:
+alwaysApply: false
+---
+${body}`;
+    writeFileSync(rulePath, cursorContent, "utf8");
+    return rulePath;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Recursively copy a directory's contents. */
+function copyDirSync(src, dest) {
+    for (const entry of readdirSync(src)) {
+        const srcPath = join(src, entry);
+        const destPath = join(dest, entry);
+        if (statSync(srcPath).isDirectory()) {
+            if (!existsSync(destPath)) mkdirSync(destPath, { recursive: true });
+            copyDirSync(srcPath, destPath);
+        }
+        else {
+            copyFileSync(srcPath, destPath);
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+/** Detect agents and install the Needle Engine skill for each. */
+async function installSkills() {
     const cwd = process.cwd();
-    const dirs = [".claude", ".github", ".agents"].map(d => join(cwd, d)).filter(d => existsSync(d));
-    if (dirs.length === 0) return; // only install if developer uses an AI coding agent
 
-    for (const dir of dirs) {
-        const path = writeSkill(dir);
-        if (path) needleLog(`[${pluginName}] Installed Needle Engine skill → ${path}`);
+    const rawContent = getSkillContent();
+    const { rewrittenContent, downloadedFiles } = await downloadAndRewriteRefs(rawContent);
+
+    // Always write to .agents/ as the canonical location
+    const canonicalDir = writeCanonicalSkillDir(cwd, rewrittenContent, downloadedFiles);
+
+    // Symlink other detected agents to the canonical dir
+    const detected = agents.filter(a => existsSync(join(cwd, a.detect)));
+    const names = ["Codex / Universal"];
+    for (const agent of detected) {
+        const path = agent.write(cwd, canonicalDir, rewrittenContent);
+        if (path) names.push(agent.name);
     }
+
+    const refCount = downloadedFiles.length;
+    const refMsg = refCount > 0 ? ` (${refCount} reference file${refCount === 1 ? "" : "s"} downloaded)` : "";
+    needleLog(pluginName, `Installed for ${names.length} agent${names.length === 1 ? "" : "s"}: ${names.join(", ")}${refMsg}`);
 }

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/src/engine/api.ts

@@ -318,6 +318,9 @@ export * from "./engine_physics.types.js";
 /** Rapier physics engine integration */
 export * from "./engine_physics_rapier.js";
 
+/** Core postprocessing stack (accessible via context.postprocessing) */
+export * from "./postprocessing/api.js";
+
 
 // ============================================================================
 // PLAYER & VIEW MANAGEMENT

package/src/engine/engine_addressables.ts

@@ -463,7 +463,10 @@ export class AssetReference {
                 if (networked) {
                     options.context = context;
                     const prefab = this.asset;
-                    prefab.guid = this.url;
+                    // Only set guid from URL if we have one — runtime Object3D prefabs
+                    // (via new AssetReference({ asset: obj })) have no URL and may already
+                    // have a user-assigned guid. Don't overwrite with empty string.
+                    if (this.url) prefab.guid = this.url;
                     const instance = syncInstantiate(prefab, options, undefined, saveOnServer);
                     if (instance) {
                         return instance;

package/src/engine/engine_animation.ts

@@ -2,9 +2,10 @@ import { AnimationAction, AnimationClip, AnimationMixer, KeyframeTrack, Object3D
 
 import { isDevEnvironment } from "./debug/index.js";
 import type { Context } from "./engine_context.js";
-import { GLTF, IAnimationComponent, Model } from "./engine_types.js";
+import { IAnimationComponent, Model } from "./engine_types.js";
 import { TypeStore } from "./engine_typestore.js";
 
+// #region Registry
 /**
  * Registry for animation related data. Use {@link registerAnimationMixer} to register an animation mixer instance.  
  * Can be accessed from {@link Context.animations} and is used internally e.g. when exporting GLTF files.
@@ -52,10 +53,11 @@ export class AnimationsRegistry {
 }
 
 
+// #region Animation Utils
 /**
  * Utility class for working with animations.
  */
-export class AnimationUtils {
+export namespace AnimationUtils {
 
     /**
      * Tests if the root object of an AnimationAction can be animated. Objects where matrixAutoUpdate or matrixWorldAutoUpdate is set to false may not animate correctly.
@@ -63,7 +65,7 @@ export class AnimationUtils {
      * @param allowLog Whether to allow logging warnings. Default is false, which only allows logging in development environments.
      * @returns True if the root object can be animated, false otherwise
      */
-    static testIfRootCanAnimate(action: AnimationAction, allowLog?: boolean): boolean {
+    export function testIfRootCanAnimate(action: AnimationAction, allowLog?: boolean): boolean {
         const root = action.getRoot();
 
         if (root && (root.userData.static || root.matrixAutoUpdate === false || root.matrixWorldAutoUpdate === false)) {
@@ -79,13 +81,15 @@ export class AnimationUtils {
      * @param mixer The animation mixer to get the actions from
      * @returns The actions or null if the mixer is invalid
      */
-    static tryGetActionsFromMixer(mixer: AnimationMixer): Array<AnimationAction> | null {
+
+    export function tryGetActionsFromMixer(mixer: AnimationMixer): Array<AnimationAction> | null {
         const actions = mixer["_actions"] as Array<AnimationAction>;
         if (!actions) return null;
         return actions;
     }
 
-    static tryGetAnimationClipsFromObjectHierarchy(obj: Object3D, target?: Array<AnimationClip>): Array<AnimationClip> {
+
+    export function tryGetAnimationClipsFromObjectHierarchy(obj: Object3D, target?: Array<AnimationClip>): Array<AnimationClip> {
         if (!target) target = new Array<AnimationClip>();
 
         if (!obj) {
@@ -96,18 +100,49 @@ export class AnimationUtils {
         }
         if (obj.children) {
             for (const child of obj.children) {
-                this.tryGetAnimationClipsFromObjectHierarchy(child, target);
+                tryGetAnimationClipsFromObjectHierarchy(child, target);
             }
         }
         return target;
     }
 
+
+    const $objectAnimationKey = Symbol("objectIsAnimatedData");
+
+    /** Internal method - This marks an object as being animated. Make sure to always call isAnimated=false if you stop animating the object
+     * @param obj The object to mark
+     * @param isAnimated Whether the object is animated or not
+     */
+    export function setObjectAnimated(obj: Object3D, animatedBy: object, isAnimated: boolean) {
+        if (!obj) return;
+        if (obj[$objectAnimationKey] === undefined) {
+            if (!isAnimated) return;
+            obj[$objectAnimationKey] = new Set<object>();
+        }
+
+        const set = obj[$objectAnimationKey] as Set<object>;
+        if (isAnimated) {
+            set.add(animatedBy);
+        }
+        else if (set.has(animatedBy))
+            set.delete(animatedBy);
+    }
+
+    /** Get is the object is currently animated. Currently used by the Animator to check if a timeline animationtrack is actively animating an object */
+    export function getObjectAnimated(obj: Object3D): boolean {
+        if (!obj) return false;
+        const set = obj[$objectAnimationKey] as Set<object>;
+        return set !== undefined && set.size > 0;
+    }
+
+    // #region Autoplay
     /**
      * Assigns animations from a GLTF file to the objects in the scene.  
      * This method will look for objects in the scene that have animations and assign them to the correct objects.  
      * @param file The GLTF file to assign the animations from
      */
-    static autoplayAnimations(file: Object3D | Pick<Model, "animations" | "scene">): Array<IAnimationComponent> | null {
+
+    export function autoplayAnimations(file: Object3D | Pick<Model, "animations" | "scene">): Array<IAnimationComponent> | null {
         if (!file || !file.animations) {
             console.debug("No animations found in file");
             return null;
@@ -171,11 +206,14 @@ export class AnimationUtils {
     }
 
 
-    static emptyClip(): AnimationClip {
+    // #region Create Clips
+
+    export function emptyClip(): AnimationClip {
         return new AnimationClip("empty", 0, []);
     }
 
-    static createScaleClip(options?: ScaleClipOptions): AnimationClip {
+
+    export function createScaleClip(options?: ScaleClipOptions): AnimationClip {
         const duration = options?.duration ?? 0.3;
 
         let baseScale: Vector3Like = { x: 1, y: 1, z: 1 };

package/src/engine/engine_components.ts

@@ -1,4 +1,5 @@
 import { Object3D, Scene } from "three";
+import { v5 } from 'uuid';
 
 import { ComponentLifecycleEvents } from "./engine_components_internal.js";
 import { activeInHierarchyFieldName } from "./engine_constants.js";
@@ -6,8 +7,35 @@ import { removeScriptFromContext, updateActiveInHierarchyWithoutEventCall } from
 import { InstantiateIdProvider } from "./engine_networking_instantiate.js";
 import { Context, registerComponent } from "./engine_setup.js";
 import type { ComponentInit, Constructor, ConstructorConcrete, IComponent, IGameObject } from "./engine_types.js";
+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';
+
+/**
+ * Generates a deterministic guid for a component based on the object's guid and the component type.
+ * If the object has a guid, the component guid is derived from `objectGuid:TypeName:index`
+ * using UUID v5 hashing. This ensures the same component type added to the same object on
+ * different clients gets the same guid — critical for networked components like SyncedTransform.
+ * Falls back to the shared counter-based IdProvider if the object has no guid.
+ */
+function generateDeterministicComponentGuid(obj: Object3D, component: IComponent): string {
+    const objectGuid = obj["guid"];
+    if (objectGuid) {
+        const typeName = component[$componentName] ?? component.constructor?.name ?? "Component";
+        // Count existing components of same type for uniqueness (e.g. multiple of the same component type)
+        const existingComponents = getComponents(obj, component.constructor as any);
+        let sameTypeCount = 0;
+        for (const c of existingComponents) {
+            if (c !== component) sameTypeCount++;
+        }
+        const key = `${objectGuid}:${typeName}:${sameTypeCount}`;
+        return v5(key, COMPONENT_GUID_NAMESPACE);
+    }
+    return getIdProvider().generateUUID();
+}
 
 
 const debug = getParam("debuggetcomponent");
@@ -57,9 +85,8 @@ export function addNewComponent<T extends IComponent>(obj: Object3D, componentIn
     if (!obj.userData.components) obj.userData.components = [];
     obj.userData.components.push(componentInstance);
     componentInstance.gameObject = obj as IGameObject;
-    // TODO: currently add component does not ensure a new component instance has a guid
     if (componentInstance.guid === undefined || componentInstance.guid === "invalid") {
-        componentInstance.guid = getIdProvider().generateUUID();
+        componentInstance.guid = generateDeterministicComponentGuid(obj, componentInstance);
     }
     apply(obj);
     // register the component - make sure to provide the component instance context (if assigned)
@@ -109,9 +136,9 @@ export function addComponent<T extends IComponent>(obj: Object3D, componentInsta
     // componentInstance.__internalEnable();
     // componentInstance.transform = obj;
     if (componentInstance.guid === undefined || componentInstance.guid === "invalid") {
-        componentInstance.guid = getIdProvider().generateUUID();
+        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;
@@ -144,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())
@@ -222,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;
@@ -335,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_context.ts

@@ -43,6 +43,7 @@ import { patchTonemapping } from './engine_tonemapping.js';
 import type { CoroutineData, ICamera, IComponent, IContext, ILight, LoadedModel, Model, SourceIdentifier, Vec2 } from "./engine_types.js";
 import { deepClone, delay, DeviceUtilities, getParam } from './engine_utils.js';
 import type { INeedleXRSessionEventReceiver, NeedleXRSession } from './engine_xr.js';
+import { PostProcessing } from './postprocessing/index.js';
 import { NeedleMenu } from './webcomponents/needle menu/needle-menu.js';
 import type { NeedleEngineWebComponent } from './webcomponents/needle-engine.js';
 
@@ -387,9 +388,11 @@ export class Context implements IContext {
 	 */
 	renderer!: WebGLRenderer;
 	/**
-	 * The effect composer can be used to render postprocessing effects. If assigned then it will automatically render the scene every frame.
+	 * The effect composer used for rendering postprocessing effects.
+	 * @deprecated Use `context.postprocessing.composer` instead.
 	 */
-	composer: EffectComposer | ThreeEffectComposer | null = null;
+	get composer(): EffectComposer | ThreeEffectComposer | null { return this.postprocessing.composer; }
+	set composer(value: EffectComposer | ThreeEffectComposer | null) { this.postprocessing.composer = value; }
 
 	// #region internal script lists
 	/**
@@ -504,6 +507,8 @@ export class Context implements IContext {
 	input: Input;
 	/** access physics related methods (e.g. raycasting). To access the phyiscs engine use `context.physics.engine` */
 	physics: Physics;
+	/** access postprocessing effects stack. Add/remove effects and configure adaptive performance settings */
+	postprocessing: PostProcessing;
 	/** access networking methods (use it to send or listen to messages or join a networking backend) */
 	connection: NetworkConnection;
 	/**  @deprecated AssetDatabase is deprecated */
@@ -564,6 +569,7 @@ export class Context implements IContext {
 		this.time = new Time();
 		this.input = new Input(this);
 		this.physics = new Physics(this);
+		this.postprocessing = new PostProcessing(this);
 		this.connection = new NetworkConnection(this);
 		// eslint-disable-next-line @typescript-eslint/no-deprecated
 		this.assets = new AssetDatabase();
@@ -1778,6 +1784,9 @@ export class Context implements IContext {
 		if (this.renderer.toneMapping !== NoToneMapping)
 			patchTonemapping(this);
 
+		// Update postprocessing stack (applies dirty effects, adaptive multisampling/pixel ratio)
+		this.postprocessing.update();
+
 		if (this.composer && !this.isInXR) {
 			// if a camera is passed in we need to check if we need to update the composer's camera
 			if (camera && "setMainCamera" in this.composer) {