tween.js user guide

More languages: English, 简体中文

NOTE This is a work in progress. If you find that something is unclear or missing details, please file an issue and help make this guide better. Or feel free to submit clarifications or improvements of your own if you feel you can help too!

What is a tween? How do they work? Why do you want to use them?

A tween (from in-between) is a concept that allows you to change the values of the properties of an object in a smooth way. You just tell it which properties you want to change, which final values should they have when the tween finishes running, and how long should this take, and the tweening engine will take care of finding the intermediate values from the starting to the ending point.

For example, suppose you have a position object with x and y coordinates:

const position = {x: 100, y: 0}

If you wanted to change the x value from 100 to 200, you'd do this:

import {Tween} from '@tweenjs/tween.js'

// Create a tween for position first
const tween = new Tween(position)

// Then tell the tween we want to animate the x property over 1000 milliseconds
tween.to({x: 200}, 1000)

Actually this won't do anything yet. The tween has been created but it's not active. You need to start it:

// And set it to start
tween.start()

Finally in order to run as smoothly as possible you should call the tween.update() function in the same main loop you're using for animating. This generally looks like this:

animate()

function animate() {
	requestAnimationFrame(animate)
	// [...]
	tween.update()
	// [...]
}

After 1 second (i.e. 1000 milliseconds) position.x will be 200.

But unless you print the value of x to the console, you can't see its value changing. You might want to use the onUpdate callback:

tween.onUpdate(function (object) {
	console.log(object.x)
})

This function will be called each time the tween is updated; how often this happens depends on many factors--how fast (and how busy!) your computer or device is, for example.

So far we've only used tweens to print values to the console, but you could use it for things such as animating positions of three.js objects:

const tween = new Tween(cube.position).to({x: 100, y: 100, z: 100}, 10000).start()

animate()

function animate() {
	requestAnimationFrame(animate)
	tween.update()

	threeRenderer.render(scene, camera)
}

In this case, because the three.js renderer will look at the object's position before rendering, you don't need to use an explicit onUpdate callback.

You might have noticed something different here too: we're chaining the tween function calls! Each tween function returns the tween instance, so you can rewrite the following code:

const tween = new Tween(position)
tween.to({x: 200}, 1000)
tween.start()

into this

const tween = new Tween(position).to({x: 200}, 1000).start()

You'll see this a lot in the examples, so it's good to be familiar with it! Check 04-simplest for a working example.

Animating with tween.js

Tween.js doesn't run by itself. You need to tell it when to run, by explicitly calling the update method of each tween, or the update method of a Group that has multiple tweens (more on Groups below). The recommended method is to do this inside your main animation loop, which should be called with requestAnimationFrame for getting the best graphics performance:

We've seen this example before:

animate()

function animate() {
	requestAnimationFrame(animate)
	// [...]
	tween.update()
	// [...]
}

If called without parameters, update will determine the current time in order to find out how long has it been since the last time it ran.

However you can also pass an explicit time parameter to update. Thus,

tween.update(100)

means "update with time = 100 milliseconds". You can use this to make sure that all the time-dependent functions in your code are using the very same time value. For example, suppose you've got a player and want to run tweens in sync. Your animate code could look like this:

let currentTime = player.currentTime
tween.update(currentTime)

We use explicit time values for the unit tests. You can have a look at tests.ts to see how we call tween.update() with different values in order to simulate time passing.

Controlling a tween

`start` and `stop`

So far we've learnt about the Tween.start method, but there are more methods that control individual tweens. Probably the most important one is the start counterpart: stop. If you want to cancel a tween, just call this method over an individual tween:

tween.stop()

Stopping a tween that was never started or that has already been stopped has no effect. No errors are thrown either.

The start method also accepts a time argument. If you use it, the tween won't start until that particular moment in time; otherwise it will start as soon as possible (i.e. on the next call to tween.update()).

The start method accepts a second boolean argument: when true, a tween that we previously used will start from the values in the target object, instead of starting from the beginning. Useful for stopping a tween, then starting another one that will continue from the current location.

`startFromCurrentValues`

This is an alias for tween.start(undefined, true), to make a previously-used tween start from the last values of the target object, instead of from the beginning.

`update`

