tickloop
v0.5.0
Published
Simple and performant wrapper around Request AnimationFrame
Downloads
190
Readme
tickloop
Simple and performant animation frame handler. The API and implementation were inspired by the GreenSock Animation Platform (GSAP) library.
Installation & Setup
tickloop
is available on npm and can be installed with your favorite package manager:
$ yarn add tickloop
# or
$ npm i tickloop
Then import the creator from the package in your code:
import { createTicker } from 'tickloop'
const ticker = createTicker()
Usage
Configuring
The createTicker
function accepts a configuration object with the following properties:
fps
: The target frames per second (fps). The ticker will make its best effort to reach this framerate. Note that you are effectively capped to 60 because the browser's ownrequestAnimationFrame
will not fire above this rate.lagThreshold
: The number of milliseconds the ticker should consider "lag". If the elapsed time between two ticks exceeds this value, the ticker will apply a lag ease. See Lag Easing below.adjustedLag
: The number of milliseconds the ticker should advance by when easing a lag spike. When a lag spike occurs, the ticker will advance time by this amount. See Lag Easing below.stopped
: Whether this ticker should notstart()
itself immediately.
Lag Easing
This effect is borrowed from GSAP. Should the ticker
encounter a lag spike, instead of advancing that time all at once
or skipping it entirely, it advances time by a fixed easing amount.
By default, the lagThreshold
is set to 500ms
and the adjustedLag
is set to 33ms
. This means that if the ticker
observes that the elapsed time between two ticks exceeds 500ms
, it will advance time by only 33ms
.
Setting lagThreshold
to 0
disables this feature.
Working with Tick Callbacks
Add a tick callback that you wish to execute every frame with the add
method:
ticker.add((time, delta, frame) => {
// ...
})
The callback receives, as arguments:
time
: The current time in millisecondsdelta
: The milliseconds since the previous tickframe
: The number of frames that have passed
Remove a tick callback with the remove
method:
const callback = (time, delta, frame) => {
// ...
}
ticker.add(callback)
// later
ticker.remove(callback)
If you only want to hook into one frame, as opposed to every frame, you can send your callback to the once
method:
ticker.once((time, delta, frame) => {
// ...
})
Getting General Information
The ticker itself makes the same time
, delta
, and frame
information sent to callbacks available on the instance. Additionally, it exposes a deltaRatio
which is the ratio of the current delta
value to the expected delta value of the target fps
:
// the time in milliseconds this ticker has been running
ticker.time
// the time in milliseconds since the last frame this ticker observed
ticker.delta
// the ratio between the current delta and the expected delta for the target frame rate
ticker.deltaRatio
// the number of frames that have passed
ticker.frames