Installation

npm install humpf
# here is the copy/paste for yarn
yarn add humpf

Imports

Humpf has three main exports as well as a few types for TypeScript users:
(you can click on each to scroll to corresponding section)

import { Spring, SpringConfig, SpringSequence } from 'humpf';
// Types exports (for TypeScript users only)
import type { SpringFn, SpringResult, SpringConfig, SpringSequenceFn, SpringSequence } from 'humpf';

Springexport

Create a spring function using an optional config.

const spring = Spring();

This function returns a SpringFn function.

The Spring function accept an optional config parameter.

const spring = Spring({ equilibrium: 200 });

This config object must be of type SpringConfig (all properties are optional).

SpringConfigtype

The SpringConfig type is used to create a Spring

The SpringConfig export is also a value (see below).

Here are all its properties as well as the default values.

const DEFAULT_CONFIG: SpringConfig = {
  // initial position
  position: 0,
  // initial velocity
  velocity: 0,
  // position to approach
  equilibrium: 100,
  // angular frequency of motion
  angularFrequency: 1,
  // damping ratio of motion
  dampingRatio: 1,
  // [advanced] multiply time by this value
  timeScale: 1 / 100,
  // time at which the animation should start (after timeScale has been applied)
  timeStart: 0,
  // precision let you specify how to round values
  // value are rounded to be able to check if velocity === 0 for example
  positionPrecision: 0.00006103515625; // 1 / (1 << 14)
  velocityPrecision: 0.00006103515625; // 1 / (1 << 14)
  dampingRatioPrecision: 0.00006103515625; // 1 / (1 << 14)
};

To better understand the different options of the spring and how to use them take a look a the Article.

SpringConfigexport

The SpringConfig namespace contains a few helper function to create and minipulate SpringConfig object.

The SpringConfig export is also a type, see above for the definition of that type.

export const SpringConfig = {
  defaults,
  // presets
  basic,
  gentle,
  wobbly,
  stiff,
  slow,
  // special
  decay,
  stable,
  // utils
  findEquilibrium,
  angularFrequencyFromMass,
  angularFrequencyFromSpringConstant,
};

presets

Preset functions let you create pre defined SpringConfig object.

const spring = Spring(SpringConfig.basic());
// same as
// const spring = Spring({ angularFrequency: 1, dampingRatio: 1 });

You can also pass a SpringConfig object to any preset function to override any property.

const spring = Spring(SpringConfig.basic({ equilibrium: 200 }));

decay

Decay take a SpringConfig and returns a new SpringConfig where the equilibrium is proportional to the velocity and the dampingRatio is 1

You can use this to animate the end of a "drag" motion, once the user lift its finger but the object has some velocity left.

const spring = Spring(SpringConfig.decay({ velocity: 50 }));

You can adjust the "force" of the decay by changing the angularFrequency

const spring = Spring(SpringConfig.decay({ velocity: 50 }));

stable

The SpringConfig.stable function produce a spring that does not move.

const spring = Spring(SpringConfig.stable(200));

spring(time); // { pos: 200, vel: 0 }

To achieve this, the equilibrium and the position are set to the same value and the initial velocity is set to 0

const spring = Spring({ equilibrium: 200, position: 200, velocity: 0 });

spring(time); // { pos: 200, vel: 0 }

findEquilibrium

Take a velocity and an optional angularFrequency and return the decay equilibrium of a critically damped spring (dampingRatio = 1).

const equilibrium = SpringConfig.findEquilibrium(50, 2);

angularFrequencyFromMass

Take a mass and an optional springContant and return the corresponding angularFrequency.

const angularFrequency = SpringConfig.angularFrequencyFromMass(100, 1);

angularFrequencyFromSpringConstant

Take a springContant and an optional mass and return the corresponding angularFrequency.

const angularFrequency = SpringConfig.angularFrequencyFromMass(1, 100);

SpringFntype

The SpringFn type is the function returned by the Spring function.

const spring = Spring();
//    ^^^^^^ this has a type SpringFn

This function take only one parameter: the time (as a number) and return a SpringResult object.

type SpringFn = (t: number) => SpringResult;

const spring = Spring();
const time = 1000;
spring(time); // { position: 0.986, velocity: 0.011 }

The SpringFn type also has two functions to get the position and velocity only.

const spring = Spring();
const time = 1000;
spring.position(time); // 0.986
spring.velocity(time); // 0.011

SpringResulttype

This object is the result of calling a SpringFn

This object contains two property position and velocity, corresponding to the position and velocity of the spring motion.

interface SpringResult {
  position: number;
  velocity: number;
}

Here is a small example combining everything above:

import { Spring, SpringConfig } from "humpf";

const spring = Spring(SpringConfig.basic({ position: 0, equilibrium: 100 }));

spring(0); // { position: 0, velocity: 0 }
spring(200); // { position: 59, velocity: 27 }
spring(400); // { position: 90, velocity: 7 }
spring(600); // { position: 98, velocity: 1 }
spring(800); // { position: 100, velocity: 0 }

SpringSequenceexport

The SpringSequence is a higher order class that let you manipulate a sequence of Spring over time.

Documentation comming soon.

SpringSequencetype

Since SpringSequence is a class, you can use SpringSequence as a type.

const seq: SpringSequence = SpringSequence.create();