Individual tweens have an update method to so that they can be updated over time in an animation loop, and on each update they will apply updated values to their target object.

const tween = new Tween(someObject).to(/*...*/).start()

function animate(time) {
	tween.update(time)
	requestAnimationFrame(animate)
}

`pause`

While an tween is running (i.e. it has already been started and may have already been updated numerous times) it can be paused. Even if update() is called while the tween is paused, its time will not move forward. isPlaying will still be true while a tween is paused and its update() method continues to track time progression (you can continue to call update() while a tween is paused).

tween.start()

function animate() {
	tween.update()
	requestAnimationFrame(animate)
}
animate()

// at any time while the tween is running
tween.pause()

`chain`

Things get more interesting when you sequence different tweens in order, i.e. setup one tween to start once a previous one has finished. We call this chaining tweens, and it's done with the chain method. Thus, to make tweenB start after tweenA finishes:

tweenA.chain(tweenB)

Or, for an infinite chain, set tweenA to start once tweenB finishes:

tweenA.chain(tweenB)
tweenB.chain(tweenA)

Check Hello world to see an example of these infinite chains.

In other cases, you may want to chain multiple tweens to another tween in a way that they (the chained tweens) all start animating at the same time:

tweenA.chain(tweenB, tweenC)

Warning Calling tweenA.chain(tweenB) actually modifies tweenA so that tweenB is always started when tweenA finishes. The return value of chain is just tweenA, not a new tween.

`repeat`

If you wanted a tween to repeat forever you could chain it to itself, but a better way is to use the repeat method. It accepts a parameter that describes how many repetitions you want after the first tween is completed:

tween.repeat(10) // repeats 10 times after the first tween and stops
tween.repeat(Infinity) // repeats forever

The total number of tweens will be the repeat parameter plus one for the initial tween. Check the Repeat example.

`yoyo`

This function only has effect if used along with repeat. When active, the behaviour of the tween will be like a yoyo, i.e. it will bounce to and from the start and end values, instead of just repeating the same sequence from the beginning:

tween.yoyo(false) // default value, animation will only go from start to end value
tween.yoyo(true) // tween will 'yoyo' between start and end values

`delay`

More complex arrangements might require delaying a tween before it actually starts running. You can do that using the delay method:

tween.delay(1000)
tween.start()

will start executing 1 second after the start method has been called.

`repeatDelay`

Normally the delay time is applied between repetitions of a tween, but if a value is provided to the repeatDelay function then that value will determine the total time elapsed between repetitions of a tween.

Consider this example:

tween.delay(1000)
tween.repeatDelay(500)
tween.start()

The first iteration of the tween will happen after one second, the second iteration will happen a half second after the first iteration ends, the third iteration will happen a half second after the second iteration ends, etc. If you want to delay the initial iteration but you don't want any delay between iterations, then make sure to call tween.repeatDelay(0).

`dynamic`

If dynamic is set to true (it defaults to false) objects passed to tween.to() can be modified on the outside of a tween while the tween is animating. This can be used to dynamically modify the outcome of a tween while it is running.

See the Dynamic to example. In that example, in both scenes, the position of the rabbit is updated during the animation. The rabbit position happens to be the object passed into the fox's tween.to() method. As the rabbit position is updated, in the first scene with .dynamic(false) the fox moves towards the initial position of the rabbit and does not chase the rabbit, and in the second scene with .dynamic(true) the final destination of the fox is hence also updated which makes the fox chase the rabbit.

See the other dynamic to examples for more ideas.

Warning When dynamic is set to false, Tween makes a copy of the object passed into tween.to() and will never modify it (hence updating the original object from the outside is not dynamic). When dynamic is true, Tween uses the original object as the source of values during animation (every update reads the values, hence they can be modified dynamically) but note that in dynamic mode, Tween will modify any interpolation arrays of the object passed into tween.to() which may cause side-effects on any external code that may also rely on the same object.

Controlling groups of tweens

Sometimes you want to update multiple tweens at once, which can be useful when grouping a set of tweens into a logical component in your application. You can do this with a Group.

First add multiple tweens to a group:

import {Group, Tween} from '@tweenjs/tween.js'

const tween1 = new Tween(obj1).to(...).start()
const tween2 = new Tween(obj2).to(...).start()

