Time and Timers

--- name: time-and-timers description: "Use this skill when using timers and time-based events in Phaser 4. Covers TimerEvent, delayed calls, looping timers, the Clock plugin, and time scaling. Triggers on: timer, delay, delayedCall, TimerEvent, Clock, time event." --- # Time and Timers > Clock plugin, TimerEvent, delays, loops, Timeline event sequencing, pausing time, time scale, and delta time in Phaser 4. Key source paths: src/time/Clock.js, src/time/TimerEvent.js, src/time/Timeline.js, src/time/typedefs/, src/time/events/ Related skills: ../scenes/SKILL.md, ../tweens/SKILL.md ## Quick Start ``js // In a Scene's create() method: // One-shot delayed call (fires once after 1 second) this.time.delayedCall(1000, () => { console.log('One second later'); }); // Repeating timer (fires 5 times, once every 500ms) this.time.addEvent({ delay: 500, callback: () => { console.log('tick'); }, repeat: 4 // 4 repeats = 5 total fires }); // Infinite loop timer this.time.addEvent({ delay: 1000, callback: this.spawnEnemy, callbackScope: this, loop: true }); ` this.time is the scene's Clock instance (registered as the 'Clock' plugin under the key time). It creates and manages TimerEvent objects that fire callbacks based on game time. ## Core Concepts ### Clock (this.time) The Clock is a Scene-level plugin that tracks game time and updates all of its TimerEvents each frame. Key properties: - **now** -- current time in ms (equivalent to time passed to the scene update method). - **startTime** -- timestamp when the scene started. - **timeScale** -- multiplier applied to delta time. Default 1. Values above 1 speed up all timers; below 1 slow them down; 0 freezes time. - **paused** -- when true, no TimerEvents are updated. The Clock listens to PRE_UPDATE (to flush pending additions/removals) and UPDATE (to tick active events). It is automatically shut down and destroyed with the scene. ### TimerEvent A TimerEvent accumulates elapsed time each frame: elapsed += delta clock.timeScale event.timeScale. When elapsed >= delay, the callback fires. After all repeats are exhausted the event is removed from the Clock on the next frame. Key properties set via config: delay, repeat, loop, callback, callbackScope, args, timeScale, startAt, paused. ### Timeline (this.add.timeline) A Timeline is a sequencer for scheduling actions at specific points in time. Unlike the Clock (which manages independent timers), a Timeline runs a linear sequence of events keyed by absolute or relative timestamps. `js const timeline = this.add.timeline([ { at: 0, run: () => { /* immediate */ } }, { at: 1000, run: () => { /* at 1s */ } }, { at: 2500, tween: { targets: sprite, alpha: 0, duration: 500 } } ]); timeline.play(); ` Timelines always start **paused**. You must call play() to start them. They are created via the GameObjectFactory and destroyed automatically when the scene shuts down. ## Common Patterns ### Delayed Call `js // Shorthand -- fires once, no repeat this.time.delayedCall(2000, () => { this.scene.start('GameOver'); }); ` ### Repeating Timer with Finite Count `js // repeat: 9 means 10 total fires (1 initial + 9 repeats) const timer = this.time.addEvent({ delay: 200, callback: this.fireBullet, callbackScope: this, repeat: 9 }); // Check progress timer.getRepeatCount(); // repeats remaining timer.getOverallProgress(); // 0..1 across all repeats ` ### Infinite Loop `js const spawner = this.time.addEvent({ delay: 3000, callback: this.spawnWave, callbackScope: this, loop: true }); // Stop it later spawner.remove(); // or spawner.paused = true to pause ` Setting repeat: -1 is equivalent to loop: true. ### First-Fire Shortcut with startAt `js // First fire happens quickly (after 100ms), then every 2s this.time.addEvent({ delay: 2000, callback: this.heartbeat, callbackScope: this, loop: true, startAt: 1900 // pre-fill elapsed so first fire is at 100ms }); ` ### Stopping and Removing Timers `js const timer = this.time.addEvent({ delay: 1000, loop: true, callback: fn }); // Option 1: Remove from clock (schedules removal next frame) timer.remove(); // silently expires timer.remove(true); // fires callback one last time, then expires // Option 2: Remove via Clock this.time.removeEvent(timer); // Option 3: Remove all timers this.time.removeAllEvents(); ` ### Pausing and Resuming `js // Pause the entire Clock (all timers freeze) this.time.paused = true; this.time.paused = false; // Pause a single timer timer.paused = true; timer.paused = false; ` ### Time Scale (Slow Motion / Fast Forward) ``js // Slow all timers in this scene to half speed this.time.timeScale = 0.5; // Speed up a single timer to 2x timer.timeScale = 2; // Combined: effective scale = clock.timeScale * event.tim