@preference-sl/pref-viewer 2.11.0-beta.2 → 2.11.0-beta.20

package/src/babylonjs-controller.js

@@ -1,21 +1,31 @@
-import { Engine, Scene, ArcRotateCamera, Vector3, Color4, HemisphericLight, DirectionalLight, PointLight, ShadowGenerator, LoadAssetContainerAsync, Tools, WebXRSessionManager, WebXRDefaultExperience, MeshBuilder, WebXRFeatureName, HDRCubeTexture, IblShadowsRenderPipeline } from "@babylonjs/core";
-import { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression";
+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 { DracoCompression } from "@babylonjs/core/Meshes/Compression/dracoCompression.js";
 import "@babylonjs/loaders";
-import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression";
+import "@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression.js";
 import { USDZExportAsync, GLTF2Export } from "@babylonjs/serializers";
+import JSZip from "jszip";
+
 import GLTFResolver from "./gltf-resolver.js";
+import { MaterialData } from "./pref-viewer-3d-data.js";
+import BabylonJSAnimationController from "./babylonjs-animation-controller.js";
 
 /**
- * BabylonJSController - Main controller for managing Babylon.js 3D scenes, assets, and interactions.
+ * BabylonJSController - Main controller for managing Babylon.js 3D scenes, assets, rendering, and user interactions in PrefViewer.
+ *
+ * Summary:
+ *  Provides a high-level API for initializing, loading, displaying, and exporting 3D models and environments using Babylon.js.
+ *  Manages advanced rendering features, AR integration, asset containers, and user interaction logic.
  *
- * Responsibilities:
+ * Key Responsibilities:
  *  - Initializes and manages the Babylon.js engine, scene, camera, lights, and asset containers.
  *  - Handles loading, replacing, and disposing of 3D models, environments, and materials.
  *  - Configures advanced rendering features such as Draco mesh compression, shadows, and image-based lighting (IBL).
  *  - Integrates Babylon.js WebXR experience for augmented reality (AR) support.
- *  - Provides methods for downloading models and scenes in GLB and USDZ formats.
+ *  - Provides methods for downloading models and scenes in GLB, glTF (ZIP), and USDZ formats.
  *  - Manages camera and material options, container visibility, and user interactions.
  *  - Observes canvas resize events and updates the engine accordingly.
+ *  - Designed for integration with PrefViewer and GLTFResolver.
+ *  - All resource management and rendering operations are performed asynchronously for performance.
  *
  * Usage:
  *  - Instantiate: const controller = new BabylonJSController(canvas, containers, options);
@@ -23,7 +33,7 @@ import GLTFResolver from "./gltf-resolver.js";
  *  - Load assets: await controller.load();
  *  - Set camera/material options: controller.setCameraOptions(), controller.setMaterialOptions();
  *  - Control visibility: controller.setContainerVisibility(name, show);
- *  - Download assets: controller.downloadModelGLB(), controller.downloadModelUSDZ(), etc.
+ *  - Download assets: controller.downloadGLB(), controller.downloadGLTF(), controller.downloadUSDZ();
  *  - Disable rendering: controller.disable();
  *
  * Public Methods:
@@ -33,25 +43,50 @@ import GLTFResolver from "./gltf-resolver.js";
  *  - setCameraOptions(): Applies camera options from configuration.
  *  - setMaterialOptions(): Applies material options from configuration.
  *  - setContainerVisibility(name, show): Shows or hides a container by name.
- *  - downloadModelGLB(), downloadModelUSDZ(), downloadModelAndSceneGLB(), downloadModelAndSceneUSDZ(): Downloads assets.
+ *  - 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.
  *
- * Private Methods:
+ * Private Methods (using ECMAScript private fields):
+ *  - #bindHandlers(): Pre-binds reusable event handlers to preserve stable references.
  *  - #configureDracoCompression(): Sets up Draco mesh compression.
- *  - #createCamera(), #createLights(), #initializeEnvironmentTexture(), #initializeIBLShadows(), #initializeShadows(): Scene setup.
- *  - #setupInteraction(): Sets up canvas interaction handlers.
- *  - #disposeEngine(): Disposes engine and resources.
- *  - #setOptionsMaterial(), #setOptions_Materials(), #setOptions_Camera(): Applies material/camera options.
- *  - #findContainerByName(), #addContainer(), #removeContainer(), #replaceContainer(): Container management.
- *  - #setVisibilityOfWallAndFloorInModel(): Controls wall/floor mesh visibility.
- *  - #stopRender(), #startRender(): Render loop control.
- *  - #loadAssetContainer(), #loadContainers(): Asset loading.
+ *  - #renderLoop(): Babylon.js render loop callback.
  *  - #addStylesToARButton(): Styles AR button.
  *  - #createXRExperience(): Initializes WebXR AR experience.
- *
- * Notes:
- *  - Designed for integration with PrefViewer and GLTFResolver.
- *  - Supports advanced Babylon.js features for product visualization and configurators.
- *  - All resource management and rendering operations are performed asynchronously for performance.
+ *  - #createCamera(): Creates and configures the main camera.
+ *  - #createLights(): Creates and configures scene lights and shadows.
+ *  - #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.
+ *  - #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).
+ *  - #onPointerMove(event, pickInfo): Handles pointer move events (e.g., mesh highlighting).
+ *  - #onMouseWheel(event, pickInfo): Handles mouse wheel events for camera zoom.
+ *  - #onKeyUp(event): Handles keyup events for download dialog and shortcuts.
+ *  - #enableInteraction(): Adds canvas and scene interaction event listeners.
+ *  - #disableInteraction(): Removes canvas and scene interaction event listeners.
+ *  - #disposeAnimationController(): Disposes the animation controller if it exists.
+ *  - #disposeXRExperience(): Disposes the Babylon.js WebXR experience if it exists.
+ *  - #disposeEngine(): Disposes engine and releases all resources.
+ *  - #setOptionsMaterial(optionMaterial): Applies a material option to relevant meshes.
+ *  - #setOptions_Materials(): Applies all material options from configuration.
+ *  - #setOptions_Camera(): Applies camera options from configuration.
+ *  - #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.
+ *  - #replaceContainer(container, newAssetContainer): Replaces a container in the scene.
+ *  - #getPrefViewer3DComponent(): Caches and retrieves the parent PREF-VIEWER-3D element.
+ *  - #getPrefViewerComponent(): Caches and retrieves the parent PREF-VIEWER element.
+ *  - #updateVisibilityAttributeInComponents(name, isVisible): Updates parent visibility attributes.
+ *  - #setVisibilityOfWallAndFloorInModel(show): Controls wall/floor mesh visibility.
+ *  - #stopRender(): Stops the Babylon.js render loop.
+ *  - #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.
+ *  - #addDateToName(name): Appends the current date/time to a name string.
+ *  - #downloadZip(files, name, comment, addDateInName): Generates and downloads a ZIP file.
+ *  - #openDownloadDialog(): Opens the modal download dialog.
  */
 export default class BabylonJSController {
     // Canvas HTML element
@@ -76,6 +111,13 @@ export default class BabylonJSController {
     #options = {};
 
     #gltfResolver = null; // GLTFResolver instance
+    #babylonJSAnimationController = null; // AnimationController instance
+
+    #handlers = {
+        onKeyUp: null,
+        onPointerObservable: null,
+        renderLoop: null,
+    };
 
     /**
      * Constructs a new BabylonJSController instance.
@@ -99,6 +141,18 @@ export default class BabylonJSController {
             };
         });
         this.#options = options;
+        this.#bindHandlers();
+    }
+
+    /**
+     * Pre-binds reusable event handlers to preserve stable references.
+     * @private
+     * @returns {void}
+     */
+    #bindHandlers() {
+        this.#handlers.onKeyUp = this.#onKeyUp.bind(this);
+        this.#handlers.onPointerObservable = this.#onPointerObservable.bind(this);
+        this.#handlers.renderLoop = this.#renderLoop.bind(this);
     }
 
     /**
@@ -290,29 +344,42 @@ export default class BabylonJSController {
             return false;
         }
 
-        let createIBLShadowPipeline = function (scene) {
+        /**
+         * 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: 7,
-                    sampleDirections: 2,
+                    resolutionExp: 8, // Higher resolution for better shadow quality
+                    sampleDirections: 4, // More sample directions for smoother shadows
                     ssShadowsEnabled: true,
-                    shadowRemanence: 0.8,
+                    shadowRemanence: 0.85,
                     triPlanarVoxelization: true,
-                    shadowOpacity: 0.8,
+                    shadowOpacity: 0.85,
                 },
-                [scene.activeCamera]
+                cameras
             );
-            pipeline.allowDebugPasses = false;
-            pipeline.gbufferDebugEnabled = true;
-            pipeline.importanceSamplingDebugEnabled = false;
-            pipeline.voxelDebugEnabled = false;
-            pipeline.voxelDebugDisplayMip = 1;
-            pipeline.voxelDebugAxis = 2;
-            pipeline.voxelTracingDebugEnabled = false;
-            pipeline.spatialBlurPassDebugEnabled = false;
-            pipeline.accumulationPassDebugEnabled = false;
+            // Disable all debug passes for performance
+            const pipelineProps = {
+                allowDebugPasses: false,
+                gbufferDebugEnabled: false,
+                importanceSamplingDebugEnabled: false,
+                voxelDebugEnabled: false,
+                voxelDebugDisplayMip: 0,
+                voxelDebugAxis: 0,
+                voxelTracingDebugEnabled: false,
+                spatialBlurPassDebugEnabled: false,
+                accumulationPassDebugEnabled: false,
+            };
+            Object.assign(pipeline, pipelineProps);
             return pipeline;
         };
 
@@ -375,24 +442,88 @@ export default class BabylonJSController {
     }
 
     /**
-     * Sets up interaction handlers for the Babylon.js canvas.
-     * Adds a wheel event listener to control camera zoom based on mouse wheel input.
-     * Prevents zoom if the active camera is locked.
+     * Handles pointer events observed on the Babylon.js scene.
      * @private
+     * @param {PointerInfo} info - The pointer event information from Babylon.js.
      * @returns {void}
      */
-    #setupInteraction() {
-        this.#canvas.addEventListener("wheel", (event) => {
-            if (!this.#scene || !this.#camera) {
-                return false;
-            }
-            //const pick = this.#scene.pick(this.#scene.pointerX, this.#scene.pointerY);
-            //this.#camera.target = pick.hit ? pick.pickedPoint.clone() : this.#camera.target;
-            if (!this.#scene.activeCamera.metadata?.locked) {
-                this.#scene.activeCamera.inertialRadiusOffset -= event.deltaY * this.#scene.activeCamera.wheelPrecision * 0.001;
-            }
-            event.preventDefault();
-        });
+    #onPointerObservable(info) {
+        const pickInfo = this.#scene.pick(this.#scene.pointerX, this.#scene.pointerY);
+        if (info.type === PointerEventTypes.POINTERUP) {
+            this.#onPointerUp(info.event, pickInfo);
+        } else if (info.type === PointerEventTypes.POINTERMOVE) {
+            this.#onPointerMove(info.event, pickInfo);
+        } else if (info.type === PointerEventTypes.POINTERWHEEL) {
+            this.#onMouseWheel(info.event, pickInfo);
+        }
+    }
+
+    /**
+     * Sets up interaction handlers for the Babylon.js canvas and scene.
+     * @private
+     * @returns {void}
+     */
+    #enableInteraction() {
+        if (this.#canvas) {
+            this.#canvas.addEventListener("keyup", this.#handlers.onKeyUp);
+        }
+        if (this.#scene) {
+            this.#scene.onPointerObservable.add(this.#handlers.onPointerObservable);
+        }
+    }
+
+    /**
+     * Removes interaction event listeners from the Babylon.js canvas.
+     * @private
+     * @returns {void}
+     */
+    #disableInteraction() {
+        if (this.#canvas) {
+            this.#canvas.removeEventListener("keyup", this.#handlers.onKeyUp);
+        }
+        if (this.#scene !== null) {
+            this.#scene.onPointerObservable.removeCallback(this.#handlers.onPointerObservable);
+        }
+    }
+
+    /**
+     * Disposes the BabylonJSAnimationController instance if it exists.
+     * @private
+     * @returns {void}
+     */
+    #disposeAnimationController() {
+        if (this.#babylonJSAnimationController) {
+            this.#babylonJSAnimationController.dispose();
+            this.#babylonJSAnimationController = null;
+        }
+    }
+
+    /**
+     * Disposes the Babylon.js WebXR experience if it exists.
+     * @private
+     * @returns {void}
+     */
+    #disposeXRExperience() {
+        if (!this.#XRExperience) {
+            return;
+        }
+
+        if (this.#XRExperience.baseExperience.state === WebXRState.IN_XR) {
+            this.#XRExperience.baseExperience
+                .exitXRAsync()
+                .then(() => {
+                    this.#XRExperience.dispose();
+                    this.#XRExperience = null;
+                })
+                .catch((error) => {
+                    console.warn("Error exiting XR experience:", error);
+                    this.#XRExperience.dispose();
+                    this.#XRExperience = null;
+                });
+        } else {
+            this.#XRExperience.dispose();
+            this.#XRExperience = null;
+        }
     }
 
     /**
@@ -408,13 +539,79 @@ export default class BabylonJSController {
         this.#engine = this.#scene = this.#camera = null;
         this.#hemiLight = this.#dirLight = this.#cameraLight = null;
         this.#shadowGen = null;
-        this.#XRExperience = null;
+    }
+
+    /**
+     * Handles keyup events on the Babylon.js canvas for triggering model and scene downloads.
+     * @private
+     * @param {KeyboardEvent} event - The keyup event.
+     * @returns {void}
+     */
+    #onKeyUp(event) {
+        // CTRL + ALT + letter
+        if (event.ctrlKey && event.altKey && event.key !== undefined) {
+            switch (event.key.toLowerCase()) {
+                case "d":
+                    this.#openDownloadDialog();
+                    break;
+                default:
+                    break;
+            }
+        }
+    }
+
+    /**
+     * Handles mouse wheel events on the Babylon.js canvas for zooming the camera.
+     * @private
+     * @param {WheelEvent} event - The mouse wheel event.
+     * @param {Object} pickInfo - The result of the scene pick operation (not used in this method).
+     * @returns {void|false} Returns false if there is no active camera; otherwise, void.
+     */
+    #onMouseWheel(event, pickInfo) {
+        if (!this.#scene?.activeCamera) {
+            return false;
+        }
+        //this.#scene.activeCamera.target = pickInfo.hit ? pickInfo.pickedPoint.clone() : this.#scene.activeCamera.target;
+        if (!this.#scene.activeCamera.metadata?.locked) {
+            this.#scene.activeCamera.inertialRadiusOffset -= event.deltaY * this.#scene.activeCamera.wheelPrecision * 0.001;
+        }
+        event.preventDefault();
+    }
+
+    /**
+     * Handles pointer up events on the Babylon.js scene.
+     * @private
+     * @param {PointerEvent} event - The pointer up event.
+     * @param {PickInfo} pickInfo - The result of the scene pick operation.
+     * @returns {void}
+     */
+    #onPointerUp(event, pickInfo) {
+        if (this.#babylonJSAnimationController) {
+            this.#babylonJSAnimationController.hideMenu();
+            // Right click for showing animation menu
+            if (event.button === 2) {
+                this.#babylonJSAnimationController.showMenu(pickInfo);
+            }
+        }
+    }
+
+    /**
+     * Handles pointer move events on the Babylon.js scene.
+     * @private
+     * @param {PointerEvent} event - The pointer move event.
+     * @param {PickInfo} pickInfo - The result of the scene pick operation.
+     * @returns {void}
+     */
+    #onPointerMove(event, pickInfo) {
+        if (this.#babylonJSAnimationController) {
+            this.#babylonJSAnimationController.hightlightMeshes(pickInfo);
+        }
     }
 
     /**
      * Applies material options from the configuration to the relevant meshes.
      * @private
-     * @param {object} optionMaterial - Material option containing value, nodePrefixes, nodeNames, and state.
+     * @param {MaterialData} optionMaterial - Material option containing value, nodePrefixes, nodeNames, and state.
      * @returns {boolean} True if any mesh material was set, false otherwise.
      */
     #setOptionsMaterial(optionMaterial) {
