physics-animator 0.1.0

package/src/Animator.ts

@@ -0,0 +1,377 @@
+import { EventSignal } from "@haxiomic/event-signal";
+import { Spring, SpringParameters } from "./Spring.js";
+
+enum AnimationType {
+	Spring = 0,
+	Tween,
+}
+
+/**
+ * Physically based animation of numeric properties of objects
+ * 
+ * Designed to avoid discontinuities for smooth animation in all conditions
+ */
+export class Animator {
+
+	onBeforeStep = new EventSignal<{dt_s: number}>();
+	onAfterStep = new EventSignal<{dt_s: number}>();
+	protected _onAnimationComplete = new EventSignal<{object: any, field: string | number | symbol}>();
+	protected _onObjectAnimationsComplete = new EventSignal<{object: any}>();
+
+	animations = new 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) {
+		if (onBeforeStep) {
+			this.onBeforeStep.addListener(e => onBeforeStep(e.dt_s));
+		}
+		if (onAfterStep) {
+			this.onAfterStep.addListener(e => onAfterStep(e.dt_s));
+		}
+	}
+
+	springTo<Obj, Name extends keyof Obj>(object: Obj, field: Name, target: Obj[Name] & number, params: SpringParameters | null = { 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<Obj, Name extends keyof Obj>(object: Obj, field: Name, target: Obj[Name] & number, duration_s: number, step: TweenStepFn) {
+		let animation = this.getAnimationOrCreate(object, field, AnimationType.Tween);
+		animation.type = AnimationType.Tween;
+		animation.target = target;
+		animation.tweenParams = {
+			x0: object[field] as number,
+			t0_ms: performance.now(),
+			duration_s: duration_s,
+		}
+		animation.step = step;
+	}
+
+	linearTo<Obj, Name extends keyof Obj>(object: Obj, field: Name, target: Obj[Name] & number, duration_s: number) {
+		this.customTweenTo(object, field, target, duration_s, Tween.linearStep);
+	}
+
+	easeInOutTo<Obj, Name extends keyof Obj>(object: Obj, field: Name, target: Obj[Name] & number, duration_s: number) {
+		this.customTweenTo(object, field, target, duration_s, Tween.easeInOutStep);
+	}
+
+	easeInTo<Obj, Name extends keyof Obj>(object: Obj, field: Name, target: Obj[Name] & number, duration_s: number) {
+		this.customTweenTo(object, field, target, duration_s, Tween.easeInStep);
+	}
+
+	easeOutTo<Obj, Name extends keyof Obj>(object: Obj, field: Name, target: Obj[Name] & number, duration_s: number) {
+		this.customTweenTo(object, field, target, duration_s, Tween.easeOutStep);
+	}
+
+	/**
+	 * 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) {
+		this.remove(object, field);
+		object[field] = target;
+	}
+
+	onComplete<Obj, Name extends keyof Obj>(object: Obj, field: Name, callback: (object: Obj, field: Name) => void) {
+		return this._onAnimationComplete.addListener(e => {
+			if (e.object === object && e.field === field) {
+				callback(object, field);
+			}
+		});
+	}
+
+	onAllComplete<Obj>(object: Obj, callback: (object: Obj) => void, once?: 'once') {
+		let listener = this._onObjectAnimationsComplete.addListener(e => {
+			if (e.object === object) {
+				callback(object);
+				if (once) {
+					listener.remove();
+				}
+			}
+		});
+		return listener;
+	}
+
+	private _springState = { x: 0, targetX: 0, v: 0 };
+	step(dt_s: number) {
+		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});
+	}
+
+	private 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;
+	}
+
+	protected _currentLoopControl: { stop: () => void, start: () => void } | null = 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: number = 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<T>(object: T, field: keyof T) {
+		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: any) {
+		this.animations.delete(object);
+	}
+
+	/**
+	 * Remove all animations
+	 */
+	removeAll() {
+		this.animations.clear();
+	}
+
+	getVelocity<Obj, Name extends keyof Obj>(object: Obj, field: Name) {
+		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
+	 */
+	private getObjectAnimations(object: any) {
+		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
+	 */
+	private getAnimationOrCreate(object: any, field: string | number | symbol, type: AnimationType) {
+		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 type TweenStepFn = (object: any, field: string | number | symbol, target: number, params: Tween.Parameters, dt_s: number) => void;
+
+export namespace Tween {
+
+	export type Parameters = {
+		x0: number,
+		t0_ms: number,
+		duration_s: number,
+	}
+
+	export function linearStep(
+		object: any,
+		field: string | number | symbol,
+		target: number,
+		params: Tween.Parameters,
+		dt_s: number
+	) {
+		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: any,
+		field: string | number | symbol,
+		target: number,
+		params: Tween.Parameters,
+		dt_s: number
+	) {
+		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: any,
+		field: string | number | symbol,
+		target: number,
+		params: Tween.Parameters,
+		dt_s: number
+	) {
+		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: any,
+		field: string | number | symbol,
+		target: number,
+		params: Tween.Parameters,
+		dt_s: number
+	) {
+		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/src/Spring.ts

@@ -0,0 +1,162 @@
+/**
+ * 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,
+    }
+
+    /**
+     * 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 {
+        // 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 {
+        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 };
+    }
+
+    export function getPhysicsParameters(
+        parameters: SpringParameters
+    ): PhysicsParameters {
+        if ('duration_s' in parameters) {
+            if ('bounce' in parameters) {
+                return Underdamped(parameters);
+            } else {
+                return Exponential(parameters);
+            }
+        } else {
+            // assume physics parameters
+            return parameters as PhysicsParameters;
+        }
+    }
+
+    /**
+     * Analytic spring integration
+     * @param dt_s 
+     * @param state 
+     * @param parameters 
+     */
+    export function stepSpring(
+        dt_s: number,
+        state: {
+            x: number,
+            targetX: number,
+            v: number,
+        },
+        parameters: PhysicsParameters
+    ) {
+        // 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;
+    }
+
+}

package/src/index.ts

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

package/src/react/index.ts

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

package/src/react/useAnimator.ts

@@ -0,0 +1,45 @@
+import { useEffect } from "react";
+import { Animator } from "../Animator.js";
+import { useInitializer } from "use-initializer";
+
+/**
+ * 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 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 function useAnimator(animator?: Animator): Animator;
+export function useAnimator(input: number | null | 'animationFrame' | Animator = 'animationFrame'): Animator {
+	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/src/react/useSpringState.ts

@@ -0,0 +1,22 @@
+import { useState } from "react";
+import { useSpringValue } from "./useSpringValue.js";
+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 function useSpringState<T extends number | number[] | { [field: PropertyKey]: number }>(
+    options: {
+        animator?: Animator,
+        initial: T;
+        target: T;
+    } & SpringParameters,
+) {
+    const [state, setState] = useState(options.initial);
+    useSpringValue(options, setState);
+    return state;
+}

package/src/react/useSpringValue.ts

@@ -0,0 +1,81 @@
+import { useRef } from "react";
+import { Animator } from "../Animator.js";
+import { Spring, SpringParameters } from "../Spring.js";
+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<T extends number | number[] | { [field: PropertyKey]: number }>(
+    options: {
+        animator?: Animator,
+        initial: T;
+        target: T;
+    } & SpringParameters,
+    onChange: (value: T) => void
+) {
+    const animator = useAnimator(options.animator);
+
+    const springValue = useInitializer(() => {
+        let value = structuredClone(options.initial);
+        return {
+            get value() {
+                return value;
+            },
+            set value(newValue: T) {
+                value = newValue;
+                onChange(value);
+            },
+        };
+    });
+
+    const afterStepListener = useRef<{ remove:() => void } | null>(null);
+    
+    switch (typeof options.initial) {
+        case 'number': {
+            animator.springTo(
+                springValue,
+                'value',
+                options.target as any,
+                options
+            );
+        } break;
+        default: {
+            if (Array.isArray(options.initial)) {
+                for (let i = 0; i < options.initial.length; i++) {
+                    animator.springTo(
+                        springValue.value as number[],
+                        i,
+                        (options.target as number[])[i],
+                        options
+                    );
+                }
+            } else {
+                // assume object, iterate over keys
+                for (const key in options.initial) {
+                    animator.springTo(
+                        springValue.value,
+                        key,
+                        (options.target as any)[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;
+    }
+}