You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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
-
<scriptsrc="path/to/tween.umd.js"></script>
94
-
```
95
-
96
-
or import TWEEN as a JavaScript module,
97
-
98
-
```html
99
-
<scripttype="module">
100
-
import*asTWEENfrom'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*asTWEENfrom'@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:
Now in any of your module scripts you can import it by its package name:
137
-
138
-
```javascript
139
-
import*asTWEENfrom'@tweenjs/tween.js'
140
-
```
141
-
142
53
# Features
143
54
144
-
- Does one thing and one thing only: tween properties
55
+
- Does one thing only and does it well: tweens properties of an object
145
56
- Doesn't take care of CSS units (e.g. appending `px`)
146
57
- Doesn't interpolate colors
147
58
- Easing functions are reusable outside of Tween
148
59
- 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.
156
62
157
63
# Examples
158
64
@@ -350,6 +256,184 @@ import * as TWEEN from '@tweenjs/tween.js'
350
256
</tr>
351
257
</table>
352
258
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
> 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
+
353
437
# Tests
354
438
355
439
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:
364
448
npm test
365
449
```
366
450
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.
0 commit comments