@vpmedia/phaser 1.94.0 → 1.96.0

package/src/phaser/core/time.js

@@ -2,42 +2,66 @@ 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;
+    /** @type {number} */
     this.time = 0;
+    /** @type {number} */
     this.prevTime = 0;
+    /** @type {number} */
     this.now = 0;
+    /** @type {number} */
     this.elapsed = 0;
+    /** @type {number} */
     this.elapsedMS = 0;
+    /** @type {number} */
     this.desiredFpsMult = 1 / 60;
+    /** @type {number} */
     this._desiredFps = 60;
+    /** @type {number} */
     this.suggestedFps = this.desiredFps;
+    /** @type {boolean} */
     this.advancedTiming = false;
+    /** @type {number} */
     this.frames = 0;
+    /** @type {number} */
     this.fps = 0;
+    /** @type {number} */
     this.fpsMin = 1000;
+    /** @type {number} */
     this.fpsMax = 0;
+    /** @type {number} */
     this.msMin = 1000;
+    /** @type {number} */
     this.msMax = 0;
+    /** @type {number} */
     this.pauseDuration = 0;
+    /** @type {number} */
     this.timeToCall = 0;
+    /** @type {number} */
     this.timeExpected = 0;
+    /** @type {Timer} */
     this.events = new Timer(this.game, false);
+    /** @type {number} */
     this._frameCount = 0;
+    /** @type {number} */
     this._elapsedAccumulator = 0;
     this._started = 0;
+    /** @type {number} */
     this._timeLastSecond = 0;
+    /** @type {number} */
     this._pauseStarted = 0;
+    /** @type {boolean} */
     this._justResumed = false;
     /** @type {Timer[]} */
     this._timers = [];
   }
 
   /**
-   * TBD.
+   * Initializes the time manager and starts tracking time.
    */
   boot() {
     this._started = Date.now();
@@ -47,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);
@@ -57,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);
@@ -68,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) {
@@ -79,7 +103,7 @@ export class Time {
   }
 
   /**
-   * TBD.
+   * Refreshes the time tracking values.
    */
   refresh() {
     const previousDateNow = this.time;
@@ -90,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;
@@ -120,7 +144,7 @@ export class Time {
   }
 
   /**
-   * TBD.
+   * Updates all timers managed by the Time manager.
    */
   updateTimers() {
     let i = 0;
@@ -137,7 +161,7 @@ export class Time {
   }
 
   /**
-   * TBD.
+   * Updates the advanced timing values.
    */
   updateAdvancedTiming() {
     // count the number of time.update calls
@@ -163,7 +187,7 @@ export class Time {
   }
 
   /**
-   * TBD.
+   * Handles game pause event.
    */
   gamePaused() {
     this._pauseStarted = Date.now();
@@ -176,7 +200,7 @@ export class Time {
   }
 
   /**
-   * TBD.
+   * Handles game resume event.
    */
   gameResumed() {
     this.time = Date.now();
@@ -190,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;
@@ -224,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,43 +3,61 @@ 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;
+    /** @type {boolean} */
     this.running = false;
+    /** @type {boolean} */
     this.autoDestroy = autoDestroy;
+    /** @type {boolean} */
     this.expired = false;
+    /** @type {number} */
     this.elapsed = 0;
     /** @type {TimerEvent[]} */
     this.events = [];
+    /** @type {Signal} */
     this.onComplete = new Signal();
+    /** @type {number} */
     this.nextTick = 0;
+    /** @type {number} */
     this.timeCap = 1000;
+    /** @type {boolean} */
     this.paused = false;
+    /** @type {boolean} */
     this._codePaused = false;
+    /** @type {number} */
     this._started = 0;
+    /** @type {number} */
     this._pauseStarted = 0;
+    /** @type {number} */
     this._pauseTotal = 0;
+    /** @type {number} */
     this._now = Date.now();
+    /** @type {number} */
     this._len = 0;
+    /** @type {number} */
     this._marked = 0;
+    /** @type {number} */
     this._i = 0;
+    /** @type {number} */
     this._diff = 0;
+    /** @type {number} */
     this._newTick = 0;
   }
 
   /**
-   * 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);
@@ -57,45 +75,45 @@ 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 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) {
@@ -109,8 +127,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;
@@ -120,9 +138,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) {
@@ -135,7 +153,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Orders the timer events by their next tick time.
    */
   order() {
     if (this.events.length > 0) {
@@ -146,10 +164,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) {
@@ -161,7 +179,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Clears pending events from the timer.
    */
   clearPendingEvents() {
     this._i = this.events.length;
@@ -176,9 +194,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) {
@@ -236,7 +254,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Pauses the timer.
    */
   pause() {
     if (!this.running) {
@@ -251,7 +269,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Internal pause method for the timer.
    */
   _pause() {
     if (this.paused || !this.running) {
@@ -262,8 +280,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) {
@@ -286,7 +304,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Resumes the timer.
    */
   resume() {
     if (!this.paused) {
@@ -301,7 +319,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Internal resume method for the timer.
    */
   _resume() {
     if (this._codePaused) {
@@ -311,7 +329,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Removes all events from the timer.
    */
   removeAll() {
     this.onComplete.removeAll();
@@ -321,7 +339,7 @@ export class Timer {
   }
 
   /**
-   * TBD.
+   * Destroys the timer and cleans up resources.
    */
   destroy() {
     this.onComplete.removeAll();
@@ -332,16 +350,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) {
@@ -351,16 +369,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) {
@@ -370,8 +388,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;