Animations can give a UI a more smoother feeling, on the other hand they can be annoying for the player if over-used or if your animations are too slow. So use animations with care.
 

A Shake-Effect

The following example shows only a small part of what is possible with animations. Check the In-Game UI API Reference to see more details about the animation features.

 

For our title-screen, we want to add a "shake-effect" effect by adding offsets to the button's position if the mouse pointer is over the button.

 

ui.UIManager.styles.titleScreenButton = {

    "resizable": true,

    "margin": [0, 0, 0, 10],

    "animations": [

        {

            "event": "onMouseHover",

            "flow": [

                { "type": "changeTo", "duration": 45,"field": "o.offset.x", "value": 10, "easing": "quad_inout", "wait": true },

                { "type": "changeTo", "duration": 45,"field": "o.offset.x", "value": -10, "easing": "quad_inout", "wait": true }

            ]

        },

        {

            "event": "onMouseLeave",

            "flow": [

                { "type": "changeTo", "duration": 0,"field": "o.offset.x", "value": 0, "easing": "quad_inout" }

            ]

        }

    ]

}

 

As we can see, animations can be added to a control using animations-property. But instead of adding that property to each button we put it into our titleScreenButton style so it is automatically applied to our three buttons. If we test-play our game now, the buttons while shake on mouse hover.

 

An animation needs to be bound to an event like a mouse-action for example. In our case we have actually two animations, one is bound to onMouseHover event and is only executed if the mouse-pointer is over the button. The other is bound to onMouseLeave event and is only executed if the mouse-pointer leaves the button's area.

 

An animation defines an animation-flow containing multiple primitive/basic animations to form the actual animation effect. Basic animations are simple movements, rotation, zooming, etc and can be played one after another or even in parallel. So its possible to move an image while rotating and zooming it at the same time. In our example we are using two "changeTo" animations to first move the button to the right and with the second "changeTo" we move the button to the left.

 

The animation-flow is always looped. If the last basic-animation has been finished the flow repeats and starts again with the first basic-animation of the animation-flow.

 

In addition, we defined a second animation played once if the mouse leaves the button's area. That is necessary to set the button's x-offset back to zero so the button goes back to its original position. We set the animation duration to zero to finish the animation immediately. You can play around with it and remove the "onMouseLeave" animation to see what happens then.

 

Lets take a closer look to the properties:

 

A list of animations executed for the control if the event occurres. Each animation needs to be bound to a different event.

 

The event when the animation should be executed. Like onMouseHover, onMouseLeave, onMouseDown, onAlways, etc.

 

The animation-flow which is a list of basic animations to create the actual animation-effect. In our case we want to create a shake-effect.

 

The type of the primitive animation. In our case it is changeTo which allows us to animate any kind of visual-properties. In our case we want to animate the x-offset of the button to create a shake effect.

 

The duration of the basic animation, in our case 45 frames. (1 frame = 1 / FRAMERATE (60 by default) seconds).

 

The easing-type used for the animation. We are using quad_inout, a quadratic easing-function to make the movements more smooth. But there are many other easing-functions available. To disable easing, just use linear_inout. Check Easings Effects page for more information.

 

Indicates if the animation-flow should wait until the current basic animation is done before playing the next. In our case we need to wait until the shake in right-direction is done before we start to shake into the other direction. But in other cases it is necessary to run two or more basic animations in parallel like to move and rotate an image at the same time for example.

 

This property is specific for the changeTo animation. Here we can define a field to animate using binding-syntax, see Data Bindings example for more info about bindings.

 

This property is specific for the changeTo animation. Here we can specify the target-value we want to reach. In our case, we want to animate x-offset to 30 pixels in first step and then animate x-offset to -30 in second step.

 

A Pulse-Effect

After we learned some basics about animations the last example, we will try another animation next: A "pulse-effect" if the mouse-pointer is over the button's area.

 

ui.UIManager.styles.titleScreenButton = {

    "resizable": true,

    "margin": [0, 0, 0, 10],

    "anchor": [0.5, 0.5],

    "animations": [

        {

            "event": "onMouseHover",

            "flow": [

                { "type": "zoomTo", "duration": 45,"zoom": [110, 110], "easing": "quad_inout", "wait": true },

                { "type": "zoomTo", "duration": 45,"zoom": [100, 100], "easing": "quad_inout", "wait": true }

            ]

        },

        {

            "event": "onMouseLeave",

            "flow": [

                { "type": "zoomTo", "duration": 0,"zoom": [100, 100], "easing": "quad_inout", "wait": true }

            ]

        }

    ]

}

 

If we test-play our game now, our buttons will zoom-in and out ("pulsing") if we move the mouse-pointer over a button's area. We are using a new type of basic-animation in this example called zoomTo which zooms the button to the percentage defined in zoom property. Lets go through the animation-flow step by step:

 

In first step we are zooming the button by 110% to reach a zoom-out of the button. Then we wait until our zoom-out is done by setting wait property to true. In next step we are zooming the button back to 100% and then wait again until the zoom-animation is done by setting wait property to true. Since the animation-flow is always looped it looks like the button is "pulsing" by zooming in and out.

 

You maybe notice that we also added a new property "anchor" to the button. With anchor-property we can change the button's anchor-point to its own center (0.5, 0.5) so that the zoom-effect goes in all 4 directions. Without that, the zoom effect would only go into lower-right direction. The best way to understand this is if you remove the anchor property to see what happens then.