@directivegames/genesys.js 3.1.24

package/src/render/PostProcessManager.ts

@@ -0,0 +1,1025 @@
+import {
+  BlendFunction,
+  EffectComposer,
+  RenderPass,
+  SelectiveBloomEffect,
+  SMAAEffect,
+  SMAAPreset,
+  ToneMappingEffect,
+  ToneMappingMode
+} from 'postprocessing';
+import * as THREE from 'three';
+
+// Re-export for convenience
+export { ToneMappingMode, SMAAPreset };
+
+import { SceneComponent } from '../components/SceneComponent.js';
+
+import { EdgeOutlineEffect } from './EdgeOutlineEffect.js';
+import { EffectPassWrapper } from './postprocessing/EffectPassWrapper.js';
+import { ObjectOutlineEffect } from './postprocessing/ObjectOutlineEffect.js';
+
+import type { Actor } from '../actors/Actor';
+import type { Effect } from 'postprocessing';
+
+export type { EdgeOutlineEffectOptions } from './EdgeOutlineEffect.js';
+
+export enum PostProcessPass {
+  ObjectOutline = 'objectOutline',
+  EdgeOutline = 'edgeOutline',
+  Bloom = 'bloom',
+  SMAA = 'smaa',
+  ToneMapping = 'toneMapping',
+}
+
+// Configuration interfaces for data-driven effects
+export interface BaseEffectConfig {
+  type: PostProcessPass;
+  enabled?: boolean;
+}
+
+/** Configuration for the Bloom post-process effect. */
+export interface BloomEffectConfig extends BaseEffectConfig {
+  type: PostProcessPass.Bloom;
+  /** Bloom intensity (strength of the bloom effect). */
+  intensity?: number;
+  /** Luminance threshold for bloom (minimum brightness to bloom). */
+  luminanceThreshold?: number;
+  /** Luminance smoothing (softness of the threshold). */
+  luminanceSmoothing?: number;
+  /** Whether to use mipmap blur for bloom. */
+  mipmapBlur?: boolean;
+  /** Blur radius for mipmap blur. */
+  radius?: number;
+  /** Number of MIP levels for blur. */
+  levels?: number;
+  /** If true, background is ignored for bloom. */
+  ignoreBackground?: boolean;
+}
+
+export interface ObjectOutlineEffectConfig extends BaseEffectConfig {
+  type: PostProcessPass.ObjectOutline;
+  /** Edge thickness in pixels (1.0 = 1px, 2.0 = 2px, etc.) */
+  edgeThickness?: number;
+  /** Edge brightness multiplier (typically 50-100 for bright outlines due to tone mapping) */
+  edgeIntensity?: number;
+  /** Edge color in hex format (e.g., 0xffffff for white) */
+  visibleEdgeColor?: number;
+}
+
+export interface EdgeOutlineEffectConfig extends BaseEffectConfig {
+  type: PostProcessPass.EdgeOutline;
+  thickness?: number;
+  color?: number;
+  alpha?: number;
+}
+
+export interface SMAAEffectConfig extends BaseEffectConfig {
+  type: PostProcessPass.SMAA;
+  preset?: SMAAPreset;
+}
+
+export interface ToneMappingEffectConfig extends BaseEffectConfig {
+  type: PostProcessPass.ToneMapping;
+  mode?: ToneMappingMode;
+  exposure?: number;
+  /** Resolution of the luminance texture. Must be a power of two. Only affects adaptive tone mapping. */
+  resolution?: number;
+  /** White point for Reinhard2 operators. */
+  whitePoint?: number;
+  /** Middle grey factor for Reinhard2 operators. */
+  middleGrey?: number;
+  /** Minimum luminance. Prevents very high exposure in dark scenes. Only affects adaptive tone mapping. */
+  minLuminance?: number;
+  /** Average luminance. Used for non-adaptive Reinhard operator. */
+  averageLuminance?: number;
+  /** Luminance adaptation rate. Only affects adaptive tone mapping. */
+  adaptationRate?: number;
+}
+
+export type EffectConfig = BloomEffectConfig | ObjectOutlineEffectConfig | EdgeOutlineEffectConfig | SMAAEffectConfig | ToneMappingEffectConfig;
+
+export interface PostProcessConfiguration {
+  effects: EffectConfig[];
+}
+
+// Default configurations for each effect type
+export const DEFAULT_CONFIGS = {
+  [PostProcessPass.ObjectOutline]: {
+    enabled: false,
+    type: PostProcessPass.ObjectOutline,
+    edgeThickness: 1.0,
+    edgeIntensity: 100.0, // High value needed to compensate for tone mapping
+    visibleEdgeColor: 0xffffff,
+  } as ObjectOutlineEffectConfig,
+
+  [PostProcessPass.EdgeOutline]: {
+    enabled: false,
+    type: PostProcessPass.EdgeOutline,
+    thickness: 0.05,
+    color: 0xffffff,
+    alpha: 1.0,
+  } as EdgeOutlineEffectConfig,
+
+  [PostProcessPass.Bloom]: {
+    enabled: false,
+    type: PostProcessPass.Bloom,
+    intensity: 2.0,
+    luminanceThreshold: 1,
+    luminanceSmoothing: 0.2,
+    mipmapBlur: true,
+    radius: 0.85,
+    levels: 8,
+    ignoreBackground: true,
+  } as BloomEffectConfig,
+
+  [PostProcessPass.SMAA]: {
+    enabled: false,
+    type: PostProcessPass.SMAA,
+    preset: SMAAPreset.HIGH,
+  } as SMAAEffectConfig,
+
+  [PostProcessPass.ToneMapping]: {
+    enabled: true,
+    type: PostProcessPass.ToneMapping,
+    mode: ToneMappingMode.LINEAR,
+    exposure: 0.25,
+    resolution: 256,
+    whitePoint: 4.0,
+    middleGrey: 0.6,
+    minLuminance: 0.01,
+    averageLuminance: 1.0,
+    adaptationRate: 1.0,
+  } as ToneMappingEffectConfig,
+};
+
+/**
+ * PostProcessManager handles post-processing effects for rendering.
+ *
+ * Provides methods to configure various post-processing effects like bloom, tone mapping,
+ * SMAA anti-aliasing, and outline effects. Supports both complete configuration replacement
+ * and incremental updates. Also allows globally enabling/disabling all post-processing.
+ *
+ * @example
+ * ```typescript
+ * // Basic setup with bloom and tone mapping
+ * const config: PostProcessConfiguration = {
+ *   effects: [
+ *     {
+ *       type: PostProcessPass.Bloom,
+ *       enabled: true,
+ *       intensity: 1.5,
+ *       luminanceThreshold: 0.4
+ *     },
+ *     {
+ *       type: PostProcessPass.ToneMapping,
+ *       enabled: true,
+ *       mode: ToneMappingMode.ACES_FILMIC,
+ *       exposure: 1.2
+ *     }
+ *   ]
+ * };
+ *
+ * // Set complete configuration (resets to defaults first)
+ * postProcessManager.setConfiguration(config);
+ *
+ * // Update specific effects (merges with current)
+ * postProcessManager.updateConfiguration({
+ *   effects: [
+ *     { type: PostProcessPass.Bloom, intensity: 2.0 }
+ *   ]
+ * });
+ *
+ * // Configure individual effects
+ * postProcessManager.configureEffect(PostProcessPass.Bloom, {
+ *   enabled: true,
+ *   intensity: 1.8,
+ *   luminanceThreshold: 0.3
+ * });
+ *
+ * // Enable/disable passes
+ * postProcessManager.enablePasses(PostProcessPass.Bloom, PostProcessPass.SMAA);
+ * postProcessManager.disablePasses(PostProcessPass.ObjectOutline);
+ *
+ * // Globally enable/disable all post-processing
+ * postProcessManager.setPostProcessingEnabled(false); // Disables all post-processing
+ * postProcessManager.setPostProcessingEnabled(true);  // Re-enables post-processing
+ *
+ * // Get current configuration
+ * const currentConfig = postProcessManager.getAllConfigurations();
+ * ```
+ *
+ * ## Method Differences
+ *
+ * ### setConfiguration()
+ * - Resets to DEFAULT_CONFIG first
+ * - Then applies provided configuration
+ * - Result: Clean slate with only specified effects
+ * - **Use case**: Loading saved worlds, switching presets
+ *
+ * ### updateConfiguration()
+ * - Merges with current configuration
+ * - Preserves existing effects
+ * - Updates/adds only specified effects
+ * - **Use case**: Settings panels, gameplay adjustments
+ *
+ * ### configure()
+ * - Same as updateConfiguration()
+ * - Kept for backward compatibility
+ *
+ * ## Usage Examples
+ *
+ * ```typescript
+ * // Loading a saved world (complete replacement with defaults as base)
+ * postProcessManager.setConfiguration(savedConfig);
+ *
+ * // Player toggles bloom in settings (incremental update)
+ * postProcessManager.updateConfiguration({
+ *   effects: [{ type: PostProcessPass.Bloom, enabled: !bloomEnabled }]
+ * });
+ *
+ * // Switching to cinematic preset (complete replacement)
+ * postProcessManager.setConfiguration(cinematicPreset);
+ *
+ * // Adjusting exposure during gameplay (incremental update)
+ * postProcessManager.updateConfiguration({
+ *   effects: [{ type: PostProcessPass.ToneMapping, exposure: newExposure }]
+ * });
+ *
+ * // Fine-tuning individual effect properties
+ * postProcessManager.configureEffect(PostProcessPass.Bloom, {
+ *   intensity: 1.2,
+ *   luminanceThreshold: 0.5,
+ *   radius: 0.9
+ * });
+ * ```
+ */
+export class PostProcessManager {
+  private lastRenderer: THREE.WebGLRenderer | null = null;
+  private lastScene: THREE.Scene | null = null;
+  private lastCamera: THREE.Camera | null = null;
+  private lastWindowSize: { width: number, height: number } | null = null;
+  private composer: EffectComposer | null = null;
+  private effects: Map<PostProcessPass, EffectPassWrapper> = new Map();
+  private useCameraVisibilityLayers: boolean = false;
+  private configuration: Map<PostProcessPass, EffectConfig> = new Map();
+  private effectsInitialized: boolean = false;
+  private postProcessingEnabled: boolean = true;
+  public readonly hiddenObjects: Set<THREE.Object3D> = new Set();
+  private edgeOutlineEffect: EdgeOutlineEffect | null = null;
+  private renderPass: RenderPass | null = null;
+  private hasCompletedFirstRender: boolean = false;
+  private layerFilteredObjects: Set<THREE.Object3D> = new Set();
+  private layersDirty: boolean = true;
+  private tempHiddenObjects: THREE.Object3D[] = [];
+  private cameraLayersMask: number = 0;
+  private edgeOutlineEnabledCache: boolean = false;
+  private cachedHasAnyEnabledPasses: boolean = false;
+  private boundOriginalRender: ((renderer: any, writeBuffer: any, readBuffer: any, deltaTime: any, maskActive: any) => void) | null = null;
+  private depthPrepassMaterial: THREE.MeshDepthMaterial | null = null;
+
+  constructor(config?: PostProcessConfiguration) {
+    this.initializeDefaults(config);
+  }
+
+  private initializeDefaults(config?: PostProcessConfiguration) {
+    for (const [passType, defaultConfig] of Object.entries(DEFAULT_CONFIGS)) {
+      let finalConfig: EffectConfig = { ...defaultConfig };
+      // If user provided config, find and merge the matching effect config
+      if (config?.effects) {
+        const userConfig = config.effects.find(effect => effect.type === passType);
+        if (userConfig) {
+          finalConfig = { ...defaultConfig, ...userConfig };
+        }
+      }
+      this.configuration.set(passType as PostProcessPass, finalConfig);
+    }
+  }
+
+  /** Apply tone mapping exposure to renderer */
+  private applyToneMappingExposure() {
+    const toneMappingConfig = this.configuration.get(PostProcessPass.ToneMapping) as ToneMappingEffectConfig;
+    if (toneMappingConfig?.exposure !== undefined && this.lastRenderer) {
+      this.lastRenderer.toneMappingExposure = toneMappingConfig.exposure;
+    }
+  }
+
+  /** Apply tone mapping mode and exposure to renderer (used when post-processing is disabled) */
+  private applyToneMappingToRenderer() {
+    if (!this.lastRenderer) return;
+
+    const toneMappingConfig = this.configuration.get(PostProcessPass.ToneMapping) as ToneMappingEffectConfig;
+
+    // If tone mapping is disabled, use NoToneMapping
+    if (!toneMappingConfig?.enabled) {
+      this.lastRenderer.toneMapping = THREE.NoToneMapping;
+      return;
+    }
+
+    // Map ToneMappingMode to THREE.ToneMapping
+    const mode = toneMappingConfig.mode ?? DEFAULT_CONFIGS[PostProcessPass.ToneMapping].mode!;
+    const modeMap = {
+      [ToneMappingMode.LINEAR]: THREE.LinearToneMapping,
+      [ToneMappingMode.REINHARD]: THREE.ReinhardToneMapping,
+      [ToneMappingMode.CINEON]: THREE.CineonToneMapping,
+      [ToneMappingMode.ACES_FILMIC]: THREE.ACESFilmicToneMapping,
+      [ToneMappingMode.AGX]: THREE.AgXToneMapping,
+      [ToneMappingMode.NEUTRAL]: THREE.NeutralToneMapping,
+      // Note: Custom modes like REINHARD2, REINHARD2_ADAPTIVE, UNCHARTED2 are not supported by THREE.js
+      // They fall back to LINEAR
+      [ToneMappingMode.REINHARD2]: THREE.LinearToneMapping,
+      [ToneMappingMode.REINHARD2_ADAPTIVE]: THREE.LinearToneMapping,
+      [ToneMappingMode.UNCHARTED2]: THREE.LinearToneMapping,
+      [ToneMappingMode.OPTIMIZED_CINEON]: THREE.CineonToneMapping,
+    };
+
+    this.lastRenderer.toneMapping = modeMap[mode] ?? THREE.LinearToneMapping;
+    this.lastRenderer.toneMappingExposure = toneMappingConfig.exposure ?? DEFAULT_CONFIGS[PostProcessPass.ToneMapping].exposure!;
+  }
+
+  /** Configure specific effect settings */
+  public configureEffect<T extends EffectConfig>(passType: PostProcessPass, config: Partial<T>) {
+    const currentConfig = this.configuration.get(passType);
+    if (!currentConfig) {
+      console.warn(`Effect ${passType} not found`);
+      return;
+    }
+
+    // Merge with current configuration
+    const updatedConfig = { ...currentConfig, ...config };
+    this.configuration.set(passType, updatedConfig);
+
+    // Update cached enabled states
+    this.updateEnabledStatesCache();
+
+    // If we have effects initialized, update the specific effect and sync
+    if (this.effectsInitialized) {
+      this.updateEffectConfig(passType);
+      this.syncPassEnabled();
+
+      // Apply tone mapping exposure if this is a tone mapping config change
+      if (passType === PostProcessPass.ToneMapping) {
+        this.applyToneMappingExposure();
+      }
+
+      // Recreate EdgeOutline effect if config changed
+      if (passType === PostProcessPass.EdgeOutline) {
+        this.initializeEdgeOutline();
+      }
+    }
+  }
+
+  /** Get current configuration for an effect */
+  public getEffectConfig(passType: PostProcessPass): EffectConfig | null {
+    return this.configuration.get(passType) ?? null;
+  }
+
+  /** Set multiple effect configurations at once */
+  public configure(config: PostProcessConfiguration) {
+    for (const effectConfig of config.effects) {
+      this.configureEffect(effectConfig.type, effectConfig as any);
+    }
+  }
+
+  /** Set post-processing configuration (merges with defaults) */
+  public setConfiguration(config: PostProcessConfiguration) {
+    // Reset to defaults first
+    this.initializeDefaults();
+    // Then apply the provided config
+    this.configure(config);
+  }
+
+  /** Update post-processing configuration (merges with current) */
+  public updateConfiguration(config: PostProcessConfiguration) {
+    this.configure(config);
+  }
+
+  /** Get all current configurations */
+  public getAllConfigurations(): PostProcessConfiguration {
+    return {
+      effects: Array.from(this.configuration.values())
+    };
+  }
+
+
+  public renderScene(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera, windowSize: { width: number, height: number }) {
+    this.lastWindowSize ??= windowSize;
+
+    const rendererChanged = this.lastRenderer !== renderer;
+    const sceneChanged = this.lastScene !== scene;
+    const cameraChanged = this.lastCamera !== camera;
+
+    if (rendererChanged || sceneChanged || cameraChanged) {
+      this.lastCamera = camera;
+      this.lastScene = scene;
+      this.lastRenderer = renderer;
+
+      // Mark layers dirty on camera or scene change
+      if (sceneChanged || cameraChanged) {
+        this.layersDirty = true;
+      }
+
+      if (rendererChanged) {
+        if (this.effectsInitialized && this.composer) {
+          // Update renderer on existing composer
+          this.composer.setRenderer(renderer);
+        } else {
+          // Initialize composer and effects on first renderer
+          this.initializeComposer();
+        }
+      }
+
+      if (sceneChanged && this.composer) {
+        this.composer.setMainScene(scene);
+      }
+
+      if (cameraChanged && this.composer) {
+        this.composer.setMainCamera(camera);
+        if (this.renderPass) {
+          (this.renderPass as any).camera = this.lastCamera;
+        }
+      }
+    }
+
+    // Check if camera layers changed (without changing camera instance)
+    if (this.useCameraVisibilityLayers && this.lastCamera?.layers && this.cameraLayersMask !== this.lastCamera.layers.mask) {
+      this.layersDirty = true;
+    }
+
+    if ((this.lastWindowSize.width !== windowSize.width || this.lastWindowSize.height !== windowSize.height) && this.composer) {
+      this.lastWindowSize = windowSize;
+      this.composer.setSize(this.lastWindowSize!.width, this.lastWindowSize!.height);
+    }
+
+    if (this.postProcessingEnabled && this.cachedHasAnyEnabledPasses && this.composer) {
+      // When using post-processing, disable renderer tone mapping (handled by post-processing effects)
+      renderer.toneMapping = THREE.NoToneMapping;
+
+      this.composer.render();
+
+      // Render EdgeOutline on top of the post-processed scene
+      if (this.edgeOutlineEnabledCache && this.edgeOutlineEffect && this.edgeOutlineEffect.selection.size > 0) {
+        // First, build a depth buffer for the current scene without affecting color
+        this.renderDepthPrepass(renderer, scene, camera);
+
+        // Then render the outline using the existing depth
+        this.edgeOutlineEffect.renderOutline(scene, camera);
+      }
+
+      this.hasCompletedFirstRender = true;
+    } else {
+      // Apply tone mapping to renderer when post-processing is off
+      this.applyToneMappingToRenderer();
+      renderer.render(scene, camera);
+
+      // Render EdgeOutline effect if enabled (when NOT using post-processing)
+      if (this.edgeOutlineEnabledCache && this.edgeOutlineEffect) {
+        // Build depth buffer before rendering outline to ensure consistent behavior
+        this.renderDepthPrepass(renderer, scene, camera);
+        this.edgeOutlineEffect.renderOutline(scene, camera);
+      }
+
+      this.hasCompletedFirstRender = true;
+    }
+  }
+
+  public enablePasses(...passes: PostProcessPass[]) {
+    for (const pass of passes) {
+      const config = this.configuration.get(pass);
+      if (config) {
+        config.enabled = true;
+      }
+    }
+    this.updateEnabledStatesCache();
+    this.syncPassEnabled();
+  }
+
+  public disablePasses(...passes: PostProcessPass[]) {
+    for (const pass of passes) {
+      const config = this.configuration.get(pass);
+      if (config) {
+        config.enabled = false;
+      }
+    }
+    this.updateEnabledStatesCache();
+    this.syncPassEnabled();
+  }
+
+  public getEffectFromPass<T extends Effect>(pass: PostProcessPass, type: new (...args: any[]) => T): T | null {
+    const wrapper = this.effects.get(pass);
+    const effect = wrapper?.getEffect(type) as T | null;
+    return effect;
+  }
+
+  public isPassEnabled(pass: PostProcessPass) {
+    const config = this.configuration.get(pass);
+    return config?.enabled ?? false;
+  }
+
+  /** Sets whether the RenderPass should use camera visibility layers */
+  public setUseCameraVisibilityLayers(enabled: boolean) {
+    if (this.useCameraVisibilityLayers !== enabled) {
+      this.useCameraVisibilityLayers = enabled;
+      this.layersDirty = true;
+    }
+  }
+
+  /** Gets whether the RenderPass uses camera visibility layers */
+  public getUseCameraVisibilityLayers(): boolean {
+    return this.useCameraVisibilityLayers;
+  }
+
+  /** Update cached layer-filtered objects (only called when dirty) */
+  private updateLayerFilteredObjects() {
+    if (!this.layersDirty) return;
+
+    this.layerFilteredObjects.clear();
+
+    if (this.useCameraVisibilityLayers && this.lastCamera?.layers && this.lastScene) {
+      this.cameraLayersMask = this.lastCamera.layers.mask;
+
+      this.lastScene.traverse(object => {
+        if (object.layers && !object.layers.test(this.lastCamera!.layers)) {
+          this.layerFilteredObjects.add(object);
+        }
+      });
+    }
+
+    this.layersDirty = false;
+  }
+
+  /** Mark layer cache as dirty (call when scene graph changes) */
+  public invalidateLayerCache() {
+    this.layersDirty = true;
+  }
+
+  /** Update cached enabled states to avoid Map lookups in hot path */
+  private updateEnabledStatesCache() {
+    const edgeOutlineConfig = this.configuration.get(PostProcessPass.EdgeOutline) as EdgeOutlineEffectConfig | undefined;
+    this.edgeOutlineEnabledCache = edgeOutlineConfig?.enabled ?? false;
+
+    // Update hasAnyEnabledPasses cache (exclude EdgeOutline as it's not an EffectPass in the composer)
+    this.cachedHasAnyEnabledPasses = false;
+    for (const [passType, config] of this.configuration.entries()) {
+      if (config.enabled && passType !== PostProcessPass.EdgeOutline) {
+        this.cachedHasAnyEnabledPasses = true;
+        break;
+      }
+    }
+  }
+
+  /** Sets whether post-processing is enabled globally */
+  public setPostProcessingEnabled(enabled: boolean) {
+    this.postProcessingEnabled = enabled;
+  }
+
+  /** Gets whether post-processing is enabled globally */
+  public getPostProcessingEnabled(): boolean {
+    return this.postProcessingEnabled;
+  }
+
+  /** Get the EdgeOutline effect instance */
+  public getEdgeOutlineEffect(): EdgeOutlineEffect | null {
+    return this.edgeOutlineEffect;
+  }
+
+  /** Render a depth-only prepass into the current framebuffer without affecting color */
+  private renderDepthPrepass(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera) {
+    const gl = renderer.getContext();
+    const prevAutoClear = renderer.autoClear;
+
+    // Disable color writes completely - only write to depth buffer
+    gl.colorMask(false, false, false, false);
+
+    // Clear depth buffer and render scene to populate depth
+    renderer.autoClear = false;
+    renderer.clearDepth();
+    renderer.render(scene, camera);
+
+    // Restore color writes
+    gl.colorMask(true, true, true, true);
+    renderer.autoClear = prevAutoClear;
+  }
+
+  public destroy() {
+    this.hiddenObjects.clear();
+    this.layerFilteredObjects.clear();
+    this.tempHiddenObjects.length = 0;
+    this.boundOriginalRender = null;
+    this.clearResources();
+    if (this.edgeOutlineEffect) {
+      this.edgeOutlineEffect.dispose();
+      this.edgeOutlineEffect = null;
+    }
+    this.renderPass = null;
+    this.hasCompletedFirstRender = false;
+    this.lastCamera = null;
+    this.lastScene = null;
+    this.lastWindowSize = null;
+    this.lastRenderer = null;
+    this.effects.clear();
+    this.configuration.clear();
+  }
+
+  //====================================================================================================
+
+  /** Initialize the effect composer and all effects once */
+  private initializeComposer() {
+    if (!this.lastRenderer || !this.lastScene || !this.lastCamera || this.effectsInitialized) return;
+
+    const isWebGL2 = this.lastRenderer.capabilities.isWebGL2;
+    const supportHalfFloat = isWebGL2 && this.lastRenderer.extensions.has('EXT_color_buffer_float');
+    const maxSamples = this.lastRenderer.capabilities.maxSamples;
+    console.log('[PostProcessManager]: initializeComposer', { isWebGL2, supportHalfFloat, maxSamples });
+
+    this.composer = new EffectComposer(this.lastRenderer, {
+      frameBufferType: supportHalfFloat ? THREE.HalfFloatType : undefined,
+      multisampling: isWebGL2 ? Math.min(4, maxSamples) : 0, // TODO: expose MSAA settings?
+    });
+
+    // Update cached enabled states
+    this.updateEnabledStatesCache();
+
+    // Create render pass
+    this.createRenderPass();
+
+    // Create all effects upfront
+    this.createAllEffects();
+
+    // Initial sync of passes
+    this.syncPassEnabled();
+
+    // Apply tone mapping exposure
+    this.applyToneMappingExposure();
+
+    // Initialize EdgeOutline effect
+    this.initializeEdgeOutline();
+
+
+    this.effectsInitialized = true;
+  }
+
+  /** Initialize the EdgeOutline effect */
+  private initializeEdgeOutline() {
+    if (!this.lastRenderer) return;
+
+    const edgeOutlineConfig = this.configuration.get(PostProcessPass.EdgeOutline) as EdgeOutlineEffectConfig;
+    if (edgeOutlineConfig) {
+      // Preserve the current selection if recreating
+      const currentSelection = this.edgeOutlineEffect ? Array.from(this.edgeOutlineEffect.selection) : [];
+
+      // Dispose of existing effect if any
+      if (this.edgeOutlineEffect) {
+        this.edgeOutlineEffect.dispose();
+      }
+
+      // Create new EdgeOutline effect
+      this.edgeOutlineEffect = new EdgeOutlineEffect(this.lastRenderer, {
+        defaultThickness: edgeOutlineConfig.thickness ?? DEFAULT_CONFIGS[PostProcessPass.EdgeOutline].thickness,
+        defaultColor: this.hexToRgbArray(edgeOutlineConfig.color ?? DEFAULT_CONFIGS[PostProcessPass.EdgeOutline].color!),
+        defaultAlpha: edgeOutlineConfig.alpha ?? DEFAULT_CONFIGS[PostProcessPass.EdgeOutline].alpha,
+      });
+
+      // Restore the selection
+      for (const object of currentSelection) {
+        this.edgeOutlineEffect.selection.add(object);
+      }
+    }
+  }
+
+  /** Convert hex color to RGB array */
+  private hexToRgbArray(hex: number): number[] {
+    return [
+      ((hex >> 16) & 255) / 255,
+      ((hex >> 8) & 255) / 255,
+      (hex & 255) / 255
+    ];
+  }
+
+  /** Enable/disable effect passes based on configuration */
+  private syncPassEnabled() {
+    if (!this.composer) return;
+
+    for (const [passType, wrapper] of this.effects) {
+      const config = this.configuration.get(passType);
+      if (config?.enabled) {
+        wrapper.enableEffect();
+      } else {
+        wrapper.disableEffect();
+      }
+    }
+
+    // Update renderToScreen flags after changing pass states
+    this.updateRenderToScreen();
+  }
+
+  /** Update renderToScreen flags to ensure the last enabled pass renders to screen */
+  private updateRenderToScreen() {
+    if (!this.composer) return;
+
+    let lastEnabledPass: any = null;
+
+    // Find the last enabled pass
+    for (const pass of this.composer.passes) {
+      if (pass.enabled) {
+        lastEnabledPass = pass;
+      }
+    }
+
+    // Set renderToScreen only on the last enabled pass
+    for (const pass of this.composer.passes) {
+      pass.renderToScreen = pass === lastEnabledPass;
+    }
+  }
+
+  /** Check if any passes are enabled */
+  private hasAnyEnabledPasses(): boolean {
+    for (const config of this.configuration.values()) {
+      if (config.enabled) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** Create the render pass once */
+  private createRenderPass() {
+    if (!this.composer || !this.lastScene || !this.lastCamera) {
+      console.warn('[PostProcessManager]: Cannot create render pass - missing composer, scene, or camera');
+      return;
+    }
+
+    this.renderPass = new RenderPass(this.lastScene, this.lastCamera);
+    // Bind original render once for better performance
+    this.boundOriginalRender = this.renderPass.render.bind(this.renderPass);
+
+    // Override render method to respect camera layers and hidden objects
+    this.renderPass.render = (renderer, writeBuffer, readBuffer, deltaTime, maskActive) => {
+      // Early exit if scene or camera not ready
+      if (!this.lastScene || !this.lastCamera) {
+        console.warn('[PostProcessManager]: Skipping render - scene or camera not ready');
+        return;
+      }
+
+      // Clear temp array instead of allocating new one
+      this.tempHiddenObjects.length = 0;
+
+      // Handle camera layer visibility - use cached filtered objects
+      if (this.useCameraVisibilityLayers) {
+        // Update cache if dirty
+        this.updateLayerFilteredObjects();
+
+        // Hide cached filtered objects
+        for (const object of this.layerFilteredObjects) {
+          if (object?.visible) {
+            object.visible = false;
+            this.tempHiddenObjects.push(object);
+          }
+        }
+      }
+
+      // Handle explicitly hidden objects
+      for (const object of this.hiddenObjects) {
+        if (object?.visible) {
+          object.visible = false;
+          this.tempHiddenObjects.push(object);
+        }
+      }
+
+      // Call bound original render - no .call() overhead
+      this.boundOriginalRender!(renderer, writeBuffer, readBuffer, deltaTime, maskActive);
+
+      // Restore visibility of hidden objects
+      for (const object of this.tempHiddenObjects) {
+        if (object) {
+          object.visible = true;
+        }
+      }
+    };
+
+    this.composer.addPass(this.renderPass);
+  }
+
+  /** Create all effects once and add them to the composer */
+  private createAllEffects() {
+    if (!this.composer || !this.lastCamera) return;
+
+    for (const [passType, config] of this.configuration) {
+      const effects = this.createEffectFromConfig(config);
+      if (effects.length > 0) {
+        const wrapper = new EffectPassWrapper(this.lastCamera, effects);
+        this.effects.set(passType, wrapper);
+        this.composer.addPass(wrapper.getPass());
+      }
+    }
+  }
+
+  /** Update an effect's configuration without recreating it */
+  private updateEffectConfig(passType: PostProcessPass) {
+    const config = this.configuration.get(passType);
+    if (!config) return;
+
+    const wrapper = this.effects.get(passType);
+    if (!wrapper) return;
+
+    // Update effect properties based on configuration
+    this.applyConfigToEffect(passType, config, wrapper);
+  }
+
+  private createEffectFromConfig(config: EffectConfig): Effect[] {
+    switch (config.type) {
+      case PostProcessPass.ObjectOutline: {
+        const outlineConfig = config as ObjectOutlineEffectConfig;
+        return [new ObjectOutlineEffect(this.lastScene!, this.lastCamera!, {
+          blendFunction: BlendFunction.ALPHA,
+          edgeThickness: outlineConfig.edgeThickness ?? DEFAULT_CONFIGS[PostProcessPass.ObjectOutline].edgeThickness,
+          edgeIntensity: outlineConfig.edgeIntensity ?? DEFAULT_CONFIGS[PostProcessPass.ObjectOutline].edgeIntensity,
+          visibleEdgeColor: outlineConfig.visibleEdgeColor ?? DEFAULT_CONFIGS[PostProcessPass.ObjectOutline].visibleEdgeColor,
+        })];
+      }
+
+      case PostProcessPass.Bloom: {
+        const bloomConfig = config as BloomEffectConfig;
+        const effect = new SelectiveBloomEffect(this.lastScene!, this.lastCamera!, {
+          intensity: bloomConfig.intensity ?? DEFAULT_CONFIGS[PostProcessPass.Bloom].intensity,
+          luminanceThreshold: bloomConfig.luminanceThreshold ?? DEFAULT_CONFIGS[PostProcessPass.Bloom].luminanceThreshold,
+          luminanceSmoothing: bloomConfig.luminanceSmoothing ?? DEFAULT_CONFIGS[PostProcessPass.Bloom].luminanceSmoothing,
+          mipmapBlur: bloomConfig.mipmapBlur ?? DEFAULT_CONFIGS[PostProcessPass.Bloom].mipmapBlur,
+          radius: bloomConfig.radius ?? DEFAULT_CONFIGS[PostProcessPass.Bloom].radius,
+          levels: bloomConfig.levels ?? DEFAULT_CONFIGS[PostProcessPass.Bloom].levels,
+        });
+        effect.inverted = true; // Use inverted true to apply to all objects
+        effect.ignoreBackground = bloomConfig.ignoreBackground ?? DEFAULT_CONFIGS[PostProcessPass.Bloom].ignoreBackground!;
+        return [effect];
+      }
+
+      case PostProcessPass.SMAA: {
+        const smaaConfig = config as SMAAEffectConfig;
+        return [new SMAAEffect({
+          preset: smaaConfig.preset ?? DEFAULT_CONFIGS[PostProcessPass.SMAA].preset,
+        })];
+      }
+
+      case PostProcessPass.ToneMapping: {
+        const toneMappingConfig = config as ToneMappingEffectConfig;
+        const defaults = DEFAULT_CONFIGS[PostProcessPass.ToneMapping] as ToneMappingEffectConfig;
+
+        // Apply exposure to renderer if specified
+        if (toneMappingConfig.exposure !== undefined && this.lastRenderer) {
+          this.lastRenderer.toneMappingExposure = toneMappingConfig.exposure;
+        }
+
+        return [new ToneMappingEffect({
+          mode: toneMappingConfig.mode ?? defaults.mode,
+          resolution: toneMappingConfig.resolution ?? defaults.resolution,
+          whitePoint: toneMappingConfig.whitePoint ?? defaults.whitePoint,
+          middleGrey: toneMappingConfig.middleGrey ?? defaults.middleGrey,
+          minLuminance: toneMappingConfig.minLuminance ?? defaults.minLuminance,
+          averageLuminance: toneMappingConfig.averageLuminance ?? defaults.averageLuminance,
+          adaptationRate: toneMappingConfig.adaptationRate ?? defaults.adaptationRate,
+        })];
+      }
+
+      default:
+        console.warn(`Unknown effect type: ${(config as any).type}`);
+        return [];
+    }
+  }
+
+  /** Apply configuration to an existing effect without recreating it */
+  private applyConfigToEffect(passType: PostProcessPass, config: EffectConfig, wrapper: EffectPassWrapper) {
+    switch (passType) {
+      case PostProcessPass.ObjectOutline: {
+        const outlineConfig = config as ObjectOutlineEffectConfig;
+        const outlineEffect = wrapper.getEffect(ObjectOutlineEffect);
+        if (outlineEffect) {
+          // Update outline effect properties
+          outlineEffect.edgeThickness = outlineConfig.edgeThickness ?? DEFAULT_CONFIGS[PostProcessPass.ObjectOutline].edgeThickness!;
+          outlineEffect.edgeIntensity = outlineConfig.edgeIntensity ?? DEFAULT_CONFIGS[PostProcessPass.ObjectOutline].edgeIntensity!;
+          outlineEffect.visibleEdgeColor = outlineConfig.visibleEdgeColor ?? DEFAULT_CONFIGS[PostProcessPass.ObjectOutline].visibleEdgeColor!;
+        }
+        break;
+      }
+
+      case PostProcessPass.Bloom: {
+        const bloomConfig = config as BloomEffectConfig;
+        const bloomEffect = wrapper.getEffect(SelectiveBloomEffect);
+        if (bloomEffect) {
+          // Update selective bloom effect properties
+          bloomEffect.intensity = bloomConfig.intensity ?? DEFAULT_CONFIGS[PostProcessPass.Bloom].intensity!;
+          bloomEffect.inverted = true; // Use inverted true to apply to all objects
+          bloomEffect.ignoreBackground = bloomConfig.ignoreBackground ?? DEFAULT_CONFIGS[PostProcessPass.Bloom].ignoreBackground!;
+
+          // Update luminance properties
+          if (bloomConfig.luminanceThreshold !== undefined) {
+            bloomEffect.luminanceMaterial.threshold = bloomConfig.luminanceThreshold;
+          }
+          if (bloomConfig.luminanceSmoothing !== undefined) {
+            bloomEffect.luminanceMaterial.smoothing = bloomConfig.luminanceSmoothing;
+          }
+
+          // Update mipmap blur properties
+          if (bloomConfig.mipmapBlur !== undefined) {
+            bloomEffect.mipmapBlurPass.enabled = bloomConfig.mipmapBlur;
+          }
+          if (bloomConfig.radius !== undefined) {
+            bloomEffect.mipmapBlurPass.radius = bloomConfig.radius;
+          }
+          if (bloomConfig.levels !== undefined) {
+            bloomEffect.mipmapBlurPass.levels = bloomConfig.levels;
+          }
+        }
+        break;
+      }
+
+      case PostProcessPass.ToneMapping: {
+        const toneMappingConfig = config as ToneMappingEffectConfig;
+        const defaults = DEFAULT_CONFIGS[PostProcessPass.ToneMapping] as ToneMappingEffectConfig;
+        const toneMappingEffect = wrapper.getEffect(ToneMappingEffect);
+        if (toneMappingEffect) {
+          // Update tone mapping effect properties
+          toneMappingEffect.mode = toneMappingConfig.mode ?? defaults.mode!;
+
+          // Cast to any to access setter properties that may not be defined in TypeScript
+          const effect = toneMappingEffect as any;
+
+          // Update white point and middle grey for Reinhard2 operators
+          if (toneMappingConfig.whitePoint !== undefined) {
+            effect.whitePoint = toneMappingConfig.whitePoint;
+          }
+          if (toneMappingConfig.middleGrey !== undefined) {
+            effect.middleGrey = toneMappingConfig.middleGrey;
+          }
+          if (toneMappingConfig.averageLuminance !== undefined) {
+            effect.averageLuminance = toneMappingConfig.averageLuminance;
+          }
+
+          // Update resolution for adaptive tone mapping
+          if (toneMappingConfig.resolution !== undefined) {
+            effect.resolution = toneMappingConfig.resolution;
+          }
+
+          // Update adaptive luminance properties if available
+          if (effect.adaptiveLuminanceMaterial) {
+            if (toneMappingConfig.minLuminance !== undefined) {
+              effect.adaptiveLuminanceMaterial.minLuminance = toneMappingConfig.minLuminance;
+            }
+            if (toneMappingConfig.adaptationRate !== undefined) {
+              effect.adaptiveLuminanceMaterial.adaptationRate = toneMappingConfig.adaptationRate;
+            }
+          }
+        }
+        break;
+      }
+
+      case PostProcessPass.SMAA: {
+        const smaaConfig = config as SMAAEffectConfig;
+        const smaaEffect = wrapper.getEffect(SMAAEffect);
+        if (smaaEffect && smaaConfig.preset !== undefined) {
+          smaaEffect.applyPreset(smaaConfig.preset);
+        }
+        break;
+      }
+    }
+  }
+
+  private clearResources() {
+    if (this.composer) {
+      this.composer.dispose();
+      this.composer = null;
+    }
+
+    for (const [_, effect] of this.effects) {
+      effect.dispose();
+    }
+    this.effects.clear();
+    this.effectsInitialized = false;
+  }
+}
+
+ObjectOutlineEffect.prototype.addSelectedActor = function (actor: Actor) {
+  const sceneObjects = actor.getComponents(SceneComponent);
+
+  for (const sceneObject of sceneObjects) {
+    sceneObject.traverse((child) => {
+      if (child instanceof THREE.Mesh) {
+        this.selection.add(child);
+      }
+    });
+  }
+
+  return this;
+};
+
+ObjectOutlineEffect.prototype.removeSelectedActor = function (actor: Actor) {
+  const sceneObjects = actor.getComponents(SceneComponent);
+  for (const sceneObject of sceneObjects) {
+    sceneObject.traverse((child) => {
+      if (child instanceof THREE.Mesh) {
+        this.selection.delete(child);
+      }
+    });
+  };
+  return this;
+};
+