Skip to content

Commit f28f069

Browse files
trusktrtrusktr
committed
feat: do not automatically add/remove a tween to/from its associated 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.
1 parent 2469f1c commit f28f069

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+4607
-1425
lines changed

‎README.md‎

Lines changed: 191 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,6 @@ More languages: [English](./README.md), [简体中文](./README_zh-CN.md)
1212
---
1313

1414
```html
15-
<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/20.0.0/tween.umd.js"></script>
16-
1715
<div id="box"></div>
1816

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

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

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

53-
# Installation
54-
55-
## From CDN
56-
57-
Install from a content-delivery network (CDN) like in the above example.
58-
59-
From cdnjs:
60-
61-
```html
62-
<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/20.0.0/tween.umd.js"></script>
63-
```
64-
65-
Or from unpkg.com:
66-
67-
```html
68-
<script src="https://unpkg.com/@tweenjs/tween.js@^20.0.0/dist/tween.umd.js"></script>
69-
```
70-
71-
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.
72-
73-
## Build and include in your project with script tag
74-
75-
Currently npm is required to build the project.
76-
77-
```bash
78-
git clone https://github.com/tweenjs/tween.js
79-
cd tween.js
80-
npm install
81-
npm run build
82-
```
83-
84-
This will create some builds in the `dist` directory. There are currently two different builds of the library:
85-
86-
- UMD : `tween.umd.js`
87-
- ES6 Module : `tween.es.js`
88-
89-
You are now able to copy tween.umd.js into your project, then include it with
90-
a script tag, which will add TWEEN to the global scope,
91-
92-
```html
93-
<script src="path/to/tween.umd.js"></script>
94-
```
95-
96-
or import TWEEN as a JavaScript module,
97-
98-
```html
99-
<script type="module">
100-
import * as TWEEN from 'path/to/tween.es.js'
101-
</script>
102-
```
103-
104-
where `path/to` is replaced with the location where you placed the file.
105-
106-
## With `npm install` and `import` from `node_modules`
107-
108-
You can add tween.js as an npm dependency:
109-
110-
```bash
111-
npm install @tweenjs/tween.js
112-
```
113-
114-
### With a build tool
115-
116-
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:
117-
118-
```javascript
119-
import * as TWEEN from '@tweenjs/tween.js'
120-
```
121-
122-
### Without a build tool
123-
124-
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:
125-
126-
```html
127-
<script type="importmap">
128-
{
129-
"imports": {
130-
"@tweenjs/tween.js": "./node_modules/@tweenjs/tween.js/dist/tween.esm.js"
131-
}
132-
}
133-
</script>
134-
```
135-
136-
Now in any of your module scripts you can import it by its package name:
137-
138-
```javascript
139-
import * as TWEEN from '@tweenjs/tween.js'
140-
```
141-
14253
# Features
14354

144-
- Does one thing and one thing only: tween properties
55+
- Does one thing only and does it well: tweens properties of an object
14556
- Doesn't take care of CSS units (e.g. appending `px`)
14657
- Doesn't interpolate colors
14758
- Easing functions are reusable outside of Tween
14859
- Can also use custom easing functions
149-
150-
# Documentation
151-
152-
- [User guide](./docs/user_guide.md)
153-
- [Contributor guide](./docs/contributor_guide.md)
154-
- [Tutorial](https://web.archive.org/web/20220601192930/http://learningthreejs.com/blog/2011/08/17/tweenjs-for-smooth-animation/) using tween.js with three.js
155-
- Also: [libtween](https://github.com/jsm174/libtween), a port of tween.js to C by [jsm174](https://github.com/jsm174)
60+
- Doesn't make its own animation loop, making it flexible for integration into
61+
any animation loop.
15662

15763
# Examples
15864

@@ -350,6 +256,184 @@ import * as TWEEN from '@tweenjs/tween.js'
350256
</tr>
351257
</table>
352258

259+
# Installation
260+
261+
The recommended method is to use `import` syntax. Here we've listed various
262+
install methods starting roughly with the most recommended first and least
263+
desirable last. Evaluate all of the following methods to pick what is most
264+
suitable for your project.
265+
266+
## With `npm install` and `import` from `node_modules`
267+
268+
You can add tween.js as an npm dependency:
269+
270+
```bash
271+
npm install @tweenjs/tween.js
272+
```
273+
274+
### Without a build tool
275+
276+
#### Installed locally
277+
278+
You can import from `node_modules` if you serve `node_modules` as part of your
279+
website, using a standard `importmap` script tag. First, assuming `node_modules`
280+
is at the root of your website, you can write an import map like so in your HTML
281+
file:
282+
283+
```html
284+
<script type="importmap">
285+
{
286+
"imports": {
287+
"@tweenjs/tween.js": "/node_modules/@tweenjs/tween.js/dist/tween.esm.js"
288+
}
289+
}
290+
</script>
291+
```
292+
293+
Now in any of your module scripts you can import Tween.js by its package name:
294+
295+
```html
296+
<script type="module">
297+
import {Tween} from '@tweenjs/tween.js'
298+
</script>
299+
```
300+
301+
#### Import from CDN
302+
303+
Note that, without the `importmap`, you can import directly from a CDN as with the first example above, like so:
304+
305+
```html
306+
<script type="module">
307+
import {Tween} from 'https://unpkg.com/browse/@tweenjs/[email protected]/dist/tween.esm.js'
308+
</script>
309+
```
310+
311+
You can also link your `importmap` to the CDN instead of a local `node_modules` folder, if you prefer that:
312+
313+
```html
314+
<script type="importmap">
315+
{
316+
"imports": {
317+
"@tweenjs/tween.js": "https://unpkg.com/browse/@tweenjs/[email protected]/dist/tween.esm.js"
318+
}
319+
}
320+
</script>
321+
322+
<script type="module">
323+
import {Tween} from '@tweenjs/tween.js'
324+
</script>
325+
```
326+
327+
### With a build tool
328+
329+
If you are using [Node.js](https://nodejs.org/),
330+
[Parcel](https://parceljs.org/), [Webpack](https://webpack.js.org/),
331+
[Rollup](https://rollupjs.org/), [Vite](https://vitejs.dev/), or another build
332+
tool, then you can install `@tweenjs/tween.js` with `npm install
333+
@tweenjs/tween.js`, and `import` the library into your JavaScript (or
334+
TypeScript) file, and the build tool will know how to find the source code from
335+
`node_modules` without needing to create an `importmap` script:
336+
337+
```javascript
338+
import * as TWEEN from '@tweenjs/tween.js'
339+
```
340+
341+
However, note that this approach requires always running a build tool for your
342+
app to work, while the `importmap` approach will simply work without any build
343+
tools as a simple static HTML site.
344+
345+
## Manual build
346+
347+
Another approach is to download the source code with git, manually build the
348+
library, then place the output in your project. Node.js is required for this.
349+
350+
```bash
351+
git clone https://github.com/tweenjs/tween.js
352+
cd tween.js
353+
npm install
354+
npm run build
355+
```
356+
357+
This will create some builds in the `dist` directory. There are currently two different builds of the library:
358+
359+
- ES6 Module in `/dist/tween.esm.js` (recommended)
360+
- UMD in `/dist/tween.umd.js` (deprecated, will be removed in a future major version)
361+
362+
You are now able to copy one of those two files into your project, and use like this (recommended):
363+
364+
```html
365+
<script type="module">
366+
import {Tween} from 'path/to/tween.esm.js'
367+
</script>
368+
```
369+
370+
or (deprecated, to be removed in future major):
371+
372+
```html
373+
<script src="path/to/tween.umd.js"></script>
374+
<script>
375+
const {Tween} = TWEEN
376+
</script>
377+
```
378+
379+
where `path/to` is replaced with the location where you placed the file.
380+
381+
> [!Note]
382+
> You can also download these files from unpkg, for example here:
383+
> https://unpkg.com/browse/@tweenjs/[email protected]/dist/
384+
385+
## Global variable from CDN (deprecated)
386+
387+
> [!Note]
388+
> This method is deprecated and will be removed in a future major version!
389+
390+
Install a global `TWEEN` variable from a content-delivery network (CDN) using the UMD file.
391+
392+
From cdnjs:
393+
394+
```html
395+
<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/23.1.3/tween.umd.js"></script>
396+
```
397+
398+
Or from unpkg.com:
399+
400+
```html
401+
<script src="https://unpkg.com/@tweenjs/tween.js@^23.1.3/dist/tween.umd.js"></script>
402+
```
403+
404+
Then use the `TWEEN` variable in any script:
405+
406+
```html
407+
<script>
408+
const {Tween, Easing, Group /*, ...*/} = TWEEN
409+
410+
const tween = new Tween(someObject)
411+
// ...
412+
</script>
413+
```
414+
415+
> [!Note]
416+
> unpkg.com supports a semver version in the URL, where the `^` in the
417+
> URL tells unpkg to give you the latest version 20.x.x.
418+
419+
## CommonJS (deprecated)
420+
421+
Skip this section if you don't know what CommonJS is!
422+
423+
> [!Note]
424+
> This method is deprecated and will be removed in a future major version!
425+
426+
Any of the above methods work in older systems that still use CommonJS. Repeat
427+
any of the above methods but using `dist/tween.cjs` instead of
428+
`dist/tween.esm.js` or `dist/tween.umd.js`.
429+
430+
# Documentation
431+
432+
- [User guide](./docs/user_guide.md)
433+
- [Contributor guide](./docs/contributor_guide.md)
434+
- [Tutorial](https://web.archive.org/web/20220601192930/http://learningthreejs.com/blog/2011/08/17/tweenjs-for-smooth-animation/) using tween.js with three.js
435+
- Also: [libtween](https://github.com/jsm174/libtween), a port of tween.js to C by [jsm174](https://github.com/jsm174)
436+
353437
# Tests
354438

355439
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:
@@ -364,7 +448,11 @@ To run the tests run:
364448
npm test
365449
```
366450

