:wavy_dash: Spring

:books: Documentation | :tada: Example | :globe_with_meridians: Internet modules

• Framerate-independant spring physics
• Small, < 1kb gzipped
• Control the spring with tension and friction
• Adjustable timestep for the physics solver
• onStart / onStop callbacks
• This lib was made to learn more about fixed timesteps and integration.
  • It's a pretty basic Euler integration - not sure it will work for complex structures like spring chaining.
  • If you need a rock-solid spring physics library, use ReboundJS
• Articles used :
  • Fix Your Timestep!
  • Frame Rate Independent Damping using Lerp
  • Integration by Example - Euler vs Verlet vs Runge-Kutta

Requirements

• ES6 Modules support
  • Using a module bundler like Webpack, Rollup or Parcel
  • Native support from browser
  • From NodeJS with esm

API

• Spring
  • new Spring([options])
  • Methods
    • .setValue(newCurrent)
    • .setTarget(newTarget)
    • .setTension(tensionValue)
    • .setFriction(frictionValue)
    • .start()
    • .stop()
    • .update(dt)
    • .dispose()
  • Properties
    • .initial : number
    • .value : number
    • .previous : number
    • .velocity : number
    • .onStart : function
    • .onStop : function

new Spring([options])

Create a new Spring instance.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | {} | Spring options. | | [options.initial] | number | 0 | Initial value / targetValue of your spring. | | [options.tension] | number | 0.1 | Tension/Stifness of your spring. | | [options.friction] | number | 0.2 | From 0 to 1. Friction (Damping) of your spring. | | [options.step] | number | 10 | Timestep of the physics solver (in ms). Step > 16.67ms will give you pretty bad results. | | [options.onStart] | function | | onStart will be called when the spring starts moving. | | [options.onStop] | function | | onStop will be called when your the spring stops moving. | | [options.precisionStop] | number | 0.0001 | Minimum distance between value and target to consider the spring stopped. | | [options.perfectStop] | boolean | false | Define if value is set precisely to targetValue when the spring stops moving. |

Example

import { raf } from '@internet/raf'
import Spring from '@internet/spring'

const move = new Spring({ initial: 0 })
move.setTarget(300)
raf.add(dt => {
  move.update(dt)
  console.log(move.value)
})

spring.setValue(newCurrent)

Change the current position of the spring. Can retrigger onStart / onStop.

Kind: instance method of Spring
Category: Methods

| Param | Type | Description | | --- | --- | --- | | newCurrent | number | New current value. |

spring.setTarget(newTarget)

Update target / resting position of the spring. Can retrigger onStart / onStop.

Kind: instance method of Spring
Category: Methods

| Param | Type | Description | | --- | --- | --- | | newTarget | number | New target value. |

spring.setTension(tensionValue)

Update tension of the spring

Kind: instance method of Spring
Category: Methods

| Param | Type | Description | | --- | --- | --- | | tensionValue | number | New tension value. |

spring.setFriction(frictionValue)

Update friction of the spring

Kind: instance method of Spring
Category: Methods

| Param | Type | Description | | --- | --- | --- | | frictionValue | number | New friction value. |

spring.start()

Force re-start of the spring. Only needed if you force-stop the spring with stop()

Kind: instance method of Spring
Category: Methods

spring.stop()

Force-stop the spring.

Kind: instance method of Spring
Category: Methods

spring.update(dt)

Update the spring physic state

Kind: instance method of Spring
Category: Methods

| Param | Type | Description | | --- | --- | --- | | dt | number | Elapsed time since the last frame (in ms) |

spring.dispose()

Stop the spring and remove callbacks referenced in onStart and onStop.

Kind: instance method of Spring
Category: Methods

spring.initial : number

Initial position of the spring

Kind: instance property of Spring
Category: Properties

spring.value : number

Current position of the spring

Kind: instance property of Spring
Category: Properties

spring.previous : number

Previous frame position of the spring

Kind: instance property of Spring
Category: Properties

spring.velocity : number

Current velocity of the spring

Kind: instance property of Spring
Category: Properties

spring.onStart : function

Optional function called when the spring starts

Kind: instance property of Spring
Category: Properties

spring.onStop : function

Optional function called when the spring stops

Kind: instance property of Spring
Category: Properties