# Tween

## Introduction¶

Change properties by tween equations, built-in object of phaser.

• Author: Richard Davey

## Usage¶

``````var tween = scene.tweens.add({
targets: gameObject,
x: 1,
// x: '+=1',
// x: '-=1',
// x: '*=1',
// x: '/=1',
// x: 'random(0.25, 0.75)',
// x: 'int(10, 100)',
// x: [100, 300, 200, 600],
// x: { from: 0, to: 1 },
// x: { start: 0, to: 1 },
// x: { start: value0, from: value1, to: value2 },
// x: {
//      getActive: function (target, key, value, targetIndex, totalTargets, tween) { return newValue; },
//      getStart: function (target, key, value, targetIndex, totalTargets, tween) { return newValue; },
//      getEnd: function (target, key, value, targetIndex, totalTargets, tween) { return newValue; }
// },
ease: 'Linear',       // 'Cubic', 'Elastic', 'Bounce', 'Back'
duration: 1000,
repeat: 0,            // -1: infinity
yoyo: false,

// interpolation: null,
});
``````
• `key: value2` : Tween to `value2`.
• `key: '+=deltaValue'` : Tween to current value + deltaValue
• Support these expressions : `key: '+=deltaValue'`, `key: '-=deltaValue'`, `key: '*=deltaValue'`, `key: '/=deltaValue'`
• `key: 'random(10, 100)'` : Tween to a random float value.
• `key: 'int(10, 100)'` : Tween to a random int value.
• `key: [100, 300, 200, 600]` : Use `interpolation` to determine the value.
• `key: { from: value1, to: value2 }` : Set the property to `value11` when tween started after delay, then tween to `value2`.
• `value1`, `value2` : A number, string, or callback(`function(target, key, value, targetIndex, totalTargets, tween) { return newValue; }`)
• `key: { start: value0, to: value2 }` : Set the property to `value0` immediately, then tween to `value2`.
• `value1`, `value2` : A number, string, or callback(`function(target, key, value, targetIndex, totalTargets, tween) { return newValue; }`)
• `key: { start: value0, from: value1, to: value2 }` : Set the property to `value0` immediately, then set to `value1` when tween started after delay, then tween to `value2`.
• `value0`, `value1`, `value2` : A number, string, or callback(`function(target, key, value, targetIndex, totalTargets, tween) { return newValue; }`)
• `key: function(target, key, value, targetIndex, totalTargets, tween) { return newValue; }`
• `target` :ă€€The tween target.
• `key` : The target property.
• `value` : The current value of the target property.
• `targetIndex` : The index of the target within the Tween.
• `totalTargets` : The total number of targets in this Tween.
• `tween` : The Tween that invoked this callback.
• `key: { getActive:callback, getStart:callback, getEnd:callback}`
• `callback` : `function(target, key, value, targetIndex, totalTargets, tween) { return newValue; }`

or

