physics-animator 0.2.1 → 0.9.1

package/README.md

@@ -2,6 +2,12 @@
 
 A TypeScript animation system grounded in physics with three.js and react support.
 
+<div align="center">
+  <a href="https://haxiomic.github.io/physics-animator/">
+    <img width="759" alt="Screenshot 2025-06-19 at 10 56 58" src="https://github.com/user-attachments/assets/3c8c4684-75fd-491f-a4ab-ece9aca4c327" />
+  </a>
+</div>
+
 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
@@ -20,7 +26,7 @@ Or via state
 ```tsx
 const opacity = useSpringState({ initial: 0, target: 1, duration_s: 0.8 })
 
-return <div style={opacity} />
+return <div style={{ opacity }} />
 ```
 
 It works with arrays and objects
@@ -36,15 +42,24 @@ Outside of react we use the animator object
 const animator = new Animator();
 animator.startAnimationFrameLoop();
 
-animator.springTo(character, 'opacity', 1, { duration_s: 0.8 })
+animator.springTo(character, { opacity: 1 }, { duration_s: 0.8, bounce: 1 })
+```
+
+We can animate nested fields
+
+```ts
+animator.springTo(character, { position: { x, y, z } }, { duration_s: 2 })
 ```
 
-We can animate three objects like vectors:
+And get notified of changes, even if they're nested within the object
 
 ```ts
