Spring

Springs: presets to give Machine.spring or a transition, and a spring as a stepper (resolve, init, step) for something you step yourself each frame. A spring is set by its physics, stiffness, damping and mass, or by time, a duration or visualDuration with a bounce. It steps exactly whatever the frame's dt, and keeps the velocity it's handed.

import * as Spring from "@wardic/core/Spring"

const spring = Spring.resolve(Spring.stiff)
const rest = Spring.restFor(spring, target - x)
let state = Spring.init({ from: x })
// each frame:
const frame = Spring.step(state, dt, target, spring, rest)
state = frame.state
x = frame.value // and `frame.done` once it rests on `target`

Its exports also name types the module doesn't export: its internal types.

Interfaces

Exact

A spring's step over a dt, exact for any dt, from wherever it is: a matrix on its distance from the target d and its velocity v, d' = dd·d + dv·v and v' = vd·d + vv·v. For a stepper written out in place; step is the one to call otherwise. The matrix for the last dt is kept, so every value on one resolved spring shares one exp/sin/cos a frame.

Properties

dd

readonly dd: number;

decay

readonly decay: number;

Its decay rate, damping / (2 · mass).

dt

readonly dt: number;

The dt the matrix is for: -1 before its first.

dv

readonly dv: number;

freq

readonly freq: number;

Its damped angular frequency (under), or its hyperbolic one (over); unused when critical.

kind

readonly kind: 0 | 1 | 2;

How it's damped: 0 under (it oscillates), 1 critically, 2 over.

vd

readonly vd: number;

vv

readonly vv: number;

w0

readonly w0: number;

Its undamped angular frequency, √(stiffness / mass).

Resolved

A spring's options with every default filled in, except its start (init's) and its rest thresholds: those given are kept, and the rest are a leg's, by its distance (restFor).

Properties

damping

readonly damping: number;

Its damping: higher settles sooner, with less overshoot.

delay

readonly delay: number;

Seconds before it moves.

duration

readonly duration: number;

How long it runs after its delay, in seconds: a duration spring's, which ends then, landing on its target; Infinity for every other, which ends at rest.

exact

readonly exact: Exact;

Its step as a matrix, and the last one worked out: read it through matrixFor.

mass

readonly mass: number;

The mass it moves: heavier is slower.

restDelta

readonly restDelta: number | undefined;

The rest threshold for the distance to the target, if given: else by distance (restFor).

restSpeed

readonly restSpeed: number | undefined;

The rest threshold for the speed, per second, if given: else by distance (restFor).

stiffness

readonly stiffness: number;

Its stiffness: higher is snappier.

Rest

A leg's rest thresholds: at rest within delta of its target, below speed per second.

Properties

delta

readonly delta: number;

speed

readonly speed: number;

State

A spring's state between steps: where it is, how fast it moves, and how long it has run.

Properties

elapsed

readonly elapsed: number;

Seconds it has run, its delay included.

position

readonly position: number;

Where it is.

velocity

readonly velocity: number;

How fast it moves, per second.

Variables

bouncy

const bouncy: object;

A spring that overshoots and bounces: stiffness 400, damping 10.

Type Declaration

damping

readonly damping: 10 = 10;

stiffness

readonly stiffness: 400 = 400;

gentle

const gentle: object;

A soft spring that settles without fuss: stiffness 120, damping 14. An everyday choice.

Type Declaration

damping

readonly damping: 14 = 14;

stiffness

readonly stiffness: 120 = 120;

GRANULAR

const GRANULAR: 5 = 5;

The distance under which a leg rests by finer thresholds: 0.005 and 0.01 a second, for opacity, a scale or a nudge, where a leg of 5 or more rests within 0.5 and below 2 a second. Motion's isGranularScale.

molasses

const molasses: object;

Slower still, creeping to its target: stiffness 280, damping 120.

Type Declaration

damping

readonly damping: 120 = 120;

