Property animation

All numeric properties (numbers, vector3, vector4 and quaterions) and shader constants can be animated with the built-in animation system, using the function go.animate(). The engine will automatically “tween” properties for you according to given playback modes and easing functions. You can also specify custom easing functions.

Property animation

To animate a game object or component property, use the function go.animate(). For GUI node properties, the corresponding function is gui.animate().

-- Set the position property y component to 200
go.set(".", "position.y", 200)
-- Then animate it
go.animate(".", "position.y", go.PLAYBACK_LOOP_PINGPONG, 100, go.EASING_OUTBOUNCE, 2)

To stop all animations of a given property, call go.cancel_animations(), or for GUI nodes, gui.cancel_animation():

-- Stop euler z rotation animation on the current game object
go.cancel_animations(".", "euler.z")

If you cancel the animation of a composite property, like position, any animations of the sub-components (position.x, position.y and position.z) will be cancelled as well.

The Properties Manual contains all the available properties on game objects, components and GUI nodes.

GUI node property animation

Almost all GUI node properties are possible to animate. You can, for instance, make a node invisible by setting its color property to full transparency and then fade it into view by animating the color to white (i.e. no tint color).

local node = gui.get_node("button")
local color = gui.get_color(node)
-- Animate the color to white
gui.animate(node, gui.PROP_COLOR, vmath.vector4(1, 1, 1, 1), gui.EASING_INOUTQUAD, 0.5)
-- Animate the outline red color component
gui.animate(node, "outline.x", 1, gui.EASING_INOUTQUAD, 0.5)
-- And move to x position 100
gui.animate(node, hash("position.x"), 100, gui.EASING_INOUTQUAD, 0.5)

Completion callbacks

The property animation functions go.animate() and gui.animate() support an optional Lua callback function as the last argument. This function will be called when the animation has played to the end. The function is never called for looping animations, nor when an animation is manually canceled via go.cancel_animations() or gui.cancel_animation(). The callback can be used to trigger events on animation completion or to chain multiple animations together.

Easing

Easing defines how the animated value changes over time. The images below describe the functions applied over time to create the easing.

The following are valid easing values for go.animate():

The following are valid easing values for gui.animate():

Custom easing

You can create custom easing curves by defining a vector with a set of values and then provide the vector instead of one of the predefined easing constants above. The vector values express a curve from the start value (0) to the target value (1). The runtime samples values from the vector and linearly interpolates when calculating values in between the points expressed in the vector.

For example, the vector:

local values = { 0, 0.4, 0.2, 0.2, 0.5, 1 }
local my_easing = vmath.vector(values)

yields the following curve:

The following example causes the y position of a game object to jump between the current position and 200 according to a square curve:

local values = { 0, 0, 0, 0, 0, 0, 0, 0,
                 1, 1, 1, 1, 1, 1, 1, 1,
                 0, 0, 0, 0, 0, 0, 0, 0,
                 1, 1, 1, 1, 1, 1, 1, 1,
                 0, 0, 0, 0, 0, 0, 0, 0,
                 1, 1, 1, 1, 1, 1, 1, 1,
                 0, 0, 0, 0, 0, 0, 0, 0,
                 1, 1, 1, 1, 1, 1, 1, 1 }
local square_easing = vmath.vector(values)
go.animate("go", "position.y", go.PLAYBACK_LOOP_PINGPONG, 200, square_easing, 2.0)