tweens

# 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 ```js // In a Scene's create() method: const logo = this.add.image(100, 300, 'logo'); // Basic tween -- move the logo to x:600 over 2 seconds this.tweens.add({ targets: logo, x: 600, duration: 2000, ease: 'Power2' }); ``` `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. ```js // Single target this.tweens.add({ targets: sprite, alpha: 0, duration: 500 }); // Multiple targets this.tweens.add({ targets: [sprite1, sprite2, sprite3], y: 100, duration: 1000 }); ``` ### Property Values ```js this.tweens.add({ targets: sprite, x: 400, // absolute value y: '-=100', // relative (subtract 100 from current) rotation: '+=3.14', // relative (add to current) alpha: { value: 0, duration: 300, ease: 'Cubic.easeIn' }, // per-property config scale: [0.5, 1.5, 1], // array: interpolates through values over duration angle: function (target, key, value, targetIndex, totalTargets, tween) { return targetIndex * 90; // function: called once per target }, duration: 1000 }); ``` Array values use linear interpolation by default; override with the `interpolation` config (`'linear'`, `'bezier'`, `'catmull'`). ## Common Patterns ### Basic Tween ```js this.tweens.add({ targets: this.player, x: 500, y: 300, duration: 1000, ease: 'Sine.easeInOut' }); ``` ### Multiple Properties with Per-Property Config ```js this.tweens.add({ targets: this.enemy, x: { value: 600, duration: 1500, ease: 'Bounce.easeOut' }, y: { value: 200, duration: 1000, ease: 'Power2' }, alpha: { value: 0.5, duration: 500, delay: 1000 } }); ``` ### Yoyo and Repeat ```js this.tweens.add({ targets: this.coin, y: '-=50', duration: 600, ease: 'Sine.easeInOut', yoyo: true, // returns to start value after reaching end hold: 200, // pause 200ms at the end value before yoyo-ing back repeat: -1, // -1 = infinite, 0 = play once, 1 = play twice, etc. repeatDelay: 300 // pause 300ms before each 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()`: ```js // 100ms delay between each target delay: this.tweens.stagger(100) // From center outward delay: this.tweens.stagger(200, { from: 'center' }) // Range: distribute 0-1000ms across targets delay: this.tweens.stagger([0, 1000]) // Grid stagger with easing delay: this.tweens.stagger(500, { grid: [10, 6], from: 'center', ease: 'Cubic.easeOut' }) ``` **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: ```js this.tweens.chain({ targets: this.player, tweens: [ { x: 300, duration: 1000, ease: 'Power2' }, { y: 500, duration: 800, ease: 'Bounce.easeOut' }, { scale: 2, duration: 500 }, { alpha: 0, duration: 400 } ], loop: 1, // loop the entire chain once (plays twice total) loopDelay: 500, onComplete: function () { console.log('Chain finished'); } }); ``` 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 ```js this.tweens.add({ targets: sprite, x: '+=200', // add 200 to current x y: '-=50', // subtract 50 from current y angle: '+=180', duration: 1000 }); ``` ### Callbacks and Events ```js this.tweens.add({ targets: sprite, x: 600, duration: 2000, // All callbacks receive (tween, targets, ...params) onStart: function (tween, targets) { }, onUpdate: function (tween, targets) { }, // per-property, per-target, per-frame onYoyo: function (tween, targets) { }, onRepeat: function (tween, targets) { }, onLoop: function (tween, targets) { }, onComplete: function (tween, targets) { }, onCompleteParams: ['extra', 'args'], callbackScope: this }); // Set callback after creation tween.setCallback('onComplete', function (tween, targets) { }, []); // Event emitter style (tweens extend EventEmitter) tween.on('complete', function (tween, targets) { }); ``` ### Number Tweens A Number Tween has no target object. It tweens between two numeric values: ```js const counter = this.tweens.addCounter({ from: 0, to: 100, duration: 2000, ease: 'Linear', onUpdate: function (tween) { const value = tween.getValue(); console.log(value); // 0 ... 100 } }); ``` ### Controlling and Killing Tweens ```js const tween = this.tweens.add({ targets: sprite, x: 600, duration: 2000, persist: true }); // Playback control tween.pause(); tween.resume(); tween.stop(); // flags for removal; fires onStop tween.restart(); // reset and replay from beginning tween.seek(1000); // seek to 1000ms (suppresses events by default) tween.complete(); // immediately complete; fires onComplete tween.completeAfterLoop(0); // finish after current loop tween.forward(500); tween.rewind(500); tween.setTimeScale(0.5); // per-tween speed tween.updateTo('x', 800); // change end value mid-tween // Manager-level control this.tweens.killAll(); // destroy all tweens this.tweens.killTweensOf(sprite); // destroy tweens on target this.tweens.isTweening(sprite); // boolean check this.tweens.pauseAll(); this.tweens.resumeAll(); this.tweens.setGlobalTimeScale(0.5); // global speed ``` ## 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)