Droid-Blog

This is a guest post by Alexander Fröhlich. Alexander is a freelance developer and is supporting ANDLABS at its libgdx-based development. 

If you are not familiar with libgdx yet, please check out the first part of this series, the Getting started with libgdx-guide.

1 Tweening?

“Tweening” in games is the process of creating intermediate states and thus frames between two or more given states.

Example (Sprite Translation):
The most simple example would be moving a sprite or image from one x1, y1 position to another x2, y2 position on the screen.

Yet, as you might already suspect, this “Universal Tween Engine” is capable of manipulating not only x, y coordinates for sprite objects…. no, this cross-platform-engine written entirely in java language lets you tween every property of any object given that it has its getter/setter methods attached.

In this tutorial I will show you how this comes in handy for game developers when building ingame hints or tutorials for their game.

The following sample code illustrates basic use and setup of the universal tween engine in a libgdx code project.

2 Ingame Tutorial Tweening

First of all, declare your tweenManager instance. The tweenManager lets you keep track and manage all your tweens (i.e. tweening, tween actions and so on)

public class MyGame implements ApplicationListener {

    // Only one manager is needed, like a 
    // libgdx Spritebatch (MyGame.java)

    private static TweenManager tweenManager;

}

Instantiate the manager inside create() of your libgdx lifecycle:

Register an accessor class, which is the key binding between the manager and the object to be tweened. Here this will be the TutorMessage class. (see below).
So after calling registerAccessor every single object of class TutorMessage we create can be tweened by the TweenManager.

@Override
public void create() {
    setTweenManager(new TweenManager());
    Tween.setCombinedAttributesLimit(4);// default is 3, yet
                                        // for rgba color setting          
                                        //we need to raise to 4! 
    Tween.registerAccessor(TutorMessage.class, new 
                             TutorMessageAccessor()); 

}

The TutorMessage’s are the internal game objects for this sample which hold the position, scale and color message attributes.

public class TutorMessage {

    private String message; // string objects can not be tweened
    private float x;
    private float y;
    private Color color;
    private float scale;

}

To tween these message properties and make them accessible by the manager we have to declare how getting and setting every single attribute works.

Getter/Setter
So we define 3 sections (POS_XY, SCALE, COLOR) that process the current float[] values, handled over by the manager during runtime when tweening is active.

Of course same applies for the setters.

public class TutorMessageAccessor implements TweenAccessor<TutorMessage> {

    public static final int POS_XY = 1;
    public static final int SCALE = 2
    public static final int COLOR = 3;

    @Override
    public int getValues(TutorMessage target, int tweenType, 
                           float[] returnValues) {
        switch (tweenType) {
            case POS_XY:
                returnValues[0] = target.getX();
                returnValues[1] = target.getY();
                return 2;

            case SCALE:
                returnValues[0] = target.getScale();
                return 1;

            case COLOR:
                returnValues[0] = target.getColor().r;
                returnValues[1] = target.getColor().g;
                returnValues[2] = target.getColor().b;
                returnValues[3] = target.getColor().a;
                return 4;

            default: 
                assert false; 
                return -1;
        }
    }

    @Override
    public void setValues(TutorMessage target, int tweenType, 
                            float[] newValues) {
        switch (tweenType) {
            case POS_XY: 
                target.setPosition(newValues[0], newValues[1]); 
                break;

            case SCALE: 
                target.setScale(newValues[0]); 
                break;

            case COLOR:
                Color c = target.getColor();
                c.set(newValues[0], newValues[1], newValues[2], 
                        newValues[3]);
                target.setColor(c);
                break;

            default: 
                assert false;
        }
    }
}

Having bind our TutorMessage class to the TweenManager we can now integrate it into the game.
Remember? We want to provide a kind of ingame tutorial system. So every time our user should see an animated on-screen help, we call the now defined method. The tweenHelpingHand method takes the parameter targetX, targetY that indicate the position where the helping hand (sprite) and its bound message (bitmapfont) should move to.

Then we say Tween
  .to (
      – TutorMessage currentTm ( the message to be moved )
      – int TutorMessageAccessor.POS_XY (constant to select which property should be tweened)
      – float 3f (total tweening duration)
  )
  .target (
    – targetX, targetY ( the final screen position of our tweened message )
  )
  .ease (
    – TweenEquations.easeOutCirc ( one possible interpolation pattern – i.e. moving pattern here)
  )
  .start (
    – MyGame.getTweenManager()  ( binds this tween to the manager )
  )

private void tweenHelpingHand(int targetX, int targetY) {

    // kill current tween - or pre-existing
    MyGame.getTweenManager().killTarget(currentTm);

    // move
    Tween.to(currentTm, TutorMessageAccessor.POS_XY, 3f)
         .target(targetX, targetY)
         .ease(TweenEquations.easeOutCirc)
         .start(MyGame.getTweenManager());

    // colorize
    Tween.to(currentTm, TutorMessageAccessor.COLOR, 3f)
         .target(1f, 1f, 1f, 1f)
         .ease(TweenEquations.easeOutCirc)
         .start(MyGame.getTweenManager());

}

Finally we have to call update inside the libgdx render() method to have the started Tween be updated constantly.

MyGame.getTweenManager().update(delta);

Here you go!
Enjoy this very powerful any easy to use tweening library.

Combining Scene2d animations and Tweening is also possible. You just have to write the ActorAccessor binding class and provide access (getter/setter) to its properties.
Like with Scene2d actions, the universal tween engine also allows sequencing of multiple tweens!

If you have any questions or suggestions, please leave a comment.