@preference-sl/pref-viewer 2.12.0-beta.2 → 2.12.0-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.12.0-beta.2",
+    "version": "2.12.0-beta.4",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {

package/src/babylonjs-controller.js

@@ -1,4 +1,4 @@
-import { ArcRotateCamera, AssetContainer, Camera, Color4, DirectionalLight, Engine, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, LoadAssetContainerAsync, MeshBuilder, PointerEventTypes, PointLight, Scene, ShadowGenerator, Tools, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState } from "@babylonjs/core";
+import { ArcRotateCamera, AssetContainer, Camera, Color4, DefaultRenderingPipeline, DirectionalLight, Engine, HDRCubeTexture, HemisphericLight, IblShadowsRenderPipeline, LoadAssetContainerAsync, MeshBuilder, PBRMaterial, PointerEventTypes, PointLight, Scene, ShadowGenerator, SpotLight, SSAORenderingPipeline, Tools, Vector3, WebXRDefaultExperience, WebXRFeatureName, WebXRSessionManager, WebXRState } from "@babylonjs/core";
 import { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression.js";
 import "@babylonjs/loaders";
 import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression.js";
@@ -38,15 +38,17 @@ import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
  *  - Disable rendering: controller.disable();
  *
  * Public Methods:
- *  - enable(): Initializes engine, scene, camera, lights, XR, and starts rendering.
- *  - disable(): Disposes engine and disconnects resize observer.
- *  - load(): Loads all asset containers and adds them to the scene.
- *  - setCameraOptions(): Applies camera options from configuration.
- *  - setMaterialOptions(): Applies material options from configuration.
- *  - setContainerVisibility(name, show): Shows or hides a container by name.
- *  - downloadGLB(content): Downloads the current scene, model, or environment as a GLB file.
- *  - downloadGLTF(content): Downloads the current scene, model, or environment as a glTF ZIP file.
- *  - downloadUSDZ(content): Downloads the current scene, model, or environment as a USDZ file.
+ *  - constructor(canvas, containers, options): Creates the controller, wires container state, and stores runtime options.
+ *  - enable(): Boots the Babylon.js engine, scene, camera, baseline lights, XR support, and the render loop.
+ *  - disable(): Stops rendering and disposes the engine, lights, XR experience, and observers.
+ *  - load(): Reloads every pending asset container, re-applies options, and resolves with the loading summary { success, error }.
+ *  - setCameraOptions(): Applies the pending camera selection, reinstalls dependent pipelines, and restarts rendering safely.
+ *  - setMaterialOptions(): Re-applies all configured material overrides across visible containers and restarts rendering.
+ *  - setIBLOptions(): Pushes pending HDR/IBL updates, refreshes dependent effects, and resumes the render loop.
+ *  - setContainerVisibility(name, show): Toggles model/environment containers, syncing wall/floor helpers and component attributes.
+ *  - downloadGLB(content): Exports the selected scope (scene/model/environment) into a time-stamped GLB and triggers the download.
+ *  - downloadGLTF(content): Generates a glTF + BIN + textures ZIP for the requested scope, adding metadata comments for traceability.
+ *  - downloadUSDZ(content): Builds an Apple USDZ archive for the requested scope and downloads it via blob streaming.
  *
  * Private Methods (using ECMAScript private fields):
  *  - #bindHandlers(): Pre-binds reusable event handlers to preserve stable references.
@@ -56,9 +58,13 @@ import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
  *  - #createXRExperience(): Initializes WebXR AR experience.
  *  - #createCamera(): Creates and configures the main camera.
  *  - #createLights(): Creates and configures scene lights and shadows.
+ *  - #initializeAmbientOcclussion(): Rebuilds the SSAO pipeline for the active camera.
+ *  - #initializeVisualImprovements(): Reinstalls the default rendering pipeline (MSAA/FXAA/grain).
  *  - #initializeEnvironmentTexture(): Loads and sets the HDR environment texture.
  *  - #initializeIBLShadows(): Sets up IBL shadow pipeline and assigns meshes/materials.
  *  - #initializeShadows(): Sets up standard or IBL shadows for meshes.
+ *  - #initializeDefaultLightShadows(): Configures soft shadows when no HDR environment exists.
+ *  - #initializeEnvironmentShadows(): Rebuilds environment-provided shadow generators.
  *  - #setMaxSimultaneousLights(): Updates max simultaneous lights for all materials.
  *  - #onPointerObservable(info): Handles pointer events and dispatches to pointer/mouse handlers.
  *  - #onPointerUp(event, pickInfo): Handles pointer up events (e.g., right-click for animation menu).
@@ -73,6 +79,7 @@ import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
  *  - #setOptionsMaterial(optionMaterial): Applies a material option to relevant meshes.
  *  - #setOptions_Materials(): Applies all material options from configuration.
  *  - #setOptions_Camera(): Applies camera options from configuration.
+ *  - #setOptions_IBL(): Applies pending HDR/IBL option updates and refreshes lights.
  *  - #findContainerByName(name): Finds a container by its name.
  *  - #addContainer(container, updateVisibility): Adds a container to the scene and updates visibility.
  *  - #removeContainer(container, updateVisibility): Removes a container from the scene and updates visibility.
@@ -85,6 +92,7 @@ import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
  *  - #startRender(): Starts the Babylon.js render loop.
  *  - #loadAssetContainer(container): Loads an asset container asynchronously.
  *  - #loadContainers(): Loads all asset containers and adds them to the scene.
+ *  - #loadCameraDepentEffects(): Re-initializes camera-bound post-processes after reloads or option changes.
  *  - #checkModelMetadata(oldMetadata, newMetadata): Processes metadata changes after loading.
  *  - #checkInnerFloorTranslation(oldMetadata, newMetadata): Applies inner floor Y translations from metadata.
  *  - #translateNodeY(name, deltaY): Adjusts the Y position of a scene node.
@@ -107,7 +115,7 @@ export default class BabylonJSController {
     #hemiLight = null;
     #dirLight = null;
     #cameraLight = null;
-    #shadowGen = null;
+    #shadowGen = [];
     #XRExperience = null;
     #canvasResizeObserver = null;
 
@@ -123,6 +131,8 @@ export default class BabylonJSController {
         renderLoop: null,
     };
 
+    #shadowsEnabled = false;
+
     /**
      * Constructs a new BabylonJSController instance.
      * Initializes the canvas, asset containers, and options for the Babylon.js scene.
@@ -288,33 +298,151 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #createLights() {
-        this.#initializeEnvironmentTexture();
+        if (this.#options.ibl && this.#options.ibl.url) {
+            this.#hemiLight = this.#dirLight = this.#cameraLight = null;
+            this.#initializeEnvironmentTexture();
+        }
 
         if (this.#scene.environmentTexture) {
             return true;
         }
 
         // 1) Stronger ambient fill
-        this.#hemiLight = new HemisphericLight("hemiLight", new Vector3(-10, 10, -10), this.#scene);
+        this.#hemiLight = new HemisphericLight("PrefViewerHemiLight", new Vector3(-10, 10, -10), this.#scene);
         this.#hemiLight.intensity = 0.6;
 
         // 2) Directional light from the front-right, angled slightly down
-        this.#dirLight = new DirectionalLight("dirLight", new Vector3(-10, 10, -10), this.#scene);
+        this.#dirLight = new DirectionalLight("PrefViewerDirLight", new Vector3(-10, 10, -10), this.#scene);
         this.#dirLight.position = new Vector3(5, 4, 5); // light is IN FRONT + ABOVE + to the RIGHT
         this.#dirLight.intensity = 0.6;
 
-        // // 3) Soft shadows
-        this.#shadowGen = new ShadowGenerator(1024, this.#dirLight);
-        this.#shadowGen.useBlurExponentialShadowMap = true;
-        this.#shadowGen.blurKernel = 16;
-        this.#shadowGen.darkness = 0.5;
-
-        // 4) Camera‐attached headlight
-        this.#cameraLight = new PointLight("pl", this.#camera.position, this.#scene);
+        // 3) Camera‐attached headlight
+        this.#cameraLight = new PointLight("PrefViewerCameraLight", this.#camera.position, this.#scene);
         this.#cameraLight.parent = this.#camera;
         this.#cameraLight.intensity = 0.3;
     }
 
+    /**
+     * Rebuilds the SSAO post-process pipeline to inject screenspace ambient occlusion on the active camera.
+     * Disposes previous SSAO pipelines, instantiates a tuned `SSAORenderingPipeline`, and attaches it to the
+     * current camera so contact shadows enhance depth perception once assets reload or the camera changes.
+     * @private
+     * @returns {boolean} True if the SSAO pipeline is supported and enabled, otherwise false.
+     */
+    #initializeAmbientOcclussion() {
+        if (!this.#scene || !this.#scene.postProcessRenderPipelineManager || this.#scene.activeCamera === null) {
+            return false;
+        }
+
+        const pipelineName = "PrefViewerSSAORenderingPipeline";
+
+        const supportedPipelines = this.#scene.postProcessRenderPipelineManager.supportedPipelines;
+
+        if (!supportedPipelines) {
+            return false;
+        }
+
+        const oldSsaoPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
+
+        if (oldSsaoPipeline) {
+            oldSsaoPipeline.dispose();
+            this.#scene.postProcessRenderPipelineManager.update();
+        }
+
+        const ssaoRatio = {
+            ssaoRatio: 0.5,
+            combineRatio: 1.0
+        };
+
+        const ssaoPipeline = new SSAORenderingPipeline(pipelineName, this.#scene, ssaoRatio, [this.#scene.activeCamera]);
+
+        if (!ssaoPipeline){
+            return false;
+        }   
+
+        if (ssaoPipeline.isSupported) {
+            ssaoPipeline.fallOff = 0.000001;
+            ssaoPipeline.area = 1;
+            ssaoPipeline.radius = 0.0001;
+            ssaoPipeline.totalStrength = 1;
+            ssaoPipeline.base = 0.6;
+            this.#scene.postProcessRenderPipelineManager.update();
+            return true;
+        } else {
+            ssaoPipeline.dispose();
+            this.#scene.postProcessRenderPipelineManager.update();
+            return false;
+        }
+    }
+
+    /**
+     * Rebuilds the custom default rendering pipeline (MSAA, FXAA, film grain) for the active camera.
+     * Disposes any previous pipeline instance to avoid duplicates, then attaches a fresh
+     * `DefaultRenderingPipeline` with tuned settings for sharper anti-aliasing and subtle grain.
+     * @private
+     * @returns {boolean} True when the pipeline is supported and active, otherwise false.
+     * @see {@link https://doc.babylonjs.com/features/featuresDeepDive/postProcesses/defaultRenderingPipeline|Using the Default Rendering Pipeline | Babylon.js Documentation}
+     */
+    #initializeVisualImprovements() {
+        if (!this.#scene || !this.#scene.postProcessRenderPipelineManager || this.#scene.activeCamera === null) {
+            return false;
+        }
+
+        const pipelineName = "PrefViewerDefaultRenderingPipeline";
+        const supportedPipelines = this.#scene.postProcessRenderPipelineManager.supportedPipelines;
+
+        if (!supportedPipelines) {
+            return false;
+        }
+
+        const oldDefaultPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
+
+        if (oldDefaultPipeline) {
+            oldDefaultPipeline.dispose();
+            this.#scene.postProcessRenderPipelineManager.update();
+        }
+
+        const defaultPipeline = new DefaultRenderingPipeline(pipelineName, true, this.#scene, [this.#scene.activeCamera], true);
+
+        if (!defaultPipeline){
+            return false;
+        } 
+
+        if (defaultPipeline.isSupported) {
+            // MSAA - Multisample Anti-Aliasing
+            const caps = this.#scene.getEngine()?.getCaps?.() || {};
+            const maxSamples = typeof caps.maxMSAASamples === "number" ? caps.maxMSAASamples : 4;
+            defaultPipeline.samples = Math.max(1, Math.min(8, maxSamples));
+
+            // FXAA - Fast Approximate Anti-Aliasing
+            defaultPipeline.fxaaEnabled = true;
+            defaultPipeline.fxaa.samples = 8;
+            defaultPipeline.fxaa.adaptScaleToCurrentViewport = true;
+            if (defaultPipeline.fxaa.edgeThreshold !== undefined) {
+                defaultPipeline.fxaa.edgeThreshold = 0.125;
+            }
+            if (defaultPipeline.fxaa.edgeThresholdMin !== undefined) {
+                defaultPipeline.fxaa.edgeThresholdMin = 0.0625;
+            }
+            if (defaultPipeline.fxaa.subPixelQuality !== undefined) {
+                defaultPipeline.fxaa.subPixelQuality = 0.75;
+            }
+
+            // Grain
+            defaultPipeline.grainEnabled = true;
+            defaultPipeline.grain.adaptScaleToCurrentViewport = true;
+            defaultPipeline.grain.animated = false;
+            defaultPipeline.grain.intensity = 3;
+
+            this.#scene.postProcessRenderPipelineManager.update();
+            return true;
+        } else {
+            defaultPipeline.dispose();
+            this.#scene.postProcessRenderPipelineManager.update();
+            return false;
+        }
+    }
+
     /**
      * Initializes the environment texture for the Babylon.js scene.
      * Loads an HDR texture from a predefined URI and assigns it to the scene's environmentTexture property.
@@ -323,15 +451,9 @@ export default class BabylonJSController {
      * @returns {boolean}
      */
     #initializeEnvironmentTexture() {
-        return false; // Environment texture disabled by the moment
-        if (this.#scene.environmentTexture) {
-            return false;
-        }
-        const hdrTextureURI = "../src/environments/noon_grass.hdr";
-        const hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, 128);
-        hdrTexture.gammaSpace = true;
-        hdrTexture._noMipmap = false;
-        hdrTexture.level = 2.0;
+        const hdrTextureURI = this.#options.ibl.url;
+        const hdrTexture = new HDRCubeTexture(hdrTextureURI, this.#scene, 128, false, false, false, true);
+        hdrTexture.level = this.#options.ibl.intensity;
         this.#scene.environmentTexture = hdrTexture;
         return true;
     }
@@ -345,61 +467,141 @@ export default class BabylonJSController {
      * @returns {void|false} Returns false if no environment texture is set; otherwise void.
      */
     #initializeIBLShadows() {
-        if (!this.#scene.environmentTexture || !this.#scene.environmentTexture.isReady()) {
+        if (!this.#scene || !this.#scene.postProcessRenderPipelineManager || this.#scene.activeCamera === null) {
             return false;
         }
 
-        /**
-         * Creates and configures the IBL shadow render pipeline for the Babylon.js scene.
-         * Sets recommended options for resolution, sampling, opacity, and disables debug passes.
-         * Accepts an optional camera array for pipeline targeting.
-         * @private
-         * @param {Scene} scene - The Babylon.js scene instance.
-         * @param {Camera[]} [cameras] - Optional array of cameras to target with the pipeline.
-         * @returns {IblShadowsRenderPipeline} The configured IBL shadow pipeline.
-         */
-        let createIBLShadowPipeline = function (scene, cameras = [scene.activeCamera]) {
-            const pipeline = new IblShadowsRenderPipeline(
-                "iblShadowsPipeline",
-                scene,
-                {
-                    resolutionExp: 8, // Higher resolution for better shadow quality
-                    sampleDirections: 4, // More sample directions for smoother shadows
-                    ssShadowsEnabled: true,
-                    shadowRemanence: 0.85,
-                    triPlanarVoxelization: true,
-                    shadowOpacity: 0.85,
-                },
-                cameras
-            );
+        // if (!this.#scene.environmentTexture || !this.#scene.environmentTexture.isReady()) {
+        if (!this.#scene.environmentTexture) {
+            return false;
+        }
+        const pipelineName = "PrefViewerIblShadowsRenderPipeline";
+        const supportedPipelines = this.#scene.postProcessRenderPipelineManager.supportedPipelines;
+
+        if (!supportedPipelines) {
+            return false;
+        }
+
+        const oldIblShadowsRenderPipeline = supportedPipelines ? supportedPipelines.find((pipeline) => pipeline.name === pipelineName) : false;
+
+        if (oldIblShadowsRenderPipeline) {
+            oldIblShadowsRenderPipeline.dispose();
+            this.#scene.postProcessRenderPipelineManager.update();
+        }
+
+        const pipelineOptions = {
+            resolutionExp: 8, // Higher resolution for better shadow quality
+            sampleDirections: 4, // More sample directions for smoother shadows
+            ssShadowsEnabled: true,
+            shadowRemanence: 0.85,
+            triPlanarVoxelization: true,
+            shadowOpacity: 0.85,
+        };
+
+        const iblShadowsRenderPipeline = new IblShadowsRenderPipeline(pipelineName, this.#scene, pipelineOptions, [this.#scene.activeCamera]);
+
+        if (!iblShadowsRenderPipeline) {
+            return false;
+        }
+       
+        if (iblShadowsRenderPipeline.isSupported) {
             // Disable all debug passes for performance
             const pipelineProps = {
                 allowDebugPasses: false,
                 gbufferDebugEnabled: false,
                 importanceSamplingDebugEnabled: false,
                 voxelDebugEnabled: false,
-                voxelDebugDisplayMip: 0,
+                voxelDebugDisplayMip: 1,
                 voxelDebugAxis: 0,
                 voxelTracingDebugEnabled: false,
                 spatialBlurPassDebugEnabled: false,
                 accumulationPassDebugEnabled: false,
             };
-            Object.assign(pipeline, pipelineProps);
-            return pipeline;
-        };
 
-        let iblShadowsPipeline = createIBLShadowPipeline(this.#scene);
+            Object.assign(iblShadowsRenderPipeline, pipelineProps);
+
+            this.#scene.meshes.forEach((mesh) => {
+                if (mesh.id.startsWith("__root__") || mesh.name === "hdri") {
+                    return false;
+                }
+                iblShadowsRenderPipeline.addShadowCastingMesh(mesh);
+                iblShadowsRenderPipeline.updateSceneBounds();
+                mesh.receiveShadows = true; // Not necessary for IBL shadows, but yes for standard shadows
+            });
+
+            this.#scene.materials.forEach((material) => {
+                if (material instanceof PBRMaterial) {
+                    material.enableSpecularAntiAliasing = false;
+                }
+                iblShadowsRenderPipeline.addShadowReceivingMaterial(material);
+            });
 
+            iblShadowsRenderPipeline.updateVoxelization();
+            this.#scene.postProcessRenderPipelineManager.update();
+            return true;
+        } else {
+            iblShadowsRenderPipeline.dispose();
+            this.#scene.postProcessRenderPipelineManager.update();
+            return false;
+        }
+    }
+
+    /**
+     * Configures soft shadows for the built-in directional light used when no HDR environment is present.
+     * @private
+     * @returns {void}
+     */
+    #initializeDefaultLightShadows() {
+        this.#shadowGen = [];
+        const shadowGenerator = new ShadowGenerator(1024, this.#dirLight);
+        shadowGenerator.useBlurExponentialShadowMap = true;
+        shadowGenerator.blurKernel = 16;
+        shadowGenerator.darkness = 0.5;
         this.#scene.meshes.forEach((mesh) => {
-            if (mesh.id.startsWith("__root__") || mesh.name === "hdri") {
+            if (mesh.id.startsWith("__root__")) {
                 return false;
             }
-            iblShadowsPipeline.addShadowCastingMesh(mesh);
-            iblShadowsPipeline.updateSceneBounds();
+            if (mesh.name !== "hdri") {
+                shadowGenerator.addShadowCaster(mesh, true);
+            }
+            mesh.receiveShadows = true;
+        });
+        this.#shadowGen.push(shadowGenerator);
+    }
+
+    /**
+     * Rebuilds the shadow generators contributed by the environment container.
+     * Keeps only the generator bound to the built-in `PrefViewerDirLight` so its shadows persist,
+     * then adds generators for every directional or spot light coming from the environment asset container.
+     * @private
+     * @returns {void}
+     */
+    #initializeEnvironmentShadows() {
+        this.#shadowGen = this.#shadowGen.filter((generator) => {
+            if (!generator || typeof generator.getLight !== "function") {
+                return false;
+            }
+            return generator.getLight()?.name === "PrefViewerDirLight";
         });
 
