9.6 KiB
Phaser 3.60.0 Change Log
Return to the Change Log index.
New Feature - New Tween Manager
TODO - TweenData to class TODO - TweenData and Tween State methods TODO - CONST removals
The Phaser 3.60 Tween system has been rewritten to help with performance, resolve some of its lingering issues and unifies the Tween events and callbacks.
The following are breaking changes:
- Tween Timelines have been removed entirely. Due to the way they were implemented they tended to cause a range of esoteric timing bugs which were non-trivial to resolve. To that end, we made the decision to remove Timelines entirely and introduced the ability to chain tweens together using the new
chain
method. This should give most developers the same level of sequencing they had using Timelines, without the timing issues. - The
Tween.seek
method used to take a value between 0 and 1, based on how far through the Tween you wished to seek. However, it did not work with infinitely looping or repeating Tweens and would crash the browser tab. The newseek
method takes a value in milliseconds instead and works perfectly on infinite Tweens. - When creating a Tween, you can no longer pass a function for the following properties:
duration
,hold
,repeat
andrepeatDelay
. These should be numbers only. You can, however, still provide a function fordelay
, to keep it compatible with the StaggerBuilder. - The
TweenManager#getAllTweens
method has been renamed toTweenManager#getTweens
. Functionally, it is the same. - The property and feature
Tween.useFrames
has been removed and is no longer a valid Tween Config option. Tweens are now entirely millisecond based. - The
TweenOnUpdateCallback
now has the following parameters:tween
,targets
,key
(the property being tweened),current
(the current value of the property),previous
(the previous value of the property) and finally any of the params that were passed in theonUpdateParams
array when the Tween was created. - The
TweenOnYoyoCallback
now has the following parameters:tween
,targets
,key
(the property being tweened),current
(the current value of the property),previous
(the previous value of the property) and finally any of the params that were passed in theonYoyoParams
array when the Tween was created. - The
TweenOnRepeatCallback
now has the following parameters:tween
,targets
,key
(the property being tweened),current
(the current value of the property),previous
(the previous value of the property) and finally any of the params that were passed in theonRepeatParams
array when the Tween was created. Tween.stop
has had theresetTo
parameter removed from it. Callingstop
on a Tween will now prepare the tween for immediate destruction. If you only wish to pause the tween, seeTween.pause
instead.- Tweens will now be automatically destroyed by the Tween Manager upon completion. This helps massively in reducing stale references and memory consumption. However, if you require your Tween to live-on, even after playback, then you can now specify a new
persist
boolean flag when creating it, or toggle theTween.persist
property before playback. This will force the Tween to not be destroyed by the Tween Manager, allowing you to replay it at any later point. The trade-off is that you are now entirely responsible for destroying the Tween when you are finished with it, in order to free-up resources. - All of the 'Scope' tween configuration callback properties have been removed, including
onActiveScope
,onCompleteScope
,onLoopScope
,onPauseScope
,onRepeatScope
,onResumeScope
,onStartScope
,onStopScope
,onUpdateScope
andonYoyoScope
. You should set thecallbackScope
property instead, which will globally set the scope for all callbacks. You can also set theTween.callbackScope
property.
The following are to do with the new Chained Tweens feature:
-
TweenManager.chain
- TODO -
Tween.getChainedTweens
is a new method that will return all of the tweens in a chained sequence, starting from the point of the Tween this is called on. -
TweenManager.getChainedTweens(tween)
is a new method that will return all of the tweens in a chained sequence, starting from the given tween. -
You can now specify a target property as 'random' to have the Tween pick a random float between two given values, for example:
alpha: 'random(0.25, 0.75)'
. If you wish to force it to select a random integer, use 'int' instead:x: 'int(300, 600)'
.
The following are further updates within the Tween system:
TweenManager.add
andTweenManager.create
can now optionally take an array of Tween Configuration objects. Each Tween will be created, added to the Tween Manager and then returned in an array. You can still pass in a single config if you wish.Tween.pause
is a new method that allows you to pause a Tween. This will emit the PAUSE event and, if set, fire theonPause
callback.Tween.resume
is a new method that allows you to resume a paused Tween. This will emit the RESUME event and, if set, fire theonResume
callback.- There is a new
TweenOnPauseCallback
available when creating a Tween (via theonPause
property). This comes with associatedonPauseParams
andonPauseScope
properties, too, like all other callbacks and can also be added via theTween.setCallbacks
method. This callback is invoked if you pause the Tween. - There is a new
TweenOnResumeCallback
available when creating a Tween (via theonResume
property). This comes with associatedonResumeParams
andonResumeScope
properties, too, like all other callbacks and can also be added via theTween.setCallbacks
method. This callback is invoked if you resume a previously paused Tween. - The property value of a Tween can now be an array, i.e.
x: [ 100, 300, 200, 600 ]
in which case the Tween will use interpolation to determine the value. - You can now specify an
interpolation
property in the Tween config to set which interpolation method the Tween will use if an array of numeric values have been given as the tween value. Valid values includeslinear
,bezier
andcatmull
(orcatmullrom
), or you can provide your own function to use. - You can now specify a
scale
property in a Tween config and, if the target does not have ascale
property itself (i.e. a GameObject) then it will automatically apply the value to bothscaleX
andscaleY
together during the tween. This is a nice short-cut way to tween the scale of Game Objects by only specifying one property, instead of two. killTweensOf(targets)
now supports deeply-nested arrays of items as thetarget
parameter. Fix #6016 (thanks @michalfialadev)killTweensOf(target)
did not stop target tweens if called immediately after tween creation. Fix #6173 (thanks @michalfialadev)- It wasn't possible to resume a Tween that was immediately paused after creation. Fix #6169 (thanks @trynx)
- Calling
Tween.setCallback()
without specifying theparams
argument would cause an error invoking the callback params. This parameter is now fully optional. Fix #6047 (thanks @orcomarcio) - Calling
Tween.play
immediately after creating a tween withpaused: true
in the config wouldn't start playback. Fix #6005 (thanks @MartinEyebab) - Fixed an issue where neither Tweens or Timelines would factor in the Tween Manager
timeScale
value unless they were using frame-based timing instead of delta timing. - The first parameter to
Tween.seek
,toPosition
now defaults to zero. Previously, you had to specify a value. - The
TweenBuilder
now uses the newGetInterpolationFunction
function internally. - The
TweenBuilder
has been optimized to perform far less functions when creating the TweenData instances. - The keyword
interpolation
has been added to the Reserved Words list and Defaults list (it defaults tonull
). - The keyword
persist
has been added to the Reserved Words list and Defaults list (it defaults tofalse
). Tween.initTweenData
is a new method that handles the initialisation of all the Tween Data and Tween values. This replaces what took place in theinit
andseek
methods previously. This is called automatically and should not usually be invoked directly.- The internal
Tween.calcDuration
method has been removed. This is now handled as part of theinitTweenData
call. - Fixed a bug where setting
repeat
andhold
would cause the Tween to include one final hold before marking itself as complete. It now completes as soon as the final repeat concludes, not after an addition hold. TweenManager.reset
is a new method that will take a tween, remove it from all internal arrays, then seek it back to its start and set it as being active.dispatchTweenEvent
would overwrite one of the callback's parameters. This fix ensures thatTween.setCallback
now works consistently. Fix #5753 (thanks @andrei-pmbcn @samme)- Calling
Tween.reset
when a tween was in a state ofPENDING_REMOVE
would cause it to fail to restart. It now restarts fully. Fix #4793 (thanks @spayton) - The default
Tween._pausedState
has changed fromINIT
toPENDING_ADD
. This fixes a bug where if you calledTween.play
immediately after creating it, it would force the tween to freeze. Fix #5454 (thanks @michal-bures) - Calling
Tween.stop(0)
would run for an additional delta before stopping, causing the Tween to not be truly 100% "reset". Fix #5986 (thanks @Mesonyx)
Return to the Change Log index.
📖 Read the Phaser 3 API Docs 💻 Browse 2000+ Code Examples 🤝 Join the awesome Phaser Discord