[lib] Universal Tween Engine

[Obli]

Hello,

I made a generic interpolation framework for java projects. This framework enables you to move, rotate, scale, etc. anything in your project using easing functions, enabling nice eye-candy effects. It's like the Actions for Actors in libGDX, but in a more generic way.

Changelogs

5.2
+ made tween objects use delta times instead of system time. You should now have a more precise control over tweens.
+ added speed control! You can now use slow-motion/fast-motion and even make a complete animation sequence go backwards! Enjoy
+ added Tween.mark() to static factories: lets you easily place beacons for callbacks in your sequences.
+ added some “ensureCapacity()” methods for every static object used, like pools.
* reduced the memory footprint of each tween object
* updated the demos (Swing demo should be more fun)

5.0
+ [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

For any additional information, please refer to the project main page (since duplicating the explanations here and there is too time-consuming).
Thank you.

Link to the framework project page (with tutorial, source code, and a JAR of the library):
http://code.google.com/p/java-universal-tween-engine/

Link to an executable test of the framework:
http://code.google.com/p/java-universal ... loads/list

[mzechner]

Wow, that's pretty nifty. A separate API for tweening that is more generic is a definitive plus. What would you say, should we include that in libgdx? Or maybe as an extension? Good job in any case

[kiro]

I just fell in love with you.

Reminds me of TweenMax, which I rely on heavily for all my Flash work. Thank you so much!

[Luapo]

Wow, fantastic work Obli.

Can't wait to get on some UI stuff now!

[caniep]

great Obli! thanks!

[Obli]

@mzechner: it's totally up to you. I will provide any support and updates needed for this API, but only include it if you think it's worth it. Of course, if you do, don't hesitate to change all the package names to something more Gdx friendly. The lib is generic enough to be used in any Java project, but I made it with a libGDX use in mind.

@kiro: actually I think it's based on the TweenMax approach. I built this API some years ago so I can't tell if it was TweenMax or anything, but the name does say something to me. What I added to their approach is the Tweenable interface, since flash Tweens are only available on MovieClip properties (at least when I used it), and the tween pool (to better fit android performance needs).

[NateS]

Sounds cool! Had an exception running the example though:
http://pastebin.com/AKAM2Wj0

Peeked at the source. Some random notes:

• You might want to avoid the enhanced for loop syntax with most JDK collections, as it allocates an iterator. If you use libgdx's Array class, it reuses the iterator (but watch out for nested loops!).
• You could use libgdx's Pool class for object pooling, then you don't have to loop through all objects to find a free one, don't need isFree, don't have to grow your pool, etc.
• runningTweens could be an Array with the ordered constructor param set to false. This avoids a memory copy when removing objects.
• Why have a completedTweens list? If to avoid ConcurrentModificationException, you can have update return a boolean where true == remove from runningTweens and invoke completed callback. Then kill can just set endTimeMillis to zero.
• You could use Gdx.graphics.getDeltaTime() rather than currentTimeMillis, but I guess it's not a big deal.
• The use of "CUSTOM_*" placeholder values makes me wonder if a TweenTypes enum makes sense. Maybe use int instead, and people manage their own constants?
• If currentTimeMillis > endTimeMillis the first time a Tween is updated, the startValue from the previous tweening will be used.
• Tween objects get reused, but isStarted is never set to false. Maybe smoke isStarted and just set the startValue in set "set" method.
• Tweenable javadoc typo: Tweenbale
• libgdx typically drops the "on" for event methods, eg mouseMove, resized, etc. onTweenUpdated would be tweenUpdated or maybe updateTween.
• Damn, I may have run out of things. Erm, I would probably name updateAll to just update.
• "to" could return the Tween, allowing it to be stopped.
• What do you think of something like this to reduce the number of args for some cases?
  

  Code: Select all

  Tween.to(obj, X, Elastic.OUT, 100, 1500);
Tween.to(obj, X, Elastic.OUT, 100, 1500).delay(1000);
Tween.to(obj, X, Elastic.OUT, 100, 1500).onComplete(something);
Tween.to(obj, X, Elastic.OUT, 100, 1500).delay(1000).onComplete(something);


[Obli]

Totally awesome answer Nates ! Thanks a lot for taling the time to read the source, I'll make all these changes asap !
(don't know why you got an opengl exception in the example though...)

* About CUSTOM_ , I totally agree, I though about something like this to let users create their own extensions, but did not even though about integers, which will let users continue to use the switch/case syntax, perfect!

* About returning a Tween with Tween.to(), again, nice find. I made a public kill() method in tweens but if users can't access them... XD

* About "Maybe smoke isStarted and just set the startValue in set "set" method."
Nice catch, isStarted was never reset to false ! However, I cannot set the startValue int he set method, because during the delay (if any) period, the starting value may have changed. This way, I need to retrieve the start value only at the end of the delay. this leads to continuous animation.

[Obli]

Done ! Everything is updated !
For the complete changelog, refer to the previous Nates reply

There are 2 main API changes (the rest is internal lib changes) that will break any previous usage:

1. Tween.to() does no longer let you set a delay and a completeCallback. Use instruction chaing for this purpose:

Code: Select all

Tween.to(obj, TweenTypes.X, Elastic.OUT, 100, 1500).delay(1000).onComplete(something);

2. Tween types are now integers. This allows you to define your own custom (named !) types. Some common types (X, Y, SCALE, ROTATION, OPACITY...) are described in TweenTypes as static final integers. If you use them, be careful to set your own custom types to values different from those of TweenTypes (even though I set them to -123456... tusing the same values would be a strange coincidence).

[Wavesonics]

Sweetness!!

Include in GDX IMO