Tweening

tween module

The tween module is a SubSystem of suki that allows you to animate properties of objects over time. AKA animation! 🎉

Usage

import { manager, Tween, TweenData  } from "@roryduncan/suki";

Quick Overview

You can instantiate the Tween class without having to use the manager export. Tween instances have an internal reference to the TweenManager.

What this means is that you probably only ever need to import Tween.

Exports

The suki module has three exports:

• manager

  An instance of the TweenManager class. TweenManager class is not exported, as it's intentionally instantiated and exported to prevent confusion and duplication.

• Tween

  The primary export of this module — instantiate a tween when you're preparing to animate something. More details below.

• TweenData

  The internal data model of a tween. Probably shouldn't be used unless you know what you're doing.

Tween Class

Primer

Tweens are collections of 'actions', where each action is a transition of values over time. It's easiest to think of actions as a set of tweens, and tween as the wrapper for it. Architecturally, allowing multiple actions per tweens is more robust for tweens that do more than one thing, restarting / looping tweens, and chaining multiple actions under a single tween.

Tween class extends an event emitter.

Events

• action-complete

  Emitted when a single action is completed. There may still be further actions.

• complete

  Emitted when all actions are completed, and the tween is no longer executing.

API

Assume all the following methods are instantiated, like so:

let tween = new Tween();

Tween.from(Object context)

The context parameter object is an object that will be mutated during the tween.

let start = { x: 0 };
tween.from(start);

Tween.to(Object target [, int duration, string easingFunction, int startingTime])

Optional parameter defaults:

• duration: 1
• easingFunction: "inOutQuad"
• startingTime: 0

Note: duration and startingTime are in seconds.

target is an object that is diffed from the object provided in .from(). Any keys in target that are in context (see .from(Object context) parameter) will be compared and possibly tweened.

You can call .to() multiple times with different targets to chain tweens.

let end = { x: 100, };
tween.to(end, 2, "linear");

Tween.start()

Starts tweening. If either .to() or .from() haven't been called yet, will do nothing and return false;

Subsequent calls to .start() will reset the animation—the equivalent of calling .reset().

Tween.stop()

Pauses the animation.

Tween.resume()

Continues a Paused animation.

Tween.clear()

Immediately stops animating and clears all TweenData attached to a tween. Does note emit a "complete" event.

Tween.remove()

Removes the tween from the tween manager. Warning: Not calling .remove() may cause memory leaks.

Code Example

You may also view the Using Tweens Example for further reference.

let tween = new Tween();


let thing = { x: 0, y: 100 };
tween.from(thing);

// we will tween the x property from 0 to 100.
tween.to({ x: 100 }, 2, "linear");

// start animating
tween.start();

tween.on("complete", () => {
  alert("The tween finished!");
});