Tween task

Introduction¶

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

Author: Richard Davey

Usage¶

Create tween task¶

var tween = scene.tweens.add({
    targets: gameObject,
    alpha: 1,
    // alpha: '+=1',
    // alpha: { from: 0, to: 1 },
    // alpha: { start: 0, to: 1 },  
    // alpha: { start: value0, from: value1, to: value2 },  
    // alpha: function(target, key, value, targetIndex, totalTargets, tween)  { return newValue; },
    // alpha: {
    //      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
});

key: value2 : Tween to value2.
key: '+=deltaValue' : Tween to current value + deltaValue
- Support these expressions : key: '+=deltaValue', key: '-=deltaValue', key: '*=deltaValue', key: '/=deltaValue'
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 () {},
    onStartScope: callbackScope,
    onStartParams: [],

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

    // tween duration
    duration: 1000,  // function(target, targetKey, value, targetIndex, totalTargets, tween) { },
    ease: 'Linear',
    easeParams: null,

    onActive: function () {},
    onUpdate: function () {},
    onUpdateScope: callbackScope,
    onUpdateParams: [],

    // delay between tween and yoyo
    hold: 0,  // function(target, targetKey, value, targetIndex, totalTargets, tween) { },
    yoyo: false,  // true to tween backward
    flipX: false,
    flipY: false,
    onYoyo: function () {},
    onYoyoScope: callbackScope,
    onYoyoParams: [],

    // repeat count (-1: infinite)
    repeat: 0,  // function(target, targetKey, value, targetIndex, totalTargets, tween) { },
    onRepeat: function () {},
    onRepeatScope: callbackScope,
    onRepeatParams: [],
    // delay to next pass
    repeatDelay: 0,  // function(target, targetKey, value, targetIndex, totalTargets, tween) { },

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

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

    // 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;
                }
            }
        },
        ....
    },

    offset: null,
    useFrames: false
});

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 :
```
function(target, targetKey, value, targetIndex, totalTargets, tween) { 
    return delay;
}
```
- 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
- A number, for all targets
- A callback function :
```
function(target, targetKey, value, targetIndex, totalTargets, tween) { 
    return duration;
}
```
- A callback function, built via stagger builder
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
- A number, for all targets
- A callback function :
```
function(target, targetKey, value, targetIndex, totalTargets, tween) { 
    return hold;
}
```
- A callback function, built via stagger builder
repeat : The number of times the tween will repeat itself (a value of 1 means the tween will play twice, as it repeated once)
- A number, for all targets
- A callback function :
```
function(target, targetKey, value, targetIndex, totalTargets, tween) { 
    return duration;
}
```
- A callback function, built via stagger builder
repeatDelay : The time the tween will pause for before starting a repeat. The tween holds in the start state.
- A number, for all targets
- A callback function :
```
function(target, targetKey, value, targetIndex, totalTargets, tween) { 
    return duration;
}
```
- A callback function, built via stagger builder
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
offset : Used when the Tween is part of a Timeline
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?
useFrames : Use frames or milliseconds?
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) { }
```
onComplete : Tween completes or is stopped.
```
function(tween, targets) { }
```
onYoyo : A tween property yoyos.
```
function(tween, key, target) { }
```
onLoop : A tween loops, after any loop delay expires.
```
function(tween, targets) { }
```
onRepeat : A tween property repeats, after any repeat delay expires.
```
function(tween, target) { }
```
onStop : A tween property stopped.
```
function(tween, targets) { }
```

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

Pause / Resume task¶

tween.pause();

tween.resume();

Stop task¶

tween.stop();

Play task¶

tween.play();

Restart task¶

tween.restart();

Remove task¶

tween.remove();

Get tweens¶

Returns an array of all Tweens or Timelines in the Tween Manager which affect the given target or array of targets.

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.

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);

A tween property updates.
```
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 yoyos.

tween.on('yoyo', function(tween, key, target){

}, scope);

A tween stopped.

tween.on('stop', function(tween, targets){

}, scope);

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;
```

Tween value¶

Create tween task

var tween = scene.tweens.addCounter({
    from: 0,
    to: 1,
    ease: 'Linear',       // 'Cubic', 'Elastic', 'Bounce', 'Back'
    duration: 1000,
    repeat: 0,            // -1: infinity
    yoyo: false,
});

or

var tween = scene.tweens.addCounter({
    from: 0,
    to: 1,
    // ...
});

Get value
```
var value = tween.getValue();
```

Custom ease function¶

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

Flow chart¶

graph TB

Start((Start)) --> CallbackOnStart
CallbackOnStart>"Callback: onStart"] --> ActiveDelay["delay"]
ActiveDelay --> DurationForward["Tween forward<br>Callback: onUpdate<br>(duration)"]

subgraph A pass

DurationForward --> 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

end

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.