Tween

View source
Entity → ceramic.Tween (Class)

A lightweight tweening engine for animating numeric values over time.

Tweens provide:

  • Smooth transitions between values with easing functions
  • Duration-based animations
  • Automatic cleanup when complete or owner is destroyed
  • Frame-perfect timing with delta time compensation

Features:

  • 30+ built-in easing functions (quad, cubic, elastic, bounce, etc.)
  • Custom easing function support
  • Bezier curve easing
  • "Eager" mode for immediate first frame updates
  • Owner-based lifecycle management

Example usage:

// Simple tween from 0 to 100 over 1 second
Tween.start(this, LINEAR, 1.0, 0, 100, (value, time) -> {
    myObject.x = value;
});

// With easing and completion callback
var tween = Tween.start(this, ELASTIC_EASE_OUT, 2.0, oldScale, newScale,
    (value, time) -> myObject.scale = value
);
tween.onceComplete(this, () -> trace("Animation complete!"));
See: Easing, BezierEasing

Static Members

start(owner: Null<Entity>, ?easing: Anonymous, duration: Float, fromValue: Float, toValue: Float, handleValueTime: Function): Tween

Start a new tween animation.

Name Type Default Description
owner Null<Entity> Optional owner entity. If provided and destroyed, the tween is also destroyed.
easing Anonymous (optional) The easing function to use. Defaults to QUAD_EASE_IN_OUT.
duration Float Duration in seconds. If <= 0, completes immediately.
fromValue Float Starting value
toValue Float Ending value
handleValueTime Function Callback function called each frame with (value, time)
Returns Description
Tween The created Tween instance
eagerStart(owner: Null<Entity>, ?easing: Anonymous, duration: Float, fromValue: Float, toValue: Float, handleValueTime: Function): Tween

Start a new "eager" tween animation.

Eager tweens update immediately on the first frame instead of waiting for the next frame. This ensures the target property is set to an interpolated value right away, preventing visual jumps.

Name Type Default Description
owner Null<Entity> Optional owner entity. If provided and destroyed, the tween is also destroyed.
easing Anonymous (optional) The easing function to use. Defaults to QUAD_EASE_IN_OUT.
duration Float Duration in seconds. If <= 0, completes immediately.
fromValue Float Starting value
toValue Float Ending value
handleValueTime Function Callback function called each frame with (value, time)
Returns Description
Tween The created Tween instance
ease(easing: Anonymous, value: Float): Float

Apply an easing function to a normalized value (0-1). Useful for custom animations without creating a full tween.

Name Type Description
easing Anonymous The easing function to apply
value Float Input value (typically 0-1, but depends on the easing)
Returns Description
Float The eased value
easingFunction(easing: Anonymous): Function

Convert an Easing enum value to a standalone Float->Float function. Useful when you need to apply easing outside of the tween system.

Name Type Description
easing Anonymous The easing type to convert
Returns Description
Function A function that takes a value (0-1) and returns the eased value

Instance Members

easing: Anonymous

The easing function used for this tween. Determines how the value transitions from start to end.

duration: Float

The total duration of this tween in seconds. If duration is 0 or negative, the tween completes immediately.

value: Float

The current interpolated value. Updated each frame between fromValue and toValue based on elapsed time and easing.

time: Float

The elapsed time since the tween started (in seconds). Ranges from 0 to duration.

immediateStart(): Void
destroy(): Void

Events

@event update(value: Float, time: Float)

Event triggered on each frame with the current interpolated value.

Name Type Description
value Float The current interpolated value between fromValue and toValue
time Float The elapsed time since the tween started (in seconds)
onUpdate(owner, handler) onceUpdate(owner, handler) offUpdate(?handler) listensUpdate()
@event complete()

Event triggered when the tween completes its full duration. Not triggered if the tween is destroyed before completion.

onComplete(owner, handler) onceComplete(owner, handler) offComplete(?handler) listensComplete()

Private Members

owner: Entity
remaining: Float
fromValue: Float
toValue: Float
eager: Bool
didCallImmediateStart: Bool
didTickThisFrame: Bool
tick(delta: Float): Void
Name Type
delta Float
endFrame(): Void
computeEasing(easing: Anonymous): Void
Name Type
easing Anonymous
emitUpdate(value: Float, time: Float): Void

Event triggered on each frame with the current interpolated value.

Name Type Description
value Float The current interpolated value between fromValue and toValue
time Float The elapsed time since the tween started (in seconds)
emitComplete(): Void

Event triggered when the tween completes its full duration. Not triggered if the tween is destroyed before completion.

computedEasing(): Void
customEasing(): Float
Returns
Float
init(): Void
updateFromTick(delta: Float): Void
Name Type
delta Float
willEmitUpdate(value: Float, time: Float): Void
Name Type
value Float
time Float
immediateComplete(): Void
new(owner: Null<Entity>, easing: Anonymous, duration: Float, fromValue: Float, toValue: Float): Void
Name Type
owner Null<Entity>
easing Anonymous
duration Float
fromValue Float
toValue Float

Metadata

Name Parameters
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()
:allow ceramic.App