GitHub - tweenjs/tween.js: JavaScript/TypeScript animation engine (original) (raw)

tween.js

JavaScript (TypeScript) tweening engine for easy animations, incorporating optimised Robert Penner's equations.

More languages: English, 简体中文

Try this example on CodePen

Features

• Does one thing only and does it well: tweens properties of an object
• Doesn't take care of CSS units (e.g. appending px)
• Doesn't interpolate colors
• Easing functions are reusable outside of Tween
• Can also use custom easing functions
• Doesn't make its own animation loop, making it flexible for integration into any animation loop.

Examples

	hello world (source)		Bars (source)
	Black and red (source)		Graphs (source)
	Simplest possible example (source)		Video and time (source)
	Array interpolation (source)		Dynamic to, object (source)
	Dynamic to, interpolation array (source)		Dynamic to, large interpolation array (source)
	Repeat (source)		Relative values (source)
	Yoyo (source)		Stop all chained tweens (source)
	Custom functions (source)		Relative start time (source)
	Pause tween (source)		Complex properties (source)
	Animate an array of values (source)

Installation

The recommended method is to use import syntax. Here we've listed various install methods starting roughly with the most recommended first and least desirable last. Evaluate all of the following methods to pick what is most suitable for your project.

With npm install and import from node_modules

You can add tween.js as an npm dependency:

npm install @tweenjs/tween.js

Without a build tool

Installed locally

You can import from node_modules if you serve node_modules as part of your website, using a standard importmap script tag. First, assuming node_modulesis at the root of your website, you can write an import map like so in your HTML file:

Now in any of your module scripts you can import Tween.js by its package name:

Import from CDN

Note that, without the importmap, you can import directly from a CDN as with the first example above, like so:

You can also link your importmap to the CDN instead of a local node_modules folder, if you prefer that:

With a build tool

If you are using Node.js,Parcel, Webpack,Rollup, Vite, or another build tool, then you can install @tweenjs/tween.js with npm install @tweenjs/tween.js, and import the library into your JavaScript (or TypeScript) file, and the build tool will know how to find the source code fromnode_modules without needing to create an importmap script:

import * as TWEEN from '@tweenjs/tween.js'

However, note that this approach requires always running a build tool for your app to work, while the importmap approach will simply work without any build tools as a simple static HTML site.

Manual build

Another approach is to download the source code with git, manually build the library, then place the output in your project. Node.js is required for this.

git clone https://github.com/tweenjs/tween.js cd tween.js npm install npm run build

This will create some builds in the dist directory. There are currently two different builds of the library:

• ES6 Module in /dist/tween.esm.js (recommended)
• UMD in /dist/tween.umd.js (deprecated, will be removed in a future major version)

You are now able to copy one of those two files into your project, and use like this (recommended):

or (deprecated, to be removed in future major):

where path/to is replaced with the location where you placed the file.

Global variable from CDN (deprecated)

Note

This method is deprecated and will be removed in a future major version!

Install a global TWEEN variable from a content-delivery network (CDN) using the UMD file.

From cdnjs:

Or from unpkg.com:

Then use the TWEEN variable in any script:

Note

unpkg.com supports a semver version in the URL, where the ^ in the URL tells unpkg to give you the latest version 20.x.x.

CommonJS (deprecated)

Skip this section if you don't know what CommonJS is!

Note

This method is deprecated and will be removed in a future major version!

Any of the above methods work in older systems that still use CommonJS. Repeat any of the above methods but using dist/tween.cjs instead ofdist/tween.esm.js or dist/tween.umd.js.

Documentation

• User guide
• Contributor guide
• Tutorial using tween.js with three.js
• Also: libtween, a port of tween.js to C by jsm174

Tests

You need to install npm first--this comes with node.js, so install that one first. Then, cd to tween.js's (or wherever you cloned the repo) directory and run:

To run the tests run:

If you want to add any feature or change existing features, you must run the tests to make sure you didn't break anything else. Any pull request (PR) needs to have updated passing tests for feature changes (or new passing tests for new features or fixes) in src/tests.ts to be accepted. Seecontributing for more information.

People

Maintainers: Joe Pea (@trusktr).

All contributors.

Projects using tween.js