const group = new Group()
group.add(tween1)
group.add(tween2)

Then call group.update() in your animation loop instead of on individual tweens:

animate()

function animate() {
	requestAnimationFrame(animate)
	// [...]
	group.update()
	// [...]
}

Note that a tween can only belong to a single group. Adding a tween to a group automatically removes it from any previous group.

`group.getAll()`

Returns an array of all tweens added to a group.

`group.add(tween)`

Add a tween to a group.

`group.remove(tween)`

Remove a tween from a group.

`group.removeAll()`

Remove all tween from a group.

`group.update(time?)`

Update all tweens in a group, with an optional time value. If time value is not supplied, it default to the current time.

Changing the easing function (AKA make it bouncy)

Tween.js will perform the interpolation between values (i.e. the easing) in a linear manner, so the change will be directly proportional to the elapsed time. This is predictable but also quite uninteresting visually wise. Worry not--this behaviour can be easily changed using the easing method. For example:

import {Tween, Easing} from '@tweenjs/tween.js'
// ...
tween.easing(Easing.Quadratic.In)

This will result in the tween slowly starting to change towards the final value, accelerating towards the middle, and then quickly reaching its final value. In contrast, Easing.Quadratic.Out would start changing quickly towards the value, but then slow down as it approaches the final value.

Available `Easing` functions

There are a few existing easing functions provided with tween.js. They are grouped by the type of equation they represent: Linear, Quadratic, Cubic, Quartic, Quintic, Sinusoidal, Exponential, Circular, Elastic, Back and Bounce, and then by the easing type: In, Out and InOut.

Probably the names won't be saying anything to you unless you're familiar with these concepts already, so it is probably the time to check the Graphs example, which graphs all the curves in one page so you can compare how they look at a glance.

Easing also has a function called generatePow(). This function generates easing functions for different curves depending on arguments. You can check the relevance of the arguments to curves in the example of pow easing page.

Credit where credit is due: these functions are derived from the original set of equations that Robert Penner graciously made available as free software a few years ago, but have been optimised to play nicely with JavaScript.

Using a custom easing function

Not only can you use any of the existing functions, but you can also provide your own, as long as it follows a couple of conventions:

it must accept one parameter:
- k: the easing progress, or how far along the duration of the tween we are. Allowed values are in the range [0, 1].
it must return a value based on the input parameters.

The easing function is only called once per tween on each update, no matter how many properties are to be changed. The result is then used with the initial value and the difference (the deltas) between this and the final values, as in this pseudocode:

easedElapsed = easing(k);
for each property:
    newPropertyValue = initialPropertyValue + propertyDelta * easedElapsed;

For the performance-obsessed people out there: the deltas are calculated only when start() is called on a tween.

So let's suppose you wanted to use a custom easing function that eased the values but applied a Math.floor to the output, so only the integer part would be returned, resulting in a sort of step-ladder output:

function tenStepEasing(k) {
	return Math.floor(k * 10) / 10
}

And you could use it in a tween by simply calling its easing method, as we've seen before:

tween.easing(tenStepEasing)

Check the graphs for custom easing functions example to see this in action (and also some metaprogramming for generating step functions).

Callbacks

Another powerful feature is to be able to run your own functions at specific times in each tween's life cycle. This is usually required when changing properties is not enough.

For example, suppose you're trying to animate some object whose properties can't be accessed directly but require you to call a setter instead. You can use an update callback to read the new updated values and then manually call the setters. All callbacks are passed the tweened object as the only parameter.

const trickyObjTween = new Tween({
	propertyA: trickyObj.getPropertyA(),
	propertyB: trickyObj.getPropertyB(),
})
	.to({propertyA: 100, propertyB: 200})
	.onUpdate(function (object) {
		object.setA(object.propertyA)
		object.setB(object.propertyB)
	})

Or imagine you want to play a sound when a tween is started. You can use a start callback:

const tween = new Tween(obj).to({x: 100}).onStart(function () {
	sound.play()
})

The scope for each callback is the tweened object--in this case, obj.

onStart

Executed right before the tween starts animating, after any delay time specified by the delay method. This will be executed only once per tween, i.e. it will not be run when the tween is repeated via repeat().

It is great for synchronising to other events or triggering actions you want to happen when a tween starts.