``````var tween = scene.tweens.add({
targets: gameObject,
paused: false,
callbackScope: tween,

// timming/callback of each state
onStart: function () {},
onStartParams: [],

// initial delay
delay: 0,  // function(target, targetKey, value, targetIndex, totalTargets, tween) { },

// tween duration
duration: 1000,
ease: 'Linear',
easeParams: null,

onActive: function () {},
onUpdate: function (tween, target, key, current, previous, param) {},
onUpdateParams: [],

// delay between tween and yoyo
hold: 0,
yoyo: false,  // true to tween backward
flipX: false,
flipY: false,
onYoyo: function (tween, target, key, current, previous, param) {},
onYoyoParams: [],

// repeat count (-1: infinite)
repeat: 0,
onRepeat: function (tween, target, key, current, previous, param) {},
onRepeatParams: [],
// delay to next pass
repeatDelay: 0,

// loop count (-1: infinite)
loop: 0,
onLoop: function () {},
onLoopParams: [],
// delay to next loop
loopDelay: 0,

// delay to onComplete callback
completeDelay: 0,
onComplete: function () {},
onCompleteParams: [],
// timming/callback of each state

onStop: function () {},
onPause: function () {},
onResume: function () {},

// properties:
x: '+=600',        // start from current value
y: 500,
rotation: ...
angle: ...
alpha: ...
// ...

// or
props: {
x: { value: '+=600', duration: 3000, ease: 'Power2' },
y: { value: '500', duration: 1500, ease: 'Bounce.easeOut' }
},

// or
props: {
x: {
duration: 400,
yoyo: true,
repeat: 8,
ease: 'Sine.easeInOut',
value: {
getActive: function (target, key, value, targetIndex, totalTargets, tween)
{
return value;
},
getStart: function (target, key, value, targetIndex, totalTargets, tween)
{
return value + 30;
},
getEnd: function (target, key, value, targetIndex, totalTargets, tween)
{
destX -= 30;
return destX;
}
}
},
....
},

persist: false,

interpolation: null,
interpolationData: null,

});
``````
• `targets` : The targets the tween is updating.
• `delay` : The time the tween will wait before it first starts
• A number, for all targets
• A callback function, built via stagger builder :
• From `0` to `endValue` :
• `scene.tweens.stagger(endValue)`
• From `startValue` to `endValue` :
• `scene.tweens.stagger([startValue, endValue])`
• From `0` to `endValue`, with specific ease function :
• `scene.tweens.stagger(endValue, {ease: 'cubic.inout'})`
• From `startValue` to `endValue`, with specific ease function :
• `scene.tweens.stagger([startValue, endValue], {ease: 'cubic.inout'})`
• From `0` to `endValue`, with specific start index :
• `scene.tweens.stagger(endValue, {from: 'last'})`
• `scene.tweens.stagger(endValue, {from: 'center'})`
• `scene.tweens.stagger(endValue, {from: index})`
• From `startValue` to `endValue`, , with specific start index :
• `scene.tweens.stagger([startValue, endValue], {from: 'last'})`
• `scene.tweens.stagger([startValue, endValue], {from: 'center'})`
• `scene.tweens.stagger([startValue, endValue], {from: index})`
• From `0` to `endValue`, with specific ease function, with specific start index :
• `scene.tweens.stagger(endValue, {from: 'last', ease: 'cubic.inout'})`
• From `startValue` to `endValue`, with specific ease function , with specific start index :
• `scene.tweens.stagger([startValue, endValue], {from: 'last', ease: 'cubic.inout'})`
• Grid mode. From `0` to `endValue`.
• `scene.tweens.stagger(endValue, {grid: [gridWidth, gridHeight], })`
• `scene.tweens.stagger(endValue, {grid: [gridWidth, gridHeight], from: 'center'})`
• `scene.tweens.stagger(endValue, {grid: [gridWidth, gridHeight], from: 'center', ease: 'cubic.inout'})`
• Grid mode. From `startValue` to `endValue`.
• `scene.tweens.stagger([startValue, endValue], {grid: [gridWidth, gridHeight], })`
• `scene.tweens.stagger([startValue, endValue], {grid: [gridWidth, gridHeight], from: 'center'})`
• `scene.tweens.stagger([startValue, endValue], {grid: [gridWidth, gridHeight], from: 'center', ease: 'cubic.inout'})`
• `duration` : The duration of the tween
• `ease` : The ease function used by the tween
• `easeParams` : The parameters to go with the ease function (if any)
• `hold` : The time the tween will pause before running a yoyo
• `repeat` : The number of times the tween will repeat itself (a value of 1 means the tween will play twice, as it repeated once)
• `repeatDelay` : The time the tween will pause for before starting a repeat. The tween holds in the start state.
• `yoyo` : boolean - Does the tween reverse itself (yoyo) when it reaches the end?
• `flipX` : flip X the GameObject on tween end
• `flipY` : flip Y the GameObject on tween end
• `completeDelay` : The time the tween will wait before the onComplete event is dispatched once it has completed
• `loop` : `-1` for an infinite loop
• `loopDelay`
• `paused` : Does the tween start in a paused state, or playing?
• `props` : The properties being tweened by the tween
• `onActive` : Tween becomes active within the Tween Manager.
``````function(tween, target) { }
``````
• `onStart` : A tween starts.
``````function(tween, targets) { }
``````
• `onUpdate` : Callback which fired when tween task updated
``````function(tween, target, key, current, previous, param) { }
``````
• `onComplete` : Tween completes or is stopped.
``````function(tween, targets) { }
``````
• `onYoyo` : A function to call each time the tween yoyos. Called once per property per target.
``````function(tween, target, key, current, previous, param) { }
``````
• `onLoop` : A function to call each time the tween loops.
``````function(tween, targets) { }
``````
• `onRepeat` : A function to call each time the tween repeats. Called once per property per target.
``````function(tween, target, key, current, previous, param) { }
``````
• `onStop` : A function to call when the tween is stopped.
``````function(tween, targets) { }
``````
• `onPause` : A function to call when the tween is paused.
``````function(tween, targets) { }
``````
• `onResume` : A function to call when the tween is resumed after being paused.
``````function(tween, targets) { }
``````
• `persist` : Will the Tween be automatically destroyed on completion, or retained for future playback?
• `interpolation` : The interpolation function to use if the `value` given is an array of numbers.
• `'linear'`, `'bezier'`, `'catmull'` (or `'catmullrom'`)

Note

Tween task will not manipulate any property that begins with an underscore.

#### Ease equations¶

