[lib] Universal Tween Engine

[Obli]

New major revision out: 5.0

Changelog:

+ [API BREAK] TweenGroup was completely rewritten for better ease of use!
+ TweenGroup now supports nested groups!
+ added .targetRelative(...) methods to Tween.java, with detailed documentation
+ added .targetCurrent(...) method to Tween.java, with detailed documentation
+ added .targetCurrentRelative(...) methods to Tween.java, with detailed documentation
+ added SimpleTweenable? interface, for tweenables with only 1 tween type
+ added Tween factories for SimpleTweenable? objects
+ added SimpleTweenable? implementations for primitives (TweenableInt?, TweenableFloat?, etc.)
+ added .addToManager() methods to Tween and TweenGroup
- removed .start() method from Tween. Adding it to a manager automatically starts it now
* updated demo
* improved performances with groups
! fixed loads of bugs

The main additions lies in the rewrite of TweenGroup, with the possibility to nest groups:

Code: Select all

TweenGroup.sequence(
    // First, set all objects to their initial positions
    TweenGroup.parallel(
        Tween.set(...),
        Tween.set(...),
        Tween.set(...)
    ),

    // Wait 1s
    TweenGroup.tempo(1000),

    // Move the objects around, one after the other
    Tween.to(...),
    Tween.to(...),
    Tween.to(...),

    // Then, move the objects around at the same time
    TweenGroup.parallel(
        Tween.to(...),
        Tween.to(...),
        Tween.to(...)
    )
).addToManager(manager);

Note that groups are pooled (if required).
Other important additions are the tween.targetRelative(...), tween.targetCurrent() and tween.targetCurrentRelative(...) methods.

Enjoy!

[tescott]

Great library, Obli. Thanks! I'm using this for some of my camera controls and it works out really nice!

--tim

[NateS]

Somewhat related, I just added some interpolation functions to libgdx:
http://code.google.com/p/libgdx/source/ ... ation.java
I see you have these in TweenEngine, but I prefer only passing a single value.

[daniel.weck]

Somewhat related, I just added some interpolation functions to libgdx:
http://code.google.com/p/libgdx/source/ ... ation.java
I see you have these in TweenEngine, but I prefer only passing a single value.

