physics-animator 0.2.0 → 0.9.0

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

@@ -1,8 +1,44 @@
-/**
- * Spring
- *
- * @author George Corney (haxiomic)
- */
+import { StepResult } from "../IFieldAnimator.js";
+const defaultSpringParameters = {
+    duration_s: 0.5,
+};
+export const 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 StepResult.Complete;
+        }
+        else {
+            return StepResult.Continue;
+        }
+    }
+};
 export var Spring;
 (function (Spring) {
     /**
@@ -13,7 +49,7 @@ export 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;
@@ -26,11 +62,12 @@ export 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) {
@@ -53,6 +90,8 @@ export 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)
@@ -71,6 +110,12 @@ export 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

package/dist/esm/animators/TweenAnimator.js

@@ -0,0 +1,68 @@
+import { StepResult } from "../IFieldAnimator.js";
+const defaultParams = {
+    duration_s: 0.5, // default duration of the tween in seconds
+    easingFn: linearStep, // default easing function is linear
+};
+export const TweenAnimator = {
+    createState(obj, field, target, params) {
+        return {
+            x0: obj[field], // initial value of the field
+            t0_ms: performance.now(), // time when the tween started in milliseconds
+            target: target,
+            velocity: 0,
+            ...(params ?? defaultParams),
+        };
+    },
+    updateState(state, object, field, target, params) {
+        state.target = target;
+        state.x0 = object[field]; // update the initial value of the field
+        state.t0_ms = performance.now(); // reset the start time of the tween
+        state.duration_s = params?.duration_s ?? defaultParams.duration_s; // update the duration of the tween
+        state.easingFn = params?.easingFn ?? defaultParams.easingFn; //
+    },
+    step(state, object, field, params, dt_s) {
+        // step the tween
+        let x = object[field];
+        params.easingFn(object, field, state.target, state, dt_s);
+        let x_new = object[field];
+        state.velocity = (x_new - x) / dt_s;
+        // remove the tween if it's complete
+        let deltaTime_s = (performance.now() - state.t0_ms) / 1000;
+        if (deltaTime_s >= state.duration_s) {
+            object[field] = state.target;
+            return StepResult.Complete;
+        }
+        else {
+            return StepResult.Continue;
+        }
+    }
+};
+export 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;
+}
+// cubic ease in out
+export 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;
+}
+export 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;
+}
+export 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;
+}

package/dist/esm/index.js

@@ -1,3 +1,3 @@
 export * from './AnimationSequencer.js';
 export * from './Animator.js';
-export * from './Spring.js';
+export * from './IFieldAnimator.js';

package/dist/esm/react/useSpringValue.js

@@ -1,6 +1,6 @@
-import { useRef } from "react";
-import { useAnimator } from "./useAnimator.js";
 import { useInitializer } from "use-initializer";
+import { useAnimator } from "./useAnimator.js";
+import { useEffect } from "react";
 /**
  * A value that animates to a target value using a spring animation.
  * This will **not** cause a re-render when the value changes.
@@ -10,47 +10,17 @@ import { useInitializer } from "use-initializer";
 export function useSpringValue(options, onChange) {
     const animator = useAnimator(options.animator);
     const springValue = useInitializer(() => {
-        let value = structuredClone(options.initial);
         return {
-            get value() {
-                return value;
-            },
-            set value(newValue) {
-                value = newValue;
-                onChange(value);
-            },
+            value: structuredClone(options.initial),
         };
     });
-    const afterStepListener = useRef(null);
-    switch (typeof options.initial) {
-        case 'number':
-            {
-                animator.springTo(springValue, 'value', options.target, options);
-            }
-            break;
-        default:
-            {
-                if (Array.isArray(options.initial)) {
-                    for (let i = 0; i < options.initial.length; i++) {
-                        animator.springTo(springValue.value, i, options.target[i], options);
-                    }
-                }
-                else {
-                    // assume object, iterate over keys
-                    for (const key in options.initial) {
-                        animator.springTo(springValue.value, key, options.target[key], options);
-                    }
-                }
-                if (!afterStepListener.current) {
-                    afterStepListener.current = animator.onAfterStep.addListener(() => {
-                        onChange(springValue.value);
-                    });
-                    animator.onAllComplete(springValue.value, () => {
-                        afterStepListener.current?.remove();
-                        afterStepListener.current = null;
-                    }, 'once');
-                }
-            }
-            break;
-    }
+    useEffect(() => {
+        let remove = animator.onChange(springValue, () => {
+            onChange(springValue.value);
+        }).remove;
+        return () => {
+            remove();
+        };
+    }, [springValue, onChange]);
+    animator.springTo(springValue, { value: options.target }, options);
 }

package/dist/types/Animator.d.ts

@@ -1,72 +1,92 @@
 import { EventSignal } from "@haxiomic/event-signal";
-import { Spring, SpringParameters } from "./Spring.js";
-declare enum AnimationType {
-    Spring = 0,
-    Tween = 1
-}
+import { IFieldAnimator } from "./IFieldAnimator.js";
+import { SpringParameters } from "./animators/SpringAnimator.js";
+import { EasingStepFn } from "./animators/TweenAnimator.js";
 /**
  * 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<{
+    animations: Map<any, Map<FieldKey, FieldAnimation<any, any>>>;
+    protected readonly events: {
+        beforeStep: EventSignal<{
+            dt_s: number;
+        }, {
+            dt_s: number;
+        }>;
+        afterStep: EventSignal<{
+            dt_s: number;
+        }, {
+            dt_s: number;
+        }>;
+        completeField: EventSignal<{
+            object: any;
+            field: FieldKey;
+        }, {
+            object: any;
+            field: FieldKey;
+        }>;
+        completeObject: EventSignal<{
+            object: any;
+        }, {
+            object: any;
+        }>;
+    };
+    protected changeObjectEvents: Map<any, EventSignal<any, any>>;
+    protected changeFieldEvents: Map<any, Map<FieldKey, EventSignal<{
         object: any;
+        field: 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;
-    }>>;
+        field: any;
+    }>>>;
+    protected beforeChange: EventSignal<void, void>;
+    protected afterChange: EventSignal<void, void>;
     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): {
+    setTo<Obj>(object: Obj, target: Partial<Obj>): void;
+    animateTo<Obj, Parameters, State, FieldType>(object: Obj, target: Partial<Obj>, animator?: IFieldAnimator<Parameters, State, FieldType>, params?: Parameters | null): void;
+    springTo<Obj>(object: Obj, target: Partial<Obj>, params: SpringParameters | null): void;
+    customTweenTo<Obj>(object: Obj, target: Partial<Obj>, duration_s: number, easingFn: EasingStepFn): void;
+    linearTo<Obj>(object: Obj, target: Partial<Obj>, duration_s: number): void;
+    easeInOutTo<Obj>(object: Obj, target: Partial<Obj>, duration_s: number): void;
+    easeInTo<Obj>(object: Obj, target: Partial<Obj>, duration_s: number): void;
+    easeOutTo<Obj>(object: Obj, target: Partial<Obj>, duration_s: number): void;
+    onCompleteField<Obj, Name extends keyof Obj>(object: Obj, field: Name, callback: (object: Obj, field: Name) => void, once?: 'once'): {
         priority: number;
         listener: (event: {
             object: any;
-            field: string | number | symbol;
+            field: FieldKey;
         }) => void;
         remove: () => void;
     };
-    onAllComplete<Obj>(object: Obj, callback: (object: Obj) => void, once?: 'once'): {
+    onComplete<Obj>(object: Obj, callback: (object: Obj) => void, once?: 'once'): {
         priority: number;
         listener: (event: {
             object: any;
         }) => void;
         remove: () => void;
     };
-    private _springState;
+    onChangeField<Obj, Name extends keyof Obj>(object: Obj, field: Name, callback: (object: Obj, field: Name) => void): {
+        remove: () => void;
+    };
+    onChange<Obj>(object: Obj, callback: (object: Obj) => void): {
+        remove: () => void;
+    };
+    onBeforeStep(callback: (dt_s: number) => void): {
+        priority: number;
+        listener: (event: {
+            dt_s: number;
+        }) => void;
+        remove: () => void;
+    };
+    onAfterStep(callback: (dt_s: number) => void): {
+        priority: number;
+        listener: (event: {
+            dt_s: number;
+        }) => void;
+        remove: () => void;
+    };
     step(dt_s: number): void;
     private t_last;
     tick(): number;
@@ -91,16 +111,27 @@ export declare class Animator {
      * 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<T>(object: T, field: keyof T, dispatchComplete?: boolean): void;
     /**
      * Remove all animations for this object
      */
-    removeObject(object: any): void;
+    removeObject(object: any, dispatchComplete?: boolean): void;
     /**
      * Remove all animations
      */
-    removeAll(): void;
-    getVelocity<Obj, Name extends keyof Obj>(object: Obj, field: Name): number;
+    removeAll(dispatchComplete?: boolean): void;
+    getState<Obj, Name extends keyof Obj>(object: Obj, field: Name): any;
+    protected dispatchChangeObjectEvent(object: any): void;
+    protected dispatchChangeFieldEvent<Obj, Name extends keyof Obj>(object: Obj, field: Name): void;
+    protected addChangeFieldListener<Obj, Name extends keyof Obj>(object: Obj, field: Name, callback: (object: Obj, field: Name) => void): {
+        remove: () => void;
+    };
+    /**
+     * Remove animation from the object and set the field to the target value
+     *
+     * This completes the animation immediately and dispatches the onComplete event
+     */
+    protected setFieldTo<Obj, Name extends keyof Obj, V extends Obj[Name]>(object: Obj, field: Name, targetValue: V): void;
     /**
      * Creates a new map if one doesn't already exist for the given object
      */
@@ -108,18 +139,12 @@ export declare class Animator {
     /**
      * 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;
+    private syncAnimation;
 }
+type FieldAnimation<Params, State> = {
+    animator: IFieldAnimator<Params, State, any>;
+    state: State;
+    params: Params | null;
+};
+type FieldKey = string | number | symbol;
 export {};

package/dist/types/IFieldAnimator.d.ts

@@ -0,0 +1,9 @@
+export declare enum StepResult {
+    Continue = 0,// continue stepping
+    Complete = 1
+}
+export interface IFieldAnimator<Params, State, FieldType> {
+    createState<Name extends keyof Obj, Obj extends Record<Name, FieldType>>(object: Obj, field: Name, target: Obj[Name], params: Params | null): State;
+    updateState<Name extends keyof Obj, Obj extends Record<Name, FieldType>>(state: State, object: Obj, field: Name, target: Obj[Name], params: Params | null): void;
+    step<Name extends keyof Obj, Obj extends Record<Name, FieldType>>(state: State, object: Obj, field: Name, params: Params, dt_s: number): StepResult;
+}

package/dist/types/{Spring.d.ts → animators/SpringAnimator.d.ts}

@@ -1,3 +1,5 @@
+import { IFieldAnimator } from "../IFieldAnimator.js";
+export declare const SpringAnimator: IFieldAnimator<SpringParameters, SpringState, number>;
 /**
  * Spring
  *
@@ -12,10 +14,16 @@ type UnderdampedParameters = {
     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
+     * It can be thought of roughly the number of oscillations it will take to reach the target
      */
     bounce: number;
 };
+type SpringState = {
+    x: number;
+    targetX: number;
+    v: number;
+    physicsParameters: Spring.PhysicsParameters;
+};
 export type SpringParameters = ExponentialParameters | UnderdampedParameters | Spring.PhysicsParameters;
 export declare namespace Spring {
     type PhysicsParameters = {
@@ -37,6 +45,8 @@ export declare namespace 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: number, state: {
         x: number;

package/dist/types/animators/TweenAnimator.d.ts

@@ -0,0 +1,21 @@
+import { IFieldAnimator } from "../IFieldAnimator.js";
+export type TweenParameters = {
+    duration_s: number;
+    easingFn: EasingStepFn;
+};
+export declare const TweenAnimator: IFieldAnimator<TweenParameters, TweenState, number>;
+type TweenState = {
+    x0: number;
+    t0_ms: number;
+    target: number;
+    duration_s: number;
+    easingFn: EasingStepFn;
+    velocity: number;
+};
+type FieldKey = string | number | symbol;
+export type EasingStepFn = (object: any, field: FieldKey, target: number, state: TweenState, dt_s: number) => void;
+export declare function linearStep(object: any, field: FieldKey, target: number, params: TweenState, dt_s: number): void;
+export declare function easeInOutStep(object: any, field: FieldKey, target: number, params: TweenState, dt_s: number): void;
+export declare function easeInStep(object: any, field: FieldKey, target: number, params: TweenState, dt_s: number): void;
+export declare function easeOutStep(object: any, field: FieldKey, target: number, params: TweenState, dt_s: number): void;
+export {};

package/dist/types/index.d.ts

@@ -1,3 +1,3 @@
 export * from './AnimationSequencer.js';
 export * from './Animator.js';
-export * from './Spring.js';
+export * from './IFieldAnimator.js';

package/dist/types/react/useSpringState.d.ts

@@ -1,5 +1,5 @@
 import { Animator } from "../Animator.js";
-import { SpringParameters } from "../Spring.js";
+import { SpringParameters } from "src/animators/SpringAnimator.js";
 /**
  * A value that animates to a target value using a spring animation.
  * This **will** cause a re-render when the value changes.

package/dist/types/react/useSpringValue.d.ts

@@ -1,5 +1,5 @@
 import { Animator } from "../Animator.js";
-import { SpringParameters } from "../Spring.js";
+import { SpringParameters } from "src/animators/SpringAnimator.js";
 /**
  * A value that animates to a target value using a spring animation.
  * This will **not** cause a re-render when the value changes.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "physics-animator",
-  "version": "0.2.0",
+  "version": "0.9.0",
   "author": "haxiomic (George Corney)",
   "license": "MIT",
-  "type": "module",
   "description": "A TypeScript animation system grounded in physics with three.js and react support.",
+  "type": "module",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -35,21 +35,13 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "@haxiomic/event-signal": "^1.0.0",
-    "use-initializer": "^1.0.2"
+    "@haxiomic/event-signal": "^1.1.0",
+    "use-initializer": "^1.1.0"
   },
   "peerDependencies": {
-    "@types/three": "x.x.x",
-    "react": ">=18.2.0",
-    "three": "x.x.x"
+    "react": ">=18.2.0"
   },
   "peerDependenciesMeta": {
-    "@types/three": {
-      "optional": true
-    },
-    "three": {
-      "optional": true
-    },
     "react": {
       "optional": true
     }