Skip to content

Commit

Permalink
feat: do not automatically add/remove a tween to/from its associated …
Browse files Browse the repository at this point in the history 
…group

feat: the `tween.group(group)` method now has a reciprocal `tween.remove()`
method that will remove a tween from its associated group, and unassociate the
group. `tween.group()` without an arg is no longer valid, see breaking changes
and migration below.

fix: when a tween is stopped before its end time, do not allow its update method
to continue, therefore preventing logic (f.e. repeat logic) from being
triggered

docs: improved the docs, adding some missing information, removing all examples
of the global `TWEEN` group which has been deprecated, and adding docs on how to
manage groups of tweens. Also updated samples to use `import` syntax for
importing Tween, avoiding the use of the `TWEEN` UMD global variable which has
been deprecated.

feat: A new `Group.allStopped()` method returns true if all tweens in
a group are not playing (i.e. stopped, and not paused), otherwise false.
Useful for stopping an animation loop once all tweens in a group have
finished their animation.

BREAKING:

- Tweens are no longer automatically added or removed from groups by default
  when you call any Tween methods such as `start()`, `stop()`, or `pause()`, and
  the `preserve` parameter to `Group.update()` now defaults to `true` and is
  deprecated to be removed in a future major version.
  - MIGRATION: To keep old behavior for a while, explicitly call
    `group.update()` with `false` for the second parameter. To migrate forward, do
    not rely on automatic add/remove of tweens, and instead add/remove tweens
    to/from groups manually.
- `Group.update()` no longer returns a boolean indicating if all tweens
  have been removed.
  - MIGRATION: Don't rely on auto-add/remove to/from groups. This
    boolean return was previously useful for stopping an animation loop
    once all tweens were finished animating. Instead, use the new
    `Group.allStopped()` method to check if all tweens in a group are stopped in
    order to determine whether or not to continue an animation loop.
- The second `group` parameter to `Tween.constructor` now defaults to
  `undefined` instead of the global `TWEEN` group. Additionally it
  accepts a value of `true` to restore the old default behavior. The
  `true` value is deprecated and will be removed in a future major
  version.
  - MIGRATION: For the time being the parameter can be set to `true` to restore
    the old behavior. To migrate forward, use `tween.group(group)` or
    `group.add(tween)` instead.
- The argless `tween.group()` signature has been removed.
  - MIGRATION: Use `group.add(tween)` or `group.remove(tween)` instead.
    `tween.group(TWEEN)`, `TWEEN.add(tween)`, and `TWEEN.remove(tween)` will also
    work for now, but they are deprecated and will be removed in a future major
    version.
- `Group.update`'s second parameter `preserve` defaults to `true` now, and is
  deprecated to be removed in a future major version, at which point tweens of a
  group will no longer be automatically added/remove to/from a group when calling
  any Tween methods such as `start()`, `pause()`, or `stop()`.
  - MIGRATION: For now, explicitly set the parameter to `false` to restore old
    default behavior when calling `group.update()`. To migrate forward, do not
    rely on the automatic add/remove behavior, and instead manually add or remove
    tweens to or from groups.
