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

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

@@ -1,14 +1,13 @@
-import type { Effect, EffectComposer } from "postprocessing";
+import type { Effect } from "postprocessing";
 
-import { isDevEnvironment, showBalloonMessage } from "../../engine/debug/index.js";
-import { Context } from "../../engine/engine_context.js";
+import { showBalloonMessage } from "../../engine/debug/index.js";
 import type { EditorModification, IEditorModification as IEditorModificationReceiver } from "../../engine/engine_editor-sync.js";
 import { serializeable } from "../../engine/engine_serialization_decorator.js";
-import { DeviceUtilities, getParam } from "../../engine/engine_utils.js";
+import { getParam } from "../../engine/engine_utils.js";
+import type { PostProcessing } from "../../engine/postprocessing/index.js";
 import { Behaviour } from "../Component.js";
 import { EffectWrapper } from "./Effects/EffectWrapper.js";
 import { PostProcessingEffect } from "./PostProcessingEffect.js";
-import { PostProcessingHandler } from "./PostProcessingHandler.js";
 import { IPostProcessingManager, setPostprocessingManagerType } from "./utils.js";
 import { VolumeParameter } from "./VolumeParameter.js";
 import { VolumeProfile } from "./VolumeProfile.js";
@@ -16,9 +15,12 @@ import { VolumeProfile } from "./VolumeProfile.js";
 const debug = getParam("debugpost");
 
 
-/** [Volume](https://engine.needle.tools/docs/api/Volume) The Volume/PostprocessingManager component is responsible for managing post processing effects.  
- * Add this component to any object in your scene to enable post processing effects.  
- * 
+/** [Volume](https://engine.needle.tools/docs/api/Volume) The Volume/PostprocessingManager component is responsible for managing post processing effects.
+ * Add this component to any object in your scene to enable post processing effects.
+ *
+ * Effects added to this Volume (via profile or code) are pushed to `context.postprocessing` when the Volume is enabled,
+ * and removed when it is disabled.
+ *
  * @example Add bloom
  * ```ts
  * const volume = new Volume();
@@ -28,22 +30,25 @@ const debug = getParam("debugpost");
  * }));
  * gameObject.addComponent(volume);
  * ```
- * 
+ *
  * @example Remove bloom
  * ```ts
  * volume.removeEffect(bloom);
  * ```
- * 
+ *
  * @example Add pixelation
  * ```ts
  * const pixelation = new PixelationEffect();
  * pixelation.granularity.value = 10;
  * volume.addEffect(pixelation);
  * ```
- * 
+ *
  * @summary Manage Post-Processing Effects
  * @category Rendering
  * @category Effects
+ * @see {@link VolumeProfile} for profile-based effect management
+ * @see {@link PostProcessingEffect} for creating custom effects
+ * @see {@link PostProcessing} for core Needle Engine postprocessing control, also accessible via `context.postprocessing`
  * @group Components
  */
 export class Volume extends Behaviour implements IEditorModificationReceiver, IPostProcessingManager {
@@ -52,7 +57,7 @@ export class Volume extends Behaviour implements IEditorModificationReceiver, IP
         return true;
     }
 
-    /** Currently active postprocessing effects */
+    /** Currently active postprocessing effects managed by this Volume */
     get effects() {
         return this._activeEffects;
     }
@@ -64,8 +69,9 @@ export class Volume extends Behaviour implements IEditorModificationReceiver, IP
     sharedProfile?: VolumeProfile;
 
     /**
-     * Set multisampling to "auto" to automatically adjust the multisampling level based on performance.   
+     * Set multisampling to "auto" to automatically adjust the multisampling level based on performance.
      * Set to a number to manually set the multisampling level.
+     * Pushed to `context.postprocessing.multisampling` when this Volume is active.
      * @default "auto"
      * @min 0
      * @max renderer.capabilities.maxSamples
@@ -76,6 +82,7 @@ export class Volume extends Behaviour implements IEditorModificationReceiver, IP
     /** When enabled, the device pixel ratio will be gradually reduced when FPS is low
      * and restored when performance recovers. This helps maintain smooth frame rates
      * on devices where full retina resolution is too expensive for postprocessing.
+     * Pushed to `context.postprocessing.adaptiveResolution` when this Volume is active.
      * Disable this if you need a fixed resolution and prefer consistent quality over frame rate.
      * @default true
      */
