TINA

Tweening and INterpolations for Animation

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.

jrouault / tina.js Goto Github PK

tina.js's Introduction