@needle-tools/engine 5.0.2 → 5.1.0-canary.87c4c44

package/src/engine/engine_networking_instantiate.ts

@@ -11,7 +11,7 @@ import type { INetworkConnection } from "./engine_networking_types.js";
 import type { IModel } from "./engine_networking_types.js";
 import { SendQueue } from "./engine_networking_types.js";
 import { Context } from "./engine_setup.js"
-import type { IComponent as Component, IGameObject as GameObject } from "./engine_types.js"
+import type { IComponent as Component, IContext,IGameObject as GameObject } from "./engine_types.js"
 import type { UIDProvider } from "./engine_types.js";
 import * as utils from "./engine_utils.js"
 
@@ -154,13 +154,46 @@ export function sendDestroyed(guid: string, con: INetworkConnection, opts?: Sync
     con.send(InstantiateEvent.InstanceDestroyed, model, SendQueue.Queued);
 }
 
+declare type SyncDestroyCallback = (guid: string, object: Object3D) => void;
+const _onSyncDestroyCallbacks: SyncDestroyCallback[] = [];
+
+/**
+ * Register a callback that fires when a remote `syncDestroy` event is received.
+ * The callback receives the guid and the resolved Object3D (or null if not found in the scene).
+ * The callback fires **before** the object is destroyed, so you can still access its state.
+ * @param callback Called with the guid and the Object3D about to be destroyed
+ * @returns An unsubscribe function
+ * @category Networking
+ * @example
+ * ```ts
+ * const unsub = onSyncDestroy((guid, obj) => {
+ *   console.log("Remote object destroyed:", guid, obj?.name);
+ * });
+ * // later: unsub();
+ * ```
+ */
+export function onSyncDestroy(callback: SyncDestroyCallback): () => void {
+    _onSyncDestroyCallbacks.push(callback);
+    return () => {
+        const idx = _onSyncDestroyCallbacks.indexOf(callback);
+        if (idx >= 0) _onSyncDestroyCallbacks.splice(idx, 1);
+    };
+}
+
 export function beginListenDestroy(context: Context) {
     context.connection.beginListen(InstantiateEvent.InstanceDestroyed, (data: DestroyInstanceModel) => {
         if (debug)
             console.log("[Remote] Destroyed", context.scene, data);
         // TODO: create global lookup table for guids
         const obj = findByGuid(data.guid, context.scene);
-        if (obj) destroy(obj);
+        if (obj) {
+            // Notify listeners before destroying
+            for (const cb of _onSyncDestroyCallbacks) {
+                try { cb(data.guid, obj as Object3D); }
+                catch (err) { console.error("Error in onSyncDestroy callback", err); }
+            }
+            destroy(obj);
+        }
     });
 }
 