@@ -83,7 +90,7 @@ export class Volume extends Behaviour implements IEditorModificationReceiver, IP
     adaptiveResolution: boolean = true;
 
     /**
-     * Add a post processing effect to the stack and schedules the effect stack to be re-created.  
+     * Add a post processing effect to this Volume and push it to the core postprocessing stack.
      */
     addEffect<T extends PostProcessingEffect | Effect>(effect: T & { order?: number }): T {
         let entry = effect as PostProcessingEffect;
@@ -94,24 +101,34 @@ export class Volume extends Behaviour implements IEditorModificationReceiver, IP
         if (entry.gameObject === undefined) this.gameObject.addComponent(entry);
         if (this._effects.includes(entry)) return effect;
         this._effects.push(entry);
+        // Track as active so removeEffectsFromCore cleans it up on disable
+        if (!this._activeEffects.includes(entry))
+            this._activeEffects.push(entry);
+        // Push to core stack
+        this.context.postprocessing.addEffect(entry);
         this._isDirty = true;
         return effect;
     }
+
     /**
-     * Remove a post processing effect from the stack and schedules the effect stack to be re-created.
+     * Remove a post processing effect from this Volume and the core postprocessing stack.
      */
     removeEffect<T extends PostProcessingEffect | Effect>(effect: T): T {
 
         let index = -1;
+        let entry: PostProcessingEffect | undefined;
         if (!(effect instanceof PostProcessingEffect)) {
             index = this._effects.findIndex(e => e instanceof EffectWrapper && e.effect === effect);
+            if (index !== -1) entry = this._effects[index];
         }
         else {
             index = this._effects.indexOf(effect);
+            if (index !== -1) entry = this._effects[index];
         }
 
-        if (index !== -1) {
+        if (index !== -1 && entry) {
             this._effects.splice(index, 1);
+            this.context.postprocessing.removeEffect(entry);
             this._isDirty = true;
             return effect;
         }
@@ -119,15 +136,15 @@ export class Volume extends Behaviour implements IEditorModificationReceiver, IP
             // if the effect is part of the shared profile remove it from there
             const si = this.sharedProfile?.components?.indexOf(effect);
             if (si !== undefined && si !== -1) {
-                this._isDirty = true;
                 this.sharedProfile?.components?.splice(si, 1);
+                this.context.postprocessing.removeEffect(effect);
+                this._isDirty = true;
             }
         }
 
         return effect;
     }
 
-    private _postprocessing?: PostProcessingHandler;
     private readonly _activeEffects: PostProcessingEffect[] = [];
     private readonly _effects: PostProcessingEffect[] = [];
 
@@ -156,144 +173,46 @@ export class Volume extends Behaviour implements IEditorModificationReceiver, IP
         this.sharedProfile?.__init(this);
     }
 
