physics-animator 0.1.0 → 0.2.0

package/dist/cjs/AnimationSequencer.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnimationSequencer = void 0;
+const event_signal_1 = require("@haxiomic/event-signal");
+class AnimationSequencer {
+    constructor() {
+        this.timeoutHandles = [];
+        this.intervalHandles = [];
+        this.sequences = [];
+        /**
+         * Execute a serial sequence of steps, firing a callback at each step. We either wait for the onCompleteEvent to be fired, or we wait for maxWait milliseconds before moving on to the next step.
+         *
+         * @returns Sequence - a function that can be called to stop the sequence
+         */
+        this.runSequence = (steps) => {
+            let sequenceEvents = {
+                onStep: new event_signal_1.EventSignal(),
+                onComplete: new event_signal_1.EventSignal(),
+                onFinally: new event_signal_1.EventSignal(),
+                onError: new event_signal_1.EventSignal(),
+            };
+            let openListeners = new Set();
+            let timeoutHandles = new Array();
+            let stepIndex = 0;
+            const executeStep = (index) => {
+                try {
+                    // check if we've reached the end of the sequence
+                    if (index >= steps.length) {
+                        sequenceEvents.onComplete.dispatch();
+                        sequenceEvents.onFinally.dispatch({
+                            complete: true,
+                            stepIndex: steps.length - 1,
+                        });
+                        return;
+                    }
+                    let step = steps[index];
+                    if (!step) {
+                        throw new Error(`Step at index ${index} is undefined`);
+                    }
+                    sequenceEvents.onStep.dispatch(index);
+                    let timeoutHandle = null;
+                    let completeListener = null;
+                    if (step.onCompleteEvent) {
+                        let listener = step.onCompleteEvent.once(() => {
+                            openListeners.delete(listener);
+                        });
+                    }
+                    if (step.maxWait_ms) {
+                        timeoutHandle = this.setTimeout(() => next(), step.maxWait_ms);
+                        timeoutHandles.push(timeoutHandle);
+                    }
+                    if (!step.onCompleteEvent && !step.maxWait_ms) {
+                        next();
+                    }
+                    let hasFinished = false;
+                    function next() {
+                        if (hasFinished)
+                            return;
+                        clearTimeout(timeoutHandle);
+                        completeListener?.remove();
+                        stepIndex++;
+                        hasFinished = true;
+                        executeStep(stepIndex);
+                    }
+                    let result = step.callback();
+                    if (result['then']) {
+                        result.then(() => {
+                            // if no onCompleteEvent, then we can move on to the next step
+                            if (!step.onCompleteEvent) {
+                                next();
+                            }
+                        }).catch((error) => {
+                            sequenceEvents.onError.dispatch(error);
+                            stop();
+                        });
+                    }
+                }
+                catch (error) {
+                    sequenceEvents.onError.dispatch(error);
+                    stop();
+                }
+            };
+            let stopped = false;
+            function stop() {
+                if (stopped)
+                    return;
+                for (let listener of openListeners) {
+                    listener.remove();
+                }
+                for (let handle of timeoutHandles) {
+                    clearTimeout(handle);
+                }
+                sequenceEvents.onFinally.dispatch({
+                    complete: false,
+                    stepIndex,
+                });
+                stopped = true;
+            }
+            // promise interface
+            let promise = new Promise((resolve, reject) => {
+                sequenceEvents.onComplete.once(() => resolve());
+                sequenceEvents.onFinally.once(() => resolve());
+                sequenceEvents.onError.once((error) => reject(error));
+            });
+            let sequence = {
+                stop,
+                events: sequenceEvents,
+                promise,
+            };
+            // track sequence
+            this.sequences.push(sequence);
+            sequenceEvents.onFinally.once(() => {
+                let index = this.sequences.indexOf(sequence);
+                this.sequences.splice(index, 1);
+            });
+            // start
+            executeStep(stepIndex);
+            return sequence;
+        };
+        this.registerSequence = (sequence) => {
+            this.sequences.push(sequence);
+            sequence.events.onFinally.once(() => {
+                let index = this.sequences.indexOf(sequence);
+                this.sequences.splice(index, 1);
+            });
+        };
+        this.setTimeout = (callback, delay) => {
+            let handle = window.setTimeout(callback, delay);
+            this.timeoutHandles.push(handle);
+            return handle;
+        };
+        this.setInterval = (callback, delay) => {
+            let handle = window.setInterval(callback, delay);
+            this.intervalHandles.push(handle);
+            return handle;
+        };
+        this.stopAllTimeouts = () => {
+            this.timeoutHandles.forEach(handle => clearTimeout(handle));
+            this.timeoutHandles = [];
+        };
+        this.stopAllIntervals = () => {
+            this.intervalHandles.forEach(handle => clearInterval(handle));
+            this.intervalHandles = [];
+        };
+        this.stopAllSequences = () => {
+            this.sequences.forEach(sequence => sequence.stop());
+            this.sequences = [];
+        };
+        this.stopAll = () => {
+            this.stopAllTimeouts();
+            this.stopAllIntervals();
+            this.stopAllSequences();
+        };
+    }
+}
+exports.AnimationSequencer = AnimationSequencer;