stiffness

readonly stiffness: 280 = 280;

resolve

const resolve: (options) => Resolved;

A spring's options with its defaults filled in: stiffness 170, damping 26, mass 1, no delay. A spring set by time is solved to its physics: a duration (with a bounce, 0.3 by default; a bounce alone is a 0.8 s duration) ends at that duration, landing on its target, and a visualDuration (with a bounce, 0 by default) has done most of its move by then and ends at rest. A stiffness, damping or mass given beside wins over them. A value no spring can take, a stiffness at or below 0 say, throws an OptionError naming the field. A bag is resolved once and kept by its identity: one changed after it's handed over isn't seen, so pass a new one.

Parameters

options

SpringOptions

Returns

Resolved

Example

const spring = Spring.resolve({ visualDuration: 0.4, bounce: 0.2 })

slow

const slow: object;

A slow, heavily damped spring with no overshoot: stiffness 280, damping 60.

Type Declaration

damping

readonly damping: 60 = 60;

stiffness

readonly stiffness: 280 = 280;

stiff

const stiff: object;

A quick, firm spring that barely overshoots: stiffness 210, damping 20. An everyday choice.

Type Declaration

damping

readonly damping: 20 = 20;

stiffness

readonly stiffness: 210 = 210;

wobbly

const wobbly: object;

A spring that overshoots and wobbles a little: stiffness 180, damping 12.

Type Declaration

damping

readonly damping: 12 = 12;

stiffness

readonly stiffness: 180 = 180;

Functions

endsOnTime()

function endsOnTime(spring): boolean;

Whether a resolved spring ends at its duration: one set by duration, which starts from rest whatever velocity it's handed, as Motion's does, so it lands on time. Step it with stepTimed.

Parameters

spring

Resolved

Returns

boolean

init()

function init(options): State;

A spring at options.from (0 by default), moving at options.velocity (0 by default).

Parameters

options

SpringOptions

Returns

State

matrixFor()

function matrixFor(spring, dt): Exact;

A resolved spring's step matrix for dt: the one it kept when dt is the last one's, else worked out and kept. For a stepper written out in place; step is the one to call otherwise. The next dt overwrites it, so read it before stepping anything else on the spring.

Parameters

spring

Resolved

dt

number

Returns

Exact

restDeltaFor()

function restDeltaFor(
   spring, 
   distance, 
   scale?
): number;

restFor's delta alone, allocating nothing: for a run that keeps its keys' thresholds in arrays.

Parameters

spring

Resolved

distance

number

scale?

number = 1

Returns

number

restFor()

function restFor(
   spring, 
   distance, 
   scale?
): Rest;

A leg's rest thresholds, as Motion's are: each one the spring gives, else by how far the leg goes, distance, its target less its start. A spring on a progress of its own, 0 to 1, passes a distance of 1000 and that as scale, so its thresholds are read in Motion's units. Once a leg: at its start, and at each new target.

Parameters

spring

Resolved

distance

number

scale?

number = 1

Returns

Rest

Example

const rest = Spring.restFor(spring, target - from)

restSpeedFor()

function restSpeedFor(
   spring, 
   distance, 
   scale?
): number;

restFor's speed alone, allocating nothing.

Parameters

spring

Resolved

distance

number

scale?

number = 1

Returns

number

step()

function step(
   state, 
   dt, 
   target, 
   spring, 
   rest
): PhysicsStepResult<State>;

One frame of a resolved spring toward target: its next state, value, velocity, and whether it's done. Only the part of dt past its delay moves it, in one exact step; it settles within rest, landing exactly on target. Resolve its options with resolve, and its thresholds with restFor, once a leg.

function stepTimed(
   state, 
   dt, 
   target, 
   spring
): PhysicsStepResult<State>;

One frame of a spring that ends at its duration (endsOnTime) toward target: a step that doesn't rest early, landing exactly on target once its duration has run after its delay.