〰️ Spring

📚 Documentation | 🎉 Example | 🌐 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'importSpringfrom'@internet/spring'constmove=newSpring({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

---