@needle-tools/engine 4.6.1-next.26cf56c → 4.6.1-next.cd98b8c

package/lib/engine-components/postprocessing/utils.js

@@ -1,6 +1,7 @@
 import { isDevEnvironment } from "../../engine/debug/index.js";
 import { addComponent } from "../../engine/engine_components.js";
 import { foreachComponentEnumerator } from "../../engine/engine_gameobject.js";
+import { MODULES } from "../../engine/engine_modules.js";
 import { getParam } from "../../engine/engine_utils.js";
 export const debug = getParam("debugpost");
 let PostprocessingManagerType = null;
@@ -35,4 +36,101 @@ export function getPostProcessingManager(effect) {
     }
     return manager;
 }
+/**
+ * Default priority for post-processing effects. This can be used to sort effects by their rendering order when creating custom effects.
+ * E.g. in your custom effect, you can set `priority: PostProcessingEffectPriority.Bloom + 1;` to ensure it gets rendered after the bloom effect.
+ * OR `priority: PostProcessingEffectPriority.Bloom - 1;` to ensure it gets rendered before the bloom effect.
+ * @example
+ * ```typescript
+ * import { PostProcessingEffectPriority } from "@needle-tools/engine"
+ *
+ * export class MyCustomEffect extends PostProcessingEffect {
+ *    priority: PostProcessingEffectPriority.Bloom + 1; // render after bloom
+ *
+ *    // ... your effect code
+ * }
+ * ```
+ */
+export const PostProcessingEffectPriority = {
+    NormalPass: 0,
+    DepthDownsamplingPass: 10,
+    SMAA: 20,
+    SSAO: 30,
+    TiltShift: 40,
+    DepthOfField: 50,
+    ChromaticAberration: 60,
+    Bloom: 70,
+    Vignette: 80,
+    Pixelation: 90,
+    ToneMapping: 100,
+    HueSaturation: 110,
+    BrightnessContrast: 120,
+    // Sharpening: 130,
+};
+// let effectsOrder: Array<Constructor<Effect | Pass>> | null = null;
+let builtinOrder = null;
+export function orderEffects(effects) {
+    if (debug === "verbose")
+        console.debug("Before ordering effects", [...effects]);
+    if (!builtinOrder) {
+        builtinOrder = new Map();
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.NormalPass, PostProcessingEffectPriority.NormalPass);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.DepthDownsamplingPass, PostProcessingEffectPriority.DepthDownsamplingPass);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.SMAAEffect, PostProcessingEffectPriority.SMAA);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.SSAOEffect, PostProcessingEffectPriority.SSAO);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.TiltShiftEffect, PostProcessingEffectPriority.TiltShift);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.DepthOfFieldEffect, PostProcessingEffectPriority.DepthOfField);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.ChromaticAberrationEffect, PostProcessingEffectPriority.ChromaticAberration);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.BloomEffect, PostProcessingEffectPriority.Bloom);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.VignetteEffect, PostProcessingEffectPriority.Vignette);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.PixelationEffect, PostProcessingEffectPriority.Pixelation);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.ToneMappingEffect, PostProcessingEffectPriority.ToneMapping);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.HueSaturationEffect, PostProcessingEffectPriority.HueSaturation);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.BrightnessContrastEffect, PostProcessingEffectPriority.BrightnessContrast);
+    }
+    // enforce correct order of effects (e.g. DOF before Bloom)
+    effects.sort((a, b) => {
+        // we use find index here because sometimes constructor names are prefixed with `_`
+        // TODO: find a more robust solution that isnt name based (not sure if that exists tho... maybe we must give effect TYPES some priority/index)
+        const aidx = typeof a.priority === "number" ? a.priority : builtinOrder.get(a.effect.constructor) || -1;
+        const bidx = typeof b.priority === "number" ? b.priority : builtinOrder.get(b.effect.constructor) || -1;
+        // Unknown effects should be rendered first
+        if (aidx < 0) {
+            if (debug)
+                console.warn("Unknown effect found: ", a.constructor.name);
+            return -1;
+        }
+        else if (bidx < 0) {
+            if (debug)
+                console.warn("Unknown effect found: ", b.constructor.name);
+            return 1;
+        }
+        // if (aidx < 0) return 1;
+        // if (bidx < 0) return -1;
+        return aidx - bidx;
+    });
+    // effects.sort((a, b) => {
+    //     if (a.beforeEffect) {
+    //         const beforeA = effectsOrder!.findIndex(e => a.beforeEffect!.constructor.name.endsWith(e.name));
+    //         if (beforeA >= 0) {
+    //             return -1; // before effect should be rendered first
+    //         }
+    //         else {
+    //             return 1; // no before effect, so we can keep the order
+    //         }
+    //     }
+    //     else if (b.beforeEffect) {
+    //         const beforeB = effectsOrder!.findIndex(e => b.beforeEffect!.constructor.name.endsWith(e.name));
+    //         if (beforeB >= 0) {
+    //             return 1; // before effect should be rendered first
+    //         }
+    //         else if (a.beforeEffect) {
+    //             return -1; // no before effect, so we can keep the order
+    //         }
+    //     }
+    //     return 0; // no before effect, so we can keep the order
+    // });
+    if (debug === "verbose")
+        console.debug("After ordering effects", [...effects]);
+}
 //# sourceMappingURL=utils.js.map

