@preference-sl/pref-viewer 2.12.0-beta.3 → 2.12.0-beta.5

package/package.json

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

package/src/babylonjs-animation-controller.js

@@ -1,4 +1,4 @@
-import { Color3, HighlightLayer, Mesh, PickingInfo, Scene } from "@babylonjs/core";
+import { AssetContainer, Color3, HighlightLayer, InstancedMesh, Mesh, PickingInfo, Quaternion, Scene, UtilityLayerRenderer, Vector3 } from "@babylonjs/core";
 import { PrefViewerColors } from "./styles.js";
 import OpeningAnimation from "./babylonjs-animation-opening.js";
 
@@ -18,27 +18,36 @@ import OpeningAnimation from "./babylonjs-animation-opening.js";
  *
  * Public Methods:
  *  - dispose(): Disposes all resources managed by the animation controller.
- *  - hightlightMeshes(pickingInfo): Highlights meshes that are children of an animated node when hovered.
+ *  - highlightMeshes(pickingInfo): Highlights meshes that are children of an animated node when hovered.
  *  - hideMenu(): Hides and disposes the animation control menu if it exists.
  *  - showMenu(pickingInfo): Displays the animation control menu for the animated node under the pointer.
  *
  * @class
  */
 export default class BabylonJSAnimationController {
-    #scene = null;
     #canvas = null;
+    #scene = null;
+    #assetContainer = null;
+
     #animatedNodes = [];
-    #highlightLayer = null;
-    #highlightColor = Color3.FromHexString(PrefViewerColors.primary);
     #openingAnimations = [];
 
+    #highlightColor = Color3.FromHexString(PrefViewerColors.primary);
+    #highlightLayer = null;
+    #overlayLayer = null;
+    #useHighlightLayer = false; // Set to true to use HighlightLayer (better performance) and false to use overlay meshes (UtilityLayerRenderer - always on top)
+    #lastHighlightedMeshId = null; // Cache to avoid redundant highlight updates
+
     /**
      * Creates a new BabylonJSAnimationController for a Babylon.js scene.
-     * @param {Scene} scene - The Babylon.js scene instance.
+     * @param {AssetContainer|Scene} assetContainer - The Babylon.js asset container or scene instance.
      */
-    constructor(scene) {
-        this.#scene = scene;
-        this.#canvas = this.#scene._engine._renderingCanvas;
+    constructor(assetContainer) {
+        if (assetContainer instanceof AssetContainer || assetContainer instanceof Scene) {
+            this.#scene = assetContainer.scene ? assetContainer.scene : assetContainer;
+            this.#assetContainer = assetContainer;
+            this.#canvas = this.#scene._engine._renderingCanvas;
+        }
         this.#initializeAnimations();
     }
 
@@ -48,7 +57,7 @@ export default class BabylonJSAnimationController {
      */
     #initializeAnimations() {
         this.hideMenu(); // Clean up any existing menus
-        if (!this.#scene.animationGroups.length) {
+        if (!this.#assetContainer?.animationGroups?.length) {
             return;
         }
         this.#getAnimatedNodes();
@@ -60,7 +69,7 @@ export default class BabylonJSAnimationController {
      * @private
      */
     #getAnimatedNodes() {
-        this.#scene.animationGroups.forEach((animationGroup) => {
+        this.#assetContainer.animationGroups.forEach((animationGroup) => {
             animationGroup.stop();
             if (!animationGroup._targetedAnimations.length) {
                 return;
@@ -81,7 +90,7 @@ export default class BabylonJSAnimationController {
      */
     #getOpeningAnimations() {
         const openings = {};
-        this.#scene.animationGroups.forEach((animationGroup) => {
+        this.#assetContainer.animationGroups.forEach((animationGroup) => {
             const match = animationGroup.name.match(/^animation_(open|close)_(.+)$/);
             if (!match) {
                 return;
@@ -118,7 +127,7 @@ export default class BabylonJSAnimationController {
      * @param {Mesh} mesh - The mesh to check.
      * @returns {Array<string>} Array of animated node IDs associated with the mesh.
      */
-    #getNodesAnimatedByMesh = function (mesh) {
+    #getNodesAnimatedByMesh(mesh) {
         let nodeId = [];
         let node = mesh;
         while (node.parent !== null) {
@@ -128,7 +137,176 @@ export default class BabylonJSAnimationController {
             }
         }
         return nodeId;
-    };
+    }
+
+    /**
+     * Creates overlay meshes with highlight rendering for a group of meshes.
+     * Handles both regular meshes and instanced meshes by creating clones in the utility layer.
+     * Synchronizes world matrix transformations between original and overlay meshes only when transforms change.
+     * @private
+     * @param {Mesh[]} meshes - Array of meshes to highlight with overlay outlines.
+     * @returns {Object} Cleanup API object with a dispose() method to release all overlay resources.
+     * @description
+     * - Uses UtilityLayerRenderer for rendering
+     * - Only syncs transforms when original mesh's world matrix changes (performance optimized)
+     * - Handles InstancedMeshes by creating instances of a shared overlay base
+     * - Removes overlay when mouse moves away from highlighted meshes
+     */
+    #addGroupOutlineOverlayForInstances(meshes) {
+        // Configuration
+        const OUTLINE_ENABLED = false; // Draw outline on individual meshes
+        const OUTLINE_COLOR = this.#highlightColor;
+        const OUTLINE_WIDTH = 1.5;
+        const OVERLAY_ENABLED = true; // Draw semi-transparent fill
+        const OVERLAY_COLOR = this.#highlightColor;
+        const OVERLAY_ALPHA = 0.25;
+        const RENDERING_GROUP_ID = 0; // MUST be > 0 to render on top of main scene
+
+        // Use UtilityLayerRenderer for rendering
+        const uScene = UtilityLayerRenderer.DefaultKeepDepthUtilityLayer.utilityLayerScene;
+
+        // Cache map: baseMesh -> overlayBaseMesh to reuse for InstancedMeshes
+        const baseToOverlayBase = new Map();
+
+        // Pairs of { original mesh, overlay mesh } for tracking
+        const pairs = [];
+
+        /**
+         * Gets the base mesh from either a regular mesh or an InstancedMesh
+         * @param {Mesh} mesh - The mesh to check
+         * @returns {Mesh} The base mesh or the mesh itself
+         */
+        function getBaseMesh(mesh) {
+            return mesh instanceof InstancedMesh ? mesh.sourceMesh : mesh;
+        }
+
+        /**
+         * Creates or retrieves an overlay base mesh in the utility scene
+         * Reuses the same base for all instances of the same source mesh
+         * @param {Mesh} baseMesh - The base mesh to clone
+         * @returns {Mesh} The overlay base mesh
+         */
+        function ensureOverlayBase(baseMesh) {
+            let overlayBase = baseToOverlayBase.get(baseMesh);
+            if (overlayBase) {
+                return overlayBase;
+            }
+
+            // Clone the source mesh into the utility scene (deep clone materials/geometry)
+            overlayBase = baseMesh.clone(baseMesh.name + "_overlayBase", null, true, false);
+            overlayBase._scene = uScene;
+            overlayBase.isPickable = false;
+            overlayBase.setEnabled(true);
+
+            // Configure visual appearance for the overlay
+            overlayBase.renderOutline = OUTLINE_ENABLED; // Only draw outline if enabled
+            overlayBase.outlineColor = OUTLINE_COLOR;
+            overlayBase.outlineWidth = OUTLINE_WIDTH;
+            
+            // Overlay color and transparency (semi-transparent colored fill)
+            overlayBase.renderOverlay = OVERLAY_ENABLED;
+            overlayBase.overlayColor = OVERLAY_COLOR;
+            overlayBase.overlayAlpha = OVERLAY_ALPHA;
+            
+            overlayBase.visibility = 1;
+
+            // Ensure always-on-top rendering or not
+            overlayBase.renderingGroupId = RENDERING_GROUP_ID;
+
+            baseToOverlayBase.set(baseMesh, overlayBase);
+            return overlayBase;
+        }
+
+        // Create overlay meshes for each input mesh
+        meshes.forEach((mesh) => {
+            // Skip meshes without geometry
+            if (!mesh.geometry && !mesh.getChildMeshes) {
+                return;
+            }
+
+            const baseMesh = getBaseMesh(mesh);
+            const overlayBase = ensureOverlayBase(baseMesh);
+
+            let overlay;
+            if (mesh instanceof InstancedMesh) {
+                // For instances, create a new instance of the overlay base
+                overlay = overlayBase.createInstance(mesh.name + "_overlayInst");
+                overlay._scene = uScene;
+                overlay.isPickable = false;
+            } else {
+                // For regular meshes, use the overlay base directly (avoids double cloning)
+                overlay = overlayBase;
+            }
+
+            // Remove parent to allow independent world matrix control
+            overlay.parent = null;
+            overlay.renderingGroupId = RENDERING_GROUP_ID;
+
+            pairs.push({ original: mesh, overlay });
+        });
+
+        // Sync world matrix transformations
+        const pos = new Vector3();
+        const scl = new Vector3();
+        const rot = new Quaternion();
+
+        // Track all observers for cleanup
+        const observers = [];
+
+        // Subscribe to world matrix update events
+        // This is more efficient than updating every frame
+        pairs.forEach(({ original, overlay }) => {
+            // Skip if mesh has no geometry to sync
+            if (!original.getWorldMatrix) {
+                return;
+            }
+
+            // Initial sync: copy the current world matrix
+            original.computeWorldMatrix(true);
+            original.getWorldMatrix().decompose(scl, rot, pos);
+
+            overlay.position.copyFrom(pos);
+            overlay.scaling.copyFrom(scl);
+            overlay.rotationQuaternion = overlay.rotationQuaternion || new Quaternion();
+            overlay.rotationQuaternion.copyFrom(rot);
+            overlay.computeWorldMatrix(true);
+
+            // Subscribe to world matrix changes
+            // Only updates when the original mesh's transformation actually changes
+            const obs = original.onAfterWorldMatrixUpdateObservable?.add(() => {
+                original.getWorldMatrix().decompose(scl, rot, pos);
+
+                overlay.position.copyFrom(pos);
+                overlay.scaling.copyFrom(scl);
+                overlay.rotationQuaternion.copyFrom(rot);
+                overlay.computeWorldMatrix(true);
+            });
+
+            if (obs) {
+                observers.push({ mesh: original, observer: obs });
+            }
+        });
+
+        // Cleanup API
+        return {
+            dispose() {
+                // Remove world matrix update observers
+                observers.forEach(({ mesh, observer }) => {
+                    mesh.onAfterWorldMatrixUpdateObservable?.remove(observer);
+                });
+
+                // Dispose overlay instances and meshes
+                pairs.forEach(({ original, overlay }) => {
+                    overlay.dispose();
+                });
+
+                // Dispose overlay base meshes
+                baseToOverlayBase.forEach((overlayBase) => {
+                    overlayBase.dispose();
+                });
+            },
+        };
+    }
 
     /**
      * ---------------------------
@@ -148,6 +326,10 @@ export default class BabylonJSAnimationController {
             this.#highlightLayer.dispose();
             this.#highlightLayer = null;
         }
+        if (this.#overlayLayer) {
+            this.#overlayLayer.dispose();
+            this.#overlayLayer = null;
+        }
         this.hideMenu();
         this.#animatedNodes = [];
         this.#openingAnimations.forEach((openingAnimation) => openingAnimation.dispose());
@@ -159,39 +341,74 @@ export default class BabylonJSAnimationController {
      * @public
      * @param {PickingInfo} pickingInfo - Raycast info from pointer position.
      */
-    hightlightMeshes(pickingInfo) {
-        if (!this.#highlightLayer) {
-            this.#highlightLayer = new HighlightLayer("hl_animations", this.#scene);
+    highlightMeshes(pickingInfo) {
+        // Check if we're hovering the same mesh to avoid recreating overlays/highlights
+        const pickedMeshId = pickingInfo?.pickedMesh?.id;
+        if (this.#lastHighlightedMeshId === pickedMeshId) {
+            return; // No need to update if hovering the same mesh
         }
+        this.#lastHighlightedMeshId = pickedMeshId;
 
-        this.#highlightLayer.removeAllMeshes();
-        if (!pickingInfo?.hit && !pickingInfo?.pickedMesh) {
-            return;
-        }
+        if (this.#useHighlightLayer) {
+            if (!this.#highlightLayer) {
+                this.#highlightLayer = new HighlightLayer("hl_animations", this.#scene);
+            }
 
-        const nodeIds = this.#getNodesAnimatedByMesh(pickingInfo.pickedMesh);
-        if (!nodeIds.length) {
-            return;
-        }
+            this.#highlightLayer.removeAllMeshes();
 
-        const transformNodes = [];
-        nodeIds.forEach((nodeId) => {
-            const transformNode = this.#scene.getTransformNodeByID(nodeId);
-            if (transformNode) {
-                transformNodes.push(transformNode);
+            if (!pickingInfo?.hit || !pickingInfo?.pickedMesh) {
+                return;
             }
-        });
 
-        transformNodes.forEach((transformNode) => {
-            const nodeMeshes = transformNode.getChildMeshes();
-            if (nodeMeshes.length) {
-                nodeMeshes.forEach((mesh) => {
-                    if (!this.#highlightLayer.hasMesh(mesh)) {
-                        this.#highlightLayer.addMesh(mesh, this.#highlightColor);
-                    }
-                });
+            const nodeIds = this.#getNodesAnimatedByMesh(pickingInfo.pickedMesh);
+            if (!nodeIds.length) {
+                return;
             }
-        });
+
+            const transformNodes = [];
+            nodeIds.forEach((nodeId) => {
+                const transformNode = this.#scene.getTransformNodeByID(nodeId);
+                if (transformNode) {
+                    transformNodes.push(transformNode);
+                }
+            });
+
+            transformNodes.forEach((transformNode) => {
+                const transformNodeMeshes = transformNode.getChildMeshes();
+                if (transformNodeMeshes.length) {
+                    transformNodeMeshes.forEach((mesh) => {
+                        if (!this.#highlightLayer.hasMesh(mesh)) {
+                            this.#highlightLayer.addMesh(mesh, this.#highlightColor);
+                        }
+                    });
+                }
+            });
+        } else {
+            if (this.#overlayLayer) {
+                this.#overlayLayer.dispose();
+                this.#overlayLayer = null;
+            }
+
+            if (!pickingInfo?.hit || !pickingInfo?.pickedMesh) {
+                return;
+            }
+
+            const nodeIds = this.#getNodesAnimatedByMesh(pickingInfo.pickedMesh);
+            if (!nodeIds.length) {
+                return;
+            }
+
+            const meshes = [];
+            nodeIds.forEach((nodeId) => {
+                const transformNode = this.#scene.getTransformNodeByID(nodeId);
+                if (transformNode) {
+                    const transformNodeMeshes = transformNode.getChildMeshes(false);
+                    meshes.push(...transformNodeMeshes);
+                }
+            });
+
+            this.#overlayLayer = this.#addGroupOutlineOverlayForInstances(meshes);
+        }
     }
 
     /**
@@ -201,7 +418,7 @@ export default class BabylonJSAnimationController {
      */
     hideMenu() {
         this.#openingAnimations.forEach((openingAnimation) => openingAnimation.hideControls());
-        this.#canvas.parentElement.querySelectorAll("div.pref-viewer-3d.animation-menu").forEach((menu) => menu.remove());
+        this.#canvas?.parentElement?.querySelectorAll("div.pref-viewer-3d.animation-menu").forEach((menu) => menu.remove());
     }
 
     /**

package/src/babylonjs-animation-opening.js

@@ -95,6 +95,8 @@ export default class OpeningAnimation {
         this.#bindHandlers();
         this.#openAnimation.onAnimationGroupEndObservable.add(this.#handlers.onOpened);
         this.#closeAnimation.onAnimationGroupEndObservable.add(this.#handlers.onClosed);
+
+        this.#goToClosed();
     }
 
     #bindHandlers() {

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, RenderTargetTexture, 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,21 +115,28 @@ export default class BabylonJSController {
     #hemiLight = null;
     #dirLight = null;
     #cameraLight = null;
-    #shadowGen = null;
+    #shadowGen = [];
     #XRExperience = null;
     #canvasResizeObserver = null;
-
+    
     #containers = {};
     #options = {};
-
+    
     #gltfResolver = null; // GLTFResolver instance
     #babylonJSAnimationController = null; // AnimationController instance
-
+    
     #handlers = {
         onKeyUp: null,
         onPointerObservable: null,
         renderLoop: null,
     };
+    
+    #settings = {
+        antiAliasingEnabled: true,
+        ambientOcclusionEnabled: true,
+        iblEnabled: true,
+        shadowsEnabled: false,
+    };
 
     /**
      * Constructs a new BabylonJSController instance.
@@ -288,33 +303,159 @@ export default class BabylonJSController {
      * @returns {void}
      */
     #createLights() {
-        this.#initializeEnvironmentTexture();
+        if (this.#settings.iblEnabled && 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;
+        }
+
+        if (!this.#settings.ambientOcclusionEnabled) {
+            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();
+        }
+
+        if (!this.#settings.antiAliasingEnabled) {
+            return false;
+        }
+
+        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 +464,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 +480,149 @@ 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 = [];
+        this.#dirLight.autoUpdateExtends = false;
+        const shadowGenerator = new ShadowGenerator(1024, this.#dirLight);
+        shadowGenerator.useBlurExponentialShadowMap = true;
+        shadowGenerator.blurKernel = 16;
+        shadowGenerator.darkness = 0.5;
+        shadowGenerator.bias = 0.0005;
+        shadowGenerator.normalBias = 0.02;
+        shadowGenerator.getShadowMap().refreshRate = RenderTargetTexture.REFRESHRATE_RENDER_ONCE;
         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);
+    }
 
-        this.#scene.materials.forEach((material) => {
-            iblShadowsPipeline.addShadowReceivingMaterial(material);
+    /**
+     * 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.#containers.environment?.AssetContainer?.lights.forEach((light) => {
+            // Only shadows for DirectionalLight and SpotLight types
+            if (!(light instanceof DirectionalLight || light instanceof SpotLight)) {
+                return;
+            }
+            light.autoUpdateExtends = false;
+            const shadowGenerator = new ShadowGenerator(1024, light);
+            shadowGenerator.useBlurExponentialShadowMap = true;
+            shadowGenerator.blurKernel = 16;
+            shadowGenerator.darkness = 0.5;
+            shadowGenerator.bias = 0.0005;
+            shadowGenerator.normalBias = 0.02;
+            shadowGenerator.getShadowMap().refreshRate = RenderTargetTexture.REFRESHRATE_RENDER_ONCE;
+            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 +635,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.#settings.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 +662,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 +770,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 = [];
     }
 
     /**
@@ -609,7 +836,7 @@ export default class BabylonJSController {
      */
     #onPointerMove(event, pickInfo) {
         if (this.#babylonJSAnimationController) {
-            this.#babylonJSAnimationController.hightlightMeshes(pickInfo);
+            this.#babylonJSAnimationController.highlightMeshes(pickInfo);
         }
     }
 
@@ -741,6 +968,22 @@ 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.#settings.iblEnabled) {
+            this.#options.ibl.setSuccess(true);
+            this.#createLights();
+            return true;
+        }
+        this.#createLights();
+        return false;
+    }
+
     /**
      * Finds and returns the asset container object by its name.
      * @private
@@ -951,6 +1194,7 @@ export default class BabylonJSController {
      */
     async #loadContainers() {
         this.#stopRender();
+        this.#scene.postProcessRenderPipelineManager?.dispose();
 
         let oldModelMetadata = { ...(this.#containers.model?.state?.metadata ?? {}) };
         let newModelMetadata = {};
@@ -988,6 +1232,7 @@ export default class BabylonJSController {
 
                 this.#setOptions_Materials();
                 this.#setOptions_Camera();
+                this.#setOptions_IBL();
                 this.#setVisibilityOfWallAndFloorInModel();
                 detail.success = true;
             })
@@ -1000,13 +1245,26 @@ export default class BabylonJSController {
             .finally(async () => {
                 this.#checkModelMetadata(oldModelMetadata, newModelMetadata);
                 this.#setMaxSimultaneousLights();
-                this.#initializeShadows();
-                this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#scene);
+                this.#loadCameraDepentEffects();
+                this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#containers.model.assetContainer);
+                this.#forceReflectionsInModelGlasses();
                 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
@@ -1083,6 +1341,21 @@ export default class BabylonJSController {
         }
     }
 
+    #forceReflectionsInModelGlasses(assetContainer) {
+        if (assetContainer === undefined) {
+            assetContainer = this.#containers.model.assetContainer;
+        }
+        if (!this.#scene || !assetContainer) {
+            return;
+        }
+        assetContainer.materials?.forEach(material => {
+            if (material && material.name && material.name.includes("Glass")) {
+                material.metallic = 1.0;
+                material.environmentIntensity = 1.0;
+            }
+        });
+    }
+
     /**
      * Translates a node along the scene's vertical (Y) axis by the provided value.
      * @private
@@ -1235,9 +1508,19 @@ 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();
         this.#enableInteraction();
         await this.#createXRExperience();
         this.#startRender();
@@ -1278,6 +1561,7 @@ export default class BabylonJSController {
     setCameraOptions() {
         this.#stopRender();
         const cameraOptionsSetted = this.#setOptions_Camera();
+        this.#loadCameraDepentEffects();
         this.#startRender();
         return cameraOptionsSetted;
     }
@@ -1295,6 +1579,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,53 @@ 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) {
+            url = options.ibl.url;
+            // TEMPORARY: Disable FileStorage usage due to efficiency problems
+            // 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 +548,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 +577,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 };
     }