@vpmedia/phaser 1.112.0 → 1.113.0

package/src/phaser/core/time.ts

@@ -2,38 +2,38 @@ import type { Game } from './game.js';
 import { Timer } from './timer.js';
 
 export class Time {
-  game!: Game;
-  time!: number;
-  prevTime!: number;
-  now!: number;
-  elapsed!: number;
-  elapsedMS!: number;
-  desiredFpsMult!: number;
-  _desiredFps!: number;
-  suggestedFps!: number;
-  advancedTiming!: boolean;
-  frames!: number;
-  fps!: number;
-  fpsMin!: number;
-  fpsMax!: number;
-  msMin!: number;
-  msMax!: number;
-  pauseDuration!: number;
-  timeToCall!: number;
-  timeExpected!: number;
-  events!: Timer;
-  _frameCount!: number;
-  _elapsedAccumulator!: number;
-  _started!: number;
-  _timeLastSecond!: number;
-  _pauseStarted!: number;
-  _justResumed!: boolean;
-  _timers!: Timer[];
+  public game!: Game;
+  public time!: number;
+  public prevTime!: number;
+  public now!: number;
+  public elapsed!: number;
+  public elapsedMS!: number;
+  public desiredFpsMult!: number;
+  public _desiredFps!: number;
+  public suggestedFps!: number;
+  public advancedTiming!: boolean;
+  public frames!: number;
+  public fps!: number;
+  public fpsMin!: number;
+  public fpsMax!: number;
+  public msMin!: number;
+  public msMax!: number;
+  public pauseDuration!: number;
+  public timeToCall!: number;
+  public timeExpected!: number;
+  public events!: Timer;
+  public _frameCount!: number;
+  public _elapsedAccumulator!: number;
+  public _started!: number;
+  public _timeLastSecond!: number;
+  public _pauseStarted!: number;
+  public _justResumed!: boolean;
+  public _timers!: Timer[];
   /**
    * Creates a new Time instance.
-   * @param {import('./game.js').Game} game - Reference to the Phaser Game instance.
+   * @param {Game} game - Reference to the Phaser Game instance.
    */
-  constructor(game: Game) {
+  public constructor(game: Game) {
     this.game = game;
     this.time = 0;
     this.prevTime = 0;
@@ -66,7 +66,7 @@ export class Time {
   /**
    * Initializes the time manager and starts tracking time.
    */
-  boot() {
+  public boot() {
     this._started = Date.now();
     this.time = Date.now();
     this.events.start();
@@ -78,7 +78,7 @@ export class Time {
    * @param {Timer} timer - The Timer to add.
    * @returns {Timer} The added Timer object.
    */
-  add(timer: Timer) {
+  public add(timer: Timer) {
     this._timers.push(timer);
     return timer;
   }
@@ -88,7 +88,7 @@ export class Time {
    * @param {boolean} autoDestroy - Whether the timer should be automatically destroyed when it completes.
    * @returns {Timer} The created Timer object.
    */
-  create(autoDestroy: boolean = true) {
+  public create(autoDestroy = true) {
     const timer = new Timer(this.game, autoDestroy);
     this._timers.push(timer);
     return timer;
@@ -97,9 +97,9 @@ export class Time {
   /**
    * Removes all timers from the Time manager.
    */
-  removeAll() {
-    for (let i = 0; i < this._timers.length; i += 1) {
-      this._timers[i].destroy();
+  public removeAll() {
+    for (const timer of this._timers) {
+      timer.destroy();
     }
     this._timers = [];
     this.events.removeAll();
@@ -108,7 +108,7 @@ export class Time {
   /**
    * Refreshes the time tracking values.
    */
-  refresh() {
+  public refresh() {
     const previousDateNow = this.time;
     // this.time always holds a Date.now value
     this.time = Date.now();
@@ -120,7 +120,7 @@ export class Time {
    * Updates the Time manager with a new timestamp.
    * @param {number} time - The new timestamp to use for updating.
    */
-  update(time: number) {
+  public update(time: number) {
     const previousDateNow = this.time;
     // this.time always holds a Date.now value
     this.time = Date.now();
@@ -140,7 +140,7 @@ export class Time {
     if (!this.game.paused) {
       //  Our internal Phaser.Timer
       this.events.update(this.time);
-      if (this._timers.length) {
+      if (this._timers.length > 0) {
         this.updateTimers();
       }
     }
@@ -149,11 +149,11 @@ export class Time {
   /**
    * Updates all timers managed by the Time manager.
    */
-  updateTimers() {
+  public updateTimers() {
     let i = 0;
     let len = this._timers.length;
     while (i < len) {
-      if (this._timers[i].update(this.time)) {
+      if (this._timers[i]!.update(this.time)) {
         i += 1;
       } else {
         //  Timer requests to be removed
@@ -166,7 +166,7 @@ export class Time {
   /**
    * Updates the advanced timing values.
    */
-  updateAdvancedTiming() {
+  public updateAdvancedTiming() {
     // count the number of time.update calls
     this._frameCount += 1;
     this._elapsedAccumulator += this.elapsed;
@@ -192,27 +192,27 @@ export class Time {
   /**
    * Handles game pause event.
    */
-  gamePaused() {
+  public gamePaused() {
     this._pauseStarted = Date.now();
     this.events.pause();
     let i = this._timers.length;
     while (i) {
       i -= 1;
-      this._timers[i]._pause();
+      this._timers[i]!._pause();
     }
   }
 
   /**
    * Handles game resume event.
    */
-  gameResumed() {
+  public gameResumed() {
     this.time = Date.now();
     this.pauseDuration = this.time - this._pauseStarted;
     this.events.resume();
     let i = this._timers.length;
     while (i) {
       i -= 1;
-      this._timers[i]._resume();
+      this._timers[i]!._resume();
     }
   }
 
@@ -220,7 +220,7 @@ export class Time {
    * Gets the total elapsed time in seconds since the game started.
    * @returns {number} The total elapsed time in seconds.
    */
-  totalElapsedSeconds() {
+  public totalElapsedSeconds() {
     return (this.time - this._started) * 0.001;
   }
 
@@ -229,7 +229,7 @@ export class Time {
    * @param {number} since - The timestamp to calculate elapsed time from.
    * @returns {number} The elapsed time in milliseconds.
    */
-  elapsedSince(since: number) {
+  public elapsedSince(since: number) {
     return this.time - since;
   }
 
@@ -238,14 +238,14 @@ export class Time {
    * @param {number} since - The timestamp to calculate elapsed time from.
    * @returns {number} The elapsed time in seconds.
    */
-  elapsedSecondsSince(since: number) {
+  public elapsedSecondsSince(since: number) {
     return (this.time - since) * 0.001;
   }
 
   /**
    * Resets the time tracking values.
    */
-  reset() {
+  public reset() {
     this._started = this.time;
     this.removeAll();
   }
@@ -253,7 +253,7 @@ export class Time {
   /**
    * Destroys the Time manager and cleans up resources.
    */
-  destroy() {
+  public destroy() {
     this.reset();
   }
 
@@ -261,14 +261,14 @@ export class Time {
    * Gets the desired frames per second.
    * @returns {number} The desired frames per second.
    */
-  get desiredFps() {
+  public get desiredFps() {
     return this._desiredFps;
   }
 
   /**
    * Sets the desired frames per second.
    */
-  set desiredFps(value) {
+  public set desiredFps(value) {
     this._desiredFps = value;
     this.desiredFpsMult = 1 / value;
   }

package/src/phaser/core/timer.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { Game } from './game.js';
+import { Timer } from './timer.js';
+
+const createGame = (time = 0): Game => ({ time: { time } }) as unknown as Game;
+
+const createTimer = (startTime = 0): Timer => {
+  const timer = new Timer(createGame(startTime));
+  timer._now = startTime;
+  return timer;
+};
+
+describe('Timer', () => {
+  describe('start', () => {
+    it('rebases every queued event onto the start time', () => {
+      const timer = createTimer(1000);
+      timer.add(100, () => undefined);
+      timer.add(300, () => undefined);
+      timer.start();
+      expect(timer.events.map((event) => event.tick)).toStrictEqual([1100, 1300]);
+    });
+
+    it('is a no-op once already running', () => {
+      const timer = createTimer(1000);
+      timer.add(100, () => undefined);
+      timer.start();
+      const ticks = timer.events.map((event) => event.tick);
+      timer.start(500);
+      expect(timer.events.map((event) => event.tick)).toStrictEqual(ticks);
+    });
+  });
+
+  describe('order', () => {
+    it('sorts events by tick and exposes the earliest as nextTick', () => {
+      const timer = createTimer(0);
+      timer.add(500, () => undefined);
+      timer.add(100, () => undefined);
+      timer.add(300, () => undefined);
+      expect(timer.events.map((event) => event.delay)).toStrictEqual([100, 300, 500]);
+      expect(timer.nextTick).toBe(100);
+    });
+
+    it('leaves nextTick untouched when there are no events', () => {
+      const timer = createTimer(0);
+      timer.nextTick = 42;
+      timer.order();
+      expect(timer.nextTick).toBe(42);
+    });
+  });
+
+  describe('remove', () => {
+    it('marks a matching event for deletion and reports success', () => {
+      const timer = createTimer(0);
+      const event = timer.add(100, () => undefined);
+      expect(timer.remove(event)).toBe(true);
+      expect(event.pendingDelete).toBe(true);
+    });
+
+    it('reports failure for an event it does not hold', () => {
+      const timer = createTimer(0);
+      timer.add(100, () => undefined);
+      const other = createTimer(0).add(100, () => undefined);
+      expect(timer.remove(other)).toBe(false);
+    });
+
+    it('reports failure for null without throwing', () => {
+      const timer = createTimer(0);
+      timer.add(100, () => undefined);
+      expect(timer.remove(null)).toBe(false);
+    });
+  });
+
+  describe('clearPendingEvents', () => {
+    it('drops only the events marked for deletion', () => {
+      const timer = createTimer(0);
+      const first = timer.add(100, () => undefined);
+      const second = timer.add(200, () => undefined);
+      timer.remove(first);
+      timer.clearPendingEvents();
+      expect(timer.events).toStrictEqual([second]);
+      expect(timer._len).toBe(1);
+    });
+  });
+
+  describe('update', () => {
+    it('fires a one-shot event once its tick is reached and marks it spent', () => {
+      const timer = createTimer(0);
+      const callback = vi.fn();
+      timer.add(100, callback);
+      timer.start();
+      timer.update(50);
+      expect(callback).not.toHaveBeenCalled();
+      timer.update(100);
+      expect(callback).toHaveBeenCalledTimes(1);
+      expect(timer.events[0]?.pendingDelete).toBe(true);
+    });
+
+    it('keeps firing a looping event and reschedules its tick', () => {
+      const timer = createTimer(0);
+      const callback = vi.fn();
+      timer.loop(100, callback);
+      timer.start();
+      timer.update(100);
+      timer.update(200);
+      timer.update(300);
+      expect(callback).toHaveBeenCalledTimes(3);
+      expect(timer.events[0]?.pendingDelete).toBe(false);
+    });
+
+    it('fires a repeating event exactly repeatCount times', () => {
+      const timer = createTimer(0);
+      const callback = vi.fn();
+      timer.repeat(100, 2, callback);
+      timer.start();
+      timer.update(100);
+      timer.update(200);
+      timer.update(300);
+      timer.update(400);
+      expect(callback).toHaveBeenCalledTimes(2);
+      expect(timer.expired).toBe(true);
+    });
+
+    it('passes the configured context and arguments to the callback', () => {
+      const timer = createTimer(0);
+      const context = { seen: null as unknown };
+      const callback = vi.fn(function callbackImpl(this: typeof context, value: string) {
+        this.seen = value;
+      });
+      timer.add(100, callback, context, 'payload');
+      timer.start();
+      timer.update(100);
+      expect(callback).toHaveBeenCalledWith('payload');
+      expect(context.seen).toBe('payload');
+    });
+
+    it('completes and dispatches onComplete once every event is spent', () => {
+      const timer = createTimer(0);
+      const onComplete = vi.fn();
+      timer.onComplete.add(onComplete);
+      timer.add(100, () => undefined);
+      timer.start();
+      timer.update(100);
+      expect(timer.expired).toBe(true);
+      expect(onComplete).toHaveBeenCalledTimes(1);
+    });
+
+    it('survives a callback that removes every event mid-tick', () => {
+      const timer = createTimer(0);
+      timer.add(100, () => {
+        timer.events.length = 0;
+      });
+      timer.start();
+      expect(() => timer.update(100)).not.toThrow();
+    });
+  });
+
+  describe('adjustEvents', () => {
+    it('shifts pending events forward by the time they missed', () => {
+      const timer = createTimer(0);
+      const event = timer.add(100, () => undefined);
+      timer.start();
+      timer._now = 5000;
+      timer.adjustEvents(0);
+      expect(event.tick).toBe(5100);
+    });
+
+    it('clamps events whose tick already passed to the current time', () => {
+      const timer = createTimer(0);
+      const event = timer.add(100, () => undefined);
+      timer.start();
+      timer._now = 5000;
+      timer.adjustEvents(500);
+      expect(event.tick).toBe(5000);
+    });
+
+    it('leaves events marked for deletion alone', () => {
+      const timer = createTimer(0);
+      const event = timer.add(100, () => undefined);
+      timer.start();
+      timer.remove(event);
+      const { tick } = event;
+      timer._now = 5000;
+      timer.adjustEvents(0);
+      expect(event.tick).toBe(tick);
+    });
+  });
+});