topazcube 0.1.33 → 0.1.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "topazcube",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "TopazCube is a real-time collaborative document editing, multiplayer game library, and WebGPU renderer.",
   "author": "László Matuska @BitOfGold",
   "license": "Apache-2.0",

package/src/renderer/DebugUI.js

@@ -42,19 +42,20 @@ class DebugUI {
 
         // Create settings folders
         this._createRenderingFolder()
-        this._createAOFolder()
-        this._createShadowFolder()
-        this._createMainLightFolder()
+        this._createCameraFolder()
         this._createEnvironmentFolder()
         this._createLightingFolder()
-        this._createCullingFolder()
-        this._createSSGIFolder()
-        this._createBloomFolder()
+        this._createMainLightFolder()
+        this._createShadowFolder()
         this._createPlanarReflectionFolder()
+        this._createAOFolder()
         this._createAmbientCaptureFolder()
-        this._createNoiseFolder()
+        this._createSSGIFolder()
+        this._createVolumetricFogFolder()
+        this._createBloomFolder()
+        this._createTonemapFolder()
         this._createDitheringFolder()
-        this._createCameraFolder()
+        this._createCRTFolder()
         this._createDebugFolder()
 
         // Close all folders by default
@@ -244,6 +245,42 @@ class DebugUI {
                     this.gui.domElement.style.display = 'none'
                 }
             })
+
+        // Culling subfolder
+        if (s.culling) {
+            const cullFolder = folder.addFolder('Culling')
+            cullFolder.add(s.culling, 'frustumEnabled').name('Frustum Culling')
+
+            if (s.occlusionCulling) {
+                cullFolder.add(s.occlusionCulling, 'enabled').name('Occlusion Culling')
+                cullFolder.add(s.occlusionCulling, 'threshold', 0.1, 2.0, 0.1).name('Occlusion Threshold')
+            }
+
+            // Planar reflection culling sub-folder
+            if (s.culling.planarReflection) {
+                const prFolder = cullFolder.addFolder('Planar Reflection')
+                prFolder.add(s.culling.planarReflection, 'frustum').name('Frustum Culling')
+                prFolder.add(s.culling.planarReflection, 'maxDistance', 10, 200, 10).name('Max Distance')
+                prFolder.add(s.culling.planarReflection, 'maxSkinned', 0, 100, 1).name('Max Skinned')
+                prFolder.add(s.culling.planarReflection, 'minPixelSize', 0, 16, 1).name('Min Pixel Size')
+                prFolder.close()
+            }
+            cullFolder.close()
+        }
+
+        // Noise subfolder
+        if (s.noise) {
+            const noiseFolder = folder.addFolder('Noise')
+            noiseFolder.add(s.noise, 'type', ['bluenoise', 'bayer8']).name('Type')
+                .onChange(() => {
+                    // Reload noise texture when type changes
+                    if (this.engine.renderer?.renderGraph) {
+                        this.engine.renderer.renderGraph.reloadNoiseTexture()
+                    }
+                })
+            noiseFolder.add(s.noise, 'animated').name('Animated')
+            noiseFolder.close()
+        }
     }
 
     _createAOFolder() {
@@ -344,6 +381,9 @@ class DebugUI {
             fogFolder.add(s.environment.fog.heightFade, '0', -100, 100, 1).name('Bottom Y')
             fogFolder.add(s.environment.fog.heightFade, '1', -50, 200, 5).name('Top Y')
             fogFolder.add(s.environment.fog, 'brightResist', 0, 1, 0.05).name('Bright Resist')
+            // Initialize debug if not present
+            if (s.environment.fog.debug === undefined) s.environment.fog.debug = 0
+            fogFolder.add(s.environment.fog, 'debug', 0, 10, 1).name('Debug Mode')
         }
     }
 
@@ -364,31 +404,6 @@ class DebugUI {
         }
     }
 
