typed-loop

A loop class to enable flexible intervals for visual experiments and games. It provides delta time in various formats and uses requestAnimationFrame for the timeouts. It's possible to use setTimeout with given targetDeltaTime.

How to use

Install by issuing npm i typed-loop.

This module exports a Loop class, DeltaTimeFormat enum and LoopParameters interface.

import { Loop } from 'typed-loop';

const loop = new Loop({
  onTick(deltaTime) {
    console.log(deltaTime)
  }
});

API

interface LoopParameters

| Name | Required? | Type | Default value | Description | |-------------------|-----------|-----------------------------------------|----------------|-----------------------------------------------------------| | onTick | Yes | (deltaTime: number) => any | undefined | callback function to be called on every tick of the loop | | deltaTimeFormat | No | 'relative' | 'milliseconds' | 'seconds' | 'milliseconds' | how the delta time should be formatted | | deltaTimeLimit | No | number | undefined | undefined | maximum delta time in milliseconds | | startWithoutDelay | No | boolean | false | should the callback be called immediately | | targetTimeout | No | number | undefined | undefined | target timeout, tick on every frame not guaranteed if set |

class Loop(config: LoopParameters)

import { Loop, LoopParameters, DeltaTimeFormat } from 'typed-loop';

const conf: LoopParameters = {
  onTick: (deltaTime) => {
    console.log(`Last tick happened ${deltaTime} seconds ago`);
  },
  startWithoutDelay: true,
  deltaTimeFormat: DeltaTimeFormat.SECONDS
};

const loop = new Loop(config).start();

// --> Last tick happened 0.017 seconds ago
// --> Last tick happened 0.016 seconds ago

setTimeout(() => {
  loop.stop();
}, 36);

Methods

#start(): self

Starts the loop.

#stop(): void

Stops the loop.

Additional info

requestAnimationFrame vs setTimeout

requestAnimationFrame schedules a function to be called right before the next screen repaint. Most commonly the repaint occurs every 16ms resulting 60 frames / second (FPS). setTimeout schedules function to be called after given milliseconds, however, it seems that the delay is always at least around 4ms even with timeout of 0.

Due to this all loops that animate visible entities will benefit using requestAnimationFrame as excess repaints (high FPS) between screen repaints will not be visible to the users and skipped screen repaints (low FPS) result in jumps and lag.

Why delta time?

Screen refresh rate is not same for all devices and furthermore the refresh rate varies a bit, typically around +-5ms based on load of the machine among other factors.

When animating movement on sceen (e.g. games and animations) the previously mentioned inaccuracy of FPS causes visible jumping and lagging. This can be mitigated by applying the actual duration of previous frame time when calculating new position for the animated elements.

Example - laggy

Without compensating the variance of FPS.

let x = 0;

function loop() {
  x += 5;
  repaint(x); // Arbitrary function to repaint to updated position
  requestAnimationFrame(loop);
}

Example - less laggy

Applying FPS variance compensation with delta time.

let x = 0;

new Loop({
  deltaTimeFormat: DeltaTimeFormat.RELATIVE,
  onTick(deltaTime => {
    x += 5 * deltaTime;
    repaint(x); // Arbitrary function to repaint to updated position
  })
}).start();

How to contribute

Open issue or make a PR if it's a simple patch or quick feature.