A tiny (~1.7 KB gzipped) spring physics micro-library that models a damped harmonic oscillator.
TypeScript JavaScript
Switch branches/tags
v1.5.0 v1.4.1 v1.4.0 v1.3.1 v1.3.0 v1.2.0 v1.1.0 v0.2.1 v0.2.0 v0.1.0 phabricator/diff/11769 phabricator/diff/11505 phabricator/diff/11504 phabricator/diff/11503 phabricator/diff/11498 phabricator/diff/11497 phabricator/diff/11496 phabricator/diff/11462 phabricator/diff/11461 phabricator/diff/11460 phabricator/diff/11458 phabricator/diff/11457 phabricator/diff/11456 phabricator/diff/11412 phabricator/diff/11411 phabricator/diff/11409 phabricator/diff/11408 phabricator/diff/11407 phabricator/diff/11405 phabricator/diff/11403 phabricator/diff/11402 phabricator/diff/11400 phabricator/diff/11398 phabricator/diff/11395 phabricator/diff/11394 phabricator/diff/11392 phabricator/diff/11391 phabricator/diff/11390 phabricator/diff/11389 phabricator/diff/11388 phabricator/diff/11387 phabricator/diff/11386 phabricator/diff/11385 phabricator/diff/11382 phabricator/diff/11381 phabricator/diff/11369 phabricator/diff/11368 phabricator/diff/11357 phabricator/diff/11356 phabricator/diff/11355 phabricator/diff/11354 phabricator/diff/11353 phabricator/diff/11352 phabricator/diff/11351 phabricator/diff/11350 phabricator/diff/11349 phabricator/diff/11348 phabricator/diff/11347 phabricator/diff/11346 phabricator/diff/11345 phabricator/diff/11344 phabricator/diff/11343 phabricator/diff/11341 phabricator/base/11769 phabricator/base/11505 phabricator/base/11504 phabricator/base/11503 phabricator/base/11498 phabricator/base/11497 phabricator/base/11496 phabricator/base/11462 phabricator/base/11461 phabricator/base/11460 phabricator/base/11458 phabricator/base/11457 phabricator/base/11456 phabricator/base/11412 phabricator/base/11411 phabricator/base/11409 phabricator/base/11408 phabricator/base/11407 phabricator/base/11405 phabricator/base/11403 phabricator/base/11402 phabricator/base/11400 phabricator/base/11398 phabricator/base/11395 phabricator/base/11394 phabricator/base/11392 phabricator/base/11391 phabricator/base/11390 phabricator/base/11389 phabricator/base/11388 phabricator/base/11387 phabricator/base/11386 phabricator/base/11385 phabricator/base/11382 phabricator/base/11381 phabricator/base/11369 phabricator/base/11368
Nothing to show
Latest commit 3a06a05 Jan 16, 2018

README.md

repo-banner

Build Status codecov

A tiny (~1.7 KB gzipped) spring physics micro-library that models a damped harmonic oscillator.

Why Would I Use This?

Use wobble if you need a very small and accurate damped harmonic spring simulation in your animation library or application. wobble intentionally only provides a way to animate a scalar value according to equations governing damped harmonic motion. That's all this library will ever do -- any other functionality (integration with [insert ui library here], multi-dimensional springs, a nice API around chaining springs together, etc.) is left to the reader to implement.

Background

Using spring physics in UI design is a common way to express natural motion, and there are several ways to model the physics behind springs.

There are two main ways that spring physics is typically implemented: numerical integration (using something like the Runge-Kutta 4th order numerical integration method) or by using a closed-form (exact) solution. Numerical integration is an approximation of the exact solution, and is generally easier to derive. The numerical integration technique can be applied to basically any ordinary differential equation. Though there are several different numerical integration methods, it's common to leverage RK4 when accuracy of the approximation is required, even though it's slightly slower. RK4 is commonly used in other animation libraries, such as Rebound and Pop.

