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 tovalue2
.key: '+=deltaValue'
: Tween to current value + deltaValue- Support these expressions :
key: '+=deltaValue'
,key: '-=deltaValue'
,key: '*=deltaValue'
,key: '/=deltaValue'
- Support these expressions :
key: { from: value1, to: value2 }
: Set the property tovalue11
when tween started after delay, then tween tovalue2
.value1
,value2
: A number, string, or callback(function(target, key, value, targetIndex, totalTargets, tween) { return newValue; }
)key: { start: value0, to: value2 }
: Set the property tovalue0
immediately, then tween tovalue2
.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 tovalue0
immediately, then set tovalue1
when tween started after delay, then tween tovalue2
.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
toendValue
:scene.tweens.stagger(endValue)
- From
startValue
toendValue
:scene.tweens.stagger([startValue, endValue])
- From
0
toendValue
, with specific ease function :scene.tweens.stagger(endValue, {ease: 'cubic.inout'})
- From
startValue
toendValue
, with specific ease function :scene.tweens.stagger([startValue, endValue], {ease: 'cubic.inout'})
- From
0
toendValue
, with specific start index :scene.tweens.stagger(endValue, {from: 'last'})
scene.tweens.stagger(endValue, {from: 'center'})
scene.tweens.stagger(endValue, {from: index})
- From
startValue
toendValue
, , 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
toendValue
, with specific ease function, with specific start index :scene.tweens.stagger(endValue, {from: 'last', ease: 'cubic.inout'})
- From
startValue
toendValue
, with specific ease function , with specific start index :scene.tweens.stagger([startValue, endValue], {from: 'last', ease: 'cubic.inout'})
- Grid mode. From
0
toendValue
.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
toendValue
.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'})
- From
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 tweeneaseParams
: 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 endflipY
: flip Y the GameObject on tween endoffset
: Used when the Tween is part of a TimelinecompleteDelay
: The time the tween will wait before the onComplete event is dispatched once it has completedloop
:-1
for an infinite looploopDelay
paused
: Does the tween start in a paused state, or playing?useFrames
: Use frames or milliseconds?props
: The properties being tweened by the tweenonActive
: Tween becomes active within the Tween Manager.function(tween, target) { }
onStart
: A tween starts.function(tween, targets) { }
onUpdate
: Callback which fired when tween task updatedfunction(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
: LinearPower1
: Quadratic.OutPower2
: Cubic.OutPower3
: Quartic.OutPower4
: Quintic.OutLinear
Quad
: Quadratic.OutCubic
: Cubic.OutQuart
: Quartic.OutQuint
: Quintic.OutSine
: Sine.OutExpo
: Expo.OutCirc
: Circular.OutElastic
: Elastic.OutBack
: Back.OutBounce
: Bounce.OutStepped
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
: Settrue
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
orscale
.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
or
var tween = scene.tweens.addCounter({ from: 0, to: 1, ease: 'Linear', // 'Cubic', 'Elastic', 'Bounce', 'Back' duration: 1000, repeat: 0, // -1: infinity yoyo: false, });
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.