-    _createCullingFolder() {
-        const s = this.engine.settings
-        if (!s.culling) return
-
-        const folder = this.gui.addFolder('Culling')
-        this.folders.culling = folder
-
-        folder.add(s.culling, 'frustumEnabled').name('Frustum Culling')
-
-        if (s.occlusionCulling) {
-            folder.add(s.occlusionCulling, 'enabled').name('Occlusion Culling')
-            folder.add(s.occlusionCulling, 'threshold', 0.1, 2.0, 0.1).name('Occlusion Threshold')
-        }
-
-        // Planar reflection culling sub-folder
-        if (s.culling.planarReflection) {
-            const prFolder = folder.addFolder('Planar Reflection')
-            prFolder.add(s.culling.planarReflection, 'frustum').name('Frustum Culling')
-            prFolder.add(s.culling.planarReflection, 'maxDistance', 10, 200, 10).name('Max Distance')
-            prFolder.add(s.culling.planarReflection, 'maxSkinned', 0, 100, 1).name('Max Skinned')
-            prFolder.add(s.culling.planarReflection, 'minPixelSize', 0, 16, 1).name('Min Pixel Size')
-            prFolder.close()
-        }
-    }
-
     _createSSGIFolder() {
         const s = this.engine.settings
         if (!s.ssgi) return
@@ -404,6 +419,71 @@ class DebugUI {
         folder.add(s.ssgi, 'saturateLevel', 0.1, 2.0, 0.1).name('Saturate Level')
     }
 
+    _createVolumetricFogFolder() {
+        const s = this.engine.settings
+        if (!s.volumetricFog) return
+
+        // Initialize defaults for missing properties
+        const vf = s.volumetricFog
+        if (vf.density === undefined && vf.densityMultiplier === undefined) vf.density = 0.5
+        if (vf.scatterStrength === undefined) vf.scatterStrength = 1.0
+        if (!vf.heightRange) vf.heightRange = [-5, 20]
+        if (vf.resolution === undefined) vf.resolution = 0.25
+        if (vf.maxSamples === undefined) vf.maxSamples = 32
+        if (vf.blurRadius === undefined) vf.blurRadius = 4
+        if (vf.noiseStrength === undefined) vf.noiseStrength = 1.0
+        if (vf.noiseScale === undefined) vf.noiseScale = 0.25
+        if (vf.noiseAnimated === undefined) vf.noiseAnimated = true
+        if (vf.shadowsEnabled === undefined) vf.shadowsEnabled = true
+        if (vf.mainLightScatter === undefined) vf.mainLightScatter = 1.0
+        if (vf.mainLightScatterDark === undefined) vf.mainLightScatterDark = 3.0
+        if (vf.mainLightSaturation === undefined) vf.mainLightSaturation = 1.0
+        if (vf.brightnessThreshold === undefined) vf.brightnessThreshold = 1.0
+        if (vf.minVisibility === undefined) vf.minVisibility = 0.15
+        if (vf.skyBrightness === undefined) vf.skyBrightness = 5.0
+        if (vf.debug === undefined) vf.debug = 0
+
+        const folder = this.gui.addFolder('Volumetric Fog')
+        this.folders.volumetricFog = folder
+
+        folder.add(vf, 'enabled').name('Enabled')
+
+        // Density - use whichever property exists
+        if (vf.density !== undefined) {
+            folder.add(vf, 'density', 0.0, 2.0, 0.05).name('Density')
+        } else if (vf.densityMultiplier !== undefined) {
+            folder.add(vf, 'densityMultiplier', 0.0, 2.0, 0.05).name('Density')
+        }
+
+        folder.add(vf, 'scatterStrength', 0.0, 10.0, 0.1).name('Scatter (Lights)')
+        folder.add(vf, 'mainLightScatter', 0.0, 5.0, 0.1).name('Sun Scatter (Light)')
+        folder.add(vf, 'mainLightScatterDark', 0.0, 10.0, 0.1).name('Sun Scatter (Dark)')
+        folder.add(vf, 'mainLightSaturation', 0.0, 1.0, 0.01).name('Sun Saturation')
+        folder.add(vf, 'brightnessThreshold', 0.1, 5.0, 0.1).name('Bright Threshold')
+        folder.add(vf, 'minVisibility', 0.0, 1.0, 0.05).name('Min Visibility')
+        folder.add(vf, 'skyBrightness', 0.0, 10.0, 0.5).name('Sky Brightness')
+        folder.add(vf.heightRange, '0', -50, 50, 1).name('Height Bottom')
+        folder.add(vf.heightRange, '1', -10, 100, 1).name('Height Top')
+
+        // Quality sub-folder
+        const qualityFolder = folder.addFolder('Quality')
+        qualityFolder.add(vf, 'resolution', 0.125, 0.5, 0.125).name('Resolution')
+        qualityFolder.add(vf, 'maxSamples', 16, 128, 8).name('Max Samples')
+        qualityFolder.add(vf, 'blurRadius', 0, 8, 1).name('Blur Radius')
+        qualityFolder.close()
+
+        // Noise sub-folder
+        const noiseFolder = folder.addFolder('Noise')
+        noiseFolder.add(vf, 'noiseStrength', 0.0, 1.0, 0.1).name('Strength')
+        noiseFolder.add(vf, 'noiseScale', 0.05, 1.0, 0.05).name('Scale (Detail)')
+        noiseFolder.add(vf, 'noiseAnimated').name('Animated')
+        noiseFolder.close()
+
+        // Shadows & Debug
+        folder.add(vf, 'shadowsEnabled').name('Shadows')
+        folder.add(vf, 'debug', 0, 12, 1).name('Debug Mode')
+    }
+
     _createBloomFolder() {
         const s = this.engine.settings
         if (!s.bloom) return
@@ -423,6 +503,19 @@ class DebugUI {
         }
     }
 
+    _createTonemapFolder() {
+        const s = this.engine.settings
+        if (!s.rendering) return
+
+        // Ensure tonemapMode exists
+        if (s.rendering.tonemapMode === undefined) s.rendering.tonemapMode = 0
+
+        const folder = this.gui.addFolder('Tone Mapping')
+        this.folders.tonemap = folder
+
+        folder.add(s.rendering, 'tonemapMode', { 'ACES': 0, 'Reinhard': 1, 'None (Linear)': 2 }).name('Mode')
+    }
+
     _createPlanarReflectionFolder() {
         const s = this.engine.settings
         if (!s.planarReflection) return
@@ -442,7 +535,7 @@ class DebugUI {
         const s = this.engine.settings
         if (!s.ambientCapture) return
 
-        const folder = this.gui.addFolder('Ambient Capture')
+        const folder = this.gui.addFolder('Probe GI (Ambient Capture)')
         this.folders.ambientCapture = folder
 
         folder.add(s.ambientCapture, 'enabled').name('Enabled')
@@ -452,17 +545,6 @@ class DebugUI {
         folder.add(s.ambientCapture, 'saturateLevel', 0.0, 2.0, 0.05).name('Saturate Level')
     }
 
-    _createNoiseFolder() {
-        const s = this.engine.settings
-        if (!s.noise) return
-
-        const folder = this.gui.addFolder('Noise')
-        this.folders.noise = folder
-
-        folder.add(s.noise, 'type', ['bluenoise', 'bayer8']).name('Type')
-        folder.add(s.noise, 'animated').name('Animated')
-    }
-
     _createDitheringFolder() {
         const s = this.engine.settings
         if (!s.dithering) return
@@ -474,6 +556,55 @@ class DebugUI {
         folder.add(s.dithering, 'colorLevels', 4, 256, 1).name('Color Levels')
     }
 
+    _createCRTFolder() {
+        const s = this.engine.settings
+        if (!s.crt) return
+
+        const folder = this.gui.addFolder('CRT Effect')
+        this.folders.crt = folder
+
+        folder.add(s.crt, 'enabled').name('CRT Enabled')
+        folder.add(s.crt, 'upscaleEnabled').name('Upscale Only')
+        folder.add(s.crt, 'upscaleTarget', 1, 8, 1).name('Upscale Target')
+
+        // Geometry sub-folder
+        const geomFolder = folder.addFolder('Geometry')
+        geomFolder.add(s.crt, 'curvature', 0, 0.25, 0.005).name('Curvature')
+        geomFolder.add(s.crt, 'cornerRadius', 0, 0.2, 0.005).name('Corner Radius')
+        geomFolder.add(s.crt, 'zoom', 1.0, 1.25, 0.005).name('Zoom')
+        geomFolder.close()
+
+        // Scanlines sub-folder
+        const scanFolder = folder.addFolder('Scanlines')
+        scanFolder.add(s.crt, 'scanlineIntensity', 0, 1, 0.05).name('Intensity')
+        scanFolder.add(s.crt, 'scanlineWidth', 0, 1, 0.05).name('Width')
+        scanFolder.add(s.crt, 'scanlineBrightBoost', 0, 2, 0.05).name('Bright Boost')
+        scanFolder.add(s.crt, 'scanlineHeight', 1, 10, 1).name('Height (px)')
+        scanFolder.close()
+
+        // Convergence sub-folder
+        const convFolder = folder.addFolder('RGB Convergence')
+        convFolder.add(s.crt.convergence, '0', -3, 3, 0.1).name('Red X Offset')
+        convFolder.add(s.crt.convergence, '1', -3, 3, 0.1).name('Green X Offset')
+        convFolder.add(s.crt.convergence, '2', -3, 3, 0.1).name('Blue X Offset')
+        convFolder.close()
+
+        // Phosphor mask sub-folder
+        const maskFolder = folder.addFolder('Phosphor Mask')
+        maskFolder.add(s.crt, 'maskType', ['none', 'aperture', 'slot', 'shadow']).name('Type')
+        maskFolder.add(s.crt, 'maskIntensity', 0, 1, 0.05).name('Intensity')
+        maskFolder.close()
+
+        // Vignette sub-folder
+        const vigFolder = folder.addFolder('Vignette')
+        vigFolder.add(s.crt, 'vignetteIntensity', 0, 1, 0.05).name('Intensity')
+        vigFolder.add(s.crt, 'vignetteSize', 0.1, 1, 0.05).name('Size')
+        vigFolder.close()
+
+        // Blur (top level, not in subfolder)
+        folder.add(s.crt, 'blurSize', 0, 8, 0.1).name('H-Blur (px)')
+    }
+
     _createCameraFolder() {
         const s = this.engine.settings
         if (!s.camera) return

package/src/renderer/Material.js

@@ -34,6 +34,9 @@ class Material {
 
         // Specular boost: enables 3 additional specular lights for shiny materials (0-1, default 0 = disabled)
         this.specularBoost = 0
+
+        // Double-sided rendering: disable backface culling
+        this.doubleSided = false
     }
 
     /**

package/src/renderer/Pipeline.js

@@ -88,6 +88,7 @@ class Pipeline {
         tileLightBuffer = null, // Optional tile light indices buffer for tiled lighting
         lightBuffer = null, // Optional light storage buffer for tiled lighting
         noiseTexture = null, // Optional noise texture for alpha hashing
+        doubleSided = false, // Optional: disable backface culling for double-sided materials
     }) {
         let texture = textures[0]
         const { canvas, device, canvasFormat, options } = engine
@@ -154,7 +155,7 @@ class Pipeline {
                 geometry.vertexBufferLayout,
                 geometry.instanceBufferLayout
             ];
-            pipelineDescriptor.primitive.cullMode = "back";
+            pipelineDescriptor.primitive.cullMode = doubleSided ? "none" : "back";
             pipelineDescriptor.depthStencil = {
                 depthWriteEnabled: true,
                 depthCompare: "less",
@@ -420,6 +421,7 @@ class Pipeline {
         p.tileLightBuffer = tileLightBuffer
         p.lightBuffer = lightBuffer
         p.noiseTexture = noiseTexture
+        p.doubleSided = doubleSided
         return p
     }
 

package/src/renderer/Renderer.js

@@ -13,6 +13,7 @@ import { InstanceManager } from "./core/InstanceManager.js"
 import { ParticleSystem } from "./core/ParticleSystem.js"
 import { ParticleEmitter } from "./core/ParticleEmitter.js"
 import { DebugUI } from "./DebugUI.js"
+import { Raycaster } from "./utils/Raycaster.js"
 
 
 // Display a failure message and stop rendering
@@ -77,7 +78,7 @@ const DEFAULT_SETTINGS = {
         fxaa: false,                // Fast approximate anti-aliasing
         renderScale: 1,             // Render resolution multiplier (1.5-2.0 for supersampling AA)
         autoScale: {
-            enabled: false,         // Auto-reduce renderScale for high resolutions
+            enabled: true,         // Auto-reduce renderScale for high resolutions
             enabledForEffects: true,// Auto scale effects at high resolutions (when main autoScale disabled)
             maxHeight: 1536,        // Height threshold (above this, scale is reduced)
             scaleFactor: 0.5,       // Factor to apply when above threshold
@@ -91,6 +92,7 @@ const DEFAULT_SETTINGS = {
         alphaHash: false,           // Enable alpha hashing/dithering for cutout transparency (global default)
         alphaHashScale: 1.0,        // Scale factor for alpha hash threshold (higher = more opaque)
         luminanceToAlpha: false,    // Derive alpha from color luminance (for old game assets where black=transparent)
+        tonemapMode: 0,             // 0=ACES, 1=Reinhard, 2=None (linear clamp)
     },
 
     // Noise settings for dithering, jittering, etc.
@@ -128,11 +130,12 @@ const DEFAULT_SETTINGS = {
         exposure: 1.6,
         fog: {
             enabled: true,
-            color: [0.8, 0.85, 0.9],
-            distances: [6, 15, 50],
+            color: [100/255.0, 135/255.0, 170/255.0],
+            distances: [0, 15, 50],
             alpha: [0.0, 0.5, 0.9],
             heightFade: [-2, 185],  // [bottomY, topY] - full fog at bottomY, zero at topY
-            brightResist: 0.2        // How much bright/emissive colors resist fog (0-1)
+            brightResist: 0.0,        // How much bright/emissive colors resist fog (0-1)
+            debug: 0,
         }
     },
 
@@ -158,6 +161,8 @@ const DEFAULT_SETTINGS = {
         normalBias: 0.015,          // ~2-3 texels for shadow acne
         surfaceBias: 0,             // Scale shadow projection larger (0.01 = 1% larger)
         strength: 1.0,
+        //frustum: false,
+        //hiZ: false,
     },
 
     // Ambient Occlusion settings
@@ -242,6 +247,33 @@ const DEFAULT_SETTINGS = {
         saturateLevel: 0.5,             // Logarithmic saturation level for indirect light
     },
 
+    // Volumetric Fog (light scattering through particles)
+    volumetricFog: {
+        enabled: false,                 // Disabled by default (performance impact)
+        resolution: 0.125,               // 1/4 render resolution for ray marching
+        maxSamples: 32,                 // Ray march samples (8-32)
+        blurRadius: 8.0,                // Gaussian blur radius
+        densityMultiplier: 1.0,         // Multiplies base fog density
+        scatterStrength: 0.35,           // Light scattering intensity
+        mainLightScatter: 1.4,          // Main directional light scattering boost
+        mainLightScatterDark: 5.0,      // Main directional light scattering boost
+        mainLightSaturation: 0.15,      // Main light color saturation in fog
+        maxFogOpacity: 0.3,             // Maximum fog opacity (0-1)
+        heightRange: [-2, 8],           // [bottom, top] Y bounds for fog (low ground fog)
+        windDirection: [1, 0, 0.2],     // Wind direction for fog animation
+        windSpeed: 0.5,                 // Wind speed multiplier
+        noiseScale: 0.9,                // 3D noise frequency (higher = finer detail)
+        noiseStrength: 0.8,             // Noise intensity (0 = uniform, 1 = full variation)
+        noiseOctaves: 6,                // Noise detail layers
+        noiseEnabled: true,             // Enable 3D noise (disable for debug)
+        lightingEnabled: true,          // Light fog from scene lights
+        shadowsEnabled: true,           // Apply shadows to fog
+        brightnessThreshold: 0.8,       // Scene luminance where fog starts fading (like bloom)
+        minVisibility: 0.15,            // Minimum fog visibility over bright surfaces (0-1)
+        skyBrightness: 1.2,             // Virtual brightness for sky pixels (depth at far plane)
+        //debugSkyCheck: true
+    },
+
     // Planar Reflections (alternative to SSR for water/floor)
     planarReflection: {
         enabled: true,                  // Disabled by default (use SSR instead)
@@ -279,6 +311,40 @@ const DEFAULT_SETTINGS = {
         fpsThreshold: 60,               // FPS threshold for auto-disable
         disableDelay: 3.0,              // Seconds below threshold before disabling
     },
+
+    // CRT effect (retro monitor simulation)
+    crt: {
+        enabled: false,                 // Enable CRT effect (geometry, scanlines, etc.)
+        upscaleEnabled: false,          // Enable upscaling (pixelated look) even when CRT disabled
+        upscaleTarget: 4,               // Target upscale multiplier (4x render resolution)
+        maxTextureSize: 4096,           // Max upscaled texture dimension
+
+        // Geometry distortion
+        curvature: 0.14,                // Screen curvature amount (0-0.15)
+        cornerRadius: 0.055,             // Rounded corner radius (0-0.1)
+        zoom: 1.06,                      // Zoom to compensate for curvature shrinkage
+
+        // Scanlines (electron beam simulation - Gaussian profile)
+        scanlineIntensity: 0.4,         // Scanline effect strength (0-1)
+        scanlineWidth: 0.0,            // Beam width (0=thin/center only, 1=no gap)
+        scanlineBrightBoost: 0.8,       // Bright pixels widen beam to fill gaps (0-1)
+        scanlineHeight: 5,              // Scanline height in canvas pixels
+
+        // RGB convergence error (color channel misalignment)
+        convergence: [0.79, 0.0, -0.77],  // RGB X offset in source pixels
+
+        // Phosphor mask
+        maskType: 'aperture',           // 'aperture', 'slot', 'shadow', 'none'
+        maskIntensity: 0.25,             // Mask strength (0-1)
+        maskScale: 1.0,                 // Mask size multiplier
+
+        // Vignette (edge darkening)
+        vignetteIntensity: 0.54,        // Edge darkening strength (0-1)
+        vignetteSize: 0.85,              // Vignette size (larger = more visible)
+
+        // Horizontal blur (beam softness)
+        blurSize: 0.79,                  // Horizontal blur in pixels (0-2)
+    },
 }
 
 // Function to create WebGPU context
@@ -377,10 +443,27 @@ async function createWebGPUContext(engine, canvasId) {
         engine.rendering = true
 
         function configureContext() {
-            const devicePixelRatio = window.devicePixelRatio || 1
-            const renderScale = engine.renderScale || 1.0
-            canvas.width = Math.floor(canvas.clientWidth * devicePixelRatio * renderScale) | 0
-            canvas.height = Math.floor(canvas.clientHeight * devicePixelRatio * renderScale) | 0
+            // Use exact device pixel size if available (from ResizeObserver)
+            // This ensures pixel-perfect rendering for CRT effects
+            let pixelWidth, pixelHeight
+            if (engine._devicePixelSize) {
+                pixelWidth = engine._devicePixelSize.width
+                pixelHeight = engine._devicePixelSize.height
+            } else {
+                // Fallback to clientWidth * devicePixelRatio
+                const devicePixelRatio = window.devicePixelRatio || 1
+                pixelWidth = Math.round(canvas.clientWidth * devicePixelRatio)
+                pixelHeight = Math.round(canvas.clientHeight * devicePixelRatio)
+            }
+
+            // Canvas is ALWAYS at full device pixel resolution for pixel-perfect CRT
+            // Render scale only affects internal render passes, not the final canvas
+            canvas.width = pixelWidth
+            canvas.height = pixelHeight
+
+            // Store device pixel size for CRT pass
+            engine._canvasPixelSize = { width: pixelWidth, height: pixelHeight }
+
             context.configure({
                 device: device,
                 format: canvasFormat,
@@ -507,9 +590,40 @@ class Engine {
             this.stats.avg_dt_render = 0.1
 
             requestAnimationFrame(() => this._frame())
-            window.addEventListener("resize", () => {
-                this.needsResize = true
-            })
+
+            // Use ResizeObserver with devicePixelContentBoxSize for pixel-perfect sizing
+            this._devicePixelSize = null
+            try {
+                const resizeObserver = new ResizeObserver((entries) => {
+                    for (const entry of entries) {
+                        // Prefer devicePixelContentBoxSize for exact device pixels
+                        if (entry.devicePixelContentBoxSize) {
+                            const size = entry.devicePixelContentBoxSize[0]
+                            this._devicePixelSize = {
+                                width: size.inlineSize,
+                                height: size.blockSize
+                            }
+                        } else if (entry.contentBoxSize) {
+                            // Fallback to contentBoxSize * devicePixelRatio
+                            const size = entry.contentBoxSize[0]
+                            const dpr = window.devicePixelRatio || 1
+                            this._devicePixelSize = {
+                                width: Math.round(size.inlineSize * dpr),
+                                height: Math.round(size.blockSize * dpr)
+                            }
+                        }
+                        this.needsResize = true
+                    }
+                })
+                resizeObserver.observe(this.canvas, { box: 'device-pixel-content-box' })
+            } catch (e) {
+                // Fallback if device-pixel-content-box not supported
+                console.log('ResizeObserver device-pixel-content-box not supported, falling back to window resize')
+                window.addEventListener("resize", () => {
+                    this.needsResize = true
+                })
+            }
+
             setInterval(() => {
               if (this.needsResize && !this._resizing) {
                   this.needsResize = false
@@ -652,12 +766,22 @@ class Engine {
      * @param {Array} options.position - Optional position offset [x, y, z]
      * @param {Array} options.rotation - Optional rotation offset [x, y, z] in radians
      * @param {number} options.scale - Optional uniform scale multiplier
+     * @param {boolean} options.doubleSided - Optional: force all materials to be double-sided
      * @returns {Promise<Object>} Object containing { meshes, nodes, skins, animations }
      */
     async loadScene(url, options = {}) {
         const result = await loadGltf(this, url, options)
         const { meshes, nodes } = result
 
+        // Apply scene-wide doubleSided option if specified
+        if (options.doubleSided) {
+            for (const mesh of Object.values(meshes)) {
+                if (mesh.material) {
+                    mesh.material.doubleSided = true
+                }
+            }
+        }
+
         // Update node world matrices from their hierarchy
         // This handles Blender's Z-up to Y-up rotation in parent nodes
         for (const node of nodes) {
@@ -685,6 +809,30 @@ class Engine {
             )
         }
 
+        // For skinned models with multiple submeshes, compute a combined bounding sphere
+        // This ensures all submeshes are culled together as a unit (especially for shadows)
+        let combinedBsphere = null
+        const hasAnySkin = Object.values(meshes).some(m => m.hasSkin)
+
+        if (hasAnySkin) {
+            // Collect all vertex positions from ALL meshes
+            const allPositions = []
+            for (const mesh of Object.values(meshes)) {
+                const positions = mesh.geometry?.attributes?.position
+                if (positions) {
+                    for (let i = 0; i < positions.length; i += 3) {
+                        allPositions.push(positions[i], positions[i + 1], positions[i + 2])
+                    }
+                }
+            }
+
+            if (allPositions.length > 0) {
+                // Calculate combined bounding sphere
+                const { calculateBoundingSphere } = await import('./utils/BoundingSphere.js')
+                combinedBsphere = calculateBoundingSphere(new Float32Array(allPositions))
+            }
+        }
+
         // For each mesh, find its node and compute world transform
         for (const [name, mesh] of Object.entries(meshes)) {
             // Find the node that references this mesh by nodeIndex
@@ -705,7 +853,8 @@ class Engine {
             }
 
             // Compute world bounding sphere from geometry bsphere + world transform
-            const localBsphere = mesh.geometry.getBoundingSphere?.()
+            // For skinned models, use the combined bsphere so all submeshes are culled together
+            const localBsphere = (hasAnySkin && combinedBsphere) ? combinedBsphere : mesh.geometry.getBoundingSphere?.()
             let worldCenter = [0, 0, 0]
             let worldRadius = 1
 
@@ -724,6 +873,11 @@ class Engine {
                 worldRadius = localBsphere.radius * Math.max(scaleX, scaleY, scaleZ)
             }
 
+            // Store combined bsphere on mesh for shadow pass culling
+            if (hasAnySkin && combinedBsphere) {
+                mesh.combinedBsphere = combinedBsphere
+            }
+
             // Add instance with world bounding sphere
             mesh.addInstance(worldCenter, worldRadius)
             mesh.updateInstance(0, worldMatrix)
@@ -816,6 +970,17 @@ class Engine {
         return this.entityManager.get(id)
     }
 
+    /**
+     * Invalidate occlusion culling data and reset warmup period.
+     * Call this after scene loading or major camera teleportation to prevent
+     * incorrect occlusion culling with stale depth buffer data.
+     */
+    invalidateOcclusionCulling() {
+        if (this.renderer) {
+            this.renderer.invalidateOcclusionCulling()
+        }
+    }
+
     async _create() {
         let camera = new Camera(this)  // Pass engine reference
         camera.updateMatrix()
@@ -848,6 +1013,10 @@ class Engine {
 
     async _after_create() {
         this.renderer = await RenderGraph.create(this, this.environment, this.environmentEncoding)
+
+        // Initialize raycaster for async ray intersection tests
+        this.raycaster = new Raycaster(this)
+        await this.raycaster.initialize()
     }
 
     _update(dt) {
@@ -971,7 +1140,9 @@ class Engine {
             this.guiCtx.clearRect(0, 0, canvas.width, canvas.height)
         }
 
-        await this.renderer.resize(canvas.width, canvas.height)
+        // Pass render scale to RenderGraph - internal passes use scaled dimensions
+        // CRT pass will still output at full canvas resolution
+        await this.renderer.resize(canvas.width, canvas.height, this.renderScale)
         this.resize()
 
         // Small delay before allowing renders to ensure all GPU resources are ready
@@ -1321,4 +1492,5 @@ export {
     ParticleSystem,
     ParticleEmitter,
     DebugUI,
+    Raycaster,
 }