package/dist/cjs/Animator.js

@@ -0,0 +1,310 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tween = exports.Animator = void 0;
+const event_signal_1 = require("@haxiomic/event-signal");
+const Spring_js_1 = require("./Spring.js");
+var AnimationType;
+(function (AnimationType) {
+    AnimationType[AnimationType["Spring"] = 0] = "Spring";
+    AnimationType[AnimationType["Tween"] = 1] = "Tween";
+})(AnimationType || (AnimationType = {}));
+/**
+ * Physically based animation of numeric properties of objects
+ *
+ * Designed to avoid discontinuities for smooth animation in all conditions
+ */
+class Animator {
+    constructor(onBeforeStep, onAfterStep) {
+        this.onBeforeStep = new event_signal_1.EventSignal();
+        this.onAfterStep = new event_signal_1.EventSignal();
+        this._onAnimationComplete = new event_signal_1.EventSignal();
+        this._onObjectAnimationsComplete = new event_signal_1.EventSignal();
+        this.animations = new Map();
+        this._springState = { x: 0, targetX: 0, v: 0 };
+        this.t_last = -1;
+        this._currentLoopControl = null;
+        if (onBeforeStep) {
+            this.onBeforeStep.addListener(e => onBeforeStep(e.dt_s));
+        }
+        if (onAfterStep) {
+            this.onAfterStep.addListener(e => onAfterStep(e.dt_s));
+        }
+    }
+    springTo(object, field, target, params = { duration_s: 0.5 }) {
+        if (params != null) {
+            let spring = this.getAnimationOrCreate(object, field, AnimationType.Spring);
+            // update the target and parameters
+            spring.type = AnimationType.Spring;
+            spring.target = target;
+            spring.springParams = Spring_js_1.Spring.getPhysicsParameters(params);
+            spring.step = null;
+        }
+        else {
+            this.setTo(object, field, target);
+        }
+    }
+    customTweenTo(object, field, target, duration_s, step) {
+        let animation = this.getAnimationOrCreate(object, field, AnimationType.Tween);
+        animation.type = AnimationType.Tween;
+        animation.target = target;
+        animation.tweenParams = {
+            x0: object[field],
+            t0_ms: performance.now(),
+            duration_s: duration_s,
+        };
+        animation.step = step;
+    }
+    linearTo(object, field, target, duration_s) {
+        this.customTweenTo(object, field, target, duration_s, Tween.linearStep);
+    }
+    easeInOutTo(object, field, target, duration_s) {
+        this.customTweenTo(object, field, target, duration_s, Tween.easeInOutStep);
+    }
+    easeInTo(object, field, target, duration_s) {
+        this.customTweenTo(object, field, target, duration_s, Tween.easeInStep);
+    }
+    easeOutTo(object, field, target, duration_s) {
+        this.customTweenTo(object, field, target, duration_s, Tween.easeOutStep);
+    }
+    /**
+     * Remove animation from the object and set the field to the target value
+     */
+    setTo(object, field, target) {
+        this.remove(object, field);
+        object[field] = target;
+    }
+    onComplete(object, field, callback) {
+        return this._onAnimationComplete.addListener(e => {
+            if (e.object === object && e.field === field) {
+                callback(object, field);
+            }
+        });
+    }
+    onAllComplete(object, callback, once) {
+        let listener = this._onObjectAnimationsComplete.addListener(e => {
+            if (e.object === object) {
+                callback(object);
+                if (once) {
+                    listener.remove();
+                }
+            }
+        });
+        return listener;
+    }
+    step(dt_s) {
+        if (this.onBeforeStep.hasListeners()) {
+            this.onBeforeStep.dispatch({ dt_s });
+        }
+        let springState = this._springState;
+        // step all animations
+        this.animations.forEach((objectAnims, object) => {
+            objectAnims.forEach((animation, field) => {
+                switch (animation.type) {
+                    case AnimationType.Spring:
+                        {
+                            // step the spring
+                            springState.x = object[field];
+                            springState.targetX = animation.target;
+                            springState.v = animation.velocity;
+                            if (animation.springParams != null) {
+                                Spring_js_1.Spring.stepSpring(dt_s, springState, animation.springParams);
+                            }
+                            else {
+                                // instant transition: set to the target
+                                springState.x = springState.targetX;
+                                springState.v = 0;
+                            }
+                            // update the object
+                            object[field] = springState.x;
+                            animation.velocity = springState.v;
+                            // remove the spring if it's close enough to the target and velocity is close to 0
+                            if (Math.abs(springState.x - springState.targetX) < 0.0001 && Math.abs(springState.v) < 0.0001) {
+                                object[field] = animation.target;
+                                objectAnims.delete(field);
+                                this._onAnimationComplete.dispatch({ object, field });
+                            }
+                        }
+                        break;
+                    case AnimationType.Tween: {
+                        // step the tween
+                        let x = object[field];
+                        animation.step(object, field, animation.target, animation.tweenParams, dt_s);
+                        let x_new = object[field];
+                        animation.velocity = (x_new - x) / dt_s;
+                        // remove the tween if it's complete
+                        let deltaTime_s = (performance.now() - animation.tweenParams.t0_ms) / 1000;
+                        if (deltaTime_s >= animation.tweenParams.duration_s) {
+                            object[field] = animation.target;
+                            objectAnims.delete(field);
+                            this._onAnimationComplete.dispatch({ object, field });
+                        }
+                        break;
+                    }
+                }
+            });
+            // remove the object if it has no more springs
+            if (objectAnims.size == 0) {
+                this.animations.delete(object);
+                this._onObjectAnimationsComplete.dispatch({ object });
+            }
+        });
+        this.onAfterStep.dispatch({ dt_s });
+    }
+    tick() {
+        let t_s = performance.now() / 1000;
+        let dt_s = this.t_last >= 0 ? t_s - this.t_last : 1 / 60;
+        this.t_last = t_s;
+        this.step(dt_s);
+        return dt_s;
+    }
+    /**
+     * Start the animation loop using requestAnimationFrame
+     *
+     * This will stop any existing animation loop
+     */
+    startAnimationFrameLoop() {
+        this.stop();
+        let frameLoopHandle = -1;
+        let frameLoop = () => {
+            this.tick();
+            frameLoopHandle = window.requestAnimationFrame(frameLoop);
+        };
+        frameLoop();
+        this._currentLoopControl = {
+            stop: () => {
+                window.cancelAnimationFrame(frameLoopHandle);
+            },
+            start: () => {
+                frameLoop();
+            }
+        };
+    }
+    /**
+     * Start the animation loop using setTimeout
+     *
+     * This will stop any existing animation loop
+     */
+    startIntervalLoop(interval_ms = 1000 / 240) {
+        this.stop();
+        let intervalHandle = -1;
+        let intervalLoop = () => {
+            this.tick();
+            intervalHandle = window.setTimeout(intervalLoop, interval_ms);
+        };
+        intervalLoop();
+        this._currentLoopControl = {
+            stop: () => {
+                window.clearTimeout(intervalHandle);
+            },
+            start: () => {
+                intervalLoop();
+            }
+        };
+    }
+    stop() {
+        if (this._currentLoopControl != null) {
+            this._currentLoopControl.stop();
+            this._currentLoopControl = null;
+        }
+    }
+    /**
+     * Remove animation for this object and field if it exists
+     * Does not change the value of the field
+     */
+    remove(object, field) {
+        let objectSprings = this.animations.get(object);
+        if (objectSprings != null) {
+            objectSprings.delete(field);
+        }
+        // if there are no more springs for this object, remove it from the map
+        if (objectSprings != null && objectSprings.size == 0) {
+            this.animations.delete(object);
+        }
+    }
+    /**
+     * Remove all animations for this object
+     */
+    removeObject(object) {
+        this.animations.delete(object);
+    }
+    /**
+     * Remove all animations
+     */
+    removeAll() {
+        this.animations.clear();
+    }
+    getVelocity(object, field) {
+        let spring = this.getObjectAnimations(object).get(field);
+        return spring?.velocity ?? 0;
+    }
+    /**
+     * Creates a new map if one doesn't already exist for the given object
+     */
+    getObjectAnimations(object) {
+        let objectAnimations = this.animations.get(object);
+        if (objectAnimations == null) {
+            // create
+            objectAnimations = new Map();
+            this.animations.set(object, objectAnimations);
+        }
+        return objectAnimations;
+    }
+    /**
+     * Creates a new spring if one doesn't already exist for the given object and field
+     */
+    getAnimationOrCreate(object, field, type) {
+        let objectAnimations = this.getObjectAnimations(object);
+        let animation = objectAnimations.get(field);
+        if (animation == null) {
+            // create
+            animation = {
+                target: 0,
+                type: type,
+                springParams: null,
+                tweenParams: null,
+                velocity: 0,
+                step: null
+            };
+            objectAnimations.set(field, animation);
+        }
+        animation.type = type;
+        return animation;
+    }
+}
+exports.Animator = Animator;
+var Tween;
+(function (Tween) {
+    function linearStep(object, field, target, params, dt_s) {
+        let dx = target - params.x0;
+        let t = (performance.now() - params.t0_ms) / 1000;
+        let u = t / params.duration_s;
+        let x_new = params.x0 + dx * u;
+        object[field] = x_new;
+    }
+    Tween.linearStep = linearStep;
+    // cubic ease in out
+    function easeInOutStep(object, field, target, params, dt_s) {
+        let dx = target - params.x0;
+        let t = (performance.now() - params.t0_ms) / 1000;
+        let u = t / params.duration_s;
+        let x_new = params.x0 + dx * u * u * (3 - 2 * u);
+        object[field] = x_new;
+    }
+    Tween.easeInOutStep = easeInOutStep;
+    function easeInStep(object, field, target, params, dt_s) {
+        let dx = target - params.x0;
+        let t = (performance.now() - params.t0_ms) / 1000;
+        let u = t / params.duration_s;
+        let x_new = params.x0 + dx * u * u * u;
+        object[field] = x_new;
+    }
+    Tween.easeInStep = easeInStep;
+    function easeOutStep(object, field, target, params, dt_s) {
+        let dx = target - params.x0;
+        let t = (performance.now() - params.t0_ms) / 1000;
+        let u = t / params.duration_s;
+        let x_new = params.x0 + dx * (1 - Math.pow(1 - u, 3));
+        object[field] = x_new;
+    }
+    Tween.easeOutStep = easeOutStep;
+})(Tween || (exports.Tween = Tween = {}));

