tween
Easing curves and value tweens for animating over time.
Motion that runs at a constant rate looks mechanical. Easing shapes that motion so it starts gently, ends gently, overshoots and springs back, or bounces to a stop, which is what makes a menu slide or a character hop feel alive. This module carries the easing curves a love2d game usually pulls from a separate library, and a small value tween that walks a number or a point from a start to a target over a set time.
ease takes one of the Easing curves and a time from 0 to 1 and returns the
eased position, also from 0 to 1, though the back and elastic curves go a
little past the ends on purpose. Hand that to lerp and you can ease anything
you can interpolate, a number, a Vec2 or a Color.
For the common case of moving one value to another over a few seconds, a
Tween holds the start, the target, the duration and the curve. You advance
it each frame with update, read where it is with value, and ask done
when it has arrived. newTween also takes a Vec2, so a position tweens the
same way a single number does.
This is an opt-in module, imported on its own with import nim2d/tween. The
core engine does not pull it in.
ease ¶
func ease(easing: Easing; t: float): float
Map a time t, from 0 at the start to 1 at the end, through the curve
easing and return the eased position. Times outside 0 to 1 are clamped
first. The result mostly stays within 0 to 1, but back and elastic
reach past the ends, which is where their snap comes from.
Parameters
-
easing(Easing) -
t(float)
Returns
float
type Tween = object
A single number easing from a start value to a target over a fixed time.
Advance it each frame with update, read where it is now with value,
and check done to know when it has arrived. Build one with newTween.
type VecTween = object
A point easing from a start position to a target over a fixed time, the
Vec2 counterpart of Tween. Both coordinates run on the one curve, so it
is what you reach for to slide something from one place to another.
newTween ¶
func newTween(start, target, duration: float; easing = Easing.linear): Tween
A tween of a single number from start to target over duration seconds
following easing. A duration of zero or less finishes at once.
Parameters
-
start(float) -
target(float) -
duration(float) -
easing(auto)
Returns
Tween
newTween ¶
func newTween(start, target: Vec2; duration: float; easing = Easing.linear): VecTween
A tween of a point from start to target over duration seconds
following easing.
Parameters
-
start(Vec2) -
target(Vec2) -
duration(float) -
easing(auto)
Returns
VecTween
update ¶
proc update(tw: var Tween; dt: float)
Advance the tween by dt seconds. It holds at the target once the duration
is up, so calling it past the end is harmless.
Parameters
-
tw(var Tween) -
dt(float)
update ¶
proc update(tw: var VecTween; dt: float)
Advance the tween by dt seconds, holding at the target once it is done.
Parameters
-
tw(var VecTween) -
dt(float)
progress ¶
func progress(tw: Tween): float
How far along the tween is before easing, from 0 at the start to 1 at the
end. This is the raw time fraction, not the eased value.
Parameters
-
tw(Tween)
Returns
float
progress ¶
func progress(tw: VecTween): float
How far along the tween is before easing, from 0 to 1.
Parameters
-
tw(VecTween)
Returns
float
value ¶
func value(tw: Tween): float
The current number, the start and target blended by the eased progress.
Read this each frame and assign it to whatever you are animating.
Parameters
-
tw(Tween)
Returns
float
value ¶
func value(tw: VecTween): Vec2
The current point, the start and target blended by the eased progress.
Parameters
-
tw(VecTween)
Returns
Vec2
done ¶
func done(tw: Tween): bool
True once the tween has reached its target.
Parameters
-
tw(Tween)
Returns
bool
done ¶
func done(tw: VecTween): bool
True once the tween has reached its target.
Parameters
-
tw(VecTween)
Returns
bool
reset ¶
proc reset(tw: var Tween)
Send the tween back to its start so it runs again from the beginning.
Parameters
-
tw(var Tween)
reset ¶
proc reset(tw: var VecTween)
Send the tween back to its start so it runs again from the beginning.
Parameters
-
tw(var VecTween)