0
# Tweens & Timeline Animation
1

2
Phaser's tweening system provides smooth property animations and complex animation sequences. It offers individual tweens, tween chains, and timeline-based animation management for creating sophisticated visual effects.
3

4
## Capabilities
5

6
### Tween Manager
7

8
Scene-based tween coordination and management for all tweening operations.
9

10
```javascript { .api }
11
// Create basic tween
12
scene.tweens.add({
13
    targets: sprite,
14
    x: 400,
15
    y: 300,
16
    duration: 2000,
17
    ease: 'Power2',
18
    onComplete: function() {
19
        console.log('Tween completed');
20
    }
21
});
22

23
// Multiple property tween
24
scene.tweens.add({
25
    targets: [sprite1, sprite2],
26
    x: '+=100',
27
    y: '-=50',
28
    scaleX: 2,
29
    scaleY: 2,
30
    rotation: Math.PI,
31
    alpha: 0.5,
32
    duration: 1500
33
});
34

35
// Advanced tween configuration
36
scene.tweens.add({
37
    targets: sprite,
38
    props: {
39
        x: { value: 600, duration: 2000, ease: 'Power1' },
40
        y: { value: 200, duration: 1000, ease: 'Bounce.easeOut' },
41
        scaleX: { value: 3, duration: 3000, ease: 'Back.easeInOut' }
42
    },
43
    delay: 500,
44
    repeat: 2,
45
    yoyo: true,
46
    paused: false
47
});
48
```
49

50
### Tween Creation Methods
51

52
```javascript { .api }
53
// Basic add method
54
scene.tweens.add(config);
55

56
// Timeline creation
57
scene.tweens.timeline(config);
58

59
// Counter tween (number animation)
60
scene.tweens.addCounter({
61
    from: 0,
62
    to: 100,
63
    duration: 2000,
64
    onUpdate: function(tween) {
65
        text.setText(Math.floor(tween.getValue()));
66
    }
67
});
68

69
// Chain multiple tweens
70
scene.tweens.chain({
71
    targets: sprite,
72
    tweens: [
73
        { x: 200, duration: 1000 },
74
        { y: 200, duration: 1000 },
75
        { x: 100, y: 100, duration: 1000 }
76
    ]
77
});
78
```
79

80
### Tween Control
81

82
```javascript { .api }
83
// Get tween reference for control
84
const tween = scene.tweens.add({
85
    targets: sprite,
86
    x: 400,
87
    duration: 2000,
88
    paused: true
89
});
90

91
// Tween control methods
92
tween.play();         // Start/resume tween
93
tween.pause();        // Pause tween
94
tween.resume();       // Resume paused tween
95
tween.stop();         // Stop and remove tween
96
tween.restart();      // Restart from beginning
97
tween.complete();     // Jump to end
98
tween.seek(0.5);      // Jump to 50% completion
99
tween.setTimeScale(2); // Double speed
100
```
101

102
### Timeline System
103

104
Complex animation sequences with precise timing control.
105

106
```javascript { .api }
107
// Create timeline
108
const timeline = scene.tweens.timeline({
109
    loop: 2,
110
    loopDelay: 500,
111
    onComplete: function() {
112
        console.log('Timeline completed');
113
    }
114
});
115

116
// Add tweens to timeline
117
timeline.add({
118
    targets: sprite1,
119
    x: 200,
120
    duration: 1000,
121
    offset: 0        // Start immediately
122
});
123

124
timeline.add({
125
    targets: sprite2,
126
    y: 200,
127
    duration: 800,
128
    offset: 500      // Start 500ms after timeline start
129
});
130

131
timeline.add({
132
    targets: [sprite1, sprite2],
133
    alpha: 0,
134
    duration: 500,
135
    offset: '-=200'  // Start 200ms before previous tween ends
136
});
137

138
timeline.play();
139
```
140

141
### Easing Functions
142