367-
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.
451+
If you want to add any feature or change existing features, you _must_ run the
452+
tests to make sure you didn't break anything else. Any pull request (PR) needs
453+
to have updated passing tests for feature changes (or new passing tests for new
454+
features or fixes) in `src/tests.ts` to be accepted. See
455+
[contributing](CONTRIBUTING.md) for more information.
368456

369457
# People
370458

‎README_zh-CN.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
---
1313

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

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

@@ -59,13 +59,13 @@
5959
cdnjs:
6060

6161
```html
62-
<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/20.0.0/tween.umd.js"></script>
62+
<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/23.1.3/tween.umd.js"></script>
6363
```
6464

6565
或者 unpkg.com:
6666

6767
```html
68-
<script src="https://unpkg.com/@tweenjs/tween.js@^20.0.0/dist/tween.umd.js"></script>
68+
<script src="https://unpkg.com/@tweenjs/tween.js@^23.1.3/dist/tween.umd.js"></script>
6969
```
7070

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

8686
- UMD : `tween.umd.js`
87-
- ES6 Module : `tween.es.js`
87+
- ES6 Module : `tween.esm.js`
8888

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

@@ -96,7 +96,7 @@ npm run build
9696

9797
```html
9898
<script type="module">
99-
import * as TWEEN from 'path/to/tween.es.js'
99+
import * as TWEEN from 'path/to/tween.esm.js'
100100
</script>
101101
```
102102

@@ -126,7 +126,7 @@ import * as TWEEN from '@tweenjs/tween.js'
126126
<script type="importmap">
127127
{
128128
"imports": {
129-
"@tweenjs/tween.js": "/node_modules/@tweenjs/tween.js/dist/tween.es.js"
129+
"@tweenjs/tween.js": "/node_modules/@tweenjs/tween.js/dist/tween.esm.js"
130130
}
131131
}
132132
</script>

0 commit comments

Comments
 (0)