-        this.#scene.materials.forEach((material) => {
-            iblShadowsPipeline.addShadowReceivingMaterial(material);
+        this.#containers.environment?.AssetContainer?.lights.forEach((light) => {
+            // Only shadows for DirectionalLight and SpotLight types
+            if (!(light instanceof DirectionalLight || light instanceof SpotLight)) {
+                return;
+            }
+            const shadowGenerator = new ShadowGenerator(1024, light);
+            shadowGenerator.useBlurExponentialShadowMap = true;
+            shadowGenerator.blurKernel = 16;
+            shadowGenerator.darkness = 0.5;
+            this.#scene.meshes.forEach((mesh) => {
+                if (mesh.id.startsWith("__root__")) {
+                    return false;
+                }
+                if (mesh.name !== "hdri") {
+                    shadowGenerator.addShadowCaster(mesh, true);
+                }
+            });
+            this.#shadowGen.push(shadowGenerator);
         });
     }
 
@@ -412,20 +614,24 @@ export default class BabylonJSController {
      * Otherwise, sets up shadow casting and receiving for all relevant meshes using the shadow generator.
      */
     #initializeShadows() {
-        if (this.#scene.environmentTexture) {
-            this.#initializeIBLShadows();
-            return true;
+        if (!this.#shadowsEnabled) {
+            return false;
         }
-
-        this.#scene.meshes.forEach((mesh) => {
-            if (mesh.id.startsWith("__root__")) {
-                return false;
-            }
-            mesh.receiveShadows = true;
-            if (mesh.name !== "hdri") {
-                this.#shadowGen.addShadowCaster(mesh, true);
+        if (this.#scene.environmentTexture) {
+            if (this.#options.ibl.shadows) {
+                if (this.#scene.environmentTexture.isReady()) {
+                    this.#initializeIBLShadows();
+                } else {
+                    const self = this;
+                    this.#scene.environmentTexture.onLoadObservable.addOnce(() => {
+                        self.#initializeIBLShadows();
+                    });
+                }
             }
-        });
+        } else {
+            this.#initializeDefaultLightShadows();
+        }
+        this.#initializeEnvironmentShadows();
     }
 
     /**
@@ -435,7 +641,7 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #setMaxSimultaneousLights() {
-        let lightsNumber = 1; // Como mínimo una luz correspondiente a la textura de environmentTexture
+        let lightsNumber = 1; // At least one light coming from the environment texture contribution
         this.#scene.lights.forEach((light) => {
             if (light.isEnabled()) {
                 ++lightsNumber;
@@ -543,7 +749,7 @@ export default class BabylonJSController {
         this.#engine.dispose();
         this.#engine = this.#scene = this.#camera = null;
         this.#hemiLight = this.#dirLight = this.#cameraLight = null;
-        this.#shadowGen = null;
+        this.#shadowGen = [];
     }
 
     /**
@@ -689,7 +895,7 @@ export default class BabylonJSController {
         const modelContainer = this.#containers.model;
         const environmentContainer = this.#containers.environment;
 
-        if (!cameraState.isPending && !modelContainer.state.isPending && !environmentContainer.state.isPending) {
+        if (!cameraState.isPending && !modelContainer.state.isSuccess && !environmentContainer.state.isSuccess) {
             return false;
         }
 
@@ -733,6 +939,7 @@ export default class BabylonJSController {
                 cameraState.setSuccess(true);
             }
         }
+        this.#scene.activeCamera?.detachControl();
         if (!cameraState.locked && cameraState.value !== null) {
             camera.attachControl(this.#canvas, true);
         }
@@ -740,6 +947,21 @@ export default class BabylonJSController {
         return true;
     }
 
+    /**
+     * Applies pending image-based lighting (IBL) option updates.
+     * Marks the IBL state as successful, recreates lights so the new environment takes effect, and reports whether anything changed.
+     * @private
+     * @returns {boolean} True when lights were refreshed due to pending IBL changes, otherwise false.
+     */
+    #setOptions_IBL() {
+        if (this.#options.ibl.isPending) {
+            this.#options.ibl.setSuccess(true);
+            this.#createLights();
+            return true;
+        }
+        return false;
+    }
+
     /**
      * Finds and returns the asset container object by its name.
      * @private
@@ -915,8 +1137,9 @@ export default class BabylonJSController {
         if (!this.#gltfResolver) {
             this.#gltfResolver = new GLTFResolver();
         }
-
-        let sourceData = await this.#gltfResolver.getSource(container.state.update.storage, container.state.size, container.state.timeStamp);
+        //let sourceData = await this.#gltfResolver.getSource(container.state.update.storage, container.state.size, container.state.timeStamp);
+        // TEMPORARY: We never pass 'size' or 'timeStamp' to always force a reload and avoid issues with the active camera in reloading assetContainers
+        let sourceData = await this.#gltfResolver.getSource(container.state.update.storage, 0, null);
         if (!sourceData) {
             return [container, false];
         }
@@ -949,6 +1172,7 @@ export default class BabylonJSController {
      */
     async #loadContainers() {
         this.#stopRender();