[NOTE: I have filed an issue on Google Code http://code.google.com/p/libgdx/issues/detail?id=516 ]

May I suggest that you use Robert Penner's easing equations (and associated terms)?
This would give developers more choice, and would lower the entry cost to the LibGDX animation code (because these named tweening formulas have become de-facto standards over time).

Have a look here:

https://github.com/jeremyckahn/shifty/b ... ormulas.js

Copied below for reference:

easeInQuad: function(pos){
return Math.pow(pos, 2);
},

easeOutQuad: function(pos){
return -(Math.pow((pos-1), 2) -1);
},

easeInOutQuad: function(pos){
if ((pos/=0.5) < 1) return 0.5*Math.pow(pos,2);
return -0.5 * ((pos-=2)*pos - 2);
},

easeInCubic: function(pos){
return Math.pow(pos, 3);
},

easeOutCubic: function(pos){
return (Math.pow((pos-1), 3) +1);
},

easeInOutCubic: function(pos){
if ((pos/=0.5) < 1) return 0.5*Math.pow(pos,3);
return 0.5 * (Math.pow((pos-2),3) + 2);
},

easeInQuart: function(pos){
return Math.pow(pos, 4);
},

easeOutQuart: function(pos){
return -(Math.pow((pos-1), 4) -1)
},

easeInOutQuart: function(pos){
if ((pos/=0.5) < 1) return 0.5*Math.pow(pos,4);
return -0.5 * ((pos-=2)*Math.pow(pos,3) - 2);
},

easeInQuint: function(pos){
return Math.pow(pos, 5);
},

easeOutQuint: function(pos){
return (Math.pow((pos-1), 5) +1);
},

easeInOutQuint: function(pos){
if ((pos/=0.5) < 1) return 0.5*Math.pow(pos,5);
return 0.5 * (Math.pow((pos-2),5) + 2);
},

easeInSine: function(pos){
return -Math.cos(pos * (Math.PI/2)) + 1;
},

easeOutSine: function(pos){
return Math.sin(pos * (Math.PI/2));
},

easeInOutSine: function(pos){
return (-.5 * (Math.cos(Math.PI*pos) -1));
},

easeInExpo: function(pos){
return (pos==0) ? 0 : Math.pow(2, 10 * (pos - 1));
},

easeOutExpo: function(pos){
return (pos==1) ? 1 : -Math.pow(2, -10 * pos) + 1;
},

easeInOutExpo: function(pos){
if(pos==0) return 0;
if(pos==1) return 1;
if((pos/=0.5) < 1) return 0.5 * Math.pow(2,10 * (pos-1));
return 0.5 * (-Math.pow(2, -10 * --pos) + 2);
},

easeInCirc: function(pos){
return -(Math.sqrt(1 - (pos*pos)) - 1);
},

easeOutCirc: function(pos){
return Math.sqrt(1 - Math.pow((pos-1), 2))
},

easeInOutCirc: function(pos){
if((pos/=0.5) < 1) return -0.5 * (Math.sqrt(1 - pos*pos) - 1);
return 0.5 * (Math.sqrt(1 - (pos-=2)*pos) + 1);
},

easeOutBounce: function(pos){
if ((pos) < (1/2.75)) {
return (7.5625*pos*pos);
} else if (pos < (2/2.75)) {
return (7.5625*(pos-=(1.5/2.75))*pos + .75);
} else if (pos < (2.5/2.75)) {
return (7.5625*(pos-=(2.25/2.75))*pos + .9375);
} else {
return (7.5625*(pos-=(2.625/2.75))*pos + .984375);
}
},

easeInBack: function(pos){
var s = 1.70158;
return (pos)*pos*((s+1)*pos - s);
},

easeOutBack: function(pos){
var s = 1.70158;
return (pos=pos-1)*pos*((s+1)*pos + s) + 1;
},

easeInOutBack: function(pos){
var s = 1.70158;
if((pos/=0.5) < 1) return 0.5*(pos*pos*(((s*=(1.525))+1)*pos -s));
return 0.5*((pos-=2)*pos*(((s*=(1.525))+1)*pos +s) +2);
},

elastic: function(pos) {
return -1 * Math.pow(4,-8*pos) * Math.sin((pos*6-1)*(2*Math.PI)/2) + 1;
},

swingFromTo: function(pos) {
var s = 1.70158;
return ((pos/=0.5) < 1) ? 0.5*(pos*pos*(((s*=(1.525))+1)*pos - s)) :
0.5*((pos-=2)*pos*(((s*=(1.525))+1)*pos + s) + 2);
},

swingFrom: function(pos) {
var s = 1.70158;
return pos*pos*((s+1)*pos - s);
},

swingTo: function(pos) {
var s = 1.70158;
return (pos-=1)*pos*((s+1)*pos + s) + 1;
},

bounce: function(pos) {
if (pos < (1/2.75)) {
return (7.5625*pos*pos);
} else if (pos < (2/2.75)) {
return (7.5625*(pos-=(1.5/2.75))*pos + .75);
} else if (pos < (2.5/2.75)) {
return (7.5625*(pos-=(2.25/2.75))*pos + .9375);
} else {
return (7.5625*(pos-=(2.625/2.75))*pos + .984375);
}
},

bouncePast: function(pos) {
if (pos < (1/2.75)) {
return (7.5625*pos*pos);
} else if (pos < (2/2.75)) {
return 2 - (7.5625*(pos-=(1.5/2.75))*pos + .75);
} else if (pos < (2.5/2.75)) {
return 2 - (7.5625*(pos-=(2.25/2.75))*pos + .9375);
} else {
return 2 - (7.5625*(pos-=(2.625/2.75))*pos + .984375);
}
},

easeFromTo: function(pos) {
if ((pos/=0.5) < 1) return 0.5*Math.pow(pos,4);
return -0.5 * ((pos-=2)*Math.pow(pos,3) - 2);
},

easeFrom: function(pos) {
return Math.pow(pos,4);
},

easeTo: function(pos) {
return Math.pow(pos,0.25);
}

[daniel.weck]

I see that the bug regarding LibGDX's easing equations has been closed.

http://code.google.com/p/libgdx/issues/detail?id=516

Here's what I think should be considered (Obli, what is your view on this?):

Please re-open this bug report and consider aligning with the Rob Penner equations.

Below is a summary of LibGDX's equations, followed by the classic Robert Penner equation categories, followed by what I think LibGDX should implement in order to be in harmony with other animation frameworks:

----------
LibGDX:

linear
fade
sine
sineIn
sineOut
exp
expIn
expOut
circle
circleIn
circleOut
elastic
elasticIn
elasticOut
back
backIn
backOut
bounce
bounceIn
bounceOut
Pow2/3/4/5
PowIn2/3/4/5
PowOut2/3/4/5

----------
Robert Penner main easing categories:

Linear
Quadratic
Cubic
Quartic
Quintic
Sinusoidal
Exponential
Circular
Elastic
Back
Bounce

----------
Desired equations:

easeInQuad
easeOutQuad
easeInOutQuad
easeInCubic
easeOutCubic
easeInOutCubic
easeInQuart
easeOutQuart
easeInOutQuart
easeInQuint
easeOutQuint
easeInOutQuint
easeInSine
easeOutSine
easeInOutSine
easeInExpo
easeOutExpo
easeInOutExpo
easeInCirc
easeOutCirc
easeInOutCirc
easeOutBounce
easeInBack
easeOutBack
easeInOutBack
elastic
swingFromTo
swingFrom
swingTo
bounce
bouncePast
easeFromTo
easeFrom
easeTo

[Obli]

Sorry for late answer, I'm still in a 2 week holiday (also explaining my lack of participation)

Indeed, Robert Penner equations seem to have become a somewhat standard, like the concept of "Tweens" instead of "Motion" or "Interpolation". However, this standard is only interesting for people who are a little bit familiar with animations. The others won't care at all, and may even miss the point since the word "Tween" won't tell them anything. I had many mails from people using the univ tween engine, from Kindle developers to java Swing ones, but I also know that these people came from the web world, where "tweens" are very common. The others just missed the engine, because of the use of the word "tween" in the name.

Therefore, I would vote for your solution David, but I think that most people won't care (and that's sad ). Even JQuery doesn't use anything from the tween world...

