@preference-sl/pref-viewer 2.11.0-beta.1 → 2.11.0-beta.11

package/src/babylonjs-animation-opening.js

@@ -0,0 +1,496 @@
+import { AdvancedDynamicTexture } from "@babylonjs/gui";
+import { OpeningAnimationMenu } from "./babylonjs-animation-opening-menu.js";
+
+/**
+ * OpeningAnimation - Manages open/close animations for a model part (e.g., a door) in a Babylon.js scene.
+ *
+ * Responsibilities:
+ *  - Controls playback of opening and closing AnimationGroups.
+ *  - Tracks animation state (paused, closed, opened, opening, closing).
+ *  - Synchronizes animation progress and UI controls.
+ *  - Handles loop mode and progress threshold logic.
+ *  - Provides methods for play, pause, go to opened/closed, and progress control.
+ *  - Manages the animation control menu (OpeningAnimationMenu) and its callbacks.
+ *
+ * Public Methods:
+ *  - isAnimationForNode(node): Checks if the animation affects the given node.
+ *  - playOpen(): Starts the opening animation.
+ *  - playClose(): Starts the closing animation.
+ *  - pause(): Pauses the current animation.
+ *  - goToOpened(): Moves animation to the fully opened state.
+ *  - goToClosed(): Moves animation to the fully closed state.
+ *  - showControls(advancedDynamicTexture): Displays the animation control menu.
+ *  - hideControls(): Hides the animation control menu.
+ *  - isControlsVisible(): Returns true if the control menu is visible for this animation.
+ *
+ * Public Properties:
+ *  - state: Returns the current animation state.
+ *
+ * Private Methods:
+ *  - #getNodesFromAnimationGroups(): Collects node IDs affected by the animation groups.
+ *  - #onOpened(): Handles end of opening animation.
+ *  - #onClosed(): Handles end of closing animation.
+ *  - #goToOpened(useLoop): Sets state to opened and optionally loops to close.
+ *  - #goToClosed(useLoop): Sets state to closed and optionally loops to open.
+ *  - #goToFrameAndPause(frame): Moves to a specific frame and pauses.
+ *  - #getCurrentFrame(): Gets the current frame based on state.
+ *  - #getFrameFromProgress(progress): Calculates frame from progress value.
+ *  - #getProgress(): Calculates progress (0-1) from current frame.
+ *  - #checkProgress(progress): Applies threshold logic to progress.
+ *  - #updateControlsSlider(): Updates the slider in the control menu.
+ *  - #updateControls(): Updates all controls in the menu.
+ *
+ * Usage Example:
+ *  const anim = new OpeningAnimation("door", openGroup, closeGroup);
+ *  anim.playOpen();
+ *  anim.pause();
+ *  anim.goToClosed();
+ *  anim.showControls(adt);
+ *  anim.hideControls();
+ */
+export class OpeningAnimation {
+    static states = {
+        paused: 0,
+        closed: 1,
+        opened: 2,
+        opening: 3,
+        closing: 4,
+    };
+
+    #openAnimation = null;
+    #closeAnimation = null;
+
+    #nodes = [];
+    #state = OpeningAnimation.states.closed;
+    #lastPausedFrame = 0;
+    #startFrame = 0;
+    #endFrame = 0;
+    #speedRatio = 1.0;
+    #loop = false;
+
+    #advancedDynamicTexture = null;
+    #menu = null;
+    #progressThreshold = 0.025;
+
+    /**
+     * Creates a new OpeningAnimation instance for managing open/close animations of a model part.
+     * @param {string} name - The identifier for this animation (e.g., door name).
+     * @param {AnimationGroup} openAnimationGroup - Babylon.js AnimationGroup for the opening animation.
+     * @param {AnimationGroup} closeAnimationGroup - Babylon.js AnimationGroup for the closing animation.
+     * @description
+     * Initializes internal state, sets up frame ranges, collects affected nodes, and attaches end-of-animation observers.
+     */
+    constructor(name, openAnimationGroup, closeAnimationGroup) {
+        this.name = name;
+        this.#openAnimation = openAnimationGroup;
+        this.#closeAnimation = closeAnimationGroup;
+
+        this.#openAnimation.stop();
+        this.#openAnimation._loopAnimation = false;
+        this.#closeAnimation.stop();
+        this.#closeAnimation._loopAnimation = false;
+
+        this.#startFrame = this.#openAnimation.from;
+        this.#endFrame = this.#openAnimation.to;
+        this.#speedRatio = this.#openAnimation.speedRatio || 1.0;
+
+        this.#getNodesFromAnimationGroups();
+        this.#openAnimation.onAnimationGroupEndObservable.add(this.#onOpened.bind(this));
+        this.#closeAnimation.onAnimationGroupEndObservable.add(this.#onClosed.bind(this));
+    }
+
+    /**
+     * Collects node IDs affected by the opening and closing animation groups.
+     * Populates the #nodes array with unique node identifiers.
+     * @private
+     */
+    #getNodesFromAnimationGroups() {
+        [this.#openAnimation, this.#closeAnimation].forEach((animationGroup) => {
+            animationGroup._targetedAnimations.forEach((targetedAnimation) => {
+                if (!this.#nodes.includes(targetedAnimation.target.id)) {
+                    this.#nodes.push(targetedAnimation.target.id);
+                }
+            });
+        });
+    }
+
+    /**
+     * Handles the end of the opening animation group.
+     * @private
+     */
+    #onOpened() {
+        this.#goToOpened(true);
+    }
+
+    /**
+     * Handles the end of the closing animation group.
+     * @private
+     */
+    #onClosed() {
+        this.#goToClosed(true);
+    }
+
+    /**
+     * Moves the animation to the fully opened state, optionally looping to close.
+     * @private
+     * @param {boolean} useLoop - If true, starts closing animation after opening.
+     */
+    #goToOpened(useLoop = false) {
+        this.#lastPausedFrame = this.#endFrame;
+
+        if (this.#openAnimation._isStarted && !this.#openAnimation._isPaused) {
+            this.#openAnimation.pause();
+        }
+        this.#openAnimation.goToFrame(this.#endFrame);
+
+        this.#closeAnimation.pause();
+        this.#closeAnimation.goToFrame(this.#startFrame);
+
+        this.#state = OpeningAnimation.states.opened;
+        this.#updateControls();
+
+        if (this.#loop && useLoop) {
+            this.playClose();
+        }
+    }
+
+    /**
+     * Moves the animation to the fully closed state, optionally looping to open.
+     * @private
+     * @param {boolean} useLoop - If true, starts opening animation after closing.
+     */
+    #goToClosed(useLoop = false) {
+        this.#lastPausedFrame = this.#startFrame;
+
+        if (this.#closeAnimation._isStarted && !this.#closeAnimation._isPaused) {
+            this.#closeAnimation.pause();
+        }
+        this.#closeAnimation.goToFrame(this.#endFrame - this.#startFrame);
+
+        this.#openAnimation.pause();
+        this.#openAnimation.goToFrame(this.#startFrame);
+
+        this.#state = OpeningAnimation.states.closed;
+        this.#updateControls();
+
+        if (this.#loop && useLoop) {
+            this.playOpen();
+        }
+    }
+
+    /**
+     * Moves the animation to a specific frame and pauses.
+     * @private
+     * @param {number} frame - The frame to go to and pause.
+     */
+    #goToFrameAndPause(frame) {
+        if (!frame) {
+            return;
+        }
+
+        if (this.#state === OpeningAnimation.states.opening) {
+            this.#openAnimation.pause();
+        }
+        if (this.#state === OpeningAnimation.states.closing) {
+            this.#closeAnimation.pause();
+        }
+
+        if (this.#openAnimation._isStarted && this.#openAnimation._isPaused) {
+            this.#openAnimation.goToFrame(frame);
+        } else {
+            this.#openAnimation.start();
+            this.#openAnimation.pause();
+            this.#openAnimation.goToFrame(frame);
+        }
+
+        this.#lastPausedFrame = frame;
+        this.#state = OpeningAnimation.states.paused;
+        this.#updateControls();
+    }
+
+    /**
+     * Gets the current frame of the animation based on its state.
+     * @private
+     * @returns {number} The current frame.
+     */
+    #getCurrentFrame() {
+        let currentFrame;
+        if (this.#state === OpeningAnimation.states.opening) {
+            currentFrame = this.#openAnimation.getCurrentFrame();
+        } else if (this.#state === OpeningAnimation.states.closing) {
+            currentFrame = this.#endFrame - this.#closeAnimation.getCurrentFrame();
+        } else {
+            currentFrame = this.#lastPausedFrame;
+        }
+
+        // Ensure currentFrame is within startFrame and endFrame
+        if (currentFrame < this.#startFrame) {
+            currentFrame = this.#startFrame;
+        } else if (currentFrame > this.#endFrame) {
+            currentFrame = this.#endFrame;
+        }
+
+        return currentFrame;
+    }
+
+    /**
+     * Calculates the frame number from a normalized progress value (0-1).
+     * @private
+     * @param {number} progress - Progress value between 0 and 1.
+     * @returns {number} The corresponding frame.
+     */
+    #getFrameFromProgress(progress) {
+        const frame = this.#startFrame + (this.#endFrame - this.#startFrame) * progress;
+        return frame;
+    }
+
+    /**
+     * Calculates the normalized progress (0-1) from the current frame.
+     * @private
+     * @returns {number} Progress value.
+     */
+    #getProgress() {
+        const currentFrame = this.#getCurrentFrame();
+        const progress = (currentFrame - this.#startFrame) / (this.#endFrame - this.#startFrame);
+        return progress;
+    }
+
+    /**
+     * Applies threshold logic to the progress value to snap to 0 or 1 if near the ends.
+     * Prevents floating point errors from leaving the animation in an in-between state.
+     * @private
+     * @param {number} progress - Progress value.
+     * @returns {number} Thresholded progress.
+     */
+    #checkProgress(progress) {
+        if (progress <= this.#progressThreshold) {
+            progress = 0;
+        } else if (progress >= 1 - this.#progressThreshold) {
+            progress = 1;
+        }
+        return progress;
+    }
+
+    /**
+     * Updates the slider value in the animation control menu to match the current progress.
+     * @private
+     */
+    #updateControlsSlider() {
+        if (!this.isControlsVisible()) {
+            return;
+        }
+        this.#menu.animationProgress = this.#getProgress();
+    }
+
+    /**
+     * Updates all controls in the animation menu (buttons, slider) to reflect the current state and progress.
+     * @private
+     */
+    #updateControls() {
+        if (!this.isControlsVisible()) {
+            return;
+        }
+        if (!this.#menu) {
+            return;
+        }
+        this.#menu.animationState = this.#state;
+        this.#menu.animationProgress = this.#getProgress();
+    }
+
+    /**
+     * ---------------------------
+     * Public methods
+     * ---------------------------
+     */
+
+    /**
+     * Checks if the animation affects the given node.
+     * @param {string} node - Node identifier.
+     * @returns {boolean}
+     */
+    isAnimationForNode(node) {
+        return this.#nodes.includes(node);
+    }
+
+    /**
+     * Starts the opening animation.
+     * @public
+     */
+    playOpen() {
+        if (this.#state === OpeningAnimation.states.opening || this.#state === OpeningAnimation.states.opened) {
+            return;
+        }
+        if (this.#state === OpeningAnimation.states.closing) {
+            this.#lastPausedFrame = this.#endFrame - this.#closeAnimation.getCurrentFrame();
+            this.#closeAnimation.pause();
+        }
+
+        if (this.#openAnimation._isStarted && this.#openAnimation._isPaused) {
+            this.#openAnimation.goToFrame(this.#lastPausedFrame);
+            this.#openAnimation.restart();
+        } else {
+            this.#openAnimation.start(false, this.#speedRatio, this.#lastPausedFrame, this.#endFrame, undefined);
+        }
+
+        this.#state = OpeningAnimation.states.opening;
+        this.#updateControls();
+    }
+
+    /**
+     * Starts the closing animation.
+     * @public
+     */
+    playClose() {
+        if (this.#state === OpeningAnimation.states.closing || this.#state === OpeningAnimation.states.closed) {
+            return;
+        }
+        if (this.#state === OpeningAnimation.states.opening) {
+            this.#lastPausedFrame = this.#openAnimation.getCurrentFrame();
+            this.#openAnimation.pause();
+        }
+
+        if (this.#closeAnimation._isStarted && this.#closeAnimation._isPaused) {
+            this.#closeAnimation.goToFrame(this.#endFrame - this.#lastPausedFrame);
+            this.#closeAnimation.restart();
+        } else {
+            this.#closeAnimation.start(false, this.#speedRatio, this.#endFrame - this.#lastPausedFrame, this.#endFrame, undefined);
+        }
+
+        this.#state = OpeningAnimation.states.closing;
+        this.#updateControls();
+    }
+
+    /**
+     * Pauses the current animation.
+     * @public
+     */
+    pause() {
+        if (this.#state === OpeningAnimation.states.opening) {
+            this.#lastPausedFrame = this.#openAnimation.getCurrentFrame();
+            this.#openAnimation.pause();
+        }
+        if (this.#state === OpeningAnimation.states.closing) {
+            this.#lastPausedFrame = this.#endFrame - this.#closeAnimation.getCurrentFrame();
+            this.#closeAnimation.pause();
+        }
+        this.#state = OpeningAnimation.states.paused;
+        this.#updateControls();
+    }
+
+    /**
+     * Moves animation to the fully opened state.
+     * @public
+     */
+    goToOpened() {
+        this.#goToOpened(false);
+    }
+
+    /**
+     * Moves animation to the fully closed state.
+     * @public
+     */
+    goToClosed() {
+        this.#goToClosed(false);
+    }
+
+    /**
+     * Displays the animation control menu and sets up callbacks.
+     * Synchronizes slider and button states with animation.
+     * @public
+     * @param {AdvancedDynamicTexture} advancedDynamicTexture - Babylon.js GUI texture.
+     */
+    showControls(advancedDynamicTexture) {
+        this.#advancedDynamicTexture = advancedDynamicTexture;
+        this.#advancedDynamicTexture.metadata = { animationName: this.name };
+        const controlCallbacks = {
+            onGoToOpened: () => {
+                if (this.#state === OpeningAnimation.states.opened) {
+                    return;
+                }
+                this.goToOpened();
+            },
+            onOpen: () => {
+                if (this.#state === OpeningAnimation.states.opened || this.#state === OpeningAnimation.states.opening) {
+                    return;
+                }
+                this.playOpen();
+            },
+            onPause: () => {
+                if (this.#state === OpeningAnimation.states.paused || this.#state === OpeningAnimation.states.closed || this.#state === OpeningAnimation.states.opened) {
+                    return;
+                }
+                this.pause();
+            },
+            onClose: () => {
+                if (this.#state === OpeningAnimation.states.closed || this.#state === OpeningAnimation.states.closing) {
+                    return;
+                }
+                this.playClose();
+            },
+            onGoToClosed: () => {
+                if (this.#state === OpeningAnimation.states.closed) {
+                    return;
+                }
+                this.goToClosed();
+            },
+            onSetAnimationProgress: (progress) => {
+                progress = this.#checkProgress(progress);
+                if (progress === 0) {
+                    this.goToClosed();
+                } else if (progress === 1) {
+                    this.goToOpened();
+                } else {
+                    const frame = this.#getFrameFromProgress(progress);
+                    this.#goToFrameAndPause(frame);
+                }
+            },
+            onToggleLoop: () => {
+                this.#loop = !this.#loop;
+                this.#menu.animationLoop = this.#loop;
+            },
+        };
+        this.#menu = new OpeningAnimationMenu(this.#advancedDynamicTexture, this.#state, this.#getProgress(), this.#loop, controlCallbacks);
+
+        // Attach to Babylon.js scene render loop for real-time updates
+        this.#openAnimation._scene.onBeforeRenderObservable.add(this.#updateControlsSlider.bind(this));
+    }
+
+    /**
+     * Hides the animation control menu and removes observers.
+     * @public
+     */
+    hideControls() {
+        if (!this.isControlsVisible()) {
+            return;
+        }
+        // Remove the observer when controls are hidden
+        this.#openAnimation._scene.onBeforeRenderObservable.removeCallback(this.#updateControlsSlider.bind(this));
+        this.#advancedDynamicTexture.dispose();
+        this.#advancedDynamicTexture = null;
+    }
+
+    /**
+     * Checks if the animation controls menu is currently visible for this animation instance.
+     * @public
+     * @returns {boolean} True if controls are visible for this animation; otherwise, false.
+     */
+    isControlsVisible() {
+        return !!(this.#advancedDynamicTexture && this.#advancedDynamicTexture.metadata?.animationName === this.name && this.#menu);
+    }
+
+    /**
+     * ---------------------------
+     * Public properties
+     * ---------------------------
+     */
+
+    /**
+     * Returns the current animation state.
+     * @public
+     * @returns {number}
+     */
+
+    get state() {
+        return this.#state;
+    }
+}