+        this.#scene.postProcessRenderPipelineManager?.dispose();
 
         let oldModelMetadata = { ...(this.#containers.model?.state?.metadata ?? {}) };
         let newModelMetadata = {};
@@ -986,6 +1210,7 @@ export default class BabylonJSController {
 
                 this.#setOptions_Materials();
                 this.#setOptions_Camera();
+                this.#setOptions_IBL();
                 this.#setVisibilityOfWallAndFloorInModel();
                 detail.success = true;
             })
@@ -998,13 +1223,25 @@ export default class BabylonJSController {
             .finally(async () => {
                 this.#checkModelMetadata(oldModelMetadata, newModelMetadata);
                 this.#setMaxSimultaneousLights();
-                this.#initializeShadows();
+                this.#loadCameraDepentEffects();
                 this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#scene);
                 this.#startRender();
             });
         return detail;
     }
 
+    /**
+     * Reinstalls every camera-sensitive post-process (default pipeline, SSAO, shadows) after loads or option changes.
+     * Ensures the active camera always owns fresh pipelines so render quality remains consistent across reload cycles.
+     * @private
+     * @returns {void}
+     */
+    #loadCameraDepentEffects() {
+        this.#initializeVisualImprovements();
+        this.#initializeAmbientOcclussion();
+        this.#initializeShadows();
+    }
+
     /**
      * Checks and applies model metadata changes after asset loading.
      * @private
@@ -1233,6 +1470,17 @@ export default class BabylonJSController {
         this.#engine = new Engine(this.#canvas, true, { alpha: true, stencil: true, preserveDrawingBuffer: false });
         this.#engine.disableUniformBuffers = true;
         this.#scene = new Scene(this.#engine);
+        
+        // Activate the rendering of geometry data into a G-buffer, essential for advanced effects like deferred shading,
+        // SSAO, and Velocity-Texture-Animation (VAT), allowing for complex post-processing by separating rendering into 
+        // different buffers (depth, normals, velocity) for later use in shaders. 
+        const geometryBufferRenderer = this.#scene.enableGeometryBufferRenderer();
+        if (geometryBufferRenderer) {
+            geometryBufferRenderer.enableScreenspaceDepth = true;
+            geometryBufferRenderer.enableDepth = false;
+            geometryBufferRenderer.generateNormalsInWorldSpace = true;
+        }
+
         this.#scene.clearColor = new Color4(1, 1, 1, 1);
         this.#createCamera();
         this.#createLights();
@@ -1276,6 +1524,7 @@ export default class BabylonJSController {
     setCameraOptions() {
         this.#stopRender();
         const cameraOptionsSetted = this.#setOptions_Camera();
+        this.#loadCameraDepentEffects();
         this.#startRender();
         return cameraOptionsSetted;
     }
@@ -1293,6 +1542,20 @@ export default class BabylonJSController {
         return materialsOptionsSetted;
     }
 
+    /**
+     * Reapplies image-based lighting configuration (HDR URL, intensity, shadow mode).
+     * Stops rendering, pushes pending IBL state into the scene, rebuilds camera-dependent effects, then resumes rendering.
+     * @public
+     * @returns {void}
+     */
+    setIBLOptions() {
+        this.#stopRender();
+        const IBLOptionsSetted = this.#setOptions_IBL();
+        this.#loadCameraDepentEffects();
+        this.#startRender();
+        return IBLOptionsSetted;
+    }
+
     /**
      * Sets the visibility of a container (model, environment, etc.) by name.
      * Adds or removes the container from the scene and updates wall/floor visibility.

package/src/pref-viewer-3d-data.js

@@ -181,3 +181,53 @@ export class CameraData {
         return this.update.success === true;
     }
 }
+
+/**
+ * IBLData - Tracks configurable settings for image-based lighting assets (IBL/HDR environments).
+ *
+ * Responsibilities:
+ *  - Stores the HDR url, intensity scalar, whether environment-provided shadows should render, and cache timestamp.
+ *  - Exposes a lightweight pending/success state machine so UI flows know when a new IBL selection is being fetched.
+ *  - Provides helpers to update values atomically via `setValues`, toggle pending state, and mark completion.
+ *
+ * Usage:
+ *  - Instantiate with defaults: `const ibl = new IBLData();`
+ *  - Call `setPending()` before kicking off an async download, `setValues()` as metadata streams in, and `setSuccess(true)` once loading finishes.
+ *  - Inspect `isPending`/`isSuccess` to drive UI or re-render logic.
+ */
+export class IBLData {
+    constructor(url = null, intensity = 1.0, shadows = false, timeStamp = null) {
+        this.url = url;
+        this.intensity = intensity;
+        this.shadows = shadows;
+        this.timeStamp = timeStamp;
+        this.reset();
+    }
+    reset() {
+        this.pending = false;
+        this.success = false;
+    }
+    setValues(url, intensity, shadows, timeStamp) {
+        this.url = url !== undefined ? url : this.url;
+        this.intensity = intensity !== undefined ? intensity : this.intensity;
+        this.shadows = shadows !== undefined ? shadows : this.shadows;
+        this.timeStamp = timeStamp !== undefined ? timeStamp : this.timeStamp;
+    }
+    setSuccess(success = false) {
+        if (success) {
+            this.success = true;
+        } else {
+            this.success = false;
+        }
+    }
+    setPending() {
+        this.pending = true;
+        this.success = false;
+    }
+    get isPending() {
+        return this.pending === true;
+    }
+    get isSuccess() {
+        return this.success === true;
+    }
+}