The original goal of the algorithm used in wobble was to replicate CASpringAnimation from Apple's Core Animation library (used to power animations on macOS and iOS) in order to mimic iOS animations in React Native. After doing a little spelunking inside QuartzCore.framework, it became clear that Apple was using the closed-form solution for damped harmonic oscillation to power CASpringAnimation. wobble leverages the same equations as CASpringAnimation in order to be able to match Apple animations precisely.

The closed-form solution lets us calculate position (x) and velocity (v) from time t, and thus it turns out that using the closed-form solution provides a couple advantages over RK4:

  • Easier to generate keyframes and build continuous/interruptible gestures and animations, due to the fact that x and v are pure functions of t.
  • Less code.
  • It's faster.

Math!

The ODE for damped harmonic motion is:

DHO ODE

Solving this ODE yields:

solution

And from this general solution, we're able to easily derive the solutions for under-damped, critically-damped, and over-damped damped harmonic oscillation.

The full proof can be found in this PDF from planetmath.org.

Demos

Wobble demos are located here: https://wobble-demos.now.sh/. Send PRs to add more!

Getting Started

yarn add wobble
# or
npm install --save wobble

Usage

import { Spring } from 'wobble';

// Create a new spring
const spring = new Spring({
  toValue: 100,
  stiffness: 1000,
  damping: 500,
  mass: 3,
});

// Set listeners for spring events, start the spring.
spring
  .onStart(() => {
    console.log('Spring started!');
  })
  .onUpdate((s) => {
    console.log(`Spring's current value: ` + s.currentValue);
    console.log(`Spring's current velocity: ` + s.currentVelocity);
  })
  .onStop(() => {
    console.log('Spring is at rest!');
  })
  .start();

API

new Spring(config: SpringConfig)

Initialize a new spring with a given spring configuration.

Configuration

fromValue: number

Starting value of the animation. Defaults to 0.

toValue: number

Ending value of the animation. Defaults to 1.

stiffness: number

The spring stiffness coefficient. Defaults to 100.

damping: number

Defines how the spring’s motion should be damped due to the forces of friction. Defaults to 10.

mass: number

The mass of the object attached to the end of the spring. Defaults to 1.

initialVelocity: number

The initial velocity (in units/ms) of the object attached to the spring. Defaults to 0.

allowsOverdamping: boolean

Whether or not the spring allows "overdamping" (a damping ratio > 1). Defaults to false.

overshootClamping: boolean

False when overshooting is allowed, true when it is not. Defaults to false.

restVelocityThreshold: number

When spring's velocity is below restVelocityThreshold, it is at rest. Defaults to .001.

restDisplacementThreshold: number

When the spring's displacement (current value) is below restDisplacementThreshold, it is at rest. Defaults to .001.

Methods

start(): Spring

If fromValue differs from toValue, or initialVelocity is non-zero, start the simulation and call the onStart listeners.

stop(): Spring

If a simulation is in progress, stop it and call the onStop listeners.

updateConfig(updatedConfig: PartialSpringConfig): Spring

Updates the spring config with the given values. Values not explicitly supplied will be reused from the existing config.

onStart(listener: SpringListenerFn): Spring

The provided callback will be invoked when the simulation begins.

onUpdate(listener: SpringListenerFn): Spring

The provided callback will be invoked on each frame while the simulation is running.

onStop(listener: SpringListenerFn): Spring

The provided callback will be invoked when the simulation ends.

removeListener(listenerFn: SpringListenerFn): Spring

Remove a single listener from this spring.

removeAllListeners(): Spring

Removes all listeners from this spring.

Properties

currentValue: number

The spring's current displacement.

currentVelocity: number

The spring's current velocity in units / ms.

isAtRest: boolean

If the spring has reached its toValue, or if its velocity is below the restVelocityThreshold, it is considered at rest. If stop() is called during a simulation, both isAnimating and isAtRest will be false.

isAnimating: boolean

Whether or not the spring is currently emitting values. Note: this is distinct from whether or not it is at rest. See also isAtRest.

Credits

Brenton Simpson (@appsforartists) - For his assistance in creating and testing this library.

Devine Lu Linvega (@neauoire) - The awesome logo!