package/lib/engine-components/postprocessing/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/engine-components/postprocessing/utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAE/E,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAGxD,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;AAW3C,IAAI,yBAAyB,GAAuD,IAAI,CAAC;AAEzF,MAAM,UAAU,4BAA4B,CAAC,IAAiD;IAC1F,yBAAyB,GAAG,IAAI,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,MAA4B;IAClE,IAAI,GAAG,GAAG,MAAM,CAAC,UAA6B,CAAC;IAC/C,OAAO,GAAG,EAAE;QACR,KAAK,MAAM,IAAI,IAAI,0BAA0B,CAAC,GAAG,CAAC,EAAE;YAChD,IAAK,IAA0C,CAAC,uBAAuB,KAAK,IAAI,EAAE;gBAC9E,OAAO,IAAyC,CAAC;aACpD;SACJ;QACD,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC;KACpB;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,MAA4B;IACjE,IAAI,OAAO,GAAkC,yBAAyB,CAAC,MAAM,CAAC,CAAC;IAC/E,IAAI,CAAC,OAAO,EAAE;QACV,IAAI,yBAAyB,EAAE;YAC3B,IAAI,KAAK;gBACL,OAAO,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;YAChE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;YAC3B,OAAO,GAAG,YAAY,CAAC,KAAK,EAAE,yBAAyB,CAAC,CAAC;SAC5D;aACI;YACD,IAAI,gBAAgB,EAAE;gBAClB,OAAO,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;SACxD;KACJ;IACD,OAAO,OAAO,CAAC;AACnB,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/engine-components/postprocessing/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/engine",
-  "version": "4.6.1-next.26cf56c",
+  "version": "4.6.1-next.cd98b8c",
   "description": "Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.",
   "main": "dist/needle-engine.min.js",
   "exports": {

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

@@ -1,4 +1,4 @@
-import type { BloomEffect as _BloomEffect } from "postprocessing";
+import { BloomEffect as _BloomEffect, EffectAttribute } from "postprocessing";
 import { MathUtils } from "three";
 
 import { MODULES } from "../../../engine/engine_modules.js";
@@ -91,8 +91,10 @@ export class BloomEffect extends PostProcessingEffect {
                 luminanceThreshold: this.threshold.value,
                 luminanceSmoothing: this.scatter.value,
                 radius: 0.85, // default value
-                intensity: this.intensity.value,
+                intensity: this.intensity.value, 
             });