package/src/pref-viewer-3d.js

@@ -1,6 +1,7 @@
-import { CameraData, ContainerData, MaterialData } from "./pref-viewer-3d-data.js";
+import { CameraData, ContainerData, MaterialData, IBLData } from "./pref-viewer-3d-data.js";
 import BabylonJSController from "./babylonjs-controller.js";
 import { PrefViewer3DStyles } from "./styles.js";
+import { FileStorage } from "./file-storage.js";
 
 /**
  * PrefViewer3D - Custom Web Component for interactive 3D visualization and configuration.
@@ -8,7 +9,7 @@ import { PrefViewer3DStyles } from "./styles.js";
  * Overview:
  *  - Encapsulates a Babylon.js-powered 3D viewer for displaying models, environments, and materials.
  *  - Manages internal state for containers (model, environment, materials) and options (camera, materials).
- *  - Handles asset loading, configuration, and option updates through attributes and public methods.
+ *  - Handles asset loading, configuration, and option updates (camera, materials, IBL) through attributes and public methods.
  *  - Provides API for showing/hiding the viewer, model, and environment, and for downloading assets.
  *  - Emits custom events for loading, loaded, and option-setting states.
  *
@@ -26,7 +27,7 @@ import { PrefViewer3DStyles } from "./styles.js";
  *  - show(): Shows the 3D viewer component.
  *  - hide(): Hides the 3D viewer component.
  *  - load(config): Loads the provided configuration into the viewer.
- *  - setOptions(options): Sets viewer options such as camera and materials.
+ *  - setOptions(options): Sets viewer options such as camera, materials, and image-based lighting (IBL).
  *  - showModel(): Shows the 3D model.
  *  - hideModel(): Hides the 3D model.
  *  - showEnvironment(): Shows the 3D environment/scene.
@@ -46,6 +47,14 @@ import { PrefViewer3DStyles } from "./styles.js";
  *  - isLoaded: Indicates whether the GLTF/GLB content is loaded and ready.
  *  - isVisible: Indicates whether the component is currently visible.
  *
+ * Internal Helpers:
+ *  - #checkNeedToUpdateContainers(config): Flags model/environment/material containers that must reload.
+ *  - #checkNeedToUpdateCamera(options): Detects camera option changes and marks them pending.
+ *  - #checkNeedToUpdateMaterials(options): Resolves material overrides that require updates.
+ *  - #checkNeedToUpdateIBL(options): Fetches HDR URLs/timestamps and enqueues IBL updates when needed.
+ *  - #resetUpdateFlags(): Clears pending/success flags after loads or option-setting flows.
+ *  - #onLoading/#onLoaded/#onSettingOptions/#onSetOptions(): Dispatch lifecycle events and synchronize attributes.
+ *
  * Events:
  *  - "scene-loading": Dispatched when a loading operation starts.
  *  - "scene-loaded": Dispatched when a loading operation completes.
@@ -202,6 +211,7 @@ export default class PrefViewer3D extends HTMLElement {
                     innerFloor: new MaterialData("innerFloor", undefined, undefined, ["innerFloor"]),
                     outerFloor: new MaterialData("outerFloor", undefined, undefined, ["outerFloor"]),
                 },
+                ibl: new IBLData(),
             },
         };
     }
@@ -225,6 +235,7 @@ export default class PrefViewer3D extends HTMLElement {
         Object.values(this.#data.containers).forEach((container) => container.reset());
         Object.values(this.#data.options.materials).forEach((material) => material.reset());
         this.#data.options.camera.reset();
+        this.#data.options.ibl.reset();
     }
 
     /**
@@ -306,6 +317,51 @@ export default class PrefViewer3D extends HTMLElement {
         return someNeedUpdate;
     }
 
+    /**
+     * Resolves incoming IBL settings (HDR URL, timestamp, intensity, shadows) and marks the option as pending when changed.
+     * Fetches signed URLs/time stamps when storage keys are provided so the Babylon controller can reload the environment map.
+     * @private
+     * @param {object} options - Options payload that may contain an `ibl` block with url, intensity, or shadow flags.
+     * @returns {Promise<boolean>} Resolves to true when any IBL property differs from the cached state, otherwise false.
+     */
+    async #checkNeedToUpdateIBL(options) {
+        if (!options || options.ibl === undefined) {
+            return false;
+        }
+        const iblState = this.#data.options.ibl;
+
+        let url = undefined;
+        let timeStamp = undefined;
+        let shadows = undefined;
+        let intensity = undefined;
+
+        if (options.ibl.url) {
+            const fileStorage = new FileStorage("PrefViewer", "Files");
+            const newURL = await fileStorage.getURL(options.ibl.url);
+            if (newURL) {
+                url = newURL;
+                timeStamp = await fileStorage.getTimeStamp(options.ibl.url);
+            }
+        }
+        if (options.ibl.shadows !== undefined) {
+            shadows = options.ibl.shadows;
+        }
+        if (options.ibl.intensity !== undefined) {
+            intensity = options.ibl.intensity;
+        }
+
+        const needUpdate = url !== undefined && url !== iblState.url ||
+            timeStamp !== undefined && timeStamp !== iblState.timeStamp ||
+            shadows !== undefined && shadows !== iblState.shadows ||
+            intensity !== undefined && intensity !== iblState.intensity;
+        if (needUpdate) {
+            iblState.setValues(url, intensity, shadows, timeStamp);
+            iblState.setPending(true);
+        }
+        
+        return needUpdate;
+    }
+
     /**
      * Dispatches a "prefviewer3d-loading" event and updates loading state attributes.
      * Used internally when a loading operation starts.
@@ -490,6 +546,7 @@ export default class PrefViewer3D extends HTMLElement {
         if (config.options) {
             this.#checkNeedToUpdateCamera(config.options);
             this.#checkNeedToUpdateMaterials(config.options);
+            this.#checkNeedToUpdateIBL(config.options);
         }
 
         const loadDetail = await this.#babylonJSController.load();
@@ -518,6 +575,9 @@ export default class PrefViewer3D extends HTMLElement {
         if (this.#checkNeedToUpdateMaterials(options)) {
             someSetted = someSetted || this.#babylonJSController.setMaterialOptions();
         }
+        if (this.#checkNeedToUpdateIBL(options)) {
+            someSetted = someSetted || this.#babylonJSController.setIBLOptions();
+        }
         const detail = this.#onSetOptions();
         return { success: someSetted, detail: detail };
     }