package/{src/Spring.ts → dist/cjs/Spring.js}

@@ -1,51 +1,30 @@
+"use strict";
 /**
  * Spring
- * 
+ *
  * @author George Corney (haxiomic)
  */
-
-type ExponentialParameters = {
-    /** Defined as the point in time we'll reach within 0.01% of target from 0 velocity start */
-    duration_s: number,
-}
-
-type UnderdampedParameters = {
-    /** Defined as the point in time we'll reach within 0.01% of target from 0 velocity start */
-    duration_s: number,
-    /**
-     * How soft / bouncy the spring, at 0 there is no bounce and decay is exponential, from 0 to infinity the spring will overshoot its target while decaying
-     * It can be loosely through of roughly the number of oscillations it will take to reach the target
-     */
-    bounce: number,
-};
-
-export type SpringParameters = ExponentialParameters | UnderdampedParameters | Spring.PhysicsParameters;
-
-export namespace Spring {
-
-    export type PhysicsParameters = {
-        strength: number,
-        damping: number,
-    }
-
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Spring = void 0;
+var Spring;
+(function (Spring) {
     /**
      * Starting with 0 velocity, this parameter describes how long it would take to reach half-way to the target
-     * 
+     *
      * `damping = 3.356694 / approxHalfLife_s`
-     * 
+     *
      * `strength = damping * damping / 4`
      */
-    export function Exponential(options: ExponentialParameters): PhysicsParameters {
+    function Exponential(options) {
         // solved numerically
         const halfLifeConstant = 3.356694; // from solve (1+u)*exp(-u)=0.5 for u, and constant = 2u
         const pointOnePercentConstant = 18.46682; // from solve (1+u)*exp(-u)=0.001 for u, and constant = 2u
         const damping = pointOnePercentConstant / options.duration_s;
-
         let strength = damping * damping / 4;
         return { damping, strength };
     }
-
-    export function Underdamped(options: UnderdampedParameters): PhysicsParameters {
+    Spring.Exponential = Exponential;
+    function Underdamped(options) {
         const { duration_s, bounce } = options;
         // -2ln(0.001) = b t
         const durationTarget = 0.001; // 0.1% of target
@@ -53,110 +32,89 @@ export namespace Spring {
         // 4k - b^2 > 0
         let bSq = damping * damping;
         const criticalStrength = bSq / 4;
-        let strength = criticalStrength + (bounce * bounce + 1); 
+        let strength = criticalStrength + (bounce * bounce + 1);
         return { damping, strength };
     }
-
-    export function getPhysicsParameters(
-        parameters: SpringParameters
-    ): PhysicsParameters {
+    Spring.Underdamped = Underdamped;
+    function getPhysicsParameters(parameters) {
         if ('duration_s' in parameters) {
             if ('bounce' in parameters) {
                 return Underdamped(parameters);
-            } else {
+            }
+            else {
                 return Exponential(parameters);
             }
-        } else {
+        }
+        else {
             // assume physics parameters
-            return parameters as PhysicsParameters;
+            return parameters;
         }
     }
-
+    Spring.getPhysicsParameters = getPhysicsParameters;
     /**
      * Analytic spring integration
-     * @param dt_s 
-     * @param state 
-     * @param parameters 
+     * @param dt_s
+     * @param state
+     * @param parameters
      */
-    export function stepSpring(
-        dt_s: number,
-        state: {
-            x: number,
-            targetX: number,
-            v: number,
-        },
-        parameters: PhysicsParameters
-    ) {
+    function stepSpring(dt_s, state, parameters) {
         // analytic integration (unconditionally stable)
         // visualization: https://www.desmos.com/calculator/c2iug0kerh
         // references:
         // https://mathworld.wolfram.com/OverdampedSimpleHarmonicMotion.html
         // https://mathworld.wolfram.com/CriticallyDampedSimpleHarmonicMotion.html
         // https://mathworld.wolfram.com/UnderdampedSimpleHarmonicMotion.html
-
         let k = parameters.strength;
         let b = parameters.damping;
         let t = dt_s;
         let v0 = state.v;
         let dx0 = state.x - state.targetX;
-
         // nothing will change; exit early
-        if (dx0 === 0 && v0 === 0) return;
-        if (dt_s === 0) return;
-
+        if (dx0 === 0 && v0 === 0)
+            return;
+        if (dt_s === 0)
+            return;
         let critical = k * 4 - b * b;
-
         if (critical > 0) {
             // under damped
             let q = 0.5 * Math.sqrt(critical); // γ
-
             let A = dx0;
             let B = ((b * dx0) * 0.5 + v0) / q;
-
             let m = Math.exp(-b * 0.5 * t);
             let c = Math.cos(q * t);
             let s = Math.sin(q * t);
-
-            let dx1 = m * (A*c + B*s);
-            let v1 = m * (
-                ( B*q - 0.5*A*b) * c +
-                (-A*q - 0.5*b*B) * s
-            );
-
+            let dx1 = m * (A * c + B * s);
+            let v1 = m * ((B * q - 0.5 * A * b) * c +
+                (-A * q - 0.5 * b * B) * s);
             state.v = v1;
             state.x = dx1 + state.targetX;
-        } else if (critical < 0) {
+        }
+        else if (critical < 0) {
             // over damped
             let u = 0.5 * Math.sqrt(-critical);
             let p = -0.5 * b + u;
             let n = -0.5 * b - u;
-            let B = -(n*dx0 - v0)/(2*u);
+            let B = -(n * dx0 - v0) / (2 * u);
             let A = dx0 - B;
-
             let ep = Math.exp(p * t);
             let en = Math.exp(n * t);
-
             let dx1 = A * en + B * ep;
             let v1 = A * n * en + B * p * ep;
-
             state.v = v1;
             state.x = dx1 + state.targetX;
-        } else {
+        }
+        else {
             // critically damped
             let w = Math.sqrt(k); // ω
-
             let A = dx0;
             let B = v0 + w * dx0;
             let e = Math.exp(-w * t);
-
             let dx1 = (A + B * t) * e;
             let v1 = (B - w * (A + B * t)) * e;
-
             state.v = v1;
             state.x = dx1 + state.targetX;
         }
-
         return 0.5 * k * state.x * state.x;
     }
-
-}
+    Spring.stepSpring = stepSpring;
+})(Spring || (exports.Spring = Spring = {}));

package/dist/cjs/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./AnimationSequencer.js"), exports);
+__exportStar(require("./Animator.js"), exports);
+__exportStar(require("./Spring.js"), exports);

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type": "commonjs"}