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

// 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.

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

// Shorthand -- fires once, no repeat
this.time.delayedCall(2000, () => {
    this.scene.start('GameOver');
});

Repeating Timer with Finite Count

// 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

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

// 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

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

// 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)

// 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