archive-gh-me/tween.js
1
0
Fork 0
mirror of https://github.com/tweenjs/tween.js.git synced 2026-02-01 17:27:10 +00:00
Code Issues Projects Releases Wiki Activity

Merge branch 'master' into patch-1

Browse Source
This commit is contained in:
Michael Casebolt 2019-06-05 21:53:08 -07:00 committed by GitHub
commit 330a553a5d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 11909 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.travis.yml
View File

@ -6,7 +6,7 @@ cache:
notifications:
email: false
node_js:
- "6"
- "10"
before_install:
- npm i -g npm@^2.0.0
before_script:

10
README.md
View File

@ -77,19 +77,13 @@ You will need to use a tool such as `browserify` to convert code using this styl
#### Use `bower`
```bash
bower install @tweenjs/tweenjs --save
```
or install an specific tag. They are git tags, and you can run `git tag` in the command line for a list if you have cloned the repository locally, or you can also check out the list in the [tween.js tags page](https://github.com/tweenjs/tween.js/tags). For example, to install `v16.3.0`:
```bash
bower install @tweenjs/tweenjs#v16.3.0
bower install tweenjs/tween.js --save
```
Then reference the library source:
```html
<script src="bower_components/@tweenjs/tweenjs/src/Tween.js"></script>
<script src="bower_components/tweenjs/src/Tween.js"></script>
```
## Features

109
docs/user_guide.md
View File

@ -1,6 +1,6 @@
# tween.js user guide
_**NOTE** this is a work in progress, please excuse the gaps. Wherever you see something marked as TODO, it's not done yet. If you find that something is unclear or missing details, please [file an issue](https://github.com/sole/tween.js/issues/new) and help make this guide better. Or feel free to submit clarifications or improvements of your own if you feel you can help too!_
_**NOTE** This is a work in progress. If you find that something is unclear or missing details, please [file an issue](https://github.com/tweenjs/tween.js/issues/new) 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?
@ -33,10 +33,10 @@ Finally in order to run as smoothly as possible you should call the `TWEEN.updat
animate();
function animate() {
requestAnimationFrame(animate);
// [...]
TWEEN.update();
// [...]
requestAnimationFrame(animate);
// [...]
TWEEN.update();
// [...]
}
````
@ -46,7 +46,7 @@ But unless you print the value of `x` to the console, you can't see its value ch
````javascript
tween.onUpdate(function(object) {
console.log(object.x);
console.log(object.x);
});
````
@ -56,16 +56,16 @@ So far we've only used tweens to print values to the console, but you could use
````javascript
var tween = new TWEEN.Tween(cube.position)
.to({ x: 100, y: 100, z: 100 }, 10000)
.start();
.to({ x: 100, y: 100, z: 100 }, 10000)
.start();
animate();
function animate() {
requestAnimationFrame(animate);
TWEEN.update();
requestAnimationFrame(animate);
TWEEN.update();
threeRenderer.render(scene, camera);
threeRenderer.render(scene, camera);
}
````
@ -83,8 +83,8 @@ into this
````javascript
var tween = new TWEEN.Tween(position)
.to({ x: 200 }, 1000)
.start();
.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](../examples/04_simplest.html) for a working example.
@ -99,10 +99,10 @@ We've seen this example before:
animate();
function animate() {
requestAnimationFrame(animate);
// [...]
TWEEN.update();
// [...]
requestAnimationFrame(animate);
// [...]
TWEEN.update();
// [...]
}
````
@ -114,7 +114,7 @@ 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:
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:
````javascript
var currentTime = player.currentTime;
@ -221,7 +221,7 @@ Used to get a reference to the active `tweens` array and to remove all of them f
### `TWEEN.add(tween)` and `TWEEN.remove(tween)`
Used to add a tween to the list of active tweens, or to remove an specific one from the list, respectively.
Used to add a tween to the list of active tweens, or to remove a specific one from the list, respectively.
These methods are usually used internally only, but are exposed just in case you want to do something _funny_.
@ -242,16 +242,16 @@ var groupA = new TWEEN.Group();
var groupB = new TWEEN.Group();
var tweenA = new TWEEN.Tween({ x: 1 }, groupA)
.to({ x: 10 }, 100)
.start();
.to({ x: 10 }, 100)
.start();
var tweenB = new TWEEN.Tween({ x: 1 }, groupB)
.to({ x: 10 }, 100)
.start();
.to({ x: 10 }, 100)
.start();
var tweenC = new TWEEN.Tween({ x: 1 })
.to({ x: 10 }, 100)
.start();
.to({ x: 10 }, 100)
.start();
groupA.update(); // only updates tweenA
groupB.update(); // only updates tweenB
@ -288,7 +288,7 @@ _Credit where credit is due:_ these functions are derived from the original set
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].
- `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:
@ -296,16 +296,16 @@ The easing function is only called _once per tween_ on each update, no matter ho
````
easedElapsed = easing(k);
for each property:
newPropertyValue = initialPropertyValue + propertyDelta * easedElapsed;
newPropertyValue = initialPropertyValue + propertyDelta * easedElapsed;
````
For the performance obsessed people out there: the deltas are calculated only when `start()` is called on a tween.
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 appplied a Math.floor to the output, so only the integer part would be returned, resulting in a sort of step-ladder output:
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:
````javascript
function tenStepEasing(k) {
return Math.floor(k * 10) / 10;
return Math.floor(k * 10) / 10;
}
````
@ -325,24 +325,24 @@ For example, suppose you're trying to animate some object whose properties can't
````javascript
var trickyObjTween = new TWEEN.Tween({
propertyA: trickyObj.getPropertyA(),
propertyB: trickyObj.getPropertyB()
propertyA: trickyObj.getPropertyA(),
propertyB: trickyObj.getPropertyB()
})
.to({ propertyA: 100, propertyB: 200 })
.onUpdate(function(object) {
object.setA( object.propertyA );
object.setB( object.propertyB );
});
.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 an `start` callback:
Or imagine you want to play a sound when a tween is started. You can use a `start` callback:
````javascript
var tween = new TWEEN.Tween(obj)
.to({ x: 100 })
.onStart(function() {
sound.play();
});
.to({ x: 100 })
.onStart(function() {
sound.play();
});
````
The scope for each callback is the tweened object--in this case, `obj`.
@ -373,6 +373,12 @@ Executed when a tween is finished normally (i.e. not stopped).
The tweened object is passed in as the first parameter.
### onRepeat
Executed whenever a tween has just finished one repetition and will begin another.
The tweened object is passed in as the first parameter.
## Advanced tweening
### Relative values
@ -451,11 +457,11 @@ When you try to animate the position of an element in the page, the easiest solu
```javascript
var element = document.getElementById('myElement');
var tween = new TWEEN.Tween({ top: 0, left: 0 })
.to({ top: 100, left: 100 }, 1000)
.onUpdate(function(object) {
element.style.top = object.top + 'px';
element.style.left = object.left + 'px';
});
.to({ top: 100, left: 100 }, 1000)
.onUpdate(function(object) {
element.style.top = object.top + 'px';
element.style.left = object.left + 'px';
});
```
but this is really inefficient because altering these properties forces the browser to recalculate the layout on each update, and this is a very costly operation. Instead of using these, you should use `transform`, which doesn't invalidate the layout and will also be hardware accelerated when possible, like this:
@ -463,10 +469,10 @@ but this is really inefficient because altering these properties forces the brow
```javascript
var element = document.getElementById('myElement');
var tween = new TWEEN.Tween({ top: 0, left: 0 })
.to({ top: 100, left: 100 }, 1000)
.onUpdate(function(object) {
element.style.transform = 'translate(' + object.left + 'px, ' + object.top + 'px);';
});
.to({ top: 100, left: 100 }, 1000)
.onUpdate(function(object) {
element.style.transform = 'translate(' + object.left + 'px, ' + object.top + 'px);';
});
```
If you want to read more about this, have a look at [this article](http://www.paulirish.com/2012/why-moving-elements-with-translate-is-better-than-posabs-topleft/).
@ -480,4 +486,3 @@ If you use an `onUpdate` callback, you need to be very careful with what you put
## Crazy tweening
This is something you might not use often, but you can use the tweening equations outside of Tween.js. They're just functions, after all. So you could use them to calculate smooth curves as input data. For example, they're used to generate audio data in [this experiment](http://5013.es/toys/tween.audio/).

11765
package-lock.json generated Normal file
View File

File diff suppressed because it is too large Load Diff

6
package.json
View File

@ -1,7 +1,7 @@
{
"name": "@tweenjs/tween.js",
"description": "Super simple, fast and easy to use tweening engine which incorporates optimised Robert Penner's equations.",
"version": "17.2.0",
"version": "17.3.5",
"main": "src/Tween.js",
"homepage": "https://github.com/tweenjs/tween.js",
"repository": {
@ -22,13 +22,13 @@
"test-unit": "nodeunit test/unit/nodeunitheadless.js",
"test-correctness": "jshint --config test/jshintrc src/Tween.js",
"test-style": "jscs --config test/jscs.json src/Tween.js",
"semantic-release": "semantic-release pre && npm publish && semantic-release post"
"semantic-release": "semantic-release"
},
"author": "tween.js contributors (https://github.com/tweenjs/tween.js/graphs/contributors)",
"devDependencies": {
"jscs": "^2.11.0",
"jshint": "^2.9.4",
"nodeunit": "^0.9.5",
"semantic-release": "^6.3.2"
"semantic-release": "^15.13.12"
}
}

69
src/Tween.js
View File

@ -138,6 +138,7 @@ TWEEN.Tween = function (object, group) {
this._onStartCallback = null;
this._onStartCallbackFired = false;
this._onUpdateCallback = null;
this._onRepeatCallback = null;
this._onCompleteCallback = null;
this._onStopCallback = null;
this._group = group || TWEEN;
@ -146,17 +147,17 @@ TWEEN.Tween = function (object, group) {
};
TWEEN.Tween.prototype = {
getId: function getId() {
getId: function () {
return this._id;
},
isPlaying: function isPlaying() {
isPlaying: function () {
return this._isPlaying;
},
to: function to(properties, duration) {
to: function (properties, duration) {
this._valuesEnd = properties;
this._valuesEnd = Object.create(properties);
if (duration !== undefined) {
this._duration = duration;
@ -166,7 +167,12 @@ TWEEN.Tween.prototype = {
},
start: function start(time) {
duration: function duration(d) {
this._duration = d;
return this;
},
start: function (time) {
this._group.add(this);
@ -212,7 +218,7 @@ TWEEN.Tween.prototype = {
},
stop: function stop() {
stop: function () {
if (!this._isPlaying) {
return this;
@ -230,14 +236,14 @@ TWEEN.Tween.prototype = {
},
end: function end() {
end: function () {
this.update(this._startTime + this._duration);
this.update(Infinity);
return this;
},
stopChainedTweens: function stopChainedTweens() {
stopChainedTweens: function () {
for (var i = 0, numChainedTweens = this._chainedTweens.length; i < numChainedTweens; i++) {
this._chainedTweens[i].stop();
@ -245,89 +251,96 @@ TWEEN.Tween.prototype = {
},
group: function group(group) {
group: function (group) {
this._group = group;
return this;
},
delay: function delay(amount) {
delay: function (amount) {
this._delayTime = amount;
return this;
},
repeat: function repeat(times) {
repeat: function (times) {
this._repeat = times;
return this;
},
repeatDelay: function repeatDelay(amount) {
repeatDelay: function (amount) {
this._repeatDelayTime = amount;
return this;
},
yoyo: function yoyo(yy) {
yoyo: function (yoyo) {
this._yoyo = yy;
this._yoyo = yoyo;
return this;
},
easing: function easing(eas) {
easing: function (easingFunction) {
this._easingFunction = eas;
this._easingFunction = easingFunction;
return this;
},
interpolation: function interpolation(inter) {
interpolation: function (interpolationFunction) {
this._interpolationFunction = inter;
this._interpolationFunction = interpolationFunction;
return this;
},
chain: function chain() {
chain: function () {
this._chainedTweens = arguments;
return this;
},
onStart: function onStart(callback) {
onStart: function (callback) {
this._onStartCallback = callback;
return this;
},
onUpdate: function onUpdate(callback) {
onUpdate: function (callback) {
this._onUpdateCallback = callback;
return this;
},
onComplete: function onComplete(callback) {
onRepeat: function onRepeat(callback) {
this._onRepeatCallback = callback;
return this;
},
onComplete: function (callback) {
this._onCompleteCallback = callback;
return this;
},
onStop: function onStop(callback) {
onStop: function (callback) {
this._onStopCallback = callback;
return this;
},
update: function update(time) {
update: function (time) {
var property;
var elapsed;
@ -387,7 +400,7 @@ TWEEN.Tween.prototype = {
}
if (this._onUpdateCallback !== null) {
this._onUpdateCallback(this._object);
this._onUpdateCallback(this._object, elapsed);
}
if (elapsed === 1) {
@ -426,6 +439,10 @@ TWEEN.Tween.prototype = {
this._startTime = time + this._delayTime;
}
if (this._onRepeatCallback !== null) {
this._onRepeatCallback(this._object);
}
return true;
} else {

42
test/unit/tests.js
View File

@ -232,6 +232,9 @@
test.ok( t.onComplete() instanceof TWEEN.Tween );
test.equal( t.onComplete(), t );
test.ok( t.duration() instanceof TWEEN.Tween );
test.equal( t.duration(), t );
test.ok( t.group() instanceof TWEEN.Tween );
test.equal( t.group(), t );
@ -1273,12 +1276,12 @@
var endObj = { x: 2 };
var duration = 1000;
var globalObj = Object.assign( startObj );
var globalObj = { x: 1 };
var globalTween = new TWEEN.Tween( globalObj )
.to( endObj, duration )
.start( 0 );
var groupObj = Object.assign( startObj );
var groupObj = { x: 1 };
var groupTween = new TWEEN.Tween( groupObj, group )
.to( endObj, duration )
.start( 0 );
@ -1299,12 +1302,12 @@
var endObj = { x: 2 };
var duration = 1000;
var globalObj = Object.assign( startObj );
var globalObj = { x: 1 };
var globalTween = new TWEEN.Tween( globalObj )
.to( endObj, duration )
.start( 0 );
var groupObj = Object.assign( startObj );
var groupObj = { x: 1 };
var groupTween = new TWEEN.Tween( groupObj, group )
.to( endObj, duration )
.start( 0 );
@ -1348,6 +1351,21 @@
},
'Set the duration with .duration': function(test) {
var obj = { x: 1 };
var t = new TWEEN.Tween( obj )
.to({x: 2})
.duration(1000)
.start(0);
t.update( 1000 );
test.deepEqual( obj.x, 2 );
test.done();
},
'Tween.group sets the tween\'s group.': function(test) {
var group = new TWEEN.Group();
@ -1362,6 +1380,22 @@
},
'Arrays in the object passed to to() are not modified by start().':
function(test) {
var start = {x: 10, y: 20};
var end = {x: 100, y: 200, values: ['a', 'b']};
var valuesArray = end.values;
new TWEEN.Tween(start).to(end).start();
test.equal(valuesArray, end.values);
test.equal(end.values.length, 2);
test.equal(end.values[0], 'a');
test.equal(end.values[1], 'b');
test.done();
},
};
return tests;