Use this skill when animating properties over time in Phaser 4. Covers tweens, tween chains, easing functions, stagger, yoyo, repeat, callbacks, number tweens, and the TweenManager. Triggers on: tween, ease, animate, this.tweens.add, tween chain, stagger.

Tweens Animating properties over time in Phaser 4 TweenManager, creating tweens, tween config, easing functions, tween chains, stagger, yoyo, repeat, callbacks, and tween targets. Key source paths: src/tweens/TweenManager.js , src/tweens/tween/Tween.js , src/tweens/tween/TweenChain.js , src/tweens/tween/BaseTween.js , src/tweens/builders/ , src/tweens/typedefs/ , src/tweens/events/ , src/math/easing/ Related skills: ../sprites and images/SKILL.md, ../animations/SKILL.md Quick Start this.tweens is the scene's TweenManager instance, available in every Scene. The add() method creates a tween, adds it to the manager, and starts playback immediately. Core Concepts Tween Lifecycle Created Active ( onActive ) Start Delayed ( delay ) Playing ( onStart , onUpdate per frame) Yoyo/Repeat ( onYoyo , onRepeat ) Loop ( onLoop ) Complete ( onComplete , then auto destroyed unless persist: true ). Fire and Forget Design Tweens auto destroy after completion. You do not need to store a reference unless you want to control them later. Set persist: true in the config to keep a tween alive after completion for replay via tween.play() or tween.restart() . You must manually call tween.destroy() on persisted tweens when done. Targets The targets property accepts a single object, an array of objects, or a function that returns either. Targets are typically Game Objects but can be any JavaScript object with numeric properties. A tween will not manipulate any property that begins with an underscore. Property Values Array values use linear interpolation by default; override with the interpolation config ( 'linear' , 'bezier' , 'catmull' ). Common Patterns Basic Tween Multiple Properties with Per Property Config Yoyo and Repeat repeat controls how many extra times each property plays. A repeat of 1 means the tween plays twice total. The loop property (on BaseTween ) restarts the entire tween from scratch, including all properties. Use repeat for property level looping and loop for tween level looping. Stagger Stagger offsets a value across multiple targets via this.tweens.stagger() : StaggerConfig: start (offset), ease (string/function), from ( 'first' / 'center' / 'last' /index), grid ([w, h]). Tween Chain A TweenChain plays tweens in sequence. Each tween in the chain starts after the previous one completes: Each entry in tweens is a standard TweenBuilderConfig . Chain level config supports loop , loopDelay , completeDelay , paused , persist , and chain level callbacks. Per tween callbacks ( onUpdate , onRepeat , onYoyo ) belong on individual entries. Use chain.add(tweenConfigs) to append dynamically. Relative Values Callbacks and Events Number Tweens A Number Tween has no target object. It tweens between two numeric values: Controlling and Killing Tweens Configuration Reference TweenBuilderConfig Property Type Default Description targets any / any[] (required) Object(s) to tween. duration number 1000 Duration in ms. delay number / function 0 Delay before start (ms). Accepts stagger() . ease string / function 'Power0' Easing function name or custom function. easeParams array null Parameters for parameterized easing (e.g. Elastic). hold number 0 Hold at end value before yoyo (ms). repeat number 0 Per property repeat count. 1 = infinite. repeatDelay number 0 Delay before each repeat (ms). yoyo boolean false Reverse back to start after reaching end. flipX / flipY boolean false Toggle flip on yoyo/repeat. loop number 0 Tween level loop count. 1 = infinite. loopDelay number 0 Delay before each loop (ms). completeDelay number 0 Delay before onComplete fires (ms). paused boolean false Start paused. Call play() to begin. persist boolean false Keep alive after completion. props object Explicit property config map (alt to top level props). interpolation string / function For array values: 'linear' , 'bezier' , 'catmull' . callbackScope any tween this context for callbacks. Callbacks function onActive , onStart , onUpdate , onYoyo , onRepeat , onLoop , onComplete , onStop , onPause , onResume . Each has matching on<Name Params array. TweenChainBuilderConfig Property Type Default Description targets any / any[] Default targets inherited by child tweens. tweens TweenBuilderConfig[] (required) Array of tween configs to play in sequence. loop number 0 Times to loop the entire chain. 1 = infinite. loopDelay number 0 Delay before each loop (ms). completeDelay number 0 Delay before onComplete fires (ms). paused boolean false Start paused. persist boolean false Keep alive after completion. Callbacks function onActive , onStart , onLoop , onComplete , onStop , onPause , onResume . NumberTweenBuilderConfig Property Type Default Description from number 0 Start value. to number 1 End value. duration number 1000 Duration in ms. ease string / function 'Power0' Easing function. All standard timing delay , hold , repeat , repeatDelay , yoyo , loop , loopDelay , completeDelay , paused , persist . All standard callbacks Same callback set as TweenBuilderConfig. TweenPropConfig (Per Property Object) Used when a property value is an object instead of a number/string. Supports: value , getActive , getEnd , getStart , ease , delay , duration , yoyo , hold , repeat , repeatDelay , flipX , flipY , interpolation . All override the tween level defaults for that one property. Easing Functions All easing names are case insensitive. Use the string name in the ease config property. Power Aliases Name Equivalent Power0 Linear Power1 Quad.easeOut (Quadratic Out) Power2 Cubic.easeOut Power3 Quart.easeOut (Quartic Out) Power4 Quint.easeOut (Quintic Out) Full Easing List Each type supports .easeIn , .easeOut , .easeInOut variants. The bare name defaults to Out. Types: Quad , Cubic , Quart , Quint , Sine , Expo , Circ , Elastic , Back , Bounce . Usage: 'Sine.easeInOut' , 'Bounce.easeIn' , 'Cubic.easeOut' , 'Back' (same as 'Back.easeOut' ). Special: Linear (no easing), Stepped (discrete steps easeParams: [numSteps] ). Custom: ease: function (t) { return t t; } where t is 0 to 1. Events Tweens (and TweenChains) extend EventEmitter . You can listen via .on() : Event String Constant Fires When 'active' Phaser.Tweens.Events.TWEEN ACTIVE Tween added to manager 'start' Phaser.Tweens.Events.TWEEN START Playback begins (after delay) 'update' Phaser.Tweens.Events.TWEEN UPDATE Property updates each frame 'yoyo' Phaser.Tweens.Events.TWEEN YOYO Property begins yoyo ing back 'repeat' Phaser.Tweens.Events.TWEEN REPEAT Property repeats 'loop' Phaser.Tweens.Events.TWEEN LOOP Entire tween loops 'complete' Phaser.Tweens.Events.TWEEN COMPLETE Tween finishes 'stop' Phaser.Tweens.Events.TWEEN STOP tween.stop() called 'pause' Phaser.Tweens.Events.TWEEN PAUSE tween.pause() called 'resume' Phaser.Tweens.Events.TWEEN RESUME tween.resume() called Event listener signature for Tween events: function(tween, targets) . During seeking ( tween.isSeeking === true ), events and callbacks are suppressed by default. API Quick Reference TweenManager ( this.tweens ) Method Returns Purpose add(config) Tween Create, add, and start a tween. addMultiple(configs[]) Tween[] Create multiple tweens at once. create(config) Tween Create without adding. Use existing() to add later. chain(config) TweenChain Create and start a sequential chain. addCounter(config) Tween Number tween (no target). stagger(value, config?) function Stagger function for delay/property values. existing(tween) this Add a pre created tween to the manager. remove(tween) this Remove without destroying. has(tween) boolean Check if tween is in manager. getTweens() Tween[] All active tweens (copy). getTweensOf(target) Tween[] Tweens affecting a target. isTweening(target) boolean Is target being tweened? killAll() / killTweensOf(target) this Destroy tweens. pauseAll() / resumeAll() this Pause/resume all tweens. setGlobalTimeScale(v) / getGlobalTimeScale() this / number Global speed. setFps(fps) this Limit tick rate (default 240). setLagSmooth(limit, skip) this Configure lag smoothing. each(cb, scope) this Iterate all tweens. Tween Instance Method Purpose play() / pause() / resume() Playback control. stop() Stop and flag for removal. Fires onStop . restart() Reset and replay. complete(delay?) Immediately complete. completeAfterLoop(loops?) Complete after N more loops. seek(ms, delta?, emit?) Seek to ms offset. forward(ms) / rewind(ms) Step forward/back. setTimeScale(v) / getTimeScale() Per tween speed. setCallback(type, fn, params?) Set callback after creation. getValue(index?) Current TweenData value. updateTo(key, value, startToCurrent?) Change end value mid tween. hasTarget(target) / isPlaying() / isPaused() State checks. remove() / destroy() Cleanup. Key properties: targets , duration , elapsed , progress (0 1), totalProgress (0 1 including loops), totalDuration , timeScale , paused , persist , data (TweenData[]), isInfinite , isNumberTween . TweenChain Instance Extends BaseTween . Has all tween playback methods ( play , pause , resume , stop , restart , complete , etc.) plus add(tweenConfigs) to append tweens dynamically. Properties: currentTween , currentIndex . Gotchas Underscore properties are ignored. A tween will skip any property whose name starts with . Tweens auto destroy. If you store a reference to a tween and try to use it after completion, it may be destroyed. Set persist: true to keep it alive, but you must destroy() it yourself when done. repeat vs loop . repeat is per property (on TweenData). loop restarts the entire tween. A repeat of 1 means the property plays twice total. loop: 1 means onComplete never fires. An infinitely looping tween never completes. Use completeAfterLoop() to end it gracefully. Seeking suppresses events. When calling tween.seek() , events and callbacks are not dispatched unless you pass true as the third argument. Stagger only works with multiple targets. Using this.tweens.stagger() on a single target tween has no visible stagger effect. Destroyed targets. A tween completes early if its target has isDestroyed set to true . Always clean up tweens before destroying the objects they reference, or rely on this auto check. TweenManager.timeScale multiplies with Tween.timeScale. The effective speed is managerTimeScale tweenTimeScale . Setting either to 0 freezes the tween. Duration cannot be zero. Internally clamped to a minimum of 0.01ms. TweenChain targets are inherited. If you set targets at the chain level, individual tweens in the chain inherit them unless they specify their own. Source File Map File Purpos