143
```javascript { .api }
144
// Linear easing
145
'Linear'
146

147
// Power easing
148
'Power0', 'Power1', 'Power2', 'Power3', 'Power4'
149

150
// Back easing (overshoot)
151
'Back.easeIn', 'Back.easeOut', 'Back.easeInOut'
152

153
// Bounce easing
154
'Bounce.easeIn', 'Bounce.easeOut', 'Bounce.easeInOut'
155

156
// Elastic easing
157
'Elastic.easeIn', 'Elastic.easeOut', 'Elastic.easeInOut'
158

159
// Expo easing
160
'Expo.easeIn', 'Expo.easeOut', 'Expo.easeInOut'
161

162
// Sine easing
163
'Sine.easeIn', 'Sine.easeOut', 'Sine.easeInOut'
164

165
// Circular easing
166
'Circ.easeIn', 'Circ.easeOut', 'Circ.easeInOut'
167

168
// Cubic easing
169
'Cubic.easeIn', 'Cubic.easeOut', 'Cubic.easeInOut'
170

171
// Quartic easing
172
'Quart.easeIn', 'Quart.easeOut', 'Quart.easeInOut'
173

174
// Quintic easing
175
'Quint.easeIn', 'Quint.easeOut', 'Quint.easeInOut'
176

177
// Custom easing function
178
function(t) {
179
    return t * t * t; // Custom cubic curve
180
}
181
```
182

183
### Tween Configuration Options
184

185
```javascript { .api }
186
const tweenConfig = {
187
    targets: sprite,           // Target object(s)
188
    x: 400,                   // End value
189
    y: '+=200',              // Relative value
190
    scaleX: { from: 1, to: 2 }, // Start and end values
191
    
192
    // Timing
193
    duration: 2000,           // Animation duration in ms
194
    delay: 500,              // Start delay in ms
195
    
196
    // Repetition
197
    repeat: 3,               // Number of repeats (-1 for infinite)
198
    repeatDelay: 200,        // Delay between repeats
199
    yoyo: true,              // Reverse on repeat
200
    
201
    // Easing
202
    ease: 'Power2',          // Easing function
203
    
204
    // Playback
205
    paused: false,           // Start paused
206
    
207
    // Callbacks
208
    onStart: function(tween, targets) {},
209
    onUpdate: function(tween, targets) {},
210
    onYoyo: function(tween, targets) {},
211
    onRepeat: function(tween, targets) {},
212
    onComplete: function(tween, targets) {},
213
    
214
    // Callback scopes
215
    onStartScope: this,
216
    onUpdateScope: this,
217
    onCompleteScope: this
218
};
219
```
220

221
### Complex Animation Examples
222

223
```javascript { .api }
224
// Staggered animation
225
scene.tweens.add({
226
    targets: spriteArray,
227
    x: 300,
228
    duration: 1000,
229
    delay: scene.tweens.stagger(100) // 100ms delay between each sprite
230
});
231

232
// Property interpolation
233
scene.tweens.add({
234
    targets: sprite,
235
    x: [100, 200, 150, 400], // Tween through multiple values
236
    duration: 2000
237
});
238

239
// Custom property tweening
240
scene.tweens.add({
241
    targets: customObject,
242
    customValue: 100,
243
    duration: 2000,
244
    onUpdate: function() {
245
        // Use customObject.customValue in your logic
246
        updateCustomGraphics(customObject.customValue);
247
    }
248
});
249

250
// Tween with pause and resume
251
const tween = scene.tweens.add({
252
    targets: sprite,
253
    x: 400,
254
    duration: 4000,
255
    paused: true
256
});
257

258
// Resume after 2 seconds
259
scene.time.delayedCall(2000, function() {
260
    tween.resume();
261
});
262
```
263

264
## Types
265

266
```javascript { .api }
267
interface TweenConfig {
268
    targets: any | any[];
269
    delay?: number;
270
    duration?: number;
271
    ease?: string | function;
272
    repeat?: number;
273
    repeatDelay?: number;
274
    yoyo?: boolean;
275
    paused?: boolean;
276
    onStart?: function;
277
    onUpdate?: function;
278
    onYoyo?: function;
279
    onRepeat?: function;
280
    onComplete?: function;
281
}
282

283
interface TimelineConfig {
284
    loop?: number;
285
    loopDelay?: number;
286
    paused?: boolean;
287
    onStart?: function;
288
    onUpdate?: function;
289
    onLoop?: function;
290
    onYoyo?: function;
291
    onComplete?: function;
292
}
293

294
class Tween {
295
    play(): this;
296
    pause(): this;
297
    resume(): this;
298
    stop(): this;
299
    restart(): this;
300
    complete(): this;
301
    seek(progress: number): this;
302
    setTimeScale(scale: number): this;
303
    getProgress(): number;
304
    getTotalProgress(): number;
305
    isPlaying(): boolean;
306
    isPaused(): boolean;
307
}
308

309
class Timeline {
310
    add(config: TweenConfig): this;
311
    play(): this;
312
    pause(): this;
313
    resume(): this;
314
    stop(): this;
315
    destroy(): void;
316
}
317
```