• `Power0` : Linear
• `Power1` : Quadratic.Out
• `Power2` : Cubic.Out
• `Power3` : Quartic.Out
• `Power4` : Quintic.Out
• `Linear`
• `Quad` : Quadratic.Out
• `Cubic` : Cubic.Out
• `Quart` : Quartic.Out
• `Quint` : Quintic.Out
• `Sine` : Sine.Out
• `Expo` : Expo.Out
• `Circ` : Circular.Out
• `Elastic` : Elastic.Out
• `Back` : Back.Out
• `Bounce` : Bounce.Out
• `Stepped`
• `Quad.easeIn`
• `Cubic.easeIn`
• `Quart.easeIn`
• `Quint.easeIn`
• `Sine.easeIn`
• `Expo.easeIn`
• `Circ.easeIn`
• `Back.easeIn`
• `Bounce.easeIn`
• `Quad.easeOut`
• `Cubic.easeOut`
• `Quart.easeOut`
• `Quint.easeOut`
• `Sine.easeOut`
• `Expo.easeOut`
• `Circ.easeOut`
• `Back.easeOut`
• `Bounce.easeOut`
• `Quad.easeInOut`
• `Cubic.easeInOut`
• `Quart.easeInOut`
• `Quint.easeInOut`
• `Sine.easeInOut`
• `Expo.easeInOut`
• `Circ.easeInOut`
• `Back.easeInOut`
• `Bounce.easeInOut`

Demo

``````tween.pause();
``````
``````tween.resume();
``````

``````tween.complete();
``````
``````tween.stop();
``````

Won't invoke `onComplete` callback (`'complete'` event)

``````tween.play();
``````

``````tween.restart();
``````

### Seek¶

``````tween.seek(amount);
// tween.seek(amount, delta, emit);
``````
• `amount` : The number of milliseconds to seek into the Tween from the beginning.
• `delta` : The size of each step when seeking through the Tween. Default value is `16.6` (1000/60)
• `emit` : While seeking, should the Tween emit any of its events or callbacks? The default is `false`.

Removes this Tween from the TweenManager

``````tween.remove();
``````

``````tween.destroy();
``````

Note

A Tween that has been destroyed cannot ever be played or used again.

### Get tweens¶

• Tweens of a target
``````var tweens = scene.tweens.getTweensOf(target);
// var tweens = scene.tweens.getTweensOf(target, includePending);
``````
• `tweens` : Array of tweens, or timelines.
• `includePending` : Set `true` to search pending tweens.
• All tweens
``````var tweens = scene.tweens.getTweens();
``````

### Destroy task of a target¶

``````scene.tweens.killTweensOf(target);
``````
• `target` : The target to kill the tweens of. Provide an array to use multiple targets.

### Time-scale¶

``````tween.setTimeScale(v);
// tween.timeScale = timescale;
``````
``````var timeScale = tween.getTimeScale();
// var timeScale = tween.timeScale;
``````

#### Global time-scale¶

``````var timeScale = scene.tweens.timeScale;
``````
``````scene.tweens.timeScale = timescale;
``````

### Events¶

• Tween becomes active within the Tween Manager.
``````tween.on('active', function(tween, targets){

}, scope);
``````
• Tween completes or is stopped.
``````tween.on('complete', function(tween, targets){

}, scope);
``````
• A tween loops, after any loop delay expires.
``````tween.on('loop', function(tween, targets){

}, scope);
``````
• A tween property repeats, after any repeat delay expires.
``````tween.on('repeat', function(tween, key, target){

}, scope);
``````
• A tween starts.
``````tween.on('start', function(tween, targets){

}, scope);
``````
``````tween.on('update', function(tween, key, target, current, previous){

}, scope);
``````
• `tween` : A reference to the Tween instance that emitted the event.
• `key` : The property that was updated, i.e. `x` or `scale`.
• `target` : The target object that was updated. Usually a Game Object, but can be of any type.
• `current` : The current value of the property that was tweened.
• `previous` : The previous value of the property that was tweened, prior to this update.
• A tween property pause.
``````tween.on('pause', function(tween, key, target){

}, scope);
``````
• A tween property resume.
``````tween.on('resume', function(tween, key, target){

}, scope);
``````
• A tween property yoyos.
``````tween.on('yoyo', function(tween, key, target){

}, scope);
``````
• A tween stopped.
``````tween.on('stop', function(tween, targets){

}, scope);
``````

### Set callbacks¶

