physics-animator 0.1.0

package/dist/Spring.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 declare namespace Spring {
+    type PhysicsParameters = {
+        strength: number;
+        damping: number;
+    };
+    /**
+     * 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`
+     */
+    function Exponential(options: ExponentialParameters): PhysicsParameters;
+    function Underdamped(options: UnderdampedParameters): PhysicsParameters;
+    function getPhysicsParameters(parameters: SpringParameters): PhysicsParameters;
+    /**
+     * Analytic spring integration
+     * @param dt_s
+     * @param state
+     * @param parameters
+     */
+    function stepSpring(dt_s: number, state: {
+        x: number;
+        targetX: number;
+        v: number;
+    }, parameters: PhysicsParameters): number | undefined;
+}
+export {};

package/dist/Spring.js

@@ -0,0 +1,117 @@
+/**
+ * Spring
+ *
+ * @author George Corney (haxiomic)
+ */
+export 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`
+     */
+    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 };
+    }
+    Spring.Exponential = Exponential;
+    function Underdamped(options) {
+        const { duration_s, bounce } = options;
+        // -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 };
+    }
+    Spring.Underdamped = Underdamped;
+    function getPhysicsParameters(parameters) {
+        if ('duration_s' in parameters) {
+            if ('bounce' in parameters) {
+                return Underdamped(parameters);
+            }
+            else {
+                return Exponential(parameters);
+            }
+        }
+        else {
+            // assume physics parameters
+            return parameters;
+        }
+    }
+    Spring.getPhysicsParameters = getPhysicsParameters;
+    /**
+     * Analytic spring integration
+     * @param dt_s
+     * @param state
+     * @param parameters
+     */
+    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;
+        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);
+            state.v = v1;
+            state.x = dx1 + state.targetX;
+        }
+        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 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 {
+            // 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 || (Spring = {}));

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/react/index.d.ts

@@ -0,0 +1,3 @@
+export * from './useAnimator.js';
+export * from './useSpringValue.js';
+export * from './useSpringState.js';

package/dist/react/index.js

@@ -0,0 +1,3 @@
+export * from './useAnimator.js';
+export * from './useSpringValue.js';
+export * from './useSpringState.js';

package/dist/react/useAnimator.d.ts

@@ -0,0 +1,12 @@
+import { Animator } from "../Animator.js";
+/**
+ * Returns an instance of Animator running an interval loop
+ * @param interval_ms interval between animation steps, pass explicit `null` to disable / stop. Defaults to `animationFrame`
+ * @returns { Animator } instance of Animator
+ */
+export declare function useAnimator(interval_ms?: number | null | 'animationFrame'): Animator;
+/**
+ * Returns the same instance of Animator that is passed in, or creates a new one if not provided.
+ * @param animator an instance of Animator to use, will not create a new one
+ */
+export declare function useAnimator(animator?: Animator): Animator;

package/dist/react/useAnimator.js

@@ -0,0 +1,26 @@
+import { useEffect } from "react";
+import { Animator } from "../Animator.js";
+import { useInitializer } from "use-initializer";
+export function useAnimator(input = 'animationFrame') {
+    if (input instanceof Animator) {
+        return input; // return the animator instance directly
+    }
+    const interval_ms = input;
+    const animator = useInitializer(() => new Animator(), (animator) => {
+        animator.stop();
+        animator.removeAll();
+    });
+    // react to change of interval handling
+    useEffect(() => {
+        animator.stop();
+        if (interval_ms !== null) {
+            if (interval_ms === 'animationFrame') {
+                animator.startAnimationFrameLoop();
+            }
+            else {
+                animator.startIntervalLoop(interval_ms);
+            }
+        }
+    }, [animator, interval_ms]);
+    return animator;
+}

package/dist/react/useSpringState.d.ts

@@ -0,0 +1,15 @@
+import { Animator } from "../Animator.js";
+import { SpringParameters } from "../Spring.js";
+/**
+ * A value that animates to a target value using a spring animation.
+ * This **will** cause a re-render when the value changes.
+ *
+ * See {@link useSpringValue} for a version that does not cause re-renders.
+ */
+export declare function useSpringState<T extends number | number[] | {
+    [field: PropertyKey]: number;
+}>(options: {
+    animator?: Animator;
+    initial: T;
+    target: T;
+} & SpringParameters): T;

package/dist/react/useSpringState.js

@@ -0,0 +1,13 @@
+import { useState } from "react";
+import { useSpringValue } from "./useSpringValue.js";
+/**
+ * A value that animates to a target value using a spring animation.
+ * This **will** cause a re-render when the value changes.
+ *
+ * See {@link useSpringValue} for a version that does not cause re-renders.
+ */
+export function useSpringState(options) {
+    const [state, setState] = useState(options.initial);
+    useSpringValue(options, setState);
+    return state;
+}

package/dist/react/useSpringValue.d.ts

@@ -0,0 +1,15 @@
+import { Animator } from "../Animator.js";
+import { SpringParameters } from "../Spring.js";
+/**
+ * A value that animates to a target value using a spring animation.
+ * This will **not** cause a re-render when the value changes.
+ *
+ * See {@link useSpringState} for a version that does cause re-renders.
+ */
+export declare function useSpringValue<T extends number | number[] | {
+    [field: PropertyKey]: number;
+}>(options: {
+    animator?: Animator;
+    initial: T;
+    target: T;
+} & SpringParameters, onChange: (value: T) => void): void;

package/dist/react/useSpringValue.js

@@ -0,0 +1,56 @@
+import { useRef } from "react";
+import { useAnimator } from "./useAnimator.js";
+import { useInitializer } from "use-initializer";
+/**
+ * A value that animates to a target value using a spring animation.
+ * This will **not** cause a re-render when the value changes.
+ *
+ * See {@link useSpringState} for a version that does cause re-renders.
+ */
+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);
+            },
+        };
+    });
+    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;
+    }
+}

package/dist/three/ThreeAnimator.d.ts

@@ -0,0 +1,56 @@
+import { Euler, Quaternion, Vector2, Vector3, Vector4 } from "three";
+import { Animator, TweenStepFn } from "../Animator.js";
+import { Spring, SpringParameters } from "../Spring.js";
+export declare enum QuaternionSpringMode {
+    DirectionRollCartesian = 0,
+    YawPitchRoll = 1
+}
+type SupportedTypes = Vector4 | Vector3 | Vector2 | Quaternion | Euler | number;
+type KeysOfType<T, U> = keyof T;
+/**
+ * Extends Animator to add support for animating vectors and quaternions
+ */
+export declare class ThreeAnimator {
+    animator: Animator;
+    get onAfterStep(): import("@haxiomic/event-signal").EventSignal<{
+        dt_s: number;
+    }, {
+        dt_s: number;
+    }>;
+    get onBeforeStep(): import("@haxiomic/event-signal").EventSignal<{
+        dt_s: number;
+    }, {
+        dt_s: number;
+    }>;
+    quaternionSprings: Map<Quaternion, {
+        q: Quaternion;
+        target: Quaternion;
+        direction: Vector3;
+        directionVelocity: Vector3;
+        rollVelocity: number;
+        params: Spring.PhysicsParameters | null;
+        mode: QuaternionSpringMode;
+    }>;
+    constructor(animator?: Animator);
+    setTo<Obj, Name extends KeysOfType<Obj, SupportedTypes>, T extends Obj[Name] & SupportedTypes>(object: Obj, field: Name, target: T): void;
+    springTo<Obj, Name extends KeysOfType<Obj, SupportedTypes>, T extends Obj[Name] & SupportedTypes>(object: Obj, field: Name, target: T, params?: SpringParameters, mode?: QuaternionSpringMode): void;
+    customTweenTo<Obj, Name extends KeysOfType<Obj, SupportedTypes>, T extends Obj[Name] & SupportedTypes>(object: Obj, field: Name, target: T, duration_s: number, step: TweenStepFn): void;
+    linearTo<Obj, Name extends KeysOfType<Obj, SupportedTypes>, T extends Obj[Name] & SupportedTypes>(object: Obj, field: Name, target: T, duration_s: number): void;
+    easeInOutTo<Obj, Name extends KeysOfType<Obj, SupportedTypes>, T extends Obj[Name] & SupportedTypes>(object: Obj, field: Name, target: T, duration_s: number): void;
+    easeInTo<Obj, Name extends KeysOfType<Obj, SupportedTypes>, T extends Obj[Name] & SupportedTypes>(object: Obj, field: Name, target: T, duration_s: number): void;
+    easeOutTo<Obj, Name extends KeysOfType<Obj, SupportedTypes>, T extends Obj[Name] & SupportedTypes>(object: Obj, field: Name, target: T, duration_s: number): void;
+    step(dt_s: number): void;
+    tick(): void;
+    remove<Obj, Name extends KeysOfType<Obj, SupportedTypes>>(object: Obj, field: Name): void;
+    removeAll(): void;
+    getVelocity<Obj, Name extends KeysOfType<Obj, SupportedTypes>, T extends Obj[Name] & (Vector4 | Vector3 | Vector2 | {
+        directionVelocity: Vector3;
+        rollVelocity: number;
+    } | Euler | number)>(object: Obj, field: Name, into?: T): T;
+    startAnimationFrameLoop(): void;
+    startIntervalLoop(interval_ms?: number): void;
+    stop(): void;
+    private stepQuaternionSprings;
+    private getQuaternionSpring;
+}
+export {};