[Netzweh]

Awesome lib! Switched today from my own not so perfect formulas to your tween engine and got really smooth camera movement. Great

There's just one thing bothering me. I'd like to have the possibility to update tween manager with delta times. At the moment I must kill tweens when pausing the game and creating new ones with the time left for the current turn when resuming game. Or is there another solution?

[NateS]

May I suggest that you use Robert Penner's easing equations (and associated terms)?
This would give developers more choice, and would lower the entry cost to the LibGDX animation code (because these named tweening formulas have become de-facto standards over time).

I don't think anything is gained by copying Penner's easing function names. I chose names I though were clear. Also, his functions are certainly not all-inclusive. You even removed "fade" from your desired list! This is a very nice easing function from Perlin noise.

[MattWay]

Awesome lib! Switched today from my own not so perfect formulas to your tween engine and got really smooth camera movement. Great

There's just one thing bothering me. I'd like to have the possibility to update tween manager with delta times. At the moment I must kill tweens when pausing the game and creating new ones with the time left for the current turn when resuming game. Or is there another solution?

A tween manager that updated with delta time would be really handy.

[Obli]

Hello guys!
Sorry about the delay, work is overwhelming me these days and I have very little spare time available.

I heard your requests (don"t hesitate to use the bug tracker of the project), and I'll add the possibility to use delta times as soon as possible.