physics-animator 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# Physics Animator
+
+A TypeScript animation system grounded in physics with three.js and react support.
+
+Why use this over other animation systems?
+
+This library focuses on simplicity and correctness – I've generally run into design troubles with popular animation libraries like framer motion: for example complex framer animations become convoluted and don't correctly handled interruptions without discontinuities in velocity
+
+For example in react, to animate opacity we could do
+
+```tsx
+useSpringValue(
+    { initial: 0, target: 1, duration_s: 0.8 },
+    value => el.style.opacity = value
+)
+```
+
+Or via state
+
+```tsx
+const opacity = useSpringState({ initial: 0, target: 1, duration_s: 0.8 })
+
+return <div style={opacity} />
+```
+
+It works with arrays and objects
+
+```tsx
+const rgb = useSpringState({ initial: [0, 0, 0], target: [1, 0, 0], duration_s: 0.8 })
+const xy = useSpringState({ initial: { x: 0, y: 0 }, target: {x: mouse.x, y: mouse.y}, duration_s: 0.1 })
+```
+
+Outside of react we use the animator object
+
+```ts
+const animator = new Animator();
+animator.startAnimationFrameLoop();
+
+animator.springTo(character, 'opacity', 1, { duration_s: 0.8 })
+```
+
+We can animate three objects like vectors:
+
+```ts
+animator.springTo(character, 'rotation', new Quaternion(), { duration_s: 2 })
+```
+
+Velocity state is stored within the animator object
+
+Tweens are also supported

package/dist/AnimationSequencer.d.ts

@@ -0,0 +1,36 @@
+import { EventSignal } from "@haxiomic/event-signal";
+export type Sequence = {
+    stop: () => void;
+    events: {
+        onStep: EventSignal<number>;
+        onComplete: EventSignal<void>;
+        onFinally: EventSignal<{
+            complete: boolean;
+            stepIndex: number;
+        }>;
+    };
+    promise: Promise<void>;
+};
+export declare class AnimationSequencer {
+    timeoutHandles: Array<any>;
+    intervalHandles: Array<any>;
+    sequences: Array<Sequence>;
+    constructor();
+    /**
+     * 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
+     */
+    runSequence: (steps: Array<{
+        callback: () => (Promise<void> | void);
+        maxWait_ms?: number;
+        onCompleteEvent?: EventSignal<any>;
+    }>) => Sequence;
+    registerSequence: (sequence: Sequence) => void;
+    setTimeout: (callback: Function, delay: number) => number;
+    setInterval: (callback: Function, delay: number) => number;
+    stopAllTimeouts: () => void;
+    stopAllIntervals: () => void;
+    stopAllSequences: () => void;
+    stopAll: () => void;
+}

package/dist/AnimationSequencer.js

