Class Tween

Namespace

Stride.CommunityToolkit.Mathematics

Assembly

Stride.CommunityToolkit.dll

A clock over one easing curve: start it, feed it the frame time, read a value between 0 and 1 or a value interpolated between two of your own. The plumbing every eased animation needs - a start, a duration, elapsed time, what happens at the end - in one object instead of three fields and an if.

public sealed class Tween

Inheritance

object

Tween

Examples

var pop = Tween.Run(0.6f, EasingFunction.BackEaseOut);

// every frame
pop.Update(gameTime);
entity.Transform.Scale = new Vector3(pop.Lerp(0f, 1f));

Remarks

A tween is not a scheduler: it does not run itself, call anything back, or know about the scene. Call Update(float) once per frame from wherever the frame time is known, then read Value or one of the Lerp helpers. That keeps it usable from a script, a processor or a plain update callback alike, and makes a paused game trivial: stop feeding it time.

Loop decides what the end means. None holds the last value and sets IsComplete; Repeat starts over; PingPong runs the curve backwards to the start and forwards again.

Constructors

Tween(float, EasingFunction, TweenLoop)

Creates a tween that is not running yet; call Start() or use Run(float, EasingFunction, TweenLoop).

public Tween(float duration, EasingFunction function = EasingFunction.Linear, TweenLoop loop = TweenLoop.None)

Parameters

duration float

How long one run takes, in seconds. Must be positive.

function EasingFunction

The curve the value follows.

loop TweenLoop

What happens at the end of a run.

Exceptions

ArgumentOutOfRangeException

duration is not a finite positive number.

Properties

Duration

How long one run takes, in seconds.

public float Duration { get; }

Property Value

float

Elapsed

Seconds fed in since the last Start(), folded into the current run for a looping tween.

public float Elapsed { get; }

Property Value

float

Function

The curve the value follows.

public EasingFunction Function { get; set; }

Property Value

EasingFunction

IsComplete

Whether a non-looping tween has reached its end. A looping tween never completes; stop it with Stop().

public bool IsComplete { get; }

Property Value

bool

Remarks

Stays set until Start() or Reset(). Code that writes a transform from the tween every frame it reports running or complete keeps writing the end pose for ever, which pins the object there against anything else that moves it, such as a camera controller. Write the end pose once on the frame it completes and then Reset(), or drive only while IsRunning and let the last update land it.

IsRunning

Whether Update(float) still advances the clock.

public bool IsRunning { get; }

Property Value

bool

Loop

What happens at the end of a run.

public TweenLoop Loop { get; set; }

Property Value

TweenLoop

Progress

The normalised time in [0, 1], before easing: where the run is, with ping-pong folded back.

public float Progress { get; }

Property Value

float

Value

The eased value in [0, 1], or briefly outside it for the elastic and back curves.

public float Value { get; }

Property Value

float

Methods

Lerp(Color, Color)

The colour between two colours at the tween's current point, channel by channel.

public Color Lerp(Color from, Color to)

Parameters

from Color

The colour at the start.

to Color

The colour at the end.

Returns

Color

The interpolated colour.

Lerp(Vector2, Vector2)

The point between two points at the tween's current point.

public Vector2 Lerp(Vector2 from, Vector2 to)

Parameters

from Vector2

The point at the start.

to Vector2

The point at the end.

Returns

Vector2

The interpolated point.

Lerp(Vector3, Vector3)

The point between two points at the tween's current point.

public Vector3 Lerp(Vector3 from, Vector3 to)

Parameters

from Vector3

The point at the start.

to Vector3

The point at the end.

Returns

Vector3

The interpolated point.

Lerp(float, float)

The value between two numbers at the tween's current point.

public float Lerp(float from, float to)

Parameters

from float

The value at the start.

to float

The value at the end.

Returns

float

The interpolated value.

Reset()

Rewinds to the start without running: the state a new tween has, so IsComplete is off and Value is the curve at 0.

public void Reset()

Resume()

Carries on from where Stop() left the clock.

public void Resume()

Run(float, EasingFunction, TweenLoop)

Creates a tween and starts it in one call.

public static Tween Run(float duration, EasingFunction function = EasingFunction.Linear, TweenLoop loop = TweenLoop.None)

Parameters

duration float

How long one run takes, in seconds.

function EasingFunction

The curve the value follows.

loop TweenLoop

What happens at the end of a run.

Returns

Tween

The running tween.

Slerp(Quaternion, Quaternion)

The rotation between two rotations at the tween's current point, along the shorter arc.

public Quaternion Slerp(Quaternion from, Quaternion to)

Parameters

from Quaternion

The rotation at the start.

to Quaternion

The rotation at the end.

Returns

Quaternion

The interpolated rotation.

Start()

Rewinds to the start and runs; on a running tween this is a restart.

public Tween Start()

Returns

Tween

This tween, so a call can chain onto the constructor.

Stop()

Freezes the clock where it is; Value keeps reporting that point. Start() rewinds, Resume() carries on.

public void Stop()

Update(GameTime)

Advances the clock by the frame time of a GameTime.

public void Update(GameTime time)

Parameters

time GameTime

The game time of the current update.

Update(float)

Advances the clock by a frame's worth of seconds.

public void Update(float deltaSeconds)

Parameters

deltaSeconds float

The seconds since the last update. Nothing happens for zero or a stopped tween.