+            // @ts-ignore Well... it's protected but bloom needs this :(
+            bloom.setAttributes(EffectAttribute.CONVOLUTION);
         }
 
         this.intensity.onValueChanged = newValue => {

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

@@ -55,6 +55,25 @@ export abstract class PostProcessingEffect extends Component implements IEffectP
 
     get isPostProcessingEffect() { return true; }
 
+    /**
+     * The priority of this effect. The higher the priority the later the effect will be applied in the post processing stack.
+     * This can be used to control the order of effects when multiple effects are applied.  
+     * It is recommended to use the PostProcessingEffectPriority constant to order your custom effects before or after built-in effects.  
+     * @default `undefined` (no specific priority set, will be applied in the order of registration)
+     * 
+     * @example
+     * ```typescript
+     * import { PostProcessingEffectPriority } from "@needle-tools/engine"
+     * 
+     * export class MyCustomEffect extends PostProcessingEffect {
+     *    priority: PostProcessingEffectPriority.Bloom + 1; // render after bloom
+     *    
+     *    // ... the rest of your effect code
+     * }
+     * ```
+     */
+    priority: number | undefined = undefined;
+
     constructor(params: any = undefined) {
         super();
         if (params) {

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

@@ -1,5 +1,5 @@
 import type { Effect, EffectComposer, Pass, ToneMappingEffect as _TonemappingEffect } from "postprocessing";
-import { Camera as Camera3, HalfFloatType, NoToneMapping } from "three";
+import { Camera as Camera3, HalfFloatType, NoToneMapping, Scene } from "three";
 
 import { showBalloonWarning } from "../../engine/debug/index.js";
 // import { internal_SetSharpeningEffectModule } from "./Effects/Sharpening.js";
@@ -9,13 +9,13 @@ import type { Constructor } from "../../engine/engine_types.js";
 import { DeviceUtilities, getParam } from "../../engine/engine_utils.js";
 import { Camera } from "../Camera.js";
 import { PostProcessingEffect, PostProcessingEffectContext } from "./PostProcessingEffect.js";
+import { orderEffects, PostprocessingEffectData } from "./utils.js";
 
 declare const NEEDLE_USE_POSTPROCESSING: boolean;
 globalThis["NEEDLE_USE_POSTPROCESSING"] = globalThis["NEEDLE_USE_POSTPROCESSING"] !== undefined ? globalThis["NEEDLE_USE_POSTPROCESSING"] : true;
 
 
 const debug = getParam("debugpost");
-const dontMergePasses = getParam("debugpostpasses");
 
 const activeKey = Symbol("needle:postprocessing-handler");
 const autoclearSetting = Symbol("needle:previous-autoclear-state");
@@ -27,7 +27,7 @@ export class PostProcessingHandler {
 
     private _composer: EffectComposer | null = null;
     private _lastVolumeComponents?: PostProcessingEffect[];
-    private _effects: Array<Effect | Pass> = [];
+    private readonly _effects: Array<PostprocessingEffectData> = [];
 
     get isActive() {
         return this._isActive;
@@ -60,7 +60,7 @@ export class PostProcessingHandler {
         return this.onApply(this.context, components);
     }
 
-    unapply() {
+    unapply(dispose: boolean = true) {
         if (debug) console.log("Unapplying postprocessing effects");
         this._isActive = false;
         if (this._lastVolumeComponents) {
@@ -73,21 +73,26 @@ export class PostProcessingHandler {
         const active = context[activeKey] as PostProcessingHandler | null;
         if (active === this) {
             delete context[activeKey];
+
+            // Restore the auto clear setting
+            if (typeof context.renderer[autoclearSetting] === "boolean") {
+                context.renderer.autoClear = context.renderer[autoclearSetting];
+            }
         }
+
+        this._composer?.removeAllPasses();
+        if (dispose) this._composer?.dispose();
+
         if (context.composer === this._composer) {
-            context.composer?.dispose();
             context.composer = null;
         }
-        if (typeof context.renderer[autoclearSetting] === "boolean") {
-            context.renderer.autoClear = context.renderer[autoclearSetting];
-        }
     }
 
     dispose() {
-        this.unapply();
+        this.unapply(true);
 
         for (const effect of this._effects) {
-            effect.dispose();
+            effect.effect.dispose();
         }
         this._effects.length = 0;
         this._composer = null;
@@ -105,6 +110,7 @@ export class PostProcessingHandler {
             // import("./Effects/Sharpening.effect")
         ]);
 
+
         // try {
         //     internal_SetSharpeningEffectModule(modules[2]);
         // }
@@ -141,10 +147,22 @@ export class PostProcessingHandler {
                     // apply or collect effects
                     const res = component.apply(ctx);
                     if (!res) continue;
+
+
                     if (Array.isArray(res)) {
-                        this._effects.push(...res);
+                        for (const effect of res) {
+                            this._effects.push({
+                                effect,
+                                priority: component.priority
+                            });
+                        }
+                    }
+                    else {
+                        this._effects.push({
+                            effect: res,
+                            priority: component.priority
+                        });
                     }
-                    else this._effects.push(res);
                 }
             }
             else {
@@ -157,7 +175,7 @@ export class PostProcessingHandler {
         if (this.context.renderer.toneMapping != NoToneMapping) {
             if (!this._effects.find(e => e instanceof MODULES.POSTPROCESSING.MODULE.ToneMappingEffect)) {
                 const tonemapping = new MODULES.POSTPROCESSING.MODULE.ToneMappingEffect();
-                this._effects.push(tonemapping);
+                this._effects.push({ effect: tonemapping });
             }
         }
 
@@ -175,9 +193,16 @@ export class PostProcessingHandler {
 
     /** Build composer passes */
     private applyEffects(context: Context) {
+        // Reset state
+        this._anyPassHasDepth = false;
+        this._anyPassHasNormal = false;
+        this._hasSmaaEffect = false;
 
         const effectsOrPasses = this._effects;
-        if (effectsOrPasses.length <= 0) return;
+        if (effectsOrPasses.length <= 0) {
+            return;
+        }
+
         const camera = context.mainCameraComponent as Camera;
         const renderer = context.renderer;
         const scene = context.scene;
@@ -186,13 +211,12 @@ export class PostProcessingHandler {
         // Store the auto clear setting because the postprocessing composer just disables it
         // and when we disable postprocessing we want to restore the original setting
         // https://github.com/pmndrs/postprocessing/blob/271944b74b543a5b743a62803a167b60cc6bb4ee/src/core/EffectComposer.js#L230C12-L230C12
+        // First we need to get the previously set autoClear setting, if it exists
+        if (typeof renderer[autoclearSetting] === "boolean") {
+            renderer.autoClear = renderer[autoclearSetting];
+        }
         renderer[autoclearSetting] = renderer.autoClear;
 
-        // Reset state
-        this._anyPassHasDepth = false;
-        this._anyPassHasNormal = false;
-        this._hasSmaaEffect = false;
-
         for (const ef of effectsOrPasses) {
             if (ef instanceof MODULES.POSTPROCESSING.MODULE.SMAAEffect) {
                 this._hasSmaaEffect = true;
@@ -229,63 +253,50 @@ export class PostProcessingHandler {
         screenpass.mainScene = scene;
         composer.addPass(screenpass);
 
-        const automaticEffectsOrdering = true;
-        if (automaticEffectsOrdering && !dontMergePasses) {
-            try {
-                this.orderEffects();
+        try {
+            orderEffects(this._effects);
 
-                const effects: Array<Effect> = [];
+            const effectsToMerge: Array<Effect> = [];
+            let hasConvolutionEffectInArray = false;
 
-                for (const ef of effectsOrPasses) {
-                    if (ef instanceof MODULES.POSTPROCESSING.MODULE.Effect) {
-                        effects.push(ef as Effect);
-                    }
-                    else if (ef instanceof MODULES.POSTPROCESSING.MODULE.Pass) {
-                        ef.renderToScreen = false;
-                        composer.addPass(ef as Pass);
-                    }
-                    else {
-                        // seems some effects are not correctly typed, but three can deal with them,
-                        // so we might need to just pass them through
-                        composer.addPass(ef);
-                    }
-                }
-
-                // create and apply uber pass
-                if (effects.length > 0) {
-                    const pass = new MODULES.POSTPROCESSING.MODULE.EffectPass(cam, ...effects);
-                    pass.name = effects.map(e => e.name).join(", ");
-                    pass.mainScene = scene;
-                    pass.enabled = true;
-                    pass.renderToScreen = false;
-                    composer.addPass(pass);
-                }
-            }
-            catch (e) {
-                console.error("Error while applying postprocessing effects", e);
-                composer.removeAllPasses();
-            }
-        }
-        else {
-            // we still want to sort passes, but we do not want to merge them for debugging
-            if (automaticEffectsOrdering)
-                this.orderEffects();
-
-            for (const ef of effectsOrPasses) {
+            for (const entry of effectsOrPasses) {
+                const ef = entry.effect;
                 if (ef instanceof MODULES.POSTPROCESSING.MODULE.Effect) {
-                    const pass = new MODULES.POSTPROCESSING.MODULE.EffectPass(cam, ef as Effect);
-                    pass.name = ef.name;
-                    composer.addPass(pass);
+                    const attributes = ef.getAttributes();
+                    const convolution = MODULES.POSTPROCESSING.MODULE.EffectAttribute.CONVOLUTION;
+                    if (attributes & convolution) {
+                        console.log("[PostProcessing] Convolution effect detected: " + ef.name, hasConvolutionEffectInArray);
+                        if (hasConvolutionEffectInArray) {
+                            hasConvolutionEffectInArray = false;
+                            console.log("[PostProcessing] Merging effects with convolution effect in array", effectsToMerge.map(e => e.name).join(", "));
+                            this.createPassForMergeableEffects(effectsToMerge, composer, cam, scene);
+
+                        }
+                        hasConvolutionEffectInArray = true;
+                    }
+                    // Otherwise we can merge it
+                    effectsToMerge.push(ef as Effect);
                 }
                 else if (ef instanceof MODULES.POSTPROCESSING.MODULE.Pass) {
+                    hasConvolutionEffectInArray = false;
+                    this.createPassForMergeableEffects(effectsToMerge, composer, cam, scene);
                     ef.renderToScreen = false;
                     composer.addPass(ef as Pass);
                 }
-                else
+                else {
                     // seems some effects are not correctly typed, but three can deal with them,
-                    // so we just pass them through
+                    // so we might need to just pass them through
+                    hasConvolutionEffectInArray = false;
+                    this.createPassForMergeableEffects(effectsToMerge, composer, cam, scene);
                     composer.addPass(ef);
+                }
             }
+
+            this.createPassForMergeableEffects(effectsToMerge, composer, cam, scene);
+        }
+        catch (e) {
+            console.error("Error while applying postprocessing effects", e);
+            composer.removeAllPasses();
         }
 
         // The last pass is the one that renders to the screen, so we need to set the gamma correction for it (and enable it for all others)
@@ -314,56 +325,20 @@ export class PostProcessingHandler {
         if (debug) this._onCreateEffectsDebug(this._composer!, cam);
     }
 
-    private orderEffects() {
-        if (debug === "verbose") console.debug("Before ordering effects", [...this._effects]);
-
-        // Order of effects for correct results.
-        // Aligned with https://github.com/pmndrs/postprocessing/wiki/Effect-Merging#effect-execution-order
-        // We can not put this into global scope because then the module might not yet be initialized
-        effectsOrder ??= [
-            MODULES.POSTPROCESSING.MODULE.NormalPass,
-            MODULES.POSTPROCESSING.MODULE.DepthDownsamplingPass,
-            MODULES.POSTPROCESSING.MODULE.SMAAEffect,
-            MODULES.POSTPROCESSING.MODULE.SSAOEffect,
-            MODULES.POSTPROCESSING_AO.MODULE.N8AOPostPass,
-            MODULES.POSTPROCESSING.MODULE.TiltShiftEffect,
-            MODULES.POSTPROCESSING.MODULE.DepthOfFieldEffect,
-            MODULES.POSTPROCESSING.MODULE.ChromaticAberrationEffect,
-            MODULES.POSTPROCESSING.MODULE.BloomEffect,
-            MODULES.POSTPROCESSING.MODULE.SelectiveBloomEffect,
-            MODULES.POSTPROCESSING.MODULE.VignetteEffect,
-            MODULES.POSTPROCESSING.MODULE.PixelationEffect,
-            MODULES.POSTPROCESSING.MODULE.ToneMappingEffect,
-            MODULES.POSTPROCESSING.MODULE.HueSaturationEffect,
-            MODULES.POSTPROCESSING.MODULE.BrightnessContrastEffect,
-            // __SHARPENING_MODULE._SharpeningEffect,
-        ];
-
-
-        // TODO: enforce correct order of effects (e.g. DOF before Bloom)
-        const effects = this._effects;
-        effects.sort((a, b) => {
-            // we use find index here because sometimes constructor names are prefixed with `_`
-            // TODO: find a more robust solution that isnt name based (not sure if that exists tho... maybe we must give effect TYPES some priority/index)
-            const aidx = effectsOrder!.findIndex(e => a.constructor.name.endsWith(e.name));
-            const bidx = effectsOrder!.findIndex(e => b.constructor.name.endsWith(e.name));
-            // Unknown effects should be rendered first
-            if (aidx < 0) {
-                if (debug) console.warn("Unknown effect found: ", a.constructor.name);
-                return -1;
-            }
-            else if (bidx < 0) {
-                if (debug) console.warn("Unknown effect found: ", b.constructor.name);
-                return 1;
-            }
-            // if (aidx < 0) return 1;
-            // if (bidx < 0) return -1;
-            return aidx - bidx;
-        });
 
-        if (debug === "verbose") console.debug("After ordering effects", [...this._effects]);
-    }
 
+    /** Should be called before `composer.addPass()` to create an effect pass with all previously collected effects that can be merged up to that point */
+    private createPassForMergeableEffects(effects: Array<Effect>, composer: EffectComposer, camera: Camera3, scene: Scene) {
+        if (effects.length > 0) {
+            const pass = new MODULES.POSTPROCESSING.MODULE.EffectPass(camera, ...effects);
+            pass.name = effects.map(e => e.name).join(", ");
+            pass.mainScene = scene;
+            pass.enabled = true;
+            pass.renderToScreen = false;
+            composer.addPass(pass);
+            effects.length = 0; // Clear effects after adding them to the pass
+        }
+    }
 
 
 

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

@@ -257,7 +257,7 @@ export class Volume extends Behaviour implements IEditorModificationReceiver, IP
     private _isDirty: boolean = false;
 
     private apply() {
-        if (debug) console.log(`Apply PostProcessing "${this.name}"`);
+        if (debug) console.log(`Apply PostProcessing "${this.name || "unnamed"}"`);
 
         if (isDevEnvironment()) {
             if (this._lastApplyTime !== undefined && Date.now() - this._lastApplyTime < 100) {
@@ -269,7 +269,6 @@ export class Volume extends Behaviour implements IEditorModificationReceiver, IP
         }
 
         this._isDirty = false;
-        this.unapply();
 
         this._activeEffects.length = 0;
         // get from profile
@@ -312,16 +311,13 @@ export class Volume extends Behaviour implements IEditorModificationReceiver, IP
                         console.warn(`[PostProcessing] No composer found`);
                     }
                 })
-
+        }
+        else {
+            this._postprocessing?.unapply(false);
         }
 
     }
 
-    private unapply() {
-        this._postprocessing?.unapply();
-    }
-
-
     private _applyPostQueue() {
         if (this._modificationQueue) {
             for (const entry of this._modificationQueue.values()) this.onEditorModification(entry);

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

@@ -3,3 +3,4 @@ export * from "./PostProcessingHandler.js"
 export { PostProcessingManager } from "./Volume.js"
 export * from "./VolumeParameter.js"
 export * from "./VolumeProfile.js";
+export { PostProcessingEffectPriority } from "./utils.js";

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

@@ -1,9 +1,11 @@
+import type { Effect, Pass } from "postprocessing";
 import { Object3D } from "three";
 
 import { isDevEnvironment } from "../../engine/debug/index.js";
 import { addComponent } from "../../engine/engine_components.js";
 import { foreachComponentEnumerator } from "../../engine/engine_gameobject.js";
-import { ConstructorConcrete, IComponent } from "../../engine/engine_types.js";
+import { MODULES } from "../../engine/engine_modules.js";
+import { Constructor, ConstructorConcrete, IComponent } from "../../engine/engine_types.js";
 import { getParam } from "../../engine/engine_utils.js";
 import { type PostProcessingEffect } from "./PostProcessingEffect.js";
 
@@ -52,4 +54,116 @@ export function getPostProcessingManager(effect: PostProcessingEffect): IPostPro
         }
     }
     return manager;
-}
+}
+
+
+
+export type PostprocessingEffectData = {
+    effect: Effect | Pass;
+    priority?: number,
+}
+
+/**
+ * Default priority for post-processing effects. This can be used to sort effects by their rendering order when creating custom effects.
+ * E.g. in your custom effect, you can set `priority: PostProcessingEffectPriority.Bloom + 1;` to ensure it gets rendered after the bloom effect.
+ * OR `priority: PostProcessingEffectPriority.Bloom - 1;` to ensure it gets rendered before the bloom effect.
+ * @example
+ * ```typescript
+ * import { PostProcessingEffectPriority } from "@needle-tools/engine"
+ * 
+ * export class MyCustomEffect extends PostProcessingEffect {
+ *    priority: PostProcessingEffectPriority.Bloom + 1; // render after bloom
+ *    
+ *    // ... your effect code
+ * }
+ * ```
+ */
+export const PostProcessingEffectPriority = {
+    NormalPass: 0,
+    DepthDownsamplingPass: 10,
+    SMAA: 20,
+    SSAO: 30,
+    TiltShift: 40,
+    DepthOfField: 50,
+    ChromaticAberration: 60,
+    Bloom: 70,
+    Vignette: 80,
+    Pixelation: 90,
+    ToneMapping: 100,
+    HueSaturation: 110,
+    BrightnessContrast: 120,
+    // Sharpening: 130,
+}
+// let effectsOrder: Array<Constructor<Effect | Pass>> | null = null;
+
+let builtinOrder: Map<Constructor<Effect | Pass>, number> | null = null;
+
+export function orderEffects(effects: Array<PostprocessingEffectData>) {
+    if (debug === "verbose") console.debug("Before ordering effects", [...effects]);
+
+    if (!builtinOrder) {
+        builtinOrder = new Map<Constructor<Effect | Pass>, number>();
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.NormalPass, PostProcessingEffectPriority.NormalPass);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.DepthDownsamplingPass, PostProcessingEffectPriority.DepthDownsamplingPass);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.SMAAEffect, PostProcessingEffectPriority.SMAA);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.SSAOEffect, PostProcessingEffectPriority.SSAO);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.TiltShiftEffect, PostProcessingEffectPriority.TiltShift);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.DepthOfFieldEffect, PostProcessingEffectPriority.DepthOfField);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.ChromaticAberrationEffect, PostProcessingEffectPriority.ChromaticAberration);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.BloomEffect, PostProcessingEffectPriority.Bloom);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.VignetteEffect, PostProcessingEffectPriority.Vignette);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.PixelationEffect, PostProcessingEffectPriority.Pixelation);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.ToneMappingEffect, PostProcessingEffectPriority.ToneMapping);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.HueSaturationEffect, PostProcessingEffectPriority.HueSaturation);
+        builtinOrder.set(MODULES.POSTPROCESSING.MODULE.BrightnessContrastEffect, PostProcessingEffectPriority.BrightnessContrast);
+    }
+
+    // enforce correct order of effects (e.g. DOF before Bloom)
+    effects.sort((a, b) => {
+        // we use find index here because sometimes constructor names are prefixed with `_`
+        // TODO: find a more robust solution that isnt name based (not sure if that exists tho... maybe we must give effect TYPES some priority/index)
+        const aidx = typeof a.priority === "number" ? a.priority : builtinOrder!.get(a.effect.constructor as Constructor<Effect | Pass>) || -1;
+        const bidx = typeof b.priority === "number" ? b.priority : builtinOrder!.get(b.effect.constructor as Constructor<Effect | Pass>) || -1;
+
+        // Unknown effects should be rendered first
+        if (aidx < 0) {
+            if (debug) console.warn("Unknown effect found: ", a.constructor.name);
+            return -1;
+        }
+        else if (bidx < 0) {
+            if (debug) console.warn("Unknown effect found: ", b.constructor.name);
+            return 1;
+        }
+        // if (aidx < 0) return 1;
+        // if (bidx < 0) return -1;
+        return aidx - bidx;
+    });
+
+    // effects.sort((a, b) => {
+    //     if (a.beforeEffect) {
+    //         const beforeA = effectsOrder!.findIndex(e => a.beforeEffect!.constructor.name.endsWith(e.name));
+    //         if (beforeA >= 0) {
+    //             return -1; // before effect should be rendered first
+    //         }
+    //         else {
+    //             return 1; // no before effect, so we can keep the order
+    //         }
+    //     }
+    //     else if (b.beforeEffect) {
+    //         const beforeB = effectsOrder!.findIndex(e => b.beforeEffect!.constructor.name.endsWith(e.name));
+    //         if (beforeB >= 0) {
+    //             return 1; // before effect should be rendered first
+    //         }
+    //         else if (a.beforeEffect) {
+    //             return -1; // no before effect, so we can keep the order
+    //         }
+
+    //     }
+    //     return 0; // no before effect, so we can keep the order
+    // });
+
+
+    if (debug === "verbose") console.debug("After ordering effects", [...effects]);
+}
+
+