Tweens

Tweens let you animate any value over time: a position, a scale, an alpha, a color component... Ceramic provides a lightweight tween system with a large catalog of easing functions.

The tween easings example, showing every available easing side by side.

Creating a tween

The most direct way to create a tween is calling tween() on any visual (or entity):

Animating a visual with tween()
// Animate from 0 to 300 in 0.5 seconds, with a bounce
visual.tween(BOUNCE_EASE_OUT, 0.5, 0, 300, (value, time) -> {
    visual.y = value;
});

The callback is called at every frame with the current value (interpolated between your from and to values) and the current time (in seconds, from 0 to the tween duration). What you do with that value is entirely up to you: assign it to a position, a rotation, a volume...

Beyond the animation itself, calling tween() on a visual (or any entity) associates the tween with that entity: the tween belongs to it. This ownership is what makes tweens safe to use: if the entity is destroyed while the tween is still running, the tween is automatically stopped and cleaned up. You never end up with a callback firing on a visual that no longer exists, and you don't have to track and cancel tweens by hand.

You can also use the static Tween.start() method, which does the same thing but lets you provide any entity as the owner explicitly:

Creating a tween with Tween.start()
Tween.start(this, QUAD_EASE_IN_OUT, 1.0, 0, 1, (value, time) -> {
    someVisual.alpha = value;
});

The owner (first argument) is exactly what visual.tween(...) sets to the visual for you: the entity the tween is tied to. When it is destroyed, its running tweens are stopped and cleaned up automatically.

Easing functions

The Easing enum provides the usual easing families, each with _EASE_IN, _EASE_OUT and _EASE_IN_OUT variants:

Family Feel
LINEAR Constant speed
QUAD, CUBIC, QUART, QUINT Polynomial acceleration, increasingly pronounced
SINE Soft and natural
EXPO Very sharp acceleration
BACK Overshoots a little, then settles
BOUNCE Bounces like a ball
ELASTIC Springs around the target

If none of these fit, you can provide your own cubic bezier curve or even a custom function:

Custom easings
// A cubic bezier curve (like CSS transitions)
visual.tween(BEZIER(0.7, 0, 0.3, 1), 1.0, 0, 300, (value, time) -> {
    visual.x = value;
});

// Any function taking a value between 0 and 1
visual.tween(CUSTOM(myEasingFunction), 1.0, 0, 300, (value, time) -> {
    visual.x = value;
});

Chaining tweens

A tween emits a complete event when it finishes. Use it to chain animations:

Chaining animations with onceComplete()
visual.tween(QUAD_EASE_IN, 0.3, 0, 100, (value, time) -> {
    visual.y = value;
})
.onceComplete(this, () -> {
    // First tween finished, start another one
    visual.tween(BOUNCE_EASE_OUT, 0.6, 100, 400, (value, time) -> {
        visual.y = value;
    });
});

Stopping a tween

Keep a reference to the tween if you need to interrupt it:

Cancelling a running tween
var tween = visual.tween(LINEAR, 10.0, 0, 100, (value, time) -> {
    visual.x = value;
});

// Later:
tween.destroy();

Also remember that a tween owned by an entity is destroyed with it: most of the time, you don't need to do anything.

Continue reading ➔ Cameras