@@ -0,0 +1,151 @@
+import { EventSignal } from "@haxiomic/event-signal";
+export class AnimationSequencer {
+    timeoutHandles = [];
+    intervalHandles = [];
+    sequences = [];
+    constructor() { }
+    /**
+     * 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
+     */
+    runSequence = (steps) => {
+        let sequenceEvents = {
+            onStep: new EventSignal(),
+            onComplete: new EventSignal(),
+            onFinally: new EventSignal(),
+            onError: new 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;
+    };
+    registerSequence = (sequence) => {
+        this.sequences.push(sequence);
+        sequence.events.onFinally.once(() => {
+            let index = this.sequences.indexOf(sequence);
+            this.sequences.splice(index, 1);
+        });
+    };
+    setTimeout = (callback, delay) => {
+        let handle = window.setTimeout(callback, delay);
+        this.timeoutHandles.push(handle);
+        return handle;
+    };
+    setInterval = (callback, delay) => {
+        let handle = window.setInterval(callback, delay);
+        this.intervalHandles.push(handle);
+        return handle;
+    };
+    stopAllTimeouts = () => {
+        this.timeoutHandles.forEach(handle => clearTimeout(handle));
+        this.timeoutHandles = [];
+    };
+    stopAllIntervals = () => {
+        this.intervalHandles.forEach(handle => clearInterval(handle));
+        this.intervalHandles = [];
+    };
+    stopAllSequences = () => {
+        this.sequences.forEach(sequence => sequence.stop());
+        this.sequences = [];
+    };
+    stopAll = () => {
+        this.stopAllTimeouts();
+        this.stopAllIntervals();
+        this.stopAllSequences();
+    };
+}

package/dist/Animator.d.ts

@@ -0,0 +1,125 @@
+import { EventSignal } from "@haxiomic/event-signal";
+import { Spring, SpringParameters } from "./Spring.js";
+declare enum AnimationType {
+    Spring = 0,
+    Tween = 1
+}
+/**
+ * Physically based animation of numeric properties of objects
+ *
+ * Designed to avoid discontinuities for smooth animation in all conditions
+ */
+export declare class Animator {
+    onBeforeStep: EventSignal<{
+        dt_s: number;
+    }, {
+        dt_s: number;
+    }>;
+    onAfterStep: EventSignal<{
+        dt_s: number;
+    }, {
+        dt_s: number;
+    }>;
+    protected _onAnimationComplete: EventSignal<{
+        object: any;
+        field: string | number | symbol;
+    }, {
+        object: any;
+        field: string | number | symbol;
+    }>;
+    protected _onObjectAnimationsComplete: EventSignal<{
+        object: any;
+    }, {
+        object: any;
+    }>;
+    animations: Map<any, Map<string | number | symbol, {
+        target: number;
+        type: AnimationType;
+        springParams: Spring.PhysicsParameters | null;
+        tweenParams: Tween.Parameters | null;
+        step: TweenStepFn | null;
+        velocity: number;
+    }>>;
+    constructor(onBeforeStep?: (dt_s: number) => void, onAfterStep?: (dt_s: number) => void);
+    springTo<Obj, Name extends keyof Obj>(object: Obj, field: Name, target: Obj[Name] & number, params?: SpringParameters | null): void;
+    customTweenTo<Obj, Name extends keyof Obj>(object: Obj, field: Name, target: Obj[Name] & number, duration_s: number, step: TweenStepFn): void;
+    linearTo<Obj, Name extends keyof Obj>(object: Obj, field: Name, target: Obj[Name] & number, duration_s: number): void;
+    easeInOutTo<Obj, Name extends keyof Obj>(object: Obj, field: Name, target: Obj[Name] & number, duration_s: number): void;
+    easeInTo<Obj, Name extends keyof Obj>(object: Obj, field: Name, target: Obj[Name] & number, duration_s: number): void;
+    easeOutTo<Obj, Name extends keyof Obj>(object: Obj, field: Name, target: Obj[Name] & number, duration_s: number): void;
+    /**
+     * Remove animation from the object and set the field to the target value
+     */
+    setTo<Obj, Name extends keyof Obj, T extends Obj[Name]>(object: Obj, field: Name, target: T): void;
+    onComplete<Obj, Name extends keyof Obj>(object: Obj, field: Name, callback: (object: Obj, field: Name) => void): {
+        priority: number;
+        listener: (event: {
+            object: any;
+            field: string | number | symbol;
+        }) => void;
+        remove: () => void;
+    };
+    onAllComplete<Obj>(object: Obj, callback: (object: Obj) => void, once?: 'once'): {
+        priority: number;
+        listener: (event: {
+            object: any;
+        }) => void;
+        remove: () => void;
+    };
+    private _springState;
+    step(dt_s: number): void;
+    private t_last;
+    tick(): number;
+    protected _currentLoopControl: {
+        stop: () => void;
+        start: () => void;
+    } | null;
+    /**
+     * Start the animation loop using requestAnimationFrame
+     *
+     * This will stop any existing animation loop
+     */
+    startAnimationFrameLoop(): void;
+    /**
+     * Start the animation loop using setTimeout
+     *
+     * This will stop any existing animation loop
+     */
+    startIntervalLoop(interval_ms?: number): void;
+    stop(): void;
+    /**
+     * Remove animation for this object and field if it exists
+     * Does not change the value of the field
+     */
+    remove<T>(object: T, field: keyof T): void;
+    /**
+     * Remove all animations for this object
+     */
+    removeObject(object: any): void;
+    /**
+     * Remove all animations
+     */
+    removeAll(): void;
+    getVelocity<Obj, Name extends keyof Obj>(object: Obj, field: Name): number;
+    /**
+     * Creates a new map if one doesn't already exist for the given object
+     */
+    private getObjectAnimations;
+    /**
+     * Creates a new spring if one doesn't already exist for the given object and field
+     */
+    private getAnimationOrCreate;
+}
+export type TweenStepFn = (object: any, field: string | number | symbol, target: number, params: Tween.Parameters, dt_s: number) => void;
+export declare namespace Tween {
+    type Parameters = {
+        x0: number;
+        t0_ms: number;
+        duration_s: number;
+    };
+    function linearStep(object: any, field: string | number | symbol, target: number, params: Tween.Parameters, dt_s: number): void;
+    function easeInOutStep(object: any, field: string | number | symbol, target: number, params: Tween.Parameters, dt_s: number): void;
+    function easeInStep(object: any, field: string | number | symbol, target: number, params: Tween.Parameters, dt_s: number): void;
+    function easeOutStep(object: any, field: string | number | symbol, target: number, params: Tween.Parameters, dt_s: number): void;
+}
+export {};

package/dist/Animator.js

@@ -0,0 +1,306 @@
+import { EventSignal } from "@haxiomic/event-signal";
+import { Spring } from "./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
+ */
+export class Animator {
+    onBeforeStep = new EventSignal();
+    onAfterStep = new EventSignal();
+    _onAnimationComplete = new EventSignal();
+    _onObjectAnimationsComplete = new EventSignal();
+    animations = new Map();
+    constructor(onBeforeStep, onAfterStep) {
+        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.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;
+    }
+    _springState = { x: 0, targetX: 0, v: 0 };
+    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.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 });
+    }
+    t_last = -1;
+    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;
+    }
+    _currentLoopControl = null;
+    /**
+     * 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;
+    }
+}
+export 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 || (Tween = {}));