- To make the fix for `tween.update()` to be a no-op for stopped tweens, we had
  to break an undocumented feature that allowed tweens to move backward in time
  (#271).
  - MIGRATION: To move tweens backward in time after they have already
    completed, first call `tween.start(startTime)` then proceed to call
    `tween.update(time)` in reverse order as before (see the unit test with "go
    backward in time" in its name). Without calling `tween.start()` nothing will
    happen because stopped/completed tweens will now always return early from
    `update()`, as they are considered to be no longer running.
  • Loading branch information
@trusktr
trusktr committed Jul 26, 2024
1 parent 2469f1c commit f28f069
Show file tree
Hide file tree
Showing 46 changed files with 4,607 additions and 1,425 deletions.
294 changes: 191 additions & 103 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,6 @@ More languages: [English](./README.md), [简体中文](./README_zh-CN.md)
---

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/20.0.0/tween.umd.js"></script>

<div id="box"></div>

<style>
Expand All @@ -24,14 +22,16 @@ More languages: [English](./README.md), [简体中文](./README_zh-CN.md)
}
</style>

<script>
<script type="module">
import {Tween, Easing} from 'https://unpkg.com/@tweenjs/[email protected]/dist/tween.esm.js'
const box = document.getElementById('box') // Get the element we want to animate.
const coords = {x: 0, y: 0} // Start at (0, 0)
const tween = new TWEEN.Tween(coords, false) // Create a new tween that modifies 'coords'.
const tween = new Tween(coords, false) // Create a new tween that modifies 'coords'.
.to({x: 300, y: 200}, 1000) // Move to (300, 200) in 1 second.
.easing(TWEEN.Easing.Quadratic.InOut) // Use an easing function to make the animation smooth.
.easing(Easing.Quadratic.InOut) // Use an easing function to make the animation smooth.
.onUpdate(() => {
// Called after tween.js updates 'coords'.
// Move 'box' to the position described by 'coords' with a CSS translation.
Expand All @@ -50,109 +50,15 @@ More languages: [English](./README.md), [简体中文](./README_zh-CN.md)

[Try this example on CodePen](https://codepen.io/trusktr/pen/KKGaBVz?editors=1000)

# Installation

## From CDN

Install from a content-delivery network (CDN) like in the above example.

From cdnjs:

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/20.0.0/tween.umd.js"></script>
```

Or from unpkg.com:

```html
<script src="https://unpkg.com/@tweenjs/tween.js@^20.0.0/dist/tween.umd.js"></script>
```

Note that 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.

## Build and include in your project with script tag

Currently npm is required to build the project.

```bash
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:

- UMD : `tween.umd.js`
- ES6 Module : `tween.es.js`

You are now able to copy tween.umd.js into your project, then include it with
a script tag, which will add TWEEN to the global scope,

```html
<script src="path/to/tween.umd.js"></script>
```

or import TWEEN as a JavaScript module,

```html
<script type="module">
import * as TWEEN from 'path/to/tween.es.js'
</script>
```

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

## With `npm install` and `import` from `node_modules`

You can add tween.js as an npm dependency:

```bash
npm install @tweenjs/tween.js
```

### With a build tool

If you are using [Node.js](https://nodejs.org/), [Parcel](https://parceljs.org/), [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/), [Vite](https://vitejs.dev/), or another build tool, then you can now use the following to include tween.js:

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

### Without a build tool

You can import from `node_modules` if you serve node_modules as part of your website, using an `importmap` script tag. First, assuming `node_modules` is at the root of your website, you can write an import map:

```html
<script type="importmap">
{
"imports": {
"@tweenjs/tween.js": "./node_modules/@tweenjs/tween.js/dist/tween.esm.js"
}
}
</script>
```

Now in any of your module scripts you can import it by its package name:

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

# Features

- Does one thing and one thing only: tween properties
- 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

# Documentation

- [User guide](./docs/user_guide.md)
- [Contributor guide](./docs/contributor_guide.md)
- [Tutorial](https://web.archive.org/web/20220601192930/http://learningthreejs.com/blog/2011/08/17/tweenjs-for-smooth-animation/) using tween.js with three.js
- Also: [libtween](https://github.com/jsm174/libtween), a port of tween.js to C by [jsm174](https://github.com/jsm174)
- Doesn't make its own animation loop, making it flexible for integration into
any animation loop.

# Examples

Expand Down Expand Up @@ -350,6 +256,184 @@ import * as TWEEN from '@tweenjs/tween.js'
</tr>
</table>

# 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:

```bash
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_modules`
is at the root of your website, you can write an import map like so in your HTML
file:

```html
<script type="importmap">
{
"imports": {
"@tweenjs/tween.js": "/node_modules/@tweenjs/tween.js/dist/tween.esm.js"
}
}
</script>
```

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

```html
<script type="module">
import {Tween} from '@tweenjs/tween.js'
</script>
```

#### Import from CDN

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

```html
<script type="module">
import {Tween} from 'https://unpkg.com/browse/@tweenjs/[email protected]/dist/tween.esm.js'
</script>
```

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

```html
<script type="importmap">
{
"imports": {
"@tweenjs/tween.js": "https://unpkg.com/browse/@tweenjs/[email protected]/dist/tween.esm.js"
}
}
</script>

<script type="module">
import {Tween} from '@tweenjs/tween.js'
</script>
```

### With a build tool

If you are using [Node.js](https://nodejs.org/),
[Parcel](https://parceljs.org/), [Webpack](https://webpack.js.org/),
[Rollup](https://rollupjs.org/), [Vite](https://vitejs.dev/), 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 from
`node_modules` without needing to create an `importmap` script:

```javascript
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.

```bash
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):

```html
<script type="module">
import {Tween} from 'path/to/tween.esm.js'
</script>
```

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

```html
<script src="path/to/tween.umd.js"></script>
<script>
const {Tween} = TWEEN
</script>
```

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

> [!Note]
> You can also download these files from unpkg, for example here:
> https://unpkg.com/browse/@tweenjs/[email protected]/dist/
## 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:

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/23.1.3/tween.umd.js"></script>
```

Or from unpkg.com:

```html
<script src="https://unpkg.com/@tweenjs/tween.js@^23.1.3/dist/tween.umd.js"></script>
```

Then use the `TWEEN` variable in any script:

```html
<script>
const {Tween, Easing, Group /*, ...*/} = TWEEN
const tween = new Tween(someObject)
// ...
</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 of
`dist/tween.esm.js` or `dist/tween.umd.js`.

# Documentation

- [User guide](./docs/user_guide.md)
- [Contributor guide](./docs/contributor_guide.md)
- [Tutorial](https://web.archive.org/web/20220601192930/http://learningthreejs.com/blog/2011/08/17/tweenjs-for-smooth-animation/) using tween.js with three.js
- Also: [libtween](https://github.com/jsm174/libtween), a port of tween.js to C by [jsm174](https://github.com/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:
Expand All @@ -364,7 +448,11 @@ To run the tests run:
npm test
```

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` a PR to be accepted. See [contributing](CONTRIBUTING.md) for more information.
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. See
[contributing](CONTRIBUTING.md) for more information.

# People

Expand Down
12 changes: 6 additions & 6 deletions README_zh-CN.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
---

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/20.0.0/tween.umd.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/23.1.3/tween.umd.js"></script>

<div id="box"></div>

Expand Down Expand Up @@ -59,13 +59,13 @@
cdnjs:

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/20.0.0/tween.umd.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/23.1.3/tween.umd.js"></script>
```

或者 unpkg.com:

```html
<script src="https://unpkg.com/@tweenjs/tween.js@^20.0.0/dist/tween.umd.js"></script>
<script src="https://unpkg.com/@tweenjs/tween.js@^23.1.3/dist/tween.umd.js"></script>
```

请注意，unpkg.com 支持 URL 中的 semver 版本，其中 URL 中的 `^` 告诉 unpkg 为你提供最新版本 20.x.x。
Expand All @@ -84,7 +84,7 @@ npm run build
这将在 `dist` 目录中创建一些构建。 目前有两种不同的库版本：

- UMD : `tween.umd.js`
- ES6 Module : `tween.es.js`
- ES6 Module : `tween.esm.js`

你现在可以将 tween.umd.js 复制到你的项目中，然后将其包含在一个 script 标签，它将 TWEEN 添加到全局范围，

Expand All @@ -96,7 +96,7 @@ npm run build

```html
<script type="module">
import * as TWEEN from 'path/to/tween.es.js'
import * as TWEEN from 'path/to/tween.esm.js'
</script>
```

Expand Down Expand Up @@ -126,7 +126,7 @@ import * as TWEEN from '@tweenjs/tween.js'
<script type="importmap">
{
"imports": {
"@tweenjs/tween.js": "/node_modules/@tweenjs/tween.js/dist/tween.es.js"
"@tweenjs/tween.js": "/node_modules/@tweenjs/tween.js/dist/tween.esm.js"
}
}
</script>
Expand Down
Loading

0 comments on commit f28f069

Please sign in to comment.