-    private _componentEnabledTime: number = -1;
-    private _multisampleAutoChangeTime: number = 0;
-    private _multisampleAutoDecreaseTime: number = 0;
+    private _isDirty: boolean = false;
 
     /** @internal */
     onEnable(): void {
-        this._componentEnabledTime = this.context.time.realtimeSinceStartup;
         this._isDirty = true;
+        this.pushEffectsToCore();
+        this.syncConfigToCore();
     }
 
     /** @internal */
     onDisable() {
-        this._postprocessing?.unapply();
+        this.removeEffectsFromCore();
         this._isDirty = false;
     }
 
     /** @internal */
     onBeforeRender(): void {
-        if (!this.context.isInXR) {
-
-            // TODO: not sure when this was/could be the case? Maybe when using the default three composer?
-            // if (this.context.composer && (this.context.composer instanceof EffectComposer) === false) {
-            //     if (debug) console.warn("PostProcessing: The current composer is not an EffectComposer - this is not supported");
-            //     return;
-            // }
-
-            // Wait for the first frame to be rendered before creating because then we know we have a camera (issue 135)
-            if (this.context.mainCamera) {
-                if (this._isDirty) {
-                    this.apply();
-                }
-            }
-
-            if (this.context.composer && this._postprocessing && this._postprocessing.composer === this.context.composer) {
-                if (this.context.renderer.getContext().isContextLost()) {
-                    this.context.renderer.forceContextRestore();
-                }
-                if (this.context.composer.getRenderer() !== this.context.renderer)
-                    this.context.composer.setRenderer(this.context.renderer);
-
-                this.context.composer.setMainScene(this.context.scene);
-
-                if (this.multisampling === "auto") {
-
-                    // If the postprocessing handler is using depth+normals (e.g. with SMAA) we ALWAYS disable multisampling to avoid ugly edges
-                    if (this._postprocessing && (this._postprocessing.hasSmaaEffect)) {
-                        if (this._postprocessing.multisampling !== 0) {
-                            this._postprocessing.multisampling = 0;
-                            if (debug || isDevEnvironment()) {
-                                console.log(`[PostProcessing] multisampling is disabled because it's set to 'auto' on your PostprocessingManager/Volume component that also has an SMAA effect.\n\nIf you need multisampling consider changing 'auto' to a fixed value (e.g. 4).`);
-                            }
-                        }
-                    }
-                    else {
-                        const timeSinceLastChange = this.context.time.realtimeSinceStartup - this._multisampleAutoChangeTime;
-
-                        if (this.context.time.realtimeSinceStartup - this._componentEnabledTime > 2
-                            && timeSinceLastChange > .5
-                        ) {
-                            const prev = this._postprocessing.multisampling;
-
-                            if (this._postprocessing.multisampling > 0 && this.context.time.smoothedFps <= 50) {
-                                this._multisampleAutoChangeTime = this.context.time.realtimeSinceStartup;
-                                this._multisampleAutoDecreaseTime = this.context.time.realtimeSinceStartup;
-                                let newMultiSample = this._postprocessing.multisampling * .5;
-                                newMultiSample = Math.floor(newMultiSample);
-                                if (newMultiSample != this._postprocessing.multisampling) {
-                                    this._postprocessing.multisampling = newMultiSample;
-                                }
-                                if (debug) console.debug(`[PostProcessing] Reduced multisampling from ${prev} to ${this._postprocessing.multisampling}`);
-                            }
-                            // if performance is good for a while try increasing multisampling again
-                            else if (timeSinceLastChange > 1
-                                && this.context.time.smoothedFps >= 59
-                                && this._postprocessing.multisampling < this.context.renderer.capabilities.maxSamples
-                                && this.context.time.realtimeSinceStartup - this._multisampleAutoDecreaseTime > 10
-                            ) {
-                                this._multisampleAutoChangeTime = this.context.time.realtimeSinceStartup;
-                                let newMultiSample = this._postprocessing.multisampling <= 0 ? 1 : this._postprocessing.multisampling * 2;
-                                newMultiSample = Math.floor(newMultiSample);
-                                if (newMultiSample !== this._postprocessing.multisampling) {
-                                    this._postprocessing.multisampling = newMultiSample;
-                                }
-                                if (debug) console.debug(`[PostProcessing] Increased multisampling from ${prev} to ${this._postprocessing.multisampling}`);
-                            }
-                        }
-                    }
-                }
-                else {
-                    const newMultiSample = Math.max(0, Math.min(this.multisampling, this.context.renderer.capabilities.maxSamples));
-                    if (newMultiSample !== this._postprocessing.multisampling)
-                        this._postprocessing.multisampling = newMultiSample;
-                }
+        if (this._isDirty) {
+            this.removeEffectsFromCore();
+            this.pushEffectsToCore();
+            this._isDirty = false;
+        }
+        // Push config changes (user may change multisampling/adaptiveResolution at runtime)
+        this.syncConfigToCore();
 
-                // Adaptively reduce pixel ratio when FPS is low
-                this._postprocessing.adaptivePixelRatio = this.adaptiveResolution;
-                this._postprocessing.updateAdaptivePixelRatio();
-
-                // only set the main camera if any pass has a different camera
-                // trying to avoid doing this regularly since it involves doing potentially unnecessary work
-                // https://github.com/pmndrs/postprocessing/blob/3d3df0576b6d49aec9e763262d5a1ff7429fd91a/src/core/EffectComposer.js#L406
-                if (this.context.mainCamera) {
-                    const passes = this.context.composer.passes;
-                    for (const pass of passes) {
-                        if (pass.mainCamera && pass.mainCamera !== this.context.mainCamera) {
-                            this.context.composer.setMainCamera(this.context.mainCamera);
-                            break;
-                        }
-                    }
-                }
-            }
+        // Process queued editor modifications after the handler is ready
+        if (this.context.postprocessing.handler) {
+            this._applyPostQueue();
         }
     }
 
     /** @internal */
     onDestroy(): void {
-        this._postprocessing?.dispose();
+        this.removeEffectsFromCore();
     }
 
-    private _lastApplyTime?: number;
-    private _rapidApplyCount = 0;
-    private _isDirty: boolean = false;
-
-    private apply() {
-        if (debug) console.log(`Apply PostProcessing "${this.name || "unnamed"}"`);
-
-        if (isDevEnvironment()) {
-            if (this._lastApplyTime !== undefined && Date.now() - this._lastApplyTime < 100) {
-                this._rapidApplyCount++;
-                if (this._rapidApplyCount === 5)
-                    console.warn("Detected rapid post processing modifications - this might be a bug", this);
-            }
-            this._lastApplyTime = Date.now();
-        }
-
-        this._isDirty = false;
-
+    /** Collect active effects from profile + code and push them to context.postprocessing */
+    private pushEffectsToCore() {
         this._activeEffects.length = 0;
+
         // get from profile
         if (this.sharedProfile?.components) {
             const comps = this.sharedProfile.components;
@@ -308,36 +227,26 @@ export class Volume extends Behaviour implements IEditorModificationReceiver, IP
                 this._activeEffects.push(effect);
         }
 
-        if (this._activeEffects.length > 0) {
-            if (!this._postprocessing)
-                this._postprocessing = new PostProcessingHandler(this.context);
-
-            this._postprocessing.apply(this._activeEffects)
-                ?.then(() => {
-                    if (!this.activeAndEnabled) return;
-
-                    this._applyPostQueue();
-
-                    if (this._postprocessing) {
-                        if (this.multisampling === "auto") {
-                            this._postprocessing.multisampling = DeviceUtilities.isMobileDevice()
-                                ? 2
-                                : 4;
-                        }
-                        else {
-                            this._postprocessing.multisampling = Math.max(0, Math.min(this.multisampling, this.context.renderer.capabilities.maxSamples));
-                        }
-                        if (debug) console.debug(`[PostProcessing] Set multisampling to ${this._postprocessing.multisampling} (Is Mobile: ${DeviceUtilities.isMobileDevice()})`);
-                    }
-                    else if (debug) {
-                        console.warn(`[PostProcessing] No composer found`);
-                    }
-                })
+        const pp = this.context.postprocessing;
+        for (const effect of this._activeEffects) {
+            pp.addEffect(effect);
         }
-        else {
-            this._postprocessing?.unapply(false);
+    }
+
+    /** Remove all effects this Volume contributed from the core stack */
+    private removeEffectsFromCore() {
+        const pp = this.context.postprocessing;
+        for (const effect of this._activeEffects) {
+            pp.removeEffect(effect);
         }
+        this._activeEffects.length = 0;
+    }
 
+    /** Push multisampling and adaptiveResolution config to the core stack */
+    private syncConfigToCore() {
+        const pp = this.context.postprocessing;
+        pp.multisampling = this.multisampling;
+        pp.adaptiveResolution = this.adaptiveResolution;
     }
 
     private _applyPostQueue() {
@@ -352,7 +261,7 @@ export class Volume extends Behaviour implements IEditorModificationReceiver, IP
 
         if (modification.propertyName.startsWith("postprocessing.")) {
 
-            if (!this._postprocessing) {
+            if (!this.context.postprocessing.handler) {
                 if (!this._modificationQueue) this._modificationQueue = new Map<string, EditorModification>();
                 this._modificationQueue.set(modification.propertyName, modification);
                 return true;
@@ -439,4 +348,4 @@ const effectVolumeProperties: Map<string, string[]> = new Map<string, string[]>(
 
 setPostprocessingManagerType(Volume);
 
-export { Volume as PostProcessingManager };
+export { Volume as PostProcessingManager };

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

@@ -2,5 +2,6 @@ export * from "./PostProcessingEffect.js";
 export * from "./PostProcessingHandler.js"
 export { PostProcessingEffectOrder } from "./utils.js";
 export { PostProcessingManager } from "./Volume.js"
+export { Volume } from "./Volume.js"
 export * from "./VolumeParameter.js"
 export * from "./VolumeProfile.js";

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

@@ -26,6 +26,7 @@ export function setPostprocessingManagerType(type: ConstructorConcrete<IPostProc
     PostprocessingManagerType = type;
 }
 
+/** @deprecated Use `context.postprocessing` instead. Effects now register directly with the core postprocessing stack. */
 export function findPostProcessingManager(effect: PostProcessingEffect): IPostProcessingManager | null {
     let obj = effect.gameObject as Object3D | null;
     while (obj) {
@@ -39,6 +40,7 @@ export function findPostProcessingManager(effect: PostProcessingEffect): IPostPr
     return null;
 }
 
+/** @deprecated Use `context.postprocessing` instead. Effects now register directly with the core postprocessing stack. */
 export function getPostProcessingManager(effect: PostProcessingEffect): IPostProcessingManager | null {
     let manager: IPostProcessingManager | null = findPostProcessingManager(effect);
     if (!manager) {

package/src/engine-components/ui/Canvas.ts

@@ -132,7 +132,7 @@ export class Canvas extends UIRootComponent implements ICanvas {
         this._renderMode = val;
         this.onRenderSettingsChanged();
     }
-    private _renderMode: RenderMode = RenderMode.Undefined;
+    private _renderMode: RenderMode = RenderMode.WorldSpace;
 
     private _rootCanvas!: Canvas;
 
@@ -159,7 +159,7 @@ export class Canvas extends UIRootComponent implements ICanvas {
     worldCamera?: Camera;
 
     @serializable()
-    planeDistance: number = -1;
+    planeDistance: number = 100;
 
     awake() {
         //@ts-ignore

package/src/engine-components/ui/Graphic.ts

@@ -35,8 +35,12 @@ export class Graphic extends BaseUIComponent implements IGraphic, IRectTransform
         if (!this._color) this._color = new RGBAColor(1, 1, 1, 1);
         return this._color;
     }
-    set color(col: RGBAColor) {
-        const changed = !this._color || this._color.r !== col.r || this._color.g !== col.g || this._color.b !== col.b || this._color.alpha !== col.alpha;
+    set color(col: RGBAColor | Color) {
+        const changed = !this._color
+            || this._color.r !== col.r
+            || this._color.g !== col.g
+            || this._color.b !== col.b
+            || ("alpha" in col ? this._color.alpha !== col.alpha : this._color.alpha !== 1);
         if (!changed) return;
         if (!this._color) {
             this._color = new RGBAColor(1, 1, 1, 1);
@@ -44,6 +48,7 @@ export class Graphic extends BaseUIComponent implements IGraphic, IRectTransform
         this._color.copy(col);
         this.onColorChanged();
     }
+    private _color: RGBAColor = null!;
 
     private _alphaFactor: number = 1;
     setAlphaFactor(factor: number) {
@@ -88,7 +93,6 @@ export class Graphic extends BaseUIComponent implements IGraphic, IRectTransform
     raycastTarget: boolean = true;
 
     protected uiObject: ThreeMeshUI.Block | null = null;
-    private _color: RGBAColor = null!;
 
     private _rect: RectTransform | null = null;