@vpmedia/phaser 1.95.0 → 1.97.0

package/src/phaser/core/time.js

@@ -2,8 +2,8 @@ import { Timer } from './timer.js';
 
 export class Time {
   /**
-   * TBD.
-   * @param {import('./game.js').Game} game - TBD.
+   * Creates a new Time instance.
+   * @param {import('./game.js').Game} game - Reference to the Phaser Game instance.
    */
   constructor(game) {
     this.game = game;
@@ -61,7 +61,7 @@ export class Time {
   }
 
   /**
-   * TBD.
+   * Initializes the time manager and starts tracking time.
    */
   boot() {
     this._started = Date.now();
@@ -71,9 +71,9 @@ export class Time {
   }
 
   /**
-   * TBD.
-   * @param {Timer} timer - TBD.
-   * @returns {Timer} TBD.
+   * Adds a Timer to the Time manager.
+   * @param {Timer} timer - The Timer to add.
+   * @returns {Timer} The added Timer object.
    */
   add(timer) {
     this._timers.push(timer);
@@ -81,9 +81,9 @@ export class Time {
   }
 
   /**
-   * TBD.
-   * @param {boolean} autoDestroy - TBD.
-   * @returns {Timer} TBD.
+   * Creates a new Timer and adds it to the Time manager.
+   * @param {boolean} autoDestroy - Whether the timer should be automatically destroyed when it completes.
+   * @returns {Timer} The created Timer object.
    */
   create(autoDestroy = true) {
     const timer = new Timer(this.game, autoDestroy);
@@ -92,7 +92,7 @@ export class Time {
   }
 
   /**
-   * TBD.
+   * Removes all timers from the Time manager.
    */
   removeAll() {
     for (let i = 0; i < this._timers.length; i += 1) {
@@ -103,7 +103,7 @@ export class Time {
   }
 
   /**
-   * TBD.
+   * Refreshes the time tracking values.
    */
   refresh() {
     const previousDateNow = this.time;
@@ -114,8 +114,8 @@ export class Time {
   }
 
   /**
-   * TBD.
-   * @param {number} time - TBD.
+   * Updates the Time manager with a new timestamp.
+   * @param {number} time - The new timestamp to use for updating.
    */
   update(time) {
     const previousDateNow = this.time;
@@ -144,7 +144,7 @@ export class Time {
   }
 
   /**
-   * TBD.
+   * Updates all timers managed by the Time manager.
    */
   updateTimers() {
     let i = 0;
@@ -161,7 +161,7 @@ export class Time {
   }
 
   /**
-   * TBD.
+   * Updates the advanced timing values.
    */
   updateAdvancedTiming() {
     // count the number of time.update calls
@@ -187,7 +187,7 @@ export class Time {
   }
 
   /**
-   * TBD.
+   * Handles game pause event.
    */
   gamePaused() {
     this._pauseStarted = Date.now();
@@ -200,7 +200,7 @@ export class Time {
   }
 
   /**
-   * TBD.
+   * Handles game resume event.
    */
   gameResumed() {
     this.time = Date.now();
@@ -214,33 +214,33 @@ export class Time {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the total elapsed time in seconds since the game started.
+   * @returns {number} The total elapsed time in seconds.
    */
   totalElapsedSeconds() {
     return (this.time - this._started) * 0.001;
   }
 
   /**
-   * TBD.
-   * @param {number} since - TBD.
-   * @returns {number} TBD.
+   * Gets the elapsed time in milliseconds since a given timestamp.
+   * @param {number} since - The timestamp to calculate elapsed time from.
+   * @returns {number} The elapsed time in milliseconds.
    */
   elapsedSince(since) {
     return this.time - since;
   }
 
   /**
-   * TBD.
-   * @param {number} since - TBD.
-   * @returns {number} TBD.
+   * Gets the elapsed time in seconds since a given timestamp.
+   * @param {number} since - The timestamp to calculate elapsed time from.
+   * @returns {number} The elapsed time in seconds.
    */
   elapsedSecondsSince(since) {
     return (this.time - since) * 0.001;
   }
 
   /**
-   * TBD.
+   * Resets the time tracking values.
    */
   reset() {
     this._started = this.time;
@@ -248,22 +248,22 @@ export class Time {
   }
 
   /**
-   * TBD.
+   * Destroys the Time manager and cleans up resources.
    */
   destroy() {
     this.reset();
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the desired frames per second.
+   * @returns {number} The desired frames per second.
    */
   get desiredFps() {
     return this._desiredFps;
   }
 
   /**
-   * TBD.
+   * Sets the desired frames per second.
    */
   set desiredFps(value) {
     this._desiredFps = value;

package/src/phaser/core/timer.js

@@ -3,9 +3,9 @@ import { TimerEvent } from './timer_event.js';
 
 export class Timer {
   /**
-   * TBD.
-   * @param {import('./game.js').Game} game - TBD.
-   * @param {boolean} autoDestroy - TBD.
+   * Creates a new Timer instance.
+   * @param {import('./game.js').Game} game - The game instance.
+   * @param {boolean} autoDestroy - Whether to automatically destroy the timer when it completes.
    */
   constructor(game, autoDestroy = false) {
     this.game = game;
@@ -50,14 +50,14 @@ export class Timer {
   }
 
   /**
-   * TBD.
-   * @param {number} delay - TBD.
-   * @param {boolean} loop - TBD.
-   * @param {number} repeatCount - TBD.
-   * @param {Function} callback - TBD.
-   * @param {object} callbackContext - TBD.
-   * @param {...any} args - TBD.
-   * @returns {TimerEvent} TBD.
+   * Creates a new TimerEvent.
+   * @param {number} delay - The delay in milliseconds before the event fires.
+   * @param {boolean} loop - Whether the event should loop indefinitely.
+   * @param {number} repeatCount - The number of times to repeat the event (0 = infinite).
+   * @param {Function} callback - The function to call when the event fires.
+   * @param {object} callbackContext - The context in which to call the callback.
+   * @param {...any} args - Arguments to pass to the callback function.
+   * @returns {TimerEvent} The created TimerEvent.
    */
   create(delay, loop, repeatCount, callback, callbackContext = null, args) {
     const roundedDelay = Math.round(delay);
@@ -75,45 +75,60 @@ export class Timer {
   }
 
   /**
-   * TBD.
-   * @param {number} delay - TBD.
-   * @param {Function} callback - TBD.
-   * @param {object} callbackContext - TBD.
-   * @param {...any} args - TBD.
-   * @returns {TimerEvent} TBD.
+   * Creates a new TimerEvent that runs once.
+   * @param {number} delay - The delay in milliseconds before the event fires.
+   * @param {Function} callback - The function to call when the event fires.
+   * @param {object} callbackContext - The context in which to call the callback.
+   * @param {...any} args - Arguments to pass to the callback function.
+   * @returns {TimerEvent} The created TimerEvent.
    */
   add(delay, callback, callbackContext = null, ...args) {
     return this.create(delay, false, 0, callback, callbackContext, args);
   }
 
   /**
-   * TBD.
-   * @param {number} delay - TBD.
-   * @param {number} repeatCount - TBD.
-   * @param {Function} callback - TBD.
-   * @param {object} callbackContext - TBD.
-   * @param {...any} args - TBD.
-   * @returns {TimerEvent} TBD.
+   * Creates a new async TimerEvent that runs once.
+   * @template T
+   * @param {number} delay - The delay in milliseconds before the promise resolves.
+   * @param {...T} args - Arguments to pass to the resolve function.
+   * @returns {Promise<T | T[]>} The created Promise.
+   */
+  wait(delay, ...args) {
+    return new Promise((resolve) => {
+      this.create(delay, false, 0, () => {
+        resolve(args.length <= 1 ? args[0] : args);
+      });
+    });
+  }
+
+  /**
+   * Creates a new TimerEvent that repeats a specified number of times.
+   * @param {number} delay - The delay in milliseconds before the event fires.
+   * @param {number} repeatCount - The number of times to repeat the event (0 = infinite).
+   * @param {Function} callback - The function to call when the event fires.
+   * @param {object} callbackContext - The context in which to call the callback.
+   * @param {...any} args - Arguments to pass to the callback function.
+   * @returns {TimerEvent} The created TimerEvent.
    */
   repeat(delay, repeatCount, callback, callbackContext = null, ...args) {
     return this.create(delay, false, repeatCount, callback, callbackContext, args);
   }
 
   /**
-   * TBD.
-   * @param {number} delay - TBD.
-   * @param {Function} callback - TBD.
-   * @param {object} callbackContext - TBD.
-   * @param {...any} args - TBD.
-   * @returns {TimerEvent} TBD.
+   * Creates a new TimerEvent that loops indefinitely.
+   * @param {number} delay - The delay in milliseconds before the event fires.
+   * @param {Function} callback - The function to call when the event fires.
+   * @param {object} callbackContext - The context in which to call the callback.
+   * @param {...any} args - Arguments to pass to the callback function.
+   * @returns {TimerEvent} The created TimerEvent.
    */
   loop(delay, callback, callbackContext = null, ...args) {
     return this.create(delay, true, 0, callback, callbackContext, args);
   }
 
   /**
-   * TBD.
-   * @param {number} delay - TBD.
+   * Starts the timer.
+   * @param {number} delay - The delay in milliseconds before starting (optional).
    */
   start(delay = 0) {
     if (this.running) {
@@ -127,8 +142,8 @@ export class Timer {
   }
 
   /**
-   * TBD.
-   * @param {boolean} clearEvents - TBD.
+   * Stops the timer.
+   * @param {boolean} clearEvents - Whether to clear all events (default: true).
    */
   stop(clearEvents = true) {
     this.running = false;
@@ -138,9 +153,9 @@ export class Timer {
   }
 
   /**
-   * TBD.
-   * @param {TimerEvent | null | undefined} event - TBD.
-   * @returns {boolean} TBD.
+   * Removes a TimerEvent from the timer.
+   * @param {TimerEvent | null | undefined} event - The TimerEvent to remove.
+   * @returns {boolean} True if the event was removed, false otherwise.
    */
   remove(event) {
     for (let i = 0; i < this.events.length; i += 1) {
@@ -153,7 +168,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Orders the timer events by their next tick time.
    */
   order() {
     if (this.events.length > 0) {
@@ -164,10 +179,10 @@ export class Timer {
   }
 
   /**
-   * TBD.
-   * @param {TimerEvent} a - TBD.
-   * @param {TimerEvent} b - TBD.
-   * @returns {number} TBD.
+   * Sorts TimerEvents by their tick time.
+   * @param {TimerEvent} a - First TimerEvent to compare.
+   * @param {TimerEvent} b - Second TimerEvent to compare.
+   * @returns {number} Comparison result (-1, 0, or 1).
    */
   sortHandler(a, b) {
     if (a.tick < b.tick) {
@@ -179,7 +194,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Clears pending events from the timer.
    */
   clearPendingEvents() {
     this._i = this.events.length;
@@ -194,9 +209,9 @@ export class Timer {
   }
 
   /**
-   * TBD.
-   * @param {number} time - TBD.
-   * @returns {boolean} TBD.
+   * Updates the timer state at a given time.
+   * @param {number} time - The current time in milliseconds.
+   * @returns {boolean} True if the timer should continue running, false if it should be destroyed.
    */
   update(time) {
     if (this.paused) {
@@ -254,7 +269,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Pauses the timer.
    */
   pause() {
     if (!this.running) {
@@ -269,7 +284,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Internal pause method for the timer.
    */
   _pause() {
     if (this.paused || !this.running) {
@@ -280,8 +295,8 @@ export class Timer {
   }
 
   /**
-   * TBD.
-   * @param {number} baseTime - TBD.
+   * Adjusts timer events when time has jumped (e.g., when tab is switched).
+   * @param {number} baseTime - The time to adjust from.
    */
   adjustEvents(baseTime) {
     for (let i = 0; i < this.events.length; i += 1) {
@@ -304,7 +319,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Resumes the timer.
    */
   resume() {
     if (!this.paused) {
@@ -319,7 +334,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Internal resume method for the timer.
    */
   _resume() {
     if (this._codePaused) {
@@ -329,7 +344,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Removes all events from the timer.
    */
   removeAll() {
     this.onComplete.removeAll();
@@ -339,7 +354,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Destroys the timer and cleans up resources.
    */
   destroy() {
     this.onComplete.removeAll();
@@ -350,16 +365,16 @@ export class Timer {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the next tick time for the timer.
+   * @returns {number} The next tick time in milliseconds.
    */
   get next() {
     return this.nextTick;
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the duration until the next event.
+   * @returns {number} The duration in milliseconds.
    */
   get duration() {
     if (this.running && this.nextTick > this._now) {
@@ -369,16 +384,16 @@ export class Timer {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the number of active events in the timer.
+   * @returns {number} The number of events.
    */
   get length() {
     return this.events.length;
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the elapsed time since the timer started.
+   * @returns {number} The elapsed time in milliseconds.
    */
   get ms() {
     if (this.running) {
@@ -388,8 +403,8 @@ export class Timer {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the elapsed time in seconds since the timer started.
+   * @returns {number} The elapsed time in seconds.
    */
   get seconds() {
     if (this.running) {

package/src/phaser/core/timer_event.js

@@ -1,14 +1,14 @@
 export class TimerEvent {
   /**
-   * TBD.
-   * @param {import('./timer.js').Timer} timer - TBD.
-   * @param {number} delay - TBD.
-   * @param {number} tick - TBD.
-   * @param {number} repeatCount - TBD.
-   * @param {boolean} loop - TBD.
-   * @param {Function} callback - TBD.
-   * @param {object} callbackContext - TBD.
-   * @param {...any} args - TBD.
+   * Creates a new TimerEvent instance.
+   * @param {import('./timer.js').Timer} timer - Reference to the parent Timer.
+   * @param {number} delay - The delay (in milliseconds) before the event should occur.
+   * @param {number} tick - The tick (in milliseconds) at which the event should occur.
+   * @param {number} repeatCount - The number of times the event should repeat.
+   * @param {boolean} loop - Whether the event should loop.
+   * @param {Function} callback - The function to call when the event occurs.
+   * @param {object} callbackContext - The context in which to call the callback function.
+   * @param {...any} args - Arguments to pass to the callback function.
    */
   constructor(timer, delay, tick, repeatCount, loop, callback, callbackContext, args) {
     this.timer = timer;