@@ -435,7 +632,7 @@ export default class BabylonJSController {
             if (container.state.name === "materials") {
                 return;
             }
-            if (container.assetContainer && (container.isPending || materialContainer.isPending || optionMaterial.isPending)) {
+            if (container.assetContainer && (container.state.isPending || materialContainer.state.isPending || optionMaterial.isPending)) {
                 assetContainersToProcess.push(container.assetContainer);
             }
         });
@@ -487,7 +684,7 @@ export default class BabylonJSController {
         const modelContainer = this.#containers.model;
         const environmentContainer = this.#containers.environment;
 
-        if (!cameraState.isPending && !modelContainer.isPending && !environmentContainer.isPending) {
+        if (!cameraState.isPending && !modelContainer.state.isPending && !environmentContainer.state.isPending) {
             return false;
         }
 
@@ -542,7 +739,7 @@ export default class BabylonJSController {
      * Finds and returns the asset container object by its name.
      * @private
      * @param {string} name - The name of the container to find.
-     * @returns {object|null} The matching container object, or null if not found.
+     * @returns {Object|null} The matching container object, or null if not found.
      */
     #findContainerByName(name) {
         return Object.values(this.#containers).find((container) => container.state.name === name) || null;
@@ -567,6 +764,13 @@ export default class BabylonJSController {
      */
     #getPrefViewerComponent() {
         if (this.#prefViewer === undefined) {
+            if (this.#prefViewer3D === undefined) {
+                this.#getPrefViewer3DComponent();
+            }
+            if (!this.#prefViewer3D) {
+                this.#prefViewer = null;
+                return;
+            }
             const rootNode = this.#prefViewer3D ? this.#prefViewer3D.getRootNode().host : null;
             this.#prefViewer = rootNode && rootNode.nodeName === "PREF-VIEWER" ? rootNode : null;
         }
@@ -579,7 +783,7 @@ export default class BabylonJSController {
      * @param {boolean} isVisible - True to show the container, false to hide it.
      * @returns {void}
      */
-    #updateVisibilityAttributeInComponentes(name, isVisible) {
+    #updateVisibilityAttributeInComponents(name, isVisible) {
         // Cache references to parent custom elements
         this.#getPrefViewer3DComponent();
         this.#getPrefViewerComponent();
@@ -596,13 +800,16 @@ export default class BabylonJSController {
      * Adds the asset container to the Babylon.js scene if it should be shown and is not already visible.
      * @private
      * @param {object} container - The container object containing asset state and metadata.
+     * @param {boolean} [updateVisibility=true] - If true, updates the visibility attribute in parent components.
      * @returns {boolean} True if the container was added, false otherwise.
      */
-    #addContainer(container) {
+    #addContainer(container, updateVisibility = true) {
         if (!container.assetContainer || container.state.isVisible || !container.state.mustBeShown) {
             return false;
         }
-        this.#updateVisibilityAttributeInComponentes(container.state.name, true);
+        if (updateVisibility) {
+            this.#updateVisibilityAttributeInComponents(container.state.name, true);
+        }
         container.assetContainer.addAllToScene();
         container.state.visible = true;
         return true;
@@ -612,13 +819,16 @@ export default class BabylonJSController {
      * Removes the asset container from the Babylon.js scene if it is currently visible.
      * @private
      * @param {object} container - The container object containing asset state and metadata.
+     * @param {boolean} [updateVisibility=true] - If true, updates the visibility attribute in parent components.
      * @returns {boolean} True if the container was removed, false otherwise.
      */
-    #removeContainer(container) {
+    #removeContainer(container, updateVisibility = true) {
         if (!container.assetContainer || !container.state.isVisible) {
             return false;
         }
-        this.#updateVisibilityAttributeInComponentes(container.state.name, false);
+        if (updateVisibility) {
+            this.#updateVisibilityAttributeInComponents(container.state.name, false);
+        }
         container.assetContainer.removeAllFromScene();
         container.state.visible = false;
         return true;
@@ -628,20 +838,20 @@ export default class BabylonJSController {
      * Replaces the asset container in the Babylon.js scene with a new one.
      * @private
      * @param {object} container - The container object containing asset state and metadata.
-     * @param {object} newAssetContainer - The new asset container to add to the scene.
-     * @returns {boolean} True if the container was replaced, false otherwise.
+     * @param {AssetContainer} newAssetContainer - The new asset container to add to the scene.
+     * @returns {boolean} True if the container was replaced and added, false otherwise.
      */
     #replaceContainer(container, newAssetContainer) {
         if (container.assetContainer) {
-            this.#removeContainer(container);
+            this.#removeContainer(container, false);
             container.assetContainer.dispose();
             container.assetContainer = null;
         }
         this.#scene.getEngine().releaseEffects();
         container.assetContainer = newAssetContainer;
-        this.#addContainer(container);
-        return true;
+        return this.#addContainer(container, false);
     }
+
     /**
      * Sets the visibility of wall and floor meshes in the model container based on the provided value or environment visibility.
      * @private
@@ -663,9 +873,8 @@ export default class BabylonJSController {
      * @private
      * @returns {void}
      */
-    #stopR;
     #stopRender() {
-        this.#engine.stopRenderLoop(this.#renderLoop.bind(this));
+        this.#engine.stopRenderLoop(this.#handlers.renderLoop);
     }
     /**
      * Starts the Babylon.js render loop for the current scene.
@@ -675,7 +884,7 @@ export default class BabylonJSController {
      */
     async #startRender() {
         await this.#scene.whenReadyAsync();
-        this.#engine.runRenderLoop(this.#renderLoop.bind(this));
+        this.#engine.runRenderLoop(this.#handlers.renderLoop);
     }
 
     /**
@@ -746,6 +955,7 @@ export default class BabylonJSController {
 
         await Promise.allSettled(promiseArray)
             .then((values) => {
+                this.#disposeAnimationController();
                 values.forEach((result) => {
                     const container = result.value ? result.value[0] : null;
                     const assetContainer = result.value ? result.value[1] : null;
@@ -777,12 +987,127 @@ export default class BabylonJSController {
             .finally(async () => {
                 this.#setMaxSimultaneousLights();
                 this.#initializeShadows();
+                this.#babylonJSAnimationController = new BabylonJSAnimationController(this.#scene);
                 this.#startRender();
             });
-
         return detail;
     }
 
+    /**
+     * Appends the current date and time to the provided name string in the format: name_YYYY-MM-DD_HH.mm.ss
+     * @private
+     * @param {string} name - The base name to which the date and time will be appended.
+     * @returns {string} The name with the appended date and time.
+     */
+    #addDateToName(name) {
+        const now = new Date();
+        const year = now.getFullYear();
+        const month = (now.getMonth() + 1).toString().padStart(2, "0");
+        const day = now.getDate().toString().padStart(2, "0");
+        const hours = now.getHours().toString().padStart(2, "0");
+        const minutes = now.getMinutes().toString().padStart(2, "0");
+        const seconds = now.getSeconds().toString().padStart(2, "0");
+        name = `${name}_${year}-${month}-${day}_${hours}.${minutes}.${seconds}`;
+        return name;
+    }
+
+    /**
+     * Generates and downloads a ZIP file with the specified folder name and files.
+     * @private
+     * @param {Object} files - An object where keys are file names and values are file contents.
+     * @param {string} [name="files"] - The name for the root folder inside the ZIP.
+     * @param {string} [comment=""] - A comment to include in the ZIP file.
+     * @param {boolean} [addDateInName=false] - Whether to append the current date/time to the folder name.
+     * @returns {void}
+     * @description
+     * Uses JSZip to create the ZIP and triggers a browser download.
+     */
+    #downloadZip(files, name = "files", comment = "", addDateInName = false) {
+        name = addDateInName ? this.#addDateToName(name) : name;
+
+        const zip = new JSZip();
+        zip.comment = comment;
+
+        const rootFolder = zip.folder(name);
+        Object.keys(files).forEach((key) => {
+            rootFolder.file(key, files[key]);
+        });
+
+        zip.generateAsync({ type: "blob" }).then((content) => {
+            const zipName = `${name}.zip`;
+            const a = document.createElement("a");
+            const url = window.URL.createObjectURL(content);
+            a.href = url;
+            a.download = zipName;
+            a.click();
+            window.URL.revokeObjectURL(url);
+        });
+    }
+
+    /**
+     * Opens a modal dialog for downloading the 3D scene, model, or environment.
+     * @private
+     * @returns {void}
+     */
+    #openDownloadDialog() {
+        this.#getPrefViewerComponent();
+        if (!this.#prefViewer) {
+            return;
+        }
+
+        const header = "Download 3D Scene";
+        const content = `
+            <form slot="content" id="download-dialog-form" style="display:flex;flex-direction:column;gap:16px;">
+                <h4>Content</h4>
+                <div style="display:flex;flex-direction:row;gap:16px;margin:0 8px 0 8px;">
+                    <label><input type="radio" name="content" value="1"> Model</label>
+                    <label><input type="radio" name="content" value="2"> Scene</label>
+                    <label><input type="radio" name="content" value="0" checked> Both</label>
+                </div>
+                <h4>Format</h4>
+                <div style="display:flex;flex-direction:row;gap:16px;margin:0 8px 0 8px;">
+                <label><input type="radio" name="format" value="gltf" checked> glTF (ZIP)</label>
+                    <label><input type="radio" name="format" value="glb"> GLB</label>
+                    <label><input type="radio" name="format" value="usdz"> USDZ</label>
+                </div>
+            </form>`;
+        const footer = `
+            <button type="button" class="primary" id="download-dialog-download">Download</button>
+            <button type="button" id="download-dialog-cancel">Cancel</button>`;
+
+        const dialog = this.#prefViewer.openDialog(header, content, footer);
+
+        if (!dialog) {
+            return;
+        }
+
+        // Button event handlers
+        const form = dialog.querySelector("#download-dialog-form");
+        const downloadButton = dialog.querySelector("#download-dialog-download");
+        const cancelButton = dialog.querySelector("#download-dialog-cancel");
+
+        downloadButton.onclick = () => {
+            const contentValue = form.content.value;
+            const formatValue = form.format.value;
+            switch (formatValue) {
+                case "glb":
+                    this.downloadGLB(Number(contentValue));
+                    break;
+                case "gltf":
+                    this.downloadGLTF(Number(contentValue));
+                    break;
+                case "usdz":
+                    this.downloadUSDZ(Number(contentValue));
+                    break;
+            }
+            this.#prefViewer.closeDialog();
+        };
+
+        cancelButton.onclick = () => {
+            this.#prefViewer.closeDialog();
+        };
+    }
+
     /**
      * ---------------------------
      * Public methods
@@ -798,13 +1123,13 @@ export default class BabylonJSController {
      */
     async enable() {
         this.#configureDracoCompression();
-        this.#engine = new Engine(this.#canvas, true, { alpha: true });
+        this.#engine = new Engine(this.#canvas, true, { alpha: true, stencil: true, preserveDrawingBuffer: false });
         this.#engine.disableUniformBuffers = true;
         this.#scene = new Scene(this.#engine);
         this.#scene.clearColor = new Color4(1, 1, 1, 1);
         this.#createCamera();
         this.#createLights();
-        this.#setupInteraction();
+        this.#enableInteraction();
         await this.#createXRExperience();
         this.#startRender();
         this.#canvasResizeObserver = new ResizeObserver(() => this.#engine && this.#engine.resize());
@@ -818,8 +1143,11 @@ export default class BabylonJSController {
      * @returns {void}
      */
     disable() {
-        this.#disposeEngine();
         this.#canvasResizeObserver.disconnect();
+        this.#disableInteraction();
+        this.#disposeAnimationController();
+        this.#disposeXRExperience();
+        this.#disposeEngine();
     }
 
     /**
@@ -883,50 +1211,105 @@ export default class BabylonJSController {
     }
 
     /**
-     * Initiates download of the current model as a GLB file.
+     * Downloads the current scene, model, or environment as a GLB file.
      * @public
+     * @param {number} content - 0 for full scene, 1 for model, 2 for environment.
      * @returns {void}
      */
-    downloadModelGLB() {
-        const fileName = "model";
-        GLTF2Export.GLBAsync(this.#containers.model.assetContainer, fileName, { exportWithoutWaitingForScene: true }).then((glb) => glb.downloadFiles());
+    downloadGLB(content = 0) {
+        let fileName = "";
+        let container = null;
+        switch (content) {
+            case 0:
+                fileName = "full-scene";
+                container = this.#scene;
+                break;
+            case 1:
+                fileName = "model";
+                container = this.#containers.model.assetContainer;
+                break;
+            case 2:
+                fileName = "scene";
+                container = this.#containers.environment.assetContainer;
+                break;
+            default:
+                break;
+        }
+        fileName = this.#addDateToName(fileName);
+        GLTF2Export.GLBAsync(container, fileName, { exportWithoutWaitingForScene: true }).then((glb) => {
+            if (glb) {
+                glb.downloadFiles();
+            }
+        });
     }
 
     /**
-     * Initiates download of the current model as a USDZ file.
+     * Downloads the current scene, model, or environment as a glTF ZIP file.
      * @public
+     * @param {number} content - 0 for full scene, 1 for model, 2 for environment.
      * @returns {void}
      */
-    downloadModelUSDZ() {
-        const fileName = "model";
-        USDZExportAsync(this.#containers.model.assetContainer).then((response) => {
-            if (response) {
-                Tools.Download(new Blob([response], { type: "model/vnd.usdz+zip" }), `${fileName}.usdz`);
+    downloadGLTF(content = 0) {
+        let fileName = "";
+        let container = null;
+        let comment = "";
+        switch (content) {
+            case 0:
+                fileName = "full-scene";
+                comment = "Export of the complete scene in glTF format, including the model and the environment.";
+                container = this.#scene;
+                break;
+            case 1:
+                fileName = "model";
+                comment = "Export of model scene in glTF format.";
+                container = this.#containers.model.assetContainer;
+                break;
+            case 2:
+                fileName = "scene";
+                comment = "Export of the environment scene in glTF format.";
+                container = this.#containers.environment.assetContainer;
+                break;
+            default:
+                break;
+        }
+        comment += "\nPrefViewer by Preference, S.L.\npreference.com\n";
+        GLTF2Export.GLTFAsync(container, fileName, { exportWithoutWaitingForScene: true }).then((gltf) => {
+            if (gltf?.files) {
+                this.#downloadZip(gltf.files, fileName, comment, true);
             }
         });
     }
 
     /**
-     * Initiates download of the entire scene (model and environment) as a USDZ file.
+     * Downloads the current scene, model, or environment as a USDZ file.
      * @public
+     * @param {number} content - 0 for full scene, 1 for model, 2 for environment.
      * @returns {void}
      */
-    downloadModelAndSceneUSDZ() {
-        const fileName = "scene";
-        USDZExportAsync(this.#scene).then((response) => {
+    downloadUSDZ(content = 0) {
+        let fileName = "";
+        let container = null;
+        switch (content) {
+            case 0:
+                fileName = "full-scene";
+                container = this.#scene;
+                break;
+            case 1:
+                fileName = "model";
+                container = this.#containers.model.assetContainer;
+                break;
+            case 2:
+                fileName = "scene";
+                container = this.#containers.environment.assetContainer;
+                break;
+            default:
+                break;
+        }
+        fileName = this.#addDateToName(fileName);
+        USDZExportAsync(container).then((response) => {
             if (response) {
                 Tools.Download(new Blob([response], { type: "model/vnd.usdz+zip" }), `${fileName}.usdz`);
             }
         });
     }
-
-    /**
-     * Initiates download of the entire scene (model and environment) as a GLB file.
-     * @public
-     * @returns {void}
-     */
-    downloadModelAndSceneGLB() {
-        const fileName = "scene";
-        GLTF2Export.GLBAsync(this.#scene, fileName, { exportWithoutWaitingForScene: true }).then((glb) => glb.downloadFiles());
-    }
 }