@needle-tools/engine 5.0.2 → 5.1.0-canary.525aa82

package/src/engine-components/OrbitControls.ts

@@ -15,10 +15,10 @@ import { DeviceUtilities, getParam } from "../engine/engine_utils.js";
 import { NeedleEngineWebComponent } from "../engine/webcomponents/needle-engine.js";
 import { Camera } from "./Camera.js";
 import { Behaviour, GameObject } from "./Component.js";
+import { LookAtConstraint } from "./LookAtConstraint.js";
 import { SyncedTransform } from "./SyncedTransform.js";
 import { type AfterHandleInputEvent, EventSystem, EventSystemEvents } from "./ui/EventSystem.js";
 import { tryGetUIComponent } from "./ui/Utils.js";
-import { LookAtConstraint } from "./LookAtConstraint.js";
 
 
 const debug = getParam("debugorbit");
@@ -309,6 +309,10 @@ export class OrbitControls extends Behaviour implements ICameraController {
     set targetLerpDuration(v) { this._lookTargetLerpDuration = v; }
     private _lookTargetLerpDuration: number = 1;
 
+    /**
+     * When set, the camera's look at target will be clamped within the bounds of the specified Object3D. The bounds are defined by the world position and world scale of the assigned Object3D. 
+     * @default null
+     */
     @serializable(Object3D)
     targetBounds: Object3D | null = null;
 

package/src/engine-components/SeeThrough.ts

@@ -176,26 +176,6 @@ export class SeeThrough extends Behaviour {
     onEnable() {
         this._needsUpdate = true;
         this._renderer = null;
-        // SeeThroughUsdzExporterPlugin.components.push(this);
-    }
-
-    /**  @internal */
-    onDisable() {
-        // this._renderer?.forEach(r => {
-        //     const original = this.rendererMaterialsOriginal.get(r);
-        //     for (let i = 0; i < r.sharedMaterials.length; i++) {
-        //         const mat = r.sharedMaterials[i];
-        //         if (!mat) continue;
-        //         if (original && original[i]) {
-        //             r.sharedMaterials[i] = original[i];
-        //         }
-        //     }
-        //     this.rendererMaterials.delete(r);
-        //     this.rendererMaterialsOriginal.delete(r);
-        // });
-
-        // const index = SeeThroughUsdzExporterPlugin.components.indexOf(this);
-        // if (index !== -1) SeeThroughUsdzExporterPlugin.components.splice(index, 1);
     }
 
     /**
@@ -207,7 +187,6 @@ export class SeeThrough extends Behaviour {
         if (this._needsUpdate) {
             this._needsUpdate = false;
             this._renderer = this.gameObject.getComponentsInChildren(Renderer);
-
             // NOTE: instead of using the object's anchor (gameObject.worldPosition) we could also get the object's bounding box center:
             // getBoundingBox(this.gameObject); // < import { getBoundingBox } from "@needle-tools/engine";
             this.updateDirection();
@@ -216,12 +195,9 @@ export class SeeThrough extends Behaviour {
             this.updateDirection();
         }
 
-
-
         if (!this.autoUpdate) return;
         if (!this.referencePoint) return;
 
-
         const dot = this._referencePointDir.dot(this.context.mainCamera.worldForward);
         const shouldHide = dot > .2;
 
@@ -272,38 +248,10 @@ export class SeeThrough extends Behaviour {
                 renderer.gameObject.raycastAllowed = true;
             }
 
-            // if (!this.rendererMaterials.has(renderer)) {
-            //     const originalMaterials = new Array<Material>();
-            //     const clonedMaterials = new Array<MaterialWithState>();
-
-            //     // We clone the materials once and store them, so we can modify the opacity without affecting other objects using the same material. This could potentially be optimized further to re-use materials between renderers if multiple renderers use the same material.
-            //     for (let i = 0; i < renderer.sharedMaterials.length; i++) {
-            //         const mat = renderer.sharedMaterials[i];
-            //         if (!mat) continue;
-            //         originalMaterials.push(mat);
-            //         const matClone = mat.clone() as MaterialWithState;
-            //         // @ts-ignore
-            //         matClone.userData = mat.userData || {};
-            //         matClone.userData.seeThrough = {
-            //             initial: {
-            //                 opacity: matClone.opacity,
-            //                 transparent: matClone.transparent,
-            //                 alphaHash: matClone.alphaHash
-            //             }
-            //         }
-            //         clonedMaterials.push(matClone);
-            //         // renderer.sharedMaterials[i] = matClone;
-            //     }
-
-            //     this.rendererMaterials.set(renderer, clonedMaterials);
-            //     this.rendererMaterialsOriginal.set(renderer, originalMaterials);
-            // }
-
             const materials = renderer.sharedMaterials;// : this.rendererMaterials.get(renderer);
             if (!materials) return;
 
             const block = MaterialPropertyBlock.get(renderer.gameObject);
-
             const currentOpacity = (block.getOverride("opacity")?.value ?? materials[0].opacity ?? 1);
 
             let newAlpha = Mathf.lerp(currentOpacity, targetAlpha, duration <= 0 ? 1 : this.context.time.deltaTime / duration);;
@@ -315,72 +263,8 @@ export class SeeThrough extends Behaviour {
             block.setOverride("alphaHash", this.useAlphaHash);
             block.setOverride("opacity", newAlpha);
             block.setOverride("transparent", newAlpha >= 0.99999 ? false : !this.useAlphaHash);
-
-
-            // for (const mat of materials) {
-            //     if (!mat) continue;
-
-            //     let newAlpha = Mathf.lerp(mat.opacity, targetAlpha, duration <= 0 ? 1 : this.context.time.deltaTime / duration);;
-            //     if (newAlpha >= 0.99) newAlpha = 1;
-            //     else if (newAlpha <= 0.01) newAlpha = 0;
-
-
-            //     const wasTransparent = mat.transparent;
-            //     const wasAlphaHash = mat.alphaHash;
-            //     const previousOpacity = mat.opacity;
-
-            //     mat.alphaHash = this.useAlphaHash;
-
-            //     if (mat.userData && "seeThrough" in mat.userData) {
-            //         const initial = mat.userData.seeThrough.initial as MaterialState;
-            //         mat.opacity = initial.opacity * newAlpha;
-            //         mat.transparent = mat.opacity >= 1 ? initial.transparent : !this.useAlphaHash;
-            //     }
-            //     else {
-            //         mat.transparent = mat.opacity >= 1 ? false : !this.useAlphaHash;
-            //     }
-
-            //     if (wasTransparent !== mat.transparent 
-            //         || wasAlphaHash !== mat.alphaHash 
-            //         || mat.opacity !== previousOpacity // MeshPhysicsMaterial needs that and maybe other materials too...
-            //     ) {
-            //         mat.needsUpdate = true;
-            //     }
-            // }
         });
     }
 
 }
 
-
-;
-// class SeeThroughUsdzExporterPlugin implements IUSDExporterExtension {
-
-//     static readonly components: SeeThrough[] = [];
-
-//     get extensionName() {
-//         return "SeeThrough";
-//     }
-
-//     // onExportObject(object: Object3D<Object3DEventMap>, model: USDObject, context: USDZExporterContext) {
-//     //     const component = SeeThroughUsdzExporterPlugin.components.find(c => c.gameObject === object);
-//     //     if(!component) return;
-//     //     console.log("OH MY GOD SEE THROUGH USDZ EXPORTER", component, model);
-
-//     //     model.materialName = "AlphaHashMaterialInstance"; // we could make this unique per object if needed
-
-//     //     model.addEventListener("serialize", (writer, context) => {
-//     //         writer.appendLine(`# SeeThrough component on ${object.name}`);
-//     //     });
-//     // }
-
-// }
-
-// const seeThroughUsdzExporterPlugin = new SeeThroughUsdzExporterPlugin();
-
-// USDZExporter.beforeExport.addEventListener(args => {
-//     if (SeeThroughUsdzExporterPlugin.components.length === 0) return;
-//     if (args.exporter.extensions.includes(seeThroughUsdzExporterPlugin) === false) {
-//         args.exporter.extensions.push(seeThroughUsdzExporterPlugin);
-//     }
-// });

package/src/engine-components/SyncedRoom.ts

@@ -121,8 +121,36 @@ export class SyncedRoom extends Behaviour {
         if (debug) console.log(`SyncedRoom roomName:${this.roomName}, urlParamName:${this.urlParameterName}, joinRandomRoom:${this.joinRandomRoom}`);
     }
 
+    private _hasConnectedBefore: boolean = false;
+
     /** @internal */
     onEnable() {
+        if (this.createJoinButton) {
+            const button = this.createRoomButton();
+            this.context.menu.appendChild(button);
+        }
+        if (this.createViewOnlyButton) {
+            this.onEnableViewOnlyButton()
+        }
+
+        // On re-enable (after disable), reconnect immediately
+        if (this._hasConnectedBefore) {
+            this._connectToRoom();
+        }
+    }
+
+    /** @internal */
+    start() {
+        // Defer initial connection to start() so other components added in the same frame
+        // have time to register their listeners in awake/onEnable (e.g. PlayerSync)
+        if (!this._hasConnectedBefore) {
+            this._connectToRoom();
+        }
+    }
+
+    private _connectToRoom() {
+        this._hasConnectedBefore = true;
+
         // if the url contains a view parameter override room and join in view mode
         const viewId = utils.getParam(viewParamName);
         if (viewId && typeof viewId === "string" && viewId.length > 0) {
@@ -130,16 +158,7 @@ export class SyncedRoom extends Behaviour {
             this.context.connection.joinRoom(viewId, true);
             return;
         }
-        // If setup to join a random room
         this.tryJoinRoom();
-
-        if (this.createJoinButton) {
-            const button = this.createRoomButton();
-            this.context.menu.appendChild(button);
-        }
-        if (this.createViewOnlyButton) {
-            this.onEnableViewOnlyButton()
-        }
     }
 
     /** @internal */

package/src/engine-components/SyncedTransform.ts

@@ -145,7 +145,7 @@ export class SyncedTransform extends Behaviour {
      */
     public requestOwnership() {
         if (debug)
-            console.log("Request ownership");
+            console.log("[SyncedTransform] Request ownership");
         if (!this._model) {
             this._shouldRequestOwnership = true;
             this._needsUpdate = true;
@@ -189,7 +189,7 @@ export class SyncedTransform extends Behaviour {
     /** @internal */
     awake() {
         if (debug)
-            console.log("new instance", this.guid, this);
+            console.log("[SyncedTransform] new instance", this.guid, this);
         this._receivedDataBefore = false;
         this._targetPosition = new Vector3();
         this._targetRotation = new Quaternion();
@@ -245,7 +245,7 @@ export class SyncedTransform extends Behaviour {
         if (this.destroyed) return;
         if (typeof data.guid === "function" && data.guid() === this.guid) {
             if (debug)
-                console.log("new data", this.context.connection.connectionId, this.context.time.frameCount, this.guid, data);
+                console.log("[SyncedTransform] new data", this.context.connection.connectionId, this.context.time.frameCount, this.guid, data);
             this.receivedUpdate = true;
             this._receivedFastUpdate = data.fast();
             const transform = data.transform();
@@ -323,7 +323,7 @@ export class SyncedTransform extends Behaviour {
 
         if (!this.context.connection.isInRoom || !this._model) {
             if (debug)
-                console.log("no model or room", this.name, this.guid, this.context.connection.isInRoom);
+                console.log("[SyncedTransform] no model or room", this.name, this.guid, this.context.connection.isInRoom);
             return;
         }
 
@@ -409,7 +409,7 @@ export class SyncedTransform extends Behaviour {
         if (this.rb && this.overridePhysics) {
             if (this._wasKinematic !== undefined) {
                 if (debug)
-                    console.log("reset kinematic", this.rb.name, this._wasKinematic);
+                    console.log("[SyncedTransform] reset kinematic", this.rb.name, this._wasKinematic);
                 this.rb.isKinematic = this._wasKinematic;
             }
 

package/src/engine-components/Voip.ts

@@ -3,10 +3,10 @@ import { Application } from "../engine/engine_application.js";
 import { RoomEvents } from "../engine/engine_networking.js";
 import { disposeStream, NetworkedStreamEvents, NetworkedStreams, StreamEndedEvent, StreamReceivedEvent } from "../engine/engine_networking_streams.js"
 import { serializable } from "../engine/engine_serialization_decorator.js";
-import { DeviceUtilities, getParam } from "../engine/engine_utils.js";
-import { delay } from "../engine/engine_utils.js";
+import { delay, DeviceUtilities, getParam } from "../engine/engine_utils.js";
 import { getIconElement } from "../engine/webcomponents/icons.js";
 import { Behaviour } from "./Component.js";
+import { EventList } from "./EventList.js";
 
 export const noVoip = "noVoip";
 const debugParam = getParam("debugvoip");
@@ -75,6 +75,66 @@ export class Voip extends Behaviour {
      */
     debug: boolean = false;
 
+    private _volume: number = 1;
+
+    /**
+     * Volume for incoming audio streams (0 = silent, 1 = full volume).
+     * Changes apply immediately to all active incoming streams.
+     */
+    @serializable()
+    get volume(): number { return this._volume; }
+    set volume(val: number) {
+        this._volume = val;
+        for (const audio of this._incomingStreams.values()) {
+            audio.volume = val;
+        }
+    }
+
+    /**
+     * Get the incoming audio element for a specific user.
+     * Use this to route audio through the Web Audio API for spatial audio, effects, or analysis.
+     * @param userId The connection ID of the remote user
+     * @returns The HTMLAudioElement for this user's stream, or undefined if not connected
+     * @example
+     * ```ts
+     * const audioEl = voip.getAudioElement(userId);
+     * if (audioEl) {
+     *   const audioCtx = new AudioContext();
+     *   const source = audioCtx.createMediaElementSource(audioEl);
+     *   const panner = audioCtx.createPanner();
+     *   source.connect(panner).connect(audioCtx.destination);
+     * }
+     * ```
+     */
+    getAudioElement(userId: string): HTMLAudioElement | undefined {
+        return this._incomingStreams.get(userId);
+    }
+
+    /**
+     * Get all active incoming audio streams as a Map of userId → HTMLAudioElement.
+     * Useful for iterating over all connected voice users.
+     */
+    get incomingStreams(): ReadonlyMap<string, HTMLAudioElement> {
+        return this._incomingStreams;
+    }
+
+    /**
+     * Threshold for speaking detection (0–255). When a user's audio amplitude exceeds this,
+     * they are considered "speaking". Default is 30.
+     */
+    @serializable()
+    speakingThreshold: number = 30;
+
+    /**
+     * Event fired when a user's speaking state changes.
+     * Passes `{ userId: string, isSpeaking: boolean, volume: number }`.
+     */
+    @serializable(EventList)
+    onSpeakingChanged: EventList = new EventList();
+
+    private _speakingStates = new Map<string, boolean>();
+    private _analysers = new Map<string, { analyser: AnalyserNode, data: Uint8Array, context: AudioContext }>();
+
     private _net?: NetworkedStreams;
     private _menubutton?: HTMLElement;
 
@@ -141,12 +201,25 @@ export class Voip extends Behaviour {
         this.onEnabledChanged();
         this.updateButton();
         window.removeEventListener("visibilitychange", this.onVisibilityChanged);
+        // Clean up analysers
+        for (const userId of [...this._analysers.keys()]) {
+            this.cleanupAnalyser(userId);
+        }
     }
 
     /** @internal */
     onDestroy(): void {
         this._menubutton?.remove();
         this._menubutton = undefined;
+        // Clean up all streams and analysers
+        for (const userId of [...this._analysers.keys()]) {
+            this.cleanupAnalyser(userId);
+        }
+        for (const incoming of this._incomingStreams.values()) {
+            disposeStream(incoming.srcObject as MediaStream);
+        }
+        this._incomingStreams.clear();
+        this._speakingStates.clear();
     }
 
     /** Set via the mic button (e.g. when the websocket connection closes and rejoins but the user was muted before we don't want to enable VOIP again automatically) */
@@ -347,10 +420,61 @@ export class Voip extends Behaviour {
             disposeStream(incoming.srcObject as MediaStream);
         }
         this._incomingStreams.clear();
+        for (const userId of this._analysers.keys()) {
+            this.cleanupAnalyser(userId);
+        }
     }
 
     private _incomingStreams: Map<string, HTMLAudioElement> = new Map();
 
+    /** @internal */
+    update() {
+        // Only run speaking detection if someone is listening
+        if (!this.onSpeakingChanged || this.onSpeakingChanged.listenerCount <= 0) return;
+
+        for (const [userId, info] of this._analysers) {
+            info.analyser.getByteFrequencyData(info.data as Uint8Array<ArrayBuffer>);
+            // Average amplitude
+            let sum = 0;
+            for (let i = 0; i < info.data.length; i++) sum += info.data[i];
+            const avg = sum / info.data.length;
+
+            const wasSpeaking = this._speakingStates.get(userId) ?? false;
+            const isSpeaking = avg > this.speakingThreshold;
+
+            if (isSpeaking !== wasSpeaking) {
+                this._speakingStates.set(userId, isSpeaking);
+                this.onSpeakingChanged.invoke({ userId, isSpeaking, volume: avg / 255 });
+            }
+        }
+    }
+
+    private setupAnalyser(userId: string, _audioElement: HTMLAudioElement, stream: MediaStream) {
+        // Only set up if someone is listening or might listen
+        if (this._analysers.has(userId)) return;
+        try {
+            const audioCtx = new AudioContext();
+            const source = audioCtx.createMediaStreamSource(stream);
+            const analyser = audioCtx.createAnalyser();
+            analyser.fftSize = 256;
+            source.connect(analyser);
+            const data = new Uint8Array(analyser.frequencyBinCount);
+            this._analysers.set(userId, { analyser, data, context: audioCtx });
+        }
+        catch (err) {
+            if (this.debug) console.warn("VOIP: Failed to create analyser for", userId, err);
+        }
+    }
+
+    private cleanupAnalyser(userId: string) {
+        const info = this._analysers.get(userId);
+        if (info) {
+            info.context.close();
+            this._analysers.delete(userId);
+        }
+        this._speakingStates.delete(userId);
+    }
+
     private onReceiveStream = (evt: StreamReceivedEvent) => {
         const userId = evt.target.userId;
         const stream = evt.stream;
@@ -361,7 +485,9 @@ export class Voip extends Behaviour {
             this._incomingStreams.set(userId, audioElement);
         }
         audioElement.srcObject = stream;
+        audioElement.volume = this._volume;
         audioElement.setAttribute("autoplay", "true");
+        this.setupAnalyser(userId, audioElement, stream);
         // for mobile we need to wait for user interaction to play audio. Auto play doesnt work on android when the page is refreshed
         Application.registerWaitForInteraction(() => {
             audioElement?.play().catch((err) => {
@@ -374,6 +500,7 @@ export class Voip extends Behaviour {
         const existing = this._incomingStreams.get(evt.userId);
         disposeStream(existing?.srcObject as MediaStream);
         this._incomingStreams.delete(evt.userId);
+        this.cleanupAnalyser(evt.userId);
     }
 
     private onEnabledChanged = () => {

package/src/engine-components/api.ts

@@ -35,6 +35,7 @@
  */
 
 export * from "./codegen/components.js";
+export { AnimatorControllerBuilder, type ConditionMode, type StateOptions, type TransitionOptions } from "./AnimatorController.js";
 export { Collider } from "./Collider.js"; // export abstract type
 export { Behaviour, Component, GameObject } from "./Component.js";
 

package/src/engine-components/codegen/components.ts

@@ -6,6 +6,7 @@ export { Animation } from "../Animation.js";
 export { Keyframe } from "../AnimationCurve.js";
 export { AnimationCurve } from "../AnimationCurve.js";
 export { Animator } from "../Animator.js";
+export { AnimatorControllerBuilder } from "../AnimatorController.js";
 export { AnimatorController } from "../AnimatorController.js";
 export { AudioListener } from "../AudioListener.js";
 export { AudioSource } from "../AudioSource.js";

package/src/engine-components/postprocessing/Effects/Tonemapping.ts

@@ -1,11 +1,11 @@
 import type { ToneMappingEffect as _TonemappingEffect, ToneMappingMode } from "postprocessing";
+import type { ToneMapping } from "three";
 
 import { MODULES } from "../../../engine/engine_modules.js";
 import { serializable } from "../../../engine/engine_serialization.js";
 import { nameToThreeTonemapping } from "../../../engine/engine_tonemapping.js";
 import { getParam } from "../../../engine/engine_utils.js";
 import { EffectProviderResult, PostProcessingEffect } from "../PostProcessingEffect.js";
-import { findPostProcessingManager } from "../utils.js";
 import { VolumeParameter } from "../VolumeParameter.js";
 import { registerCustomEffectType } from "../VolumeProfile.js";
 import { NEToneMappingMode, NEToneMappingModeNames, threeToNeedleToneMapping, threeToneMappingToEffectMode, toThreeToneMapping } from "./Tonemapping.utils.js";
@@ -14,8 +14,8 @@ const debug = getParam("debugpost");
 
 
 /**
- * [ToneMappingEffect](https://engine.needle.tools/docs/api/ToneMappingEffect) adjusts the brightness and contrast of the rendered scene to map high dynamic range (HDR) colors to a displayable range.  
- * This effect is essential for achieving realistic lighting and color representation in 3D scenes, as it helps to preserve details in both bright and dark areas.  
+ * [ToneMappingEffect](https://engine.needle.tools/docs/api/ToneMappingEffect) adjusts the brightness and contrast of the rendered scene to map high dynamic range (HDR) colors to a displayable range.
+ * This effect is essential for achieving realistic lighting and color representation in 3D scenes, as it helps to preserve details in both bright and dark areas.
  * Various tonemapping algorithms can be applied to achieve different visual styles and effects.
  * @summary Tonemapping Post-Processing Effect
  * @category Effects
@@ -46,18 +46,23 @@ export class ToneMappingEffect extends PostProcessingEffect {
 
     get isToneMapping() { return true; }
 
-    onEffectEnabled(): void {
-        // Tonemapping works with and without a postprocessing manager. 
-        // If there's no manager already in the scene we don't need to create one because tonemapping can also be applied without a postprocessing pass
-        const ppmanager = findPostProcessingManager(this);
-        if (!ppmanager) return;
-        super.onEffectEnabled(ppmanager);
+    /** The three.js ToneMapping enum value resolved from the current mode */
+    get threeToneMapping(): ToneMapping {
+        if (this.mode.isInitialized && this.mode.overrideState)
+            return toThreeToneMapping(this.mode.value);
+        return this.context.renderer.toneMapping as ToneMapping;
+    }
+
+    /** The exposure value to apply */
+    get toneMappingExposure(): number {
+        if (this.exposure.overrideState && this.exposure.value !== undefined)
+            return Math.max(0.0, this.exposure.value);
+        return this.context.renderer.toneMappingExposure;
     }
 
     private _tonemappingEffect: _TonemappingEffect | null = null;
     onCreateEffect(): EffectProviderResult | undefined {
 
-
         // ensure the effect tonemapping value is initialized
         if (this.mode.isInitialized == false) {
             const mode = threeToNeedleToneMapping(this.context.renderer.toneMapping);
@@ -90,19 +95,6 @@ export class ToneMappingEffect extends PostProcessingEffect {
         return tonemapping;
     }
 
-
-    onBeforeRender(): void {
-        if (this._tonemappingEffect && this.postprocessingContext?.handler.getEffectIsActive(this._tonemappingEffect)) {
-            if (this.mode.overrideState)
-                this.context.renderer.toneMapping = toThreeToneMapping(this.mode.value);
-            if (this.exposure.overrideState && this.exposure.value !== undefined) {
-                const newValue = Math.max(0.0, this.exposure.value);
-                this.context.renderer.toneMappingExposure = newValue;
-            }
-        }
-    }
-
-
 }
 
-registerCustomEffectType("Tonemapping", ToneMappingEffect);
+registerCustomEffectType("Tonemapping", ToneMappingEffect);

package/src/engine-components/postprocessing/PostProcessingEffect.ts

@@ -3,9 +3,10 @@ import type { Effect, Pass } from "postprocessing";
 import type { EditorModification, IEditorModification } from "../../engine/engine_editor-sync.js";
 import { serializable } from "../../engine/engine_serialization.js";
 import { getParam } from "../../engine/engine_utils.js";
+import type { PostProcessing } from "../../engine/postprocessing/index.js";
+import type { IPostProcessingEffect } from "../../engine/postprocessing/types.js";
 import { Component } from "../Component.js";
 import type { PostProcessingHandler } from "./PostProcessingHandler.js";
-import { getPostProcessingManager, IPostProcessingManager } from "./utils.js";
 import { VolumeParameter } from "./VolumeParameter.js";
 
 const debug = getParam("debugpost");
@@ -50,8 +51,9 @@ export interface IEffectProvider {
  * 
  * @category Effects
  * @group Components
+ * @see {@link PostProcessing} for core Needle Engine postprocessing control, also accessible via `context.postprocessing`
  */
-export abstract class PostProcessingEffect extends Component implements IEffectProvider, IEditorModification {
+export abstract class PostProcessingEffect extends Component implements IPostProcessingEffect, IEffectProvider, IEditorModification {
 
     get isPostProcessingEffect() { return true; }
 
@@ -101,31 +103,22 @@ export abstract class PostProcessingEffect extends Component implements IEffectP
     @serializable()
     active: boolean = true;
 
-    private _manager: IPostProcessingManager | null = null;
-
     onEnable(): void {
         super.onEnable();
         if (debug) console.warn("Enable", this.constructor.name + (!this.__internalDidAwakeAndStart ? " (awake)" : ""));
-        // Dont override the serialized value by enabling (we could also just disable this component / map enabled to active)
-        if (this.__internalDidAwakeAndStart)
-            this.active = true;
-        this.onEffectEnabled();
+        // Ensure active is synced with the component's enabled state
+        this.active = true;
+        // Register directly with the core postprocessing stack
+        this.context.postprocessing.addEffect(this);
     }
 
     onDisable(): void {
         super.onDisable();
         if (debug) console.warn("Disable", this.constructor.name);
-        this._manager?.removeEffect(this);
+        this.context.postprocessing.removeEffect(this);
         this.active = false;
     }
 
-    protected onEffectEnabled(manager?: IPostProcessingManager) {
-        if (manager && manager.isPostProcessingManager === true) this._manager = manager;
-        else if (!this._manager) this._manager = getPostProcessingManager(this);
-        this._manager!.addEffect(this);
-        this._manager!.dirty = true;
-    }
-
     /** override to initialize bindings on parameters */
     init() { }
 

package/src/engine-components/postprocessing/PostProcessingHandler.ts

@@ -8,6 +8,7 @@ import { Context } from "../../engine/engine_setup.js";
 import { Graphics } from "../../engine/engine_three_utils.js";
 import { Constructor } from "../../engine/engine_types.js";
 import { getParam } from "../../engine/engine_utils.js";
+import type { IPostProcessingHandler } from "../../engine/postprocessing/types.js";
 import { Camera } from "../Camera.js";
 import { threeToneMappingToEffectMode } from "./Effects/Tonemapping.utils.js";
 import { PostProcessingEffect, PostProcessingEffectContext } from "./PostProcessingEffect.js";
@@ -26,7 +27,7 @@ const previousToneMapping = Symbol("needle:previous-tone-mapping");
 /**
  * [PostProcessingHandler](https://engine.needle.tools/docs/api/PostProcessingHandler) Is responsible for applying post processing effects to the scene. It is internally used by the {@link Volume} component
  */
-export class PostProcessingHandler {
+export class PostProcessingHandler implements IPostProcessingHandler {
 
     private _composer: EffectComposer | null = null;
     private _lastVolumeComponents?: PostProcessingEffect[];