@@ -215,27 +248,125 @@ export class NewInstanceModel implements IModel {
 
 /**
  * Instantiation options for {@link syncInstantiate}
+ * @category Networking
+ * @see {@link syncInstantiate} - Instantiate objects across the network
  */
 export type SyncInstantiateOptions = IInstantiateOptions & Pick<IModel, "deleteOnDisconnect">;
 
 // #region Sync Instantiate
+
+/**
+ * Callback type for {@link onSyncInstantiate}
+ * @param instance The instantiated object
+ * @param model The network model data sent with the instantiate event
+ * @param context The network context in which the instantiate event was received
+ * @category Networking
+ */
+declare type SyncInstantiateCallback = (instance: GameObject, model: NewInstanceModel, context: IContext) => void;
+/** Registered callbacks for remote instantiation events */
+const _onSyncInstantiateCallbacks: SyncInstantiateCallback[] = [];
+
 /**
- * Instantiate an object across the network. See also {@link syncDestroy}.
+ * Register a callback that fires when a remote `syncInstantiate` object is created on this client.
+ * Use this to get references to objects spawned by other users.
+ * @param callback Called with the instantiated Object3D, the network model data, and the Needle Engine context in which the instantiate event was received
+ * @returns An unsubscribe function
  * @category Networking
+ * @example
+ * ```ts
+ * const unsub = onSyncInstantiate((instance, model, context) => {
+ *   console.log("Remote object created:", instance.name, model.originalGuid, context);
+ * });
+ * // later: unsub();
+ * ```
+ * @see {@link syncInstantiate} - Instantiate objects across the network
+ * @see {@link syncDestroy} - Destroy objects across the network
+ */
+export function onSyncInstantiate(callback: SyncInstantiateCallback): () => void {
+    _onSyncInstantiateCallbacks.push(callback);
+    return () => {
+        const idx = _onSyncInstantiateCallbacks.indexOf(callback);
+        if (idx >= 0) _onSyncInstantiateCallbacks.splice(idx, 1);
+    };
+}
+
+/**
+ * Instantiate an object across the network. The object is cloned locally and a network message
+ * is sent so all connected clients create the same clone. Late joiners receive the message
+ * via room state replay (unless `deleteOnDisconnect` is set or `save` is false).
+ *
+ * ## How it works internally
+ * 1. The prefab is cloned locally using a seeded {@link InstantiateIdProvider}
+ * 2. The seed ensures all clients generate **identical deterministic guids** for the clone
+ *    and all its children — no need to send individual guids over the network
+ * 3. A {@link NewInstanceModel} message is sent containing the prefab's `originalGuid`,
+ *    the clone's `guid`, the `seed`, and transform data
+ * 4. On receiving clients, the prefab is resolved via {@link registerPrefabProvider} or
+ *    by searching the scene for an object with matching guid, then cloned with the same seed
+ *
+ * ## Runtime-created prefabs (no GLB)
+ * If the object has a `guid` but no prefab provider is registered for it, `syncInstantiate`
+ * will **auto-register** the object as a prefab provider. This means for code-only prefabs
+ * you just need to set a `guid` — no manual `registerPrefabProvider` call needed, as long as
+ * all clients run the same setup code that creates the same prefab with the same guid.
+ *
+ * @param object The object to instantiate. Must have a `guid` property (set one for runtime objects).
+ * @param opts Options for the instantiation, including the network context to send the instantiate event to
+ * @param hostData Optional data about a file to download when this object is instantiated (e.g. when instantiated via file drop)
+ * @param save When false, the state of this instance will not be saved in the networking backend. Default is true.
+ * @returns The instantiated object, or null if instantiation failed (e.g. missing guid or network context)
+ * @see {@link syncDestroy} - Destroy objects across the network
+ * @see {@link onSyncInstantiate} - Register a callback to get references to remotely instantiated objects
+ * @see {@link registerPrefabProvider} - Manually register a prefab provider (auto-registered by syncInstantiate)
+ * @see {@link unregisterPrefabProvider} - Remove a registered prefab provider
+ * @category Networking
+ *
+ * @example Basic usage with a runtime-created prefab
+ * ```ts
+ * const cookie = ObjectUtils.createPrimitive("Cube", { color: 0xff8c00 });
+ * cookie.guid = "cookie-prefab";
+ * // No need to call registerPrefabProvider — syncInstantiate auto-registers it
+ * syncInstantiate(cookie, { parent: ctx.scene, deleteOnDisconnect: false });
+ * ```
+ *
+ * @example With deterministic seed (advanced)
+ * ```ts
+ * const idProvider = new InstantiateIdProvider("my-seed");
+ * const instance = syncInstantiate(prefab, { context, idProvider });
+ * ```
+ * The seed generates deterministic guids via UUID v5, so all clients produce identical
+ * identifiers for the clone and its children without sending them over the network.
  */
 export function syncInstantiate(object: GameObject | Object3D, opts: SyncInstantiateOptions, hostData?: HostData, save?: boolean): GameObject | null {
 
     const obj: GameObject = object as GameObject;
 
     if (!obj.guid) {
-        console.warn("Can not instantiate: No guid", obj);
-        return null;
+        // Auto-assign guid from object name if available.
+        // The name must be the same on all clients (which it is when both run the same setup code).
+        if (obj.name) {
+            obj.guid = obj.name;
+        }
+        else {
+            console.error("[syncInstantiate] Can not instantiate: a 'guid' is required. For runtime-created objects, either set a name (`obj.name = 'my-prefab'`) or a guid (`obj.guid = 'my-prefab-id'`). The identifier must be the same on all clients.", obj);
+            return null;
+        }
     }
 
-    if (!opts.context) opts.context = Context.Current;
+    // Auto-register the prefab provider if none exists for this guid.
+    // This allows runtime-created objects to work with syncInstantiate without
+    // manual Prefabs.register calls, as long as all clients create the
+    // same prefab with the same guid in their setup code.
+    if (!Prefabs.has(obj.guid)) {
+        Prefabs.register(obj.guid, async () => obj);
+    }
 
     if (!opts.context) {
-        console.error("Missing network instantiate options / reference to network connection in sync instantiate");
+        opts.context = Context.Current;
+    }
+
+    if (!opts.context) {
+        console.error("[syncInstantiate] Missing network instantiate options / reference to network connection in sync instantiate. Please pass in the Needle Engine context.");
         return null;
     }
 
@@ -318,7 +449,6 @@ const syncedInstantiated = new Array<WeakRef<Object3D>>();
 
 export function beginListenInstantiate(context: Context) {
 
-
     const cb1 = context.connection.beginListen(InstantiateEvent.NewInstanceCreated, async (model: NewInstanceModel) => {
         const obj: GameObject | null = await tryResolvePrefab(model.originalGuid, context.scene) as GameObject;
         if (model.preventCreation === true) {
@@ -350,6 +480,11 @@ export function beginListenInstantiate(context: Context) {
                 context.scene.add(inst);
             if (debug)
                 console.log("[Remote] new instance", "gameobject:", inst?.guid, obj);
+            // Notify listeners about the remote instantiation
+            for (const cb of _onSyncInstantiateCallbacks) {
+                try { cb(inst, model, context); }
+                catch (err) { console.error("Error in onSyncInstantiate callback", err); }
+            }
         }
     });
     const cb2 = context.connection.beginListen("left-room", () => {
@@ -377,21 +512,28 @@ function instantiateSeeded(obj: GameObject, opts: IInstantiateOptions | null): {
     return { seed: seed, instance: instance };
 }
 
-export declare type PrefabProviderCallback = (guid: string) => Promise<Object3D | null>;
+export { type PrefabProviderCallback,Prefabs } from "./engine_networking_prefabs.js";
+import { Prefabs } from "./engine_networking_prefabs.js";
 
-const registeredPrefabProviders: { [key: string]: PrefabProviderCallback } = {};
+/**
+ * Register a prefab provider. Forwards to {@link Prefabs.register}.
+ * @category Networking
+ */
+export function registerPrefabProvider(key: string, fn: (guid: string) => Promise<Object3D | null>) {
+    Prefabs.register(key, fn);
+}
 
-//** e.g. provide a function that can return a instantiated object when instantiation event is received */
-export function registerPrefabProvider(key: string, fn: PrefabProviderCallback) {
-    registeredPrefabProviders[key] = fn;
+/**
+ * Unregister a prefab provider. Forwards to {@link Prefabs.unregister}.
+ * @category Networking
+ */
+export function unregisterPrefabProvider(key: string) {
+    Prefabs.unregister(key);
 }
 
 async function tryResolvePrefab(guid: string, obj: Object3D): Promise<Object3D | null> {
-    const prov = registeredPrefabProviders[guid];
-    if (prov !== null && prov !== undefined) {
-        const res = await prov(guid);
-        if (res) return res;
-    }
+    const res = await Prefabs.resolve(guid);
+    if (res) return res;
     return tryFindObjectByGuid(guid, obj) as Object3D;
 }
 

package/src/engine/engine_networking_prefabs.ts

@@ -0,0 +1,80 @@
+import { Object3D } from "three";
+
+/**
+ * Callback type for prefab providers.
+ * @param guid The guid of the prefab to resolve
+ * @returns The prefab Object3D, or null if not found
+ */
+export declare type PrefabProviderCallback = (guid: string) => Promise<Object3D | null>;
+
+const registeredProviders: { [key: string]: PrefabProviderCallback } = {};
+
+/**
+ * Prefab registry for networked instantiation.
+ *
+ * When a remote {@link syncInstantiate} event is received, the engine looks up the prefab
+ * by its guid using this registry. Both GLB-loaded objects and runtime-created objects
+ * can be registered here.
+ *
+ * Note: {@link syncInstantiate} auto-registers prefabs if no provider exists for their guid,
+ * so manual registration is only needed for custom resolution logic.
+ *
+ * @example
+ * ```ts
+ * import { Prefabs, ObjectUtils } from "@needle-tools/engine";
+ *
+ * const cookie = ObjectUtils.createPrimitive("Cube", { color: 0xff8c00 });
+ * cookie.guid = "cookie-prefab";
+ * Prefabs.register("cookie-prefab", async () => cookie);
+ *
+ * console.log(Prefabs.list()); // ["cookie-prefab"]
+ * Prefabs.unregister("cookie-prefab");
+ * ```
+ *
+ * @category Networking
+ */
+export const Prefabs = {
+
+    /**
+     * Register a prefab provider that resolves objects by guid for networked instantiation.
+     * When a remote `syncInstantiate` event is received, the engine uses this to find the prefab
+     * to clone on the receiving client.
+     *
+     * @param key The guid to register the provider for
+     * @param fn Callback that returns the prefab Object3D for the given guid
+     */
+    register(key: string, fn: PrefabProviderCallback) {
+        registeredProviders[key] = fn;
+    },
+
+    /**
+     * Unregister a previously registered prefab provider.
+     * @param key The guid to unregister
+     */
+    unregister(key: string) {
+        delete registeredProviders[key];
+    },
+
+    /**
+     * Returns a list of all registered prefab provider keys (guids).
+     * Useful for debugging to see which prefabs are available for networked instantiation.
+     */
+    list(): string[] {
+        return Object.keys(registeredProviders);
+    },
+
+    /**
+     * Check if a prefab provider is registered for the given guid.
+     * @param key The guid to check
+     */
+    has(key: string): boolean {
+        return key in registeredProviders;
+    },
+
+    /** @internal Resolve a prefab by guid. Used by the networking system. */
+    async resolve(guid: string): Promise<Object3D | null> {
+        const prov = registeredProviders[guid];
+        if (prov) return prov(guid);
+        return null;
+    },
+} as const;

package/src/engine/postprocessing/api.ts

@@ -0,0 +1,2 @@
+export { PostProcessing } from "./index.js";
+export type { IPostProcessingEffect, IPostProcessingHandler, ITonemappingEffect } from "./types.js";

package/src/engine/postprocessing/index.ts

@@ -0,0 +1,2 @@
+export { PostProcessing } from "./postprocessing.js";
+export type { IPostProcessingEffect, IPostProcessingHandler, ITonemappingEffect } from "./types.js";

package/src/engine/postprocessing/postprocessing.ts

@@ -0,0 +1,322 @@
+import type { EffectComposer } from "postprocessing";
+import type { ToneMapping } from "three";
+import type { EffectComposer as ThreeEffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
+
+import { isDevEnvironment } from "../debug/index.js";
+import type { Context } from "../engine_context.js";
+import { DeviceUtilities, getParam } from "../engine_utils.js";
+import type { IPostProcessingEffect, IPostProcessingHandler, ITonemappingEffect } from "./types.js";
+
+const debug = getParam("debugpost");
+
+/**
+ * Core postprocessing stack accessible via `context.postprocessing`.
+ * Manages the effect pipeline independently of any specific component.
+ *
+ * Volumes and individual PostProcessingEffect components add/remove effects
+ * to this stack. The stack builds the EffectComposer pipeline when dirty.
+ *
+ * @example Add an effect directly
+ * ```ts
+ * const bloom = new BloomEffect({ intensity: 3 });
+ * this.context.postprocessing.addEffect(bloom);
+ * ```
+ *
+ * @example Remove an effect
+ * ```ts
+ * this.context.postprocessing.removeEffect(bloom);
+ * ```
+ */
+export class PostProcessing {
+
+    private readonly _context: Context;
+    private _handler: IPostProcessingHandler | null = null;
+    private readonly _effects: IPostProcessingEffect[] = [];
+    private _isDirty: boolean = false;
+
+    /** Currently active postprocessing effects in the stack */
+    get effects(): readonly IPostProcessingEffect[] {
+        return this._effects;
+    }
+
+    get dirty() { return this._isDirty; }
+    set dirty(value: boolean) { this._isDirty = value; }
+
+    /** The internal PostProcessingHandler that manages the EffectComposer pipeline */
+    get handler(): IPostProcessingHandler | null { return this._handler; }
+
+    /**
+     * The effect composer used to render postprocessing effects.
+     * This is set internally by the PostProcessingHandler when effects are applied.
+     */
+    get composer(): EffectComposer | ThreeEffectComposer | null { return this._composer; }
+    set composer(value: EffectComposer | ThreeEffectComposer | null) { this._composer = value; }
+    private _composer: EffectComposer | ThreeEffectComposer | null = null;
+
+    /**
+     * Set multisampling to "auto" to automatically adjust the multisampling level based on performance.
+     * Set to a number to manually set the multisampling level.
+     * @default "auto"
+     */
+    multisampling: "auto" | number = "auto";
+
+    /** When enabled, the device pixel ratio will be gradually reduced when FPS is low
+     * and restored when performance recovers.
+     * @default true
+     */
+    adaptiveResolution: boolean = true;
+
+    constructor(context: Context) {
+        this._context = context;
+    }
+
+    /**
+     * Add a post processing effect to the stack.
+     * The effect stack will be rebuilt on the next update.
+     */
+    addEffect(effect: IPostProcessingEffect): void {
+        if (this._effects.includes(effect)) return;
+        this._effects.push(effect);
+        this._isDirty = true;
+    }
+
+    /**
+     * Remove a post processing effect from the stack.
+     * The effect stack will be rebuilt on the next update.
+     */
+    removeEffect(effect: IPostProcessingEffect): void {
+        const index = this._effects.indexOf(effect);
+        if (index !== -1) {
+            this._effects.splice(index, 1);
+            this._isDirty = true;
+        }
+    }
+
+    /** Mark the stack as dirty so the effects are rebuilt on the next update */
+    markDirty(): void {
+        this._isDirty = true;
+    }
+
+    // --- Adaptive multisampling state ---
+    private _enabledTime: number = -1;
+    private _multisampleAutoChangeTime: number = 0;
+    private _multisampleAutoDecreaseTime: number = 0;
+
+    /** @internal Called from the context render loop to update the postprocessing pipeline */
+    update(): void {
+        const context = this._context;
+        if (context.isInXR) return;
+
+        // Wait for a camera before applying
+        if (this._isDirty && context.mainCamera) {
+            this.apply();
+        }
+
+        // In tonemapping-only mode, keep renderer values in sync with the active effect
+        if (this._tonemappingOnlyActive) {
+            const activeEffects = this._effects.filter(e => e.active && e.enabled && e.isToneMapping === true);
+            if (activeEffects.length > 0) {
+                const effect = activeEffects[activeEffects.length - 1] as ITonemappingEffect;
+                context.renderer.toneMapping = effect.threeToneMapping;
+                context.renderer.toneMappingExposure = effect.toneMappingExposure;
+            }
+            return;
+        }
+
+        if (!this._handler || !this._composer || this._handler.composer !== this._composer) return;
+
+        // The composer is always a pmndrs EffectComposer (created by PostProcessingHandler)
+        const composer = this._composer as EffectComposer;
+
+        // Handle context lost
+        if (context.renderer.getContext().isContextLost()) {
+            context.renderer.forceContextRestore();
+        }
+        if (composer.getRenderer() !== context.renderer)
+            composer.setRenderer(context.renderer);
+
+        composer.setMainScene(context.scene);
+
+        // --- Adaptive multisampling ---
+        if (this.multisampling === "auto") {
+            if (this._handler.hasSmaaEffect) {
+                if (this._handler.multisampling !== 0) {
+                    this._handler.multisampling = 0;
+                    if (debug || isDevEnvironment()) {
+                        console.log(`[PostProcessing] multisampling is disabled because it's set to 'auto' and there is an SMAA effect.\n\nIf you need multisampling consider changing 'auto' to a fixed value (e.g. 4).`);
+                    }
+                }
+            }
+            else {
+                const timeSinceLastChange = context.time.realtimeSinceStartup - this._multisampleAutoChangeTime;
+
+                if (context.time.realtimeSinceStartup - this._enabledTime > 2
+                    && timeSinceLastChange > .5
+                ) {
+                    const prev = this._handler.multisampling;
+
+                    if (this._handler.multisampling > 0 && context.time.smoothedFps <= 50) {
+                        this._multisampleAutoChangeTime = context.time.realtimeSinceStartup;
+                        this._multisampleAutoDecreaseTime = context.time.realtimeSinceStartup;
+                        let newMultiSample = this._handler.multisampling * .5;
+                        newMultiSample = Math.floor(newMultiSample);
+                        if (newMultiSample != this._handler.multisampling) {
+                            this._handler.multisampling = newMultiSample;
+                        }
+                        if (debug) console.debug(`[PostProcessing] Reduced multisampling from ${prev} to ${this._handler.multisampling}`);
+                    }
+                    else if (timeSinceLastChange > 1
+                        && context.time.smoothedFps >= 59
+                        && this._handler.multisampling < context.renderer.capabilities.maxSamples
+                        && context.time.realtimeSinceStartup - this._multisampleAutoDecreaseTime > 10
+                    ) {
+                        this._multisampleAutoChangeTime = context.time.realtimeSinceStartup;
+                        let newMultiSample = this._handler.multisampling <= 0 ? 1 : this._handler.multisampling * 2;
+                        newMultiSample = Math.floor(newMultiSample);
+                        if (newMultiSample !== this._handler.multisampling) {
+                            this._handler.multisampling = newMultiSample;
+                        }
+                        if (debug) console.debug(`[PostProcessing] Increased multisampling from ${prev} to ${this._handler.multisampling}`);
+                    }
+                }
+            }
+        }
+        else {
+            const newMultiSample = Math.max(0, Math.min(this.multisampling as number, context.renderer.capabilities.maxSamples));
+            if (newMultiSample !== this._handler.multisampling)
+                this._handler.multisampling = newMultiSample;
+        }
+
+        // --- Adaptive pixel ratio ---
+        this._handler.adaptivePixelRatio = this.adaptiveResolution;
+        this._handler.updateAdaptivePixelRatio();
+
+        // Update camera on passes if needed
+        if (context.mainCamera) {
+            const passes = composer.passes;
+            for (const pass of passes) {
+                if (pass.mainCamera && pass.mainCamera !== context.mainCamera) {
+                    composer.setMainCamera(context.mainCamera);
+                    break;
+                }
+            }
+        }
+    }
+
+    private _lastApplyTime?: number;
+    private _rapidApplyCount = 0;
+
+    // --- Tonemapping-only state ---
+    /** When true, tonemapping is applied directly to the renderer (no full pipeline) */
+    private _tonemappingOnlyActive = false;
+    private _previousToneMapping?: ToneMapping;
+    private _previousToneMappingExposure?: number;
+
+    private apply() {
+        if (debug) console.log(`[PostProcessing] Apply stack (${this._effects.length} effects)`);
+
+        if (isDevEnvironment()) {
+            if (this._lastApplyTime !== undefined && Date.now() - this._lastApplyTime < 100) {
+                this._rapidApplyCount++;
+                if (this._rapidApplyCount === 5)
+                    console.warn("[PostProcessing] Detected rapid post processing modifications - this might be a bug");
+            }
+            this._lastApplyTime = Date.now();
+        }
+
+        this._isDirty = false;
+
+        // Collect active effects
+        const activeEffects = this._effects.filter(e => e.active && e.enabled);
+
+        if (activeEffects.length <= 0) {
+            this.restoreTonemapping();
+            this._handler?.unapply(false);
+            return;
+        }
+
+        // Check if ALL active effects are tonemapping-only
+        const allToneMapping = activeEffects.every(e => e.isToneMapping === true);
+
+        if (allToneMapping) {
+            // Use the last tonemapping effect added (last in the array)
+            const tonemappingEffect = activeEffects[activeEffects.length - 1] as ITonemappingEffect;
+
+            if (debug) console.log(`[PostProcessing] Only tonemapping effects in stack — applying directly to renderer`);
+
+            // Store previous values on first activation
+            if (!this._tonemappingOnlyActive) {
+                this._previousToneMapping = this._context.renderer.toneMapping as ToneMapping;
+                this._previousToneMappingExposure = this._context.renderer.toneMappingExposure;
+                this._tonemappingOnlyActive = true;
+            }
+
+            // Apply tonemapping directly to renderer
+            this._context.renderer.toneMapping = tonemappingEffect.threeToneMapping;
+            this._context.renderer.toneMappingExposure = tonemappingEffect.toneMappingExposure;
+
+            // Tear down any existing postprocessing pipeline
+            this._handler?.unapply(false);
+            return;
+        }
+
+        // We have non-tonemapping effects — restore renderer tonemapping if we were in tonemapping-only mode
+        this.restoreTonemapping();
+
+        // Build full postprocessing pipeline
+        this.ensureHandler()
+            .then(handler => {
+                if (!handler) return;
+                return handler.apply(activeEffects) as Promise<void> | void;
+            })
+            .then(() => {
+                if (this._handler) {
+                    if (this.multisampling === "auto") {
+                        this._handler.multisampling = DeviceUtilities.isMobileDevice()
+                            ? 2
+                            : 4;
+                    }
+                    else {
+                        this._handler.multisampling = Math.max(0, Math.min(this.multisampling as number, this._context.renderer.capabilities.maxSamples));
+                    }
+                    if (debug) console.debug(`[PostProcessing] Set multisampling to ${this._handler.multisampling} (Is Mobile: ${DeviceUtilities.isMobileDevice()})`);
+                }
+            });
+
+        this._enabledTime = this._context.time.realtimeSinceStartup;
+    }
+
+    /** Restore renderer tonemapping to previous values when leaving tonemapping-only mode */
+    private restoreTonemapping() {
+        if (this._tonemappingOnlyActive) {
+            if (this._previousToneMapping !== undefined)
+                this._context.renderer.toneMapping = this._previousToneMapping;
+            if (this._previousToneMappingExposure !== undefined)
+                this._context.renderer.toneMappingExposure = this._previousToneMappingExposure;
+            this._tonemappingOnlyActive = false;
+            this._previousToneMapping = undefined;
+            this._previousToneMappingExposure = undefined;
+            if (debug) console.log(`[PostProcessing] Restored renderer tonemapping`);
+        }
+    }
+
+    /** Lazily creates the PostProcessingHandler to avoid loading the postprocessing library until actually needed */
+    private async ensureHandler(): Promise<IPostProcessingHandler> {
+        if (!this._handler) {
+            const { PostProcessingHandler } = await import("../../engine-components/postprocessing/PostProcessingHandler.js");
+            if (!this._handler) {
+                this._handler = new PostProcessingHandler(this._context);
+            }
+        }
+        return this._handler;
+    }
+
+    /** @internal */
+    dispose() {
+        this.restoreTonemapping();
+        this._handler?.dispose();
+        this._handler = null;
+        this._composer = null;
+        this._effects.length = 0;
+    }
+}