Tweeno.js

A super simple, fast and easy to use tweening engine which incorporates optimized Robert Penner's equations.

Tweeno was originally created by refactoring Tween.js

Why I refactored Tween.js

Overview

Tweeno is a simple tweening engine designed to be used in html5 game development.

Library objects

• Queue manages an array of tween objects updating them every update loop.
• Tween handles the change of a target object's numeric property values over a span of time.
• Filter assists in tweening numeric values within strings. For example rgba(10,20,30,1).
• Easing equations for easing
• Interpolation equations for interpolation

Example Usage

    /** nodejs / browserify **/
    var Tween = require('tweeno').Tween,
        Queue = require('tweeno').Queue,
        Easing = require('tweeno').Easing;

    /** browser **/
    var Tween = Tweeno.Tween,
        Queue = Tweeno.Queue,
        Easing = Tweeno.Easing;

    // creating a div to tween
    var targetDiv = document.createElement('div');
        targetDiv.style.cssText = 'position: absolute; left: 50px; top: 300px; font-size: 50px';
        document.body.appendChild(targetDiv);

    // target object with internal state to be tweened
    var target = {
        x: 0,
        y: 0,
        div: targetDiv,
        // updates the div object state every update loop
        update: function(){
            var innerHTML = '',
            innerHTML += 'x: ' + Math.round(this.x);

            this.div.innerHTML = innerHTML;
            this.div.style.left = this.x + 'px';
        }
    };

    // tween settings
    var settings = {
        // set when starting tween
        from: {
            x: 50,
            y: 0
        },
        // state to tween to
        to: {
            x: 400,
            y: 20
        },
        // 2 seconds
        duration: 2000,
        // repeat 2 times
        repeat: 2,
        // do it smoothly
        easing: Easing.Elastic.InOut,
    };

    var queue = new Queue(),
        tween = new Tween(target, settings);

    // add the tween to the queue
    queue.add(tween);

    // start the queue
    queue.start();

    // update loop
    var animate = function() {
        requestAnimationFrame(animate);
        // update the queued tweens
        queue.update();
        // update the target object state
        target.update();
    };

    // start the update loop
    animate();

Installation

Note: Tweeno has no dependencies

Nodejs / Browserify

$ npm install tweeno --save

var Tweeno        = require('tweeno'),
    Queue         = Tweeno.Queue,
    Tween         = Tweeno.Tween,
    Filter        = Tweeno.Filter,
    Easing        = Tweeno.Easing,
    Interpolation = Tweeno.Interpolation;

Browser

var Queue         = Tweeno.Queue,
    Tween         = Tweeno.Tween,
    Filter        = Tweeno.Filter,
    Easing        = Tweeno.Easing,
    Interpolation = Tweeno.Interpolation;

Documentation

Tween

Tween objects manage the state of a target object over a span of time.

Tween(target, settings)

• target object to tween the state of.

// example
  var target = {
      x: 0,
      y: 0,
      width: 10,
      height: 10
  };

• settings (optional) contains tween settings.

    // example
  var settings = {
      from: {
          x: 10,
          y: 10
      },
      to: {
          x: 100,
          y: 10
      },
      delay: 10,
      duration: 500,
      repeatDelay: 15,
      repeat: 4,

      yoyo: true,

      easing: Tweeno.Easing.Elastic.InOut,
      interpolation: Tweeno.Interpolation.Linear,

      chained: [], // array of tweens to be started when this tween is completed

      onStart:        false, // or: function(target, tween, easedProgress){},
      onYoYo:         false, // or: function(target, tween, easedProgress){},
      onRepeat:       false, // or: function(target, tween, easedProgress){},
      onUpdate:       false, // or: function(target, tween, easedProgress){},
      onComplete:     false, // or: function(target, tween, easedProgress){},
      filters:        false, // or: function(target, tween, easedProgress){},
  };

var tween = new Tweeno.Tween(target, settings);

Settings Param

Name | Type | Default | Description ---------------|------------|--------------------------------|----------------------------------------------- from | Object | {} | Starting state applied to the target when the tween starts (when tween.start() is called) to | Object | {} | Ending target state to be tweened to delay | Number | 0 | Delay in milliseconds (when repeat is set, only the first cycle is affected) duration | Number | 1000 | Tween duration in milliseconds repeatDelay | Number | 0 | Delay in milliseconds (when repeat is set, every cycle after the first is affected) repeat | Number | false | Number of times to repeat the tween yoyo | Bool | false | Reverses the tween every other repeat cycle starting with the second cylce (requires repeat to be set) easing | Function | Tweeno.Easing.None | Easing function, available in Tweeno.Easing (see list below) interpolation | Function | Tweeno.Interpolation.Linear | Interpolation function, available in Tween.Interpolation. (see list below) onStart | Function | false | Callback when started onUpdate | Function | false | Callback when updated onRepeat | Function | false | Callback when repeated (end of tween) onYoYo | Function | false | Callback when tween reversed (end of tween, every other repeat cycle) onComplete | Function | false | Callback when completed filters | Object | false | list of Tweeno.Filter objects indexed by the target object property name they are applied to (see more about filters below) chained | Array | false | list of Tween objects to add to the Queue object containing this Tween, when this Tween is complete.

Callback Parameters

All callback functions are given the same paramaters. onStart, onUpdate, onRepeat, onYoYo, onComplete

Name | Type | Description ---------------|------------|----------------- target | Object | The target object of the tween calling the function tween | Object | The Tweeno.Tween object calling the function easedProgress | Number | Number between 0 and 1 showing current progress of the tween (easing function is already applied) progress | Number | Number between 0 and 1 showing current progress of the tween

var settings = {
    onUpdate: function(target, tween, easedProgress, progress){
        // onUpdate callback code
    }
}

Tween Settings After Creation

Any of the properties on the settings object can also be assigned or accessed directly on the tween object. They can be safely modified at any time before start() is called.

var target = {
    x: 0
};

var settings = {
    to: {
        x: 10
    },
    repeat: 5
};

var tween = new Tweeno.Tween(target, settings);

// set or access any settings properties directly on the tween object before start() is called
tween.duration = 500;
tween.repeat = false;
// start the tween
tween.start();

---

Tween.start(startTime)

Sets the startTime and prepares the Tween to begin.

• startTime (optional) a timestamp to be used as the Tween startTime.

Returns: Tween object instance.

var tween = new Tweeno.Tween(target, settings);
    tween.start();

When Tween.start() is Called:

• The tween startTime is set automatically if none was specified.
• The from object properties are applied to the target.

---

Tween.update(currentTime)

Updates the state of the Tween's target. The currentTime is compared to the startTime to determine the progress of the Tween. Tween.update() should be called every requestAnimationFrame() update loop. It is typically called by the Queue object containing the Tween via queue.update().

• currentTime (optional) a timestamp to be used as the tween start time.

Returns: true if the Tween has not completed, false if it has.

var tween = new Tweeno.Tween(target, settings);
tween.update();

When Tween.update() is Called:

• The onStart callback is called ( if not already called ).
• The onUpdate callback is called.
• The onRepeat callback is called ( if the end of the tween has been reached and the tween is set to repeat ).
• The onYoYo callback is called ( if the end of the tween has been reached and the tween is set to repeat and yoyo).
• The onComplete callback is called ( if the end of the tween has been reached ).

---

Tween.getDuration()

Returns: The total duration of the tween [ ( delay + duration) * repeat ]

    var tween = new Tweeno.Tween(target, settings);
    var duration = tween.getDuration();

Queue

A Queue object manages an array of Tweens. The Queu