tina

    0.3.23 • Public • Published

    TINA

    Tweening and INterpolations for Animation

    Install with NPM

    A comprehensive, high performance, easy to use, open source animation library in JavaScript.

    • Easy to use (API strongly inspired by Tween.js)
    • High performance (Competitive with Tweenjs and GSAP, benchmark coming soon)
    • High flexibility (tween transitions can easily be modified after creation)
    • High customizability (possibility to use custom easings, interpolations and components)
    • Play options (delay, iterations, pingpong, persist and speed)
    • Open source and MIT License (use it as you please)
    • A consequent library of easing and interpolation methods
    • A variety of components such as Timeline, Sequence and Recorder (CSSTween coming soon)
    • Good synchronisation between tweens
    • Relative tweening enables the possibility to apply several simultaneous tweens on a single property
    • Nested object tweening enables the possibility to alter nested objects using a single tween
    • Compatible with Node.js!
    • Bonus: Creation and removal of tweens within the callback of another tween will not result in any unwanted side effect (infamous bug of other tweening libraries)

    Note: Do not hesitate to contribute by reporting issues or by submitting your own components and interpolations.

    Warning: Still in beta version! Do not be shy, report issues

    How to use

    In a browser

    Include TINA's build in your html using either the minified library or the unminified version.

    <script src="tina.min.js"></script>

    In Node.js

    Install TINA using npm install tina, then require it:

    var TINA = require('tina');

    JSFiddle examples

    API

    Existing playable components are: Tween, NestedTween, Timeline, Sequence, Delay, Timer, Ticker, Recorder (CSSTween coming soon). The following is a non-exhaustive list of possibilities offered by TINA.

    Tween

    To create and start a tween (it will be automatically updated):

    var myObject = { x: 0 };
    var properties = ['x'];
    var duration = 500; // in milliseconds
    var myTween = new TINA.Tween(myObject, properties)
        .to({ x: 1 }, duration)
        .start();

    To create and start a tween without affecting it to a variable:

    TINA.Tween(myObject, ['x'])
        .to({ x: 1 }, duration)
        .start();

    To tween an array:

    var myArray = [0, 1, 0];
    var myTween = new TINA.Tween(myArray)
        .to([0, 2, 1], duration)
        .start();

    To tween several properties:

    var myTween = new TINA.Tween(myObject, ['x', 'y'])
        .to({ x: 1, y: 0 }, duration)
        .start();

    To chain several transitions:

    var myTween = new TINA.Tween(myObject, ['x'])
        .to({ x: 1 }, duration1)
        .to({ x: 2 }, duration2)
        .start();

    To ease the tweening:

    var myObject = { x: 0 };
    var easingParameter = 2;
     
    var myTween = new TINA.Tween(myObject, ['x'])
        .to({ x: 1 }, duration, 'elasticInOut', easingParameter)
        .start();
    // or
    var myTween = new TINA.Tween(myObject, ['x'])
        .to({ x: 1 }, duration, TINA.easing.elasticInOut, easingParameter)
        .start();

    To use interpolation functions:

    var myObject = { abc: 'Hello' };
     
    var myTween = new TINA.Tween(myObject, ['abc'])
        .interpolations({ abc: 'string' })
        .to({ abc: 'World' }, duration)
        .start();
    // or
    var myTween = new TINA.Tween(myObject, ['abc'])
        .interpolations({ abc: TINA.interpolation.string })
        .to({ abc: 'World' }, duration)
        .start();

    To start tweening after a given delay:

    var myTween = new TINA.Tween(myObject, ['x'])
        .to({ x: 1 }, duration)
        .delay(1000);

    To add callbacks on specific events:

    var myTween = new TINA.Tween(myObject, ['x'])
        .to({ x: 1 }, duration)
        .onStart(function () {
            console.log('Tweening will now start');
        })
        .onUpdate(function (time, dt) {
            console.log('My object at time', time, 'is', myObject);
        })
        .onComplete(function () {
            console.log('Tweening is complete');
        })
        .delay(1000);

    NestedTween

    Nested tweens give the ability to tween nested objects using a single tween. A nested tween allows to interpolate between nested objects. To tween a nested tween:

    var nestedObject = {
        position: { x: 0, y: 0 },
        alpha: 0
    }
     
    var myNestedTween = new TINA.NestedTween(nestedObject, ['position.x', 'position.y', 'alpha'])
    .to({
        position: { x: 10, y: 20 },
        alpha: 1
    }, 500)
    .start();

    Note: the NestedTween API remains identical to Tween and all the functionalities of Tween are available to the NestedTween component.

    Timeline

    Timelines are used to play tweens in parallel. To create a timeline:

    var timePosTweenA = 0;
    var timePosTweenB = 2000;
    var myTimeline = new TINA.Timeline()
        .add(myTweenA, timePosTweenA)
        .add(myTweenB, timePosTweenB)
        .start();

    Sequence

    Sequences are used to chain tweens. To create a sequence:

    // 1 second delay between the end of myTweenB and the start of myTweenC
    var mySequence = new TINA.Sequence()
        .add(myTweenA)
        .add(myTweenB)
        .addDelay(1000)
        .add(myTweenC)
        .start();

    Delay

    To create a delay:

    var myDelay = new TINA.Delay(duration);

    Delays can be used as a setTimeout that would be synchronised with all the other tweens. It can also be used to apply some treatment to objects for a given duration. For example, moving a particle for a fixed duration and then destroy it:

    var particleSpeedX = 5;
    var particleSpeedY = 0;
    var myParticle = new Particle();
    Delay(duration)
        .onUpdate(function (time, dt) {
            myParticle.x += particleSpeedX * dt;
            myParticle.y += particleSpeedY * dt;
     
            particleSpeedX *= Math.pow(0.95, dt);
            particleSpeedY += gravity * dt;
        })
        .onComplete(function () {
            myParticle.destroy()
        })
        .start();

    Tweener

    A tweener is responsible for tweening playable components. The tweener can be either a timer or a ticker.

    If no tweener is specified, any started playable will be tweened by the default tweener.

    // myTween will be tweened by the default tweener
    var myTween = new TINA.Tween(myObject, ['x'])
        .to({ x: 5 }, 1000)
        .start();

    To manually specify a tweener for a playable component:

    // myTween will be tweened by myTweener
    var myTween = new TINA.Tween(myObject, ['x'])
        .to({ x: 5 }, 1000)
        .tweener(myTweener)
        .start();

    To specify the default tweener for every tween:

    // I choose a timer as my default tweener
    var myTimer = new TINA.Timer().useAsDefault();
    // myTween will be attached to myTimer
    var myTween = new TINA.Tween(myObject, ['x'])
        .to({ x: 5 }, 1000)
        .start();

    Timer

    At every update its internal time is increased by a fixed proportion of the time elapsed since the previous update. To create a default timer that will update automatically:

    var myTimer = new TINA.Timer().useAsDefault().start();

    To create a timer and update it manually:

    var myTimer = new TINA.Timer().useAsDefault();
    TINA.add(myTimer);
     
    function update() {
        TINA.update();
        requestAnimationFrame(update);
    }
     
    requestAnimationFrame(update);

    It is possible to specify the speed at which time will elapse for the timer. This flexbility allows the user to use units that he is comfortable with. It could be 1 unit per second, 24 ups, 60 ups or 1000 ups (or even 237.6 ups if you come from another planet).

    By default the timer goes at a speed of 1000 units per second (milliseconds). Every second, the time will increase by the given tups:

    var tups = 60; // Time units per second
    var myTimer = new TINA.Timer(tups);

    Effect of different values for the tups:

    var myTimer1 = new TINA.Timer(1);
    var myTimer60 = new TINA.Timer(60);
    var myTimer1000 = new TINA.Timer(1000);
     
    // The following will tween myObject in 100 seconds
    TINA.Tween(myObject, ['x']).to({ x: 1 }, 100).tweener(myTimer1);
     
    // The following will tween myObject in 1.667 seconds
    TINA.Tween(myObject, ['x']).to({ x: 1 }, 100).tweener(myTimer60);
     
    // The following will tween myObject in 0.1 seconds
    TINA.Tween(myObject, ['x']).to({ x: 1 }, 100).tweener(myTimer1000);

    Ticker

    At every update its internal time is increased by a fixed amount.

    To create a ticker with automatic updates:

    var myTicker = new TINA.Ticker().useAsDefault().start();

    To create a ticker and update it manually:

    var myTicker = new TINA.Ticker().useAsDefault();
    TINA.add(myTicker);
     
    function update() {
        TINA.update();
        requestAnimationFrame(update);
    }
     
    requestAnimationFrame(update);

    By default the ticker goes at a speed of 1 unit per update. But similarly to a timer it is possible to specify how fast the time goes for a ticker. At every update the time will increase by the given tupt:

    var tupt = 2; // Time units per tick/update
    var myTicker = new TINA.Ticker(tupt);

    Effect of different values for the tupt:

    var myTicker1 = new TINA.Ticker(1);
    var myTicker10 = new TINA.Ticker(10);
    var myTicker20 = new TINA.Ticker(20);
     
    // The following will tween myObject in 100 updates
    TINA.Tween(myObject, ['x']).to({ x: 1 }, 100).tweener(myTicker1);
     
    // The following will tween myObject in 10 updates
    TINA.Tween(myObject, ['x']).to({ x: 1 }, 100).tweener(myTicker10);
     
    // The following will tween myObject in 5 updates
    TINA.Tween(myObject, ['x']).to({ x: 1 }, 100).tweener(myTicker20);

    TINA's update callback

    In the case when tweeners automatically update, TINA can be used as the main loop of the application.

    // t is the total time elapsed since TINA started
    // dt is the time elapsed since TINA's previous update
    // both durations are in milliseconds
    TINA.onUpdate(function (t, dt) {
        // At this point,
        // all my tweens are up to date
        // for the current iteration
        myGameLogic.update(t, dt);
        myPhysics.update(dt);
        myRenderer.update();
        ...
    });

    Made in Wizcorp.

    Install

    npm i tina

    DownloadsWeekly Downloads

    143

    Version

    0.3.23

    License

    MIT

    Last publish

    Collaborators

    • notawizard
    • almirkadric
    • stelcheck
    • cstoquer
    • bchevalier
    • cainm