``````tween.setCallback(type, callback, param);
``````
• `type` :
• `'onActive'` : When the Tween is first created it moves to an 'active' state when added to the Tween Manager. 'Active' does not mean 'playing'.
• `'onStart'` : When the Tween starts playing after a delayed or paused state. This will happen at the same time as `onActive` if the tween has no delay and isn't paused.
• `'onLoop'` : When a Tween loops, if it has been set to do so. This happens after the `loopDelay` expires, if set.
• `'onComplete'` : When the Tween finishes playback fully. Never invoked if the Tween is set to repeat infinitely.
• `'onStop'` : Invoked only if the `Tween.stop` method is called.
• `'onPause'` : Invoked only if the `Tween.pause` method is called. Not invoked if the Tween Manager is paused.
• `'onResume'` : Invoked only if the `Tween.resume` method is called. Not invoked if the Tween Manager is resumed.
• `'onYoyo'` : When a TweenData starts a yoyo. This happens after the `hold` delay expires, if set.
• `'onRepeat'` : When a TweenData repeats playback. This happens after the `repeatDelay` expires, if set.
• `'onUpdate'` : When a TweenData updates a property on a source target during playback.
• `callback` :
• `'onRepeat'`, `'onUpdate'`, `'onYoyo'`
``````function(tween, targets, key, current, previous, param) {

}
``````
• `'onActive'`, `'onLoop'`, `'onPause'`, `'onResume'`, `'onComplete'`, `'onStart'`, `'onStop'`,
``````function(tween, targets, param) {

}
``````

### State¶

• Is playing
``````var isPlaying = tween.isPlaying();
``````
• Is paused
``````var isPaused = tween.isPaused();
``````
• Is actively and not just in a delayed state
``````var hasStarted = tween.hasStarted;
``````

### Custom ease function¶

``````var tween = scene.tweens.add({
targets: gameObject,
// ...
ease: function (t) {  // t: 0~1
return value;     // value: 0~1
},
// ...
});
``````

### Has target¶

``````var hasTarget = tween.hasTarget(gameObject);
``````

### Tween value¶

``````var tween = scene.tweens.addCounter({
from: 0,
to: 1,
ease: 'Linear',       // 'Cubic', 'Elastic', 'Bounce', 'Back'
duration: 1000,
repeat: 0,            // -1: infinity
yoyo: false,
onUpdate(tween, targets, key, current, previous, param) {
// var value = current;
// var value = tween.getValue();
}
});
``````
• Get value
``````var value = tween.getValue();
``````

### Chain¶

#### Create chain¶

``````var chain = scene.tweens.chain({
targets: null,
tweens: [
{
// targets: gameObject,
alpha: 1,
ease: 'Linear',       // 'Cubic', 'Elastic', 'Bounce', 'Back'
duration: 1000,
repeat: 0,            // -1: infinity
yoyo: false
},
// ...
],

delay: 0,
completeDelay: 0,
loop: 0,  // repeat: 0,
repeatDelay: 0,
paused: false,
persist: true,
// callbackScope: this,
})
``````
• `targets`, or `tweenConfig.targets`
• `tweens` : Array of tween config

#### Pause / Resume chain¶

``````chain.pause();
``````
``````chain.resume();
``````

#### Restart chain¶

``````chain.restart();
``````

``````chain.add({
targets: gameObject,
alpha: 1,
ease: 'Linear',       // 'Cubic', 'Elastic', 'Bounce', 'Back'
duration: 1000,
repeat: 0,            // -1: infinity
yoyo: false
})
``````

or

``````chain.add([tweenConfig0, tweenConfig1, ...]);
``````

``````chain.remove(tweenTask);
``````

#### Has target¶

``````var hasTarget = chain.hasTarget(gameObject);
``````

### Flow chart¶

``````graph TB

Start((Start)) --> CallbackOnStart
CallbackOnStart>"Callback: onStart"] --> ActiveDelay(("delay"))
ActiveDelay --> DurationForward

DurationForward(("Tween forward<br>Callback: onUpdate<br>(duration)")) --> Hold["hold"]
Hold((hold)) --> IsYoyo{Is yoyo}
IsYoyo --> |Yes| CallbackOnYoyo>"Callback: onYoyo"]
CallbackOnYoyo --> DurationBackward(("Tween backword<br>Callback: onUpdate<br>(duration)"))
DurationBackward --> IsRepeat{"Repeat count > 0"}
IsYoyo --> |No| IsRepeat
IsRepeat --> |Yes| CallbackOnRepeat>"Callback: onRepeat"]
CallbackOnRepeat --> RepeatDelay(("repeatDelay"))
RepeatDelay --> DurationForward

IsRepeat --> |No| IsLoop{"Loop count > 0"}

IsLoop --> |Yes| CallbackOnLoop
CallbackOnLoop>"Callback: onLoop"] --> LoopDelay(("loopDelay"))
LoopDelay --> DurationForward

IsLoop --> |No| CompleteDelay
CompleteDelay(("completeDelay")) --> CallbackOnComplete>"Callback: onComplete"]
CallbackOnComplete --> End((End))``````

### Tween data¶

• `tween.data` : An array of TweenData objects, each containing a unique property and target being tweened.
• `tween.data[i].key` : The property of the target to tween.
• `tween.data[i].start`, `tween.data[i].end`, `tween.data[i].current` : Ease Value Data.