-animator.springTo(character, 'rotation', new Quaternion(), { duration_s: 2 })
+animator.springTo(character.color, { rgb: [1, 0, 0] }, { duration_s: 2 })
+
+// will fire if any property within character is changed by the animator
+animator.onChange(character, () => render());
 ```
 
 Velocity state is stored within the animator object
 
-Tweens are also supported
+Tweens are also supported

package/dist/cjs/Animator.js

@@ -1,13 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Tween = exports.Animator = void 0;
+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 = {}));
+const IFieldAnimator_js_1 = require("./IFieldAnimator.js");
+const SpringAnimator_js_1 = require("./animators/SpringAnimator.js");
+const TweenAnimator_js_1 = require("./animators/TweenAnimator.js");
 /**
  * Physically based animation of numeric properties of objects
  *
@@ -15,73 +12,74 @@ var AnimationType;
  */
 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.events = {
+            beforeStep: new event_signal_1.EventSignal(),
+            afterStep: new event_signal_1.EventSignal(),
+            completeField: new event_signal_1.EventSignal(),
+            completeObject: new event_signal_1.EventSignal(),
+        };
+        this.changeObjectEvents = new Map();
+        this.changeFieldEvents = new Map();
+        // we use these signals to coalesce object change events
+        this.beforeChange = new event_signal_1.EventSignal();
+        this.afterChange = new event_signal_1.EventSignal();
         this.t_last = -1;
         this._currentLoopControl = null;
         if (onBeforeStep) {
-            this.onBeforeStep.addListener(e => onBeforeStep(e.dt_s));
+            this.events.beforeStep.addListener(e => onBeforeStep(e.dt_s));
         }
         if (onAfterStep) {
-            this.onAfterStep.addListener(e => onAfterStep(e.dt_s));
+            this.events.afterStep.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);
-        }
+    setTo(object, target) {
+        this.beforeChange.dispatch();
+        forObjectFieldsRecursive(object, target, (obj, field, targetValue) => {
+            this.setFieldTo(obj, field, targetValue);
+            this.dispatchChangeObjectEvent(obj);
+        });
+        this.afterChange.dispatch();
     }
-    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;
+    animateTo(object, target, animator = SpringAnimator_js_1.SpringAnimator, params = null) {
+        forObjectFieldsRecursive(object, target, (subObj, field, targetValue) => {
+            this.syncAnimation(subObj, field, targetValue, animator, params);
+        });
     }
-    linearTo(object, field, target, duration_s) {
-        this.customTweenTo(object, field, target, duration_s, Tween.linearStep);
+    springTo(object, target, params) {
+        this.animateTo(object, target, SpringAnimator_js_1.SpringAnimator, params);
     }
-    easeInOutTo(object, field, target, duration_s) {
-        this.customTweenTo(object, field, target, duration_s, Tween.easeInOutStep);
+    customTweenTo(object, target, duration_s, easingFn) {
+        this.animateTo(object, target, TweenAnimator_js_1.TweenAnimator, {
+            duration_s,
+            easingFn,
+        });
     }
-    easeInTo(object, field, target, duration_s) {
-        this.customTweenTo(object, field, target, duration_s, Tween.easeInStep);
+    linearTo(object, target, duration_s) {
+        this.customTweenTo(object, target, duration_s, TweenAnimator_js_1.linearStep);
     }
-    easeOutTo(object, field, target, duration_s) {
-        this.customTweenTo(object, field, target, duration_s, Tween.easeOutStep);
+    easeInOutTo(object, target, duration_s) {
+        this.customTweenTo(object, target, duration_s, TweenAnimator_js_1.easeInOutStep);
     }
-    /**
-     * Remove animation from the object and set the field to the target value
-     */
-    setTo(object, field, target) {
-        this.remove(object, field);
-        object[field] = target;
+    easeInTo(object, target, duration_s) {
+        this.customTweenTo(object, target, duration_s, TweenAnimator_js_1.easeInStep);
     }
-    onComplete(object, field, callback) {
-        return this._onAnimationComplete.addListener(e => {
+    easeOutTo(object, target, duration_s) {
+        this.customTweenTo(object, target, duration_s, TweenAnimator_js_1.easeOutStep);
+    }
+    onCompleteField(object, field, callback, once) {
+        let listener = this.events.completeField.addListener(e => {
             if (e.object === object && e.field === field) {
                 callback(object, field);
+                if (once) {
+                    listener.remove();
+                }
             }
         });
+        return listener;
     }
-    onAllComplete(object, callback, once) {
-        let listener = this._onObjectAnimationsComplete.addListener(e => {
+    onComplete(object, callback, once) {
+        const listener = this.events.completeObject.addListener(e => {
             if (e.object === object) {
                 callback(object);
                 if (once) {
@@ -91,64 +89,92 @@ class Animator {
         });
         return listener;
     }
-    step(dt_s) {
-        if (this.onBeforeStep.hasListeners()) {
-            this.onBeforeStep.dispatch({ dt_s });
+    onChangeField(object, field, callback) {
+        // check if field is an object
+        if (typeof object[field] === 'object' && object[field] !== null) {
+            return this.onChange(object[field], (subObject) => {
+                callback(object, field);
+            });
+        }
+        else {
+            // add a listener for this field
+            return this.addChangeFieldListener(object, field, callback);
         }
-        let springState = this._springState;
+    }
+    onChange(object, callback) {
+        // add a listener for this object and every sub-object
+        const removeCallbacks = new Array();
+        // coalesce events within a single step
+        let objectChanged = false;
+        removeCallbacks.push(this.beforeChange.addListener(() => {
+            objectChanged = false;
+        }).remove, this.afterChange.addListener(() => {
+            if (objectChanged) {
+                callback(object);
+            }
+        }).remove);
+        const subObjectChangedCallback = (subObject) => {
+            objectChanged = true;
+        };
+        enumerateObjects(object, (subObject) => {
+            let signal = this.changeObjectEvents.get(object);
+            if (signal == null) {
+                signal = new event_signal_1.EventSignal();
+                this.changeObjectEvents.set(subObject, signal);
+            }
+            const subListener = signal.addListener(subObjectChangedCallback);
+            removeCallbacks.push(() => {
+                subListener.remove();
+                if (!signal.hasListeners()) {
+                    this.changeObjectEvents.delete(object);
+                }
+            });
+        });
+        return {
+            remove: () => {
+                for (const remove of removeCallbacks) {
+                    remove();
+                }
+            }
+        };
+    }
+    onBeforeStep(callback) {
+        return this.events.beforeStep.addListener(e => callback(e.dt_s));
+    }
+    onAfterStep(callback) {
+        return this.events.afterStep.addListener(e => callback(e.dt_s));
+    }
+    step(dt_s) {
+        this.events.beforeStep.dispatch({ dt_s });
+        this.beforeChange.dispatch();
         // step all animations
-        this.animations.forEach((objectAnims, object) => {
-            objectAnims.forEach((animation, field) => {
-                switch (animation.type) {
-                    case AnimationType.Spring:
+        for (let [object, objectAnims] of this.animations.entries()) {
+            for (let [field, animation] of objectAnims.entries()) {
+                let result = animation.animator.step(animation.state, object, field, animation.params, dt_s);
+                // dispatch the field change event
+                this.dispatchChangeFieldEvent(object, field);
+                // handle animation completion
+                switch (result) {
+                    case IFieldAnimator_js_1.StepResult.Complete:
                         {
-                            // 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 });
+                            this.events.completeField.dispatch({ object, field });
                         }
                         break;
-                    }
                 }
-            });
+            }
+            ;
+            // dispatch the object change event
+            this.dispatchChangeObjectEvent(object);
             // remove the object if it has no more springs
             if (objectAnims.size == 0) {
                 this.animations.delete(object);
-                this._onObjectAnimationsComplete.dispatch({ object });
+                this.events.completeObject.dispatch({ object });
             }
-        });
-        this.onAfterStep.dispatch({ dt_s });
+        }
+        ;
+        this.afterChange.dispatch();
+        this.events.afterStep.dispatch({ dt_s });
     }
     tick() {
         let t_s = performance.now() / 1000;
@@ -211,31 +237,106 @@ class Animator {
      * 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);
+    remove(object, field, dispatchComplete = false) {
+        let objectAnimations = this.animations.get(object);
+        if (objectAnimations != null) {
+            objectAnimations.delete(field);
+            if (dispatchComplete) {
+                this.events.completeField.dispatch({ object, 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);
+        if (objectAnimations != null && objectAnimations.size == 0) {
+            this.removeObject(object, dispatchComplete);
         }
     }
     /**
      * Remove all animations for this object
      */
-    removeObject(object) {
+    removeObject(object, dispatchComplete = false) {
         this.animations.delete(object);
+        if (dispatchComplete) {
+            this.events.completeObject.dispatch({ object });
+        }
     }
     /**
      * Remove all animations
      */
-    removeAll() {
+    removeAll(dispatchComplete = false) {
+        for (let [object, objectAnimations] of this.animations.entries()) {
+            for (let field of objectAnimations.keys()) {
+                this.remove(object, field, dispatchComplete);
+            }
+        }
         this.animations.clear();
     }
-    getVelocity(object, field) {
-        let spring = this.getObjectAnimations(object).get(field);
-        return spring?.velocity ?? 0;
+    getState(object, field) {
+        let animation = this.getObjectAnimations(object).get(field);
+        return animation?.state;
+    }
+    dispatchChangeObjectEvent(object) {
+        let signal = this.changeObjectEvents.get(object);
+        if (signal == null) {
+            return;
+        }
+        signal.dispatch(object);
+    }
+    dispatchChangeFieldEvent(object, field) {
+        const map = this.changeFieldEvents.get(object);
+        if (map == null) {
+            return;
+        }
+        let signal = map.get(field);
+        if (signal == null) {
+            return;
+        }
+        if (signal.hasListeners()) {
+            signal.dispatch({ object, field });
+        }
+    }
+    addChangeFieldListener(object, field, callback) {
+        const getOrCreateChangeFieldSignal = (object, field) => {
+            let map = this.changeFieldEvents.get(object);
+            if (map == null) {
+                map = new Map();
+                this.changeFieldEvents.set(object, map);
+            }
+            let signal = map.get(field);
+            if (signal == null) {
+                signal = new event_signal_1.EventSignal();
+                map.set(field, signal);
+            }
+            return signal;
+        };
+        const signal = getOrCreateChangeFieldSignal(object, field);
+        const listener = signal.addListener((e) => {
+            callback(e.object, e.field);
+        });
+        return {
+            remove: () => {
+                listener.remove();
+                // cleanup
+                if (!signal.hasListeners()) {
+                    let map = this.changeFieldEvents.get(object);
+                    map?.delete(field);
+                    if (map != null && map.size === 0) {
+                        this.changeFieldEvents.delete(object);
+                    }
+                }
+            }
+        };
+    }
+    /**
+     * Remove animation from the object and set the field to the target value
+     *
+     * This completes the animation immediately and dispatches the onComplete event
+     */
+    setFieldTo(object, field, targetValue) {
+        const dispatchComplete = true;
+        this.remove(object, field, dispatchComplete);
+        object[field] = targetValue;
+        // dispatch the field change event
+        this.dispatchChangeFieldEvent(object, field);
     }
     /**
      * Creates a new map if one doesn't already exist for the given object
@@ -252,59 +353,56 @@ class Animator {
     /**
      * Creates a new spring if one doesn't already exist for the given object and field
      */
-    getAnimationOrCreate(object, field, type) {
+    syncAnimation(object, field, targetValue, fieldAnimator, params = null) {
         let objectAnimations = this.getObjectAnimations(object);
         let animation = objectAnimations.get(field);
-        if (animation == null) {
+        let animatorChanged = animation?.animator !== fieldAnimator;
+        if (animation == null || animatorChanged) {
             // create
             animation = {
-                target: 0,
-                type: type,
-                springParams: null,
-                tweenParams: null,
-                velocity: 0,
-                step: null
+                animator: fieldAnimator,
+                state: fieldAnimator.createState(object, field, targetValue, params),
+                params,
             };
             objectAnimations.set(field, animation);
         }
-        animation.type = type;
+        else {
+            animation.params = params;
+            animation.animator.updateState(animation.state, object, field, targetValue, params);
+        }
         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 = {}));
+function forObjectFieldsRecursive(sourceObj, targetObj, callback) {
+    for (let field in targetObj) {
+        if (Object.prototype.hasOwnProperty.call(targetObj, field)) {
+            let targetValue = targetObj[field];
+            if (typeof targetValue === 'object') {
+                forObjectFieldsRecursive(sourceObj[field], targetValue, callback);
+            }
+            else {
+                callback(sourceObj, field, targetValue);
+            }
+        }
+    }
+}
+function enumerateObjects(input, callback) {
+    // Call callback for the current object if it's an object or array
+    if (typeof input === 'object' && input !== null) {
+        callback(input);
+        // Recursively enumerate nested objects
+        if (Array.isArray(input)) {
+            for (const item of input) {
+                enumerateObjects(item, callback);
+            }
+        }
+        else {
+            for (const key in input) {
+                if (input.hasOwnProperty(key)) {
+                    enumerateObjects(input[key], callback);
+                }
+            }
+        }
+    }
+}

package/dist/cjs/IFieldAnimator.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StepResult = void 0;
+var StepResult;
+(function (StepResult) {
+    StepResult[StepResult["Continue"] = 0] = "Continue";
+    StepResult[StepResult["Complete"] = 1] = "Complete";
+})(StepResult || (exports.StepResult = StepResult = {}));

package/dist/cjs/{Spring.js → animators/SpringAnimator.js}

@@ -1,11 +1,47 @@
 "use strict";
-/**
- * Spring
- *
- * @author George Corney (haxiomic)
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Spring = void 0;
+exports.Spring = exports.SpringAnimator = void 0;
+const IFieldAnimator_js_1 = require("../IFieldAnimator.js");
+const defaultSpringParameters = {
+    duration_s: 0.5,
+};
+exports.SpringAnimator = {
+    createState(obj, field, target, params) {
+        return {
+            x: obj[field],
+            targetX: target,
+            v: 0,
+            physicsParameters: Spring.getPhysicsParameters(params ?? defaultSpringParameters),
+        };
+    },
+    updateState(state, object, field, target, params) {
+        state.x = object[field];
+        state.targetX = target;
+        state.physicsParameters = Spring.getPhysicsParameters(params ?? defaultSpringParameters);
+    },
+    step(state, object, field, params, dt_s) {
+        let physicsParameters = state.physicsParameters;
+        // step the spring
+        if (physicsParameters != null && isFinite(physicsParameters.strength) && isFinite(physicsParameters.damping)) {
+            Spring.stepSpring(dt_s, state, physicsParameters);
+        }
+        else {
+            // instant transition: set to the target
+            state.x = state.targetX;
+            state.v = 0;
+        }
+        // update the object
+        object[field] = state.x;
+        // complete the animation if it's close enough to the target and velocity is close to 0
+        if (Math.abs(state.x - state.targetX) < 0.0001 && Math.abs(state.v) < 0.0001) {
+            object[field] = state.targetX;
+            return IFieldAnimator_js_1.StepResult.Complete;
+        }
+        else {
+            return IFieldAnimator_js_1.StepResult.Continue;
+        }
+    }
+};
 var Spring;
 (function (Spring) {
     /**
@@ -16,7 +52,7 @@ var Spring;
      * `strength = damping * damping / 4`
      */
     function Exponential(options) {
-        // solved numerically
+        // found 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;
@@ -29,11 +65,12 @@ var Spring;
         // -2ln(0.001) = b t
         const durationTarget = 0.001; // 0.1% of target
         let damping = -2 * Math.log(durationTarget) / duration_s;
-        // 4k - b^2 > 0
-        let bSq = damping * damping;
-        const criticalStrength = bSq / 4;
-        let strength = criticalStrength + (bounce * bounce + 1);
-        return { damping, strength };
+        // see https://www.desmos.com/calculator/h43ylohte7
+        const strength = 0.25 * (((2 * bounce * Math.PI) / duration_s) ** 2 + damping ** 2);
+        return {
+            damping,
+            strength,
+        };
     }
     Spring.Underdamped = Underdamped;
     function getPhysicsParameters(parameters) {
@@ -56,6 +93,8 @@ var Spring;
      * @param dt_s
      * @param state
      * @param parameters
+     *
+     * If parameters are NaN or infinite, the spring will skip to the target
      */
     function stepSpring(dt_s, state, parameters) {
         // analytic integration (unconditionally stable)
@@ -74,6 +113,12 @@ var Spring;
             return;
         if (dt_s === 0)
             return;
+        if (!isFinite(k) || !isFinite(b) || !isFinite(v0) || !isFinite(dx0)) {
+            // skip to target
+            state.x = state.targetX;
+            state.v = 0;
+            return 0; // no energy
+        }
         let critical = k * 4 - b * b;
         if (critical > 0) {
             // under damped