@vpmedia/phaser 1.94.0 → 1.96.0

package/src/phaser/core/tween.js

@@ -5,48 +5,64 @@ import { TweenData } from './tween_data.js';
 
 export class Tween {
   /**
-   * TBD.
-   * @param {import('../display/display_object.js').DisplayObject} target - TBD.
-   * @param {import('./game.js').Game} game - TBD.
-   * @param {import('./tween_manager.js').TweenManager} manager - TBD.
+   * Creates a new Tween instance.
+   * @param {import('../display/display_object.js').DisplayObject} target - The object to tween.
+   * @param {import('./game.js').Game} game - Reference to the Phaser Game instance.
+   * @param {import('./tween_manager.js').TweenManager} manager - Reference to the Tween Manager.
    */
   constructor(target, game, manager) {
     this.game = game;
     this.target = target;
+    /** @type {import('./tween_manager.js').TweenManager} */
     this.manager = manager;
     /** @type {TweenData[]} */
     this.timeline = [];
+    /** @type {boolean} */
     this.reverse = false;
+    /** @type {number} */
     this.timeScale = 1;
+    /** @type {number} */
     this.repeatCounter = 0;
+    /** @type {boolean} */
     this.pendingDelete = false;
+    /** @type {Signal} */
     this.onStart = new Signal();
+    /** @type {Signal} */
     this.onLoop = new Signal();
+    /** @type {Signal} */
     this.onRepeat = new Signal();
+    /** @type {Signal} */
     this.onChildComplete = new Signal();
+    /** @type {Signal} */
     this.onComplete = new Signal();
+    /** @type {boolean} */
     this.isRunning = false;
+    /** @type {number} */
     this.current = 0;
     this.properties = {};
     this.chainedTween = null;
+    /** @type {boolean} */
     this.isPaused = false;
     this._onUpdateCallback = null;
     this._onUpdateCallbackContext = null;
+    /** @type {number} */
     this._pausedTime = 0;
+    /** @type {boolean} */
     this._codePaused = false;
+    /** @type {boolean} */
     this._hasStarted = false;
   }
 
   /**
-   * TBD.
-   * @param {object} properties - TBD.
-   * @param {number} duration - TBD.
-   * @param {string | Function} ease - TBD.
-   * @param {boolean} autoStart - TBD.
-   * @param {number} delay - TBD.
-   * @param {number} repeat - TBD.
-   * @param {boolean} yoyo - TBD.
-   * @returns {Tween} TBD.
+   * Adds a tween to the timeline that animates properties to their target values.
+   * @param {object} properties - The properties to tween and their target values.
+   * @param {number} duration - The duration of the tween in milliseconds.
+   * @param {string | Function} ease - The easing function to use.
+   * @param {boolean} autoStart - Whether to start the tween immediately.
+   * @param {number} delay - The delay before starting the tween in milliseconds.
+   * @param {number} repeat - Number of times to repeat the tween.
+   * @param {boolean} yoyo - Whether to reverse the tween on repeat.
+   * @returns {Tween} This Tween object for chaining.
    */
   to(properties, duration = 1000, ease = 'Linear', autoStart = false, delay = 0, repeat = 0, yoyo = false) {
     if (typeof ease === 'string' && this.manager.easeMap[ease]) {
@@ -64,15 +80,15 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {object} properties - TBD.
-   * @param {number} duration - TBD.
-   * @param {string | Function} ease - TBD.
-   * @param {boolean} autoStart - TBD.
-   * @param {number} delay - TBD.
-   * @param {number} repeat - TBD.
-   * @param {boolean} yoyo - TBD.
-   * @returns {Tween} TBD.
+   * Adds a tween to the timeline that animates properties from their current values.
+   * @param {object} properties - The properties to tween and their target values.
+   * @param {number} duration - The duration of the tween in milliseconds.
+   * @param {string | Function} ease - The easing function to use.
+   * @param {boolean} autoStart - Whether to start the tween immediately.
+   * @param {number} delay - The delay before starting the tween in milliseconds.
+   * @param {number} repeat - Number of times to repeat the tween.
+   * @param {boolean} yoyo - Whether to reverse the tween on repeat.
+   * @returns {Tween} This Tween object for chaining.
    */
   from(properties, duration = 1000, ease = 'Linear', autoStart = false, delay = 0, repeat = 0, yoyo = false) {
     if (typeof ease === 'string' && this.manager.easeMap[ease]) {
@@ -91,9 +107,9 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {number} index - TBD.
-   * @returns {Tween} TBD.
+   * Starts the tween timeline from a specific index.
+   * @param {number} index - The index to start from in the timeline.
+   * @returns {Tween} This Tween object for chaining.
    */
   start(index = 0) {
     if (this.game === null || this.target === null || this.timeline.length === 0 || this.isRunning) {
@@ -126,9 +142,9 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {boolean} complete - TBD.
-   * @returns {Tween} TBD.
+   * Stops the tween and optionally completes it.
+   * @param {boolean} complete - Whether to dispatch the complete event.
+   * @returns {Tween} This Tween object for chaining.
    */
   stop(complete = false) {
     this.isRunning = false;
@@ -146,11 +162,11 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {string} property - TBD.
-   * @param {object} value - TBD.
-   * @param {number} index - TBD.
-   * @returns {Tween} TBD.
+   * Updates a property in the tween data.
+   * @param {string} property - The property name to update.
+   * @param {object} value - The new value for the property.
+   * @param {number} index - The index in the timeline to update.
+   * @returns {Tween} This Tween object for chaining.
    */
   updateTweenData(property, value, index = 0) {
     if (this.timeline.length === 0) {
@@ -167,21 +183,21 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {number} duration - TBD.
-   * @param {number} index - TBD.
-   * @returns {Tween} TBD.
+   * Sets a delay for a specific timeline entry.
+   * @param {number} duration - The delay in milliseconds.
+   * @param {number} index - The index in the timeline to apply the delay to.
+   * @returns {Tween} This Tween object for chaining.
    */
   delay(duration, index) {
     return this.updateTweenData('delay', duration, index);
   }
 
   /**
-   * TBD.
-   * @param {number} total - TBD.
-   * @param {number} repeatDelay - TBD.
-   * @param {number} index - TBD.
-   * @returns {Tween} TBD.
+   * Sets how many times to repeat the tween.
+   * @param {number} total - The number of times to repeat (-1 for infinite).
+   * @param {number} repeatDelay - Delay between repeats in milliseconds.
+   * @param {number} index - The index in the timeline to apply the repeat to.
+   * @returns {Tween} This Tween object for chaining.
    */
   repeat(total, repeatDelay = 0, index = 0) {
     this.updateTweenData('repeatCounter', total, index);
@@ -189,21 +205,21 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {number} duration - TBD.
-   * @param {number} index - TBD.
-   * @returns {Tween} TBD.
+   * Sets the repeat delay for a specific timeline entry.
+   * @param {number} duration - The delay between repeats in milliseconds.
+   * @param {number} index - The index in the timeline to apply the delay to.
+   * @returns {Tween} This Tween object for chaining.
    */
   repeatDelay(duration, index) {
     return this.updateTweenData('repeatDelay', duration, index);
   }
 
   /**
-   * TBD.
-   * @param {boolean} enable - TBD.
-   * @param {number} yoyoDelay - TBD.
-   * @param {number} index - TBD.
-   * @returns {Tween} TBD.
+   * Enables or disables yoyo behavior for a timeline entry.
+   * @param {boolean} enable - Whether to enable yoyo behavior.
+   * @param {number} yoyoDelay - Delay between yoyo cycles in milliseconds.
+   * @param {number} index - The index in the timeline to apply yoyo to.
+   * @returns {Tween} This Tween object for chaining.
    */
   yoyo(enable, yoyoDelay = 0, index = 0) {
     this.updateTweenData('yoyo', enable, index);
@@ -211,20 +227,20 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {number} duration - TBD.
-   * @param {number} index - TBD.
-   * @returns {Tween} TBD.
+   * Sets the yoyo delay for a specific timeline entry.
+   * @param {number} duration - The delay between yoyo cycles in milliseconds.
+   * @param {number} index - The index in the timeline to apply the delay to.
+   * @returns {Tween} This Tween object for chaining.
    */
   yoyoDelay(duration, index) {
     return this.updateTweenData('yoyoDelay', duration, index);
   }
 
   /**
-   * TBD.
-   * @param {string|Function} ease - TBD.
-   * @param {number} index - TBD.
-   * @returns {Tween} TBD.
+   * Sets the easing function for a timeline entry.
+   * @param {string|Function} ease - The easing function to use.
+   * @param {number} index - The index in the timeline to apply easing to.
+   * @returns {Tween} This Tween object for chaining.
    */
   easing(ease, index) {
     if (typeof ease === 'string' && this.manager.easeMap[ease]) {
@@ -234,11 +250,11 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {Function} interpolation - TBD.
-   * @param {object} context - TBD.
-   * @param {number} index - TBD.
-   * @returns {Tween} TBD.
+   * Sets the interpolation function for a timeline entry.
+   * @param {Function} interpolation - The interpolation function to use.
+   * @param {object} context - The context in which to call the interpolation function.
+   * @param {number} index - The index in the timeline to apply interpolation to.
+   * @returns {Tween} This Tween object for chaining.
    */
   interpolation(interpolation, context = MathUtils, index = 0) {
     this.updateTweenData('interpolationFunction', interpolation, index);
@@ -246,9 +262,9 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {number} total - TBD.
-   * @returns {Tween} TBD.
+   * Sets how many times to repeat all timeline entries.
+   * @param {number} total - The number of times to repeat (-1 for infinite).
+   * @returns {Tween} This Tween object for chaining.
    */
   repeatAll(total = 0) {
     this.repeatCounter = total;
@@ -256,9 +272,9 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {...any} args - TBD.
-   * @returns {Tween} TBD.
+   * Chains one or more tweens to this tween.
+   * @param {...any} args - The tweens to chain.
+   * @returns {Tween} This Tween object for chaining.
    */
   chain(...args) {
     let i = args.length;
@@ -274,9 +290,9 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {boolean} value - TBD.
-   * @returns {Tween} TBD.
+   * Sets whether the tween should loop infinitely.
+   * @param {boolean} value - Whether to loop infinitely.
+   * @returns {Tween} This Tween object for chaining.
    */
   loop(value = true) {
     this.repeatCounter = value ? -1 : 0;
@@ -284,10 +300,10 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {Function} callback - TBD.
-   * @param {object} callbackContext - TBD.
-   * @returns {Tween} TBD.
+   * Sets a callback to be called when the tween updates.
+   * @param {Function} callback - The callback function to call.
+   * @param {object} callbackContext - The context in which to call the callback.
+   * @returns {Tween} This Tween object for chaining.
    */
   onUpdateCallback(callback, callbackContext) {
     this._onUpdateCallback = callback;
@@ -296,7 +312,7 @@ export class Tween {
   }
 
   /**
-   * TBD.
+   * Pauses the tween.
    */
   pause() {
     this.isPaused = true;
@@ -305,7 +321,7 @@ export class Tween {
   }
 
   /**
-   * TBD.
+   * Internal method to pause the tween.
    */
   _pause() {
     if (!this._codePaused) {
@@ -315,7 +331,7 @@ export class Tween {
   }
 
   /**
-   * TBD.
+   * Resumes the tween.
    */
   resume() {
     if (this.isPaused) {
@@ -330,7 +346,7 @@ export class Tween {
   }
 
   /**
-   * TBD.
+   * Internal method to resume the tween.
    */
   _resume() {
     if (!this._codePaused) {
@@ -339,9 +355,9 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {number} time - TBD.
-   * @returns {boolean} TBD.
+   * Updates the tween state at a given time.
+   * @param {number} time - The current game time.
+   * @returns {boolean} True if the tween should continue running, false if it's complete.
    */
   update(time) {
     if (this.pendingDelete || !this.target) {
@@ -422,10 +438,10 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @param {number} frameRate - TBD.
-   * @param {object[]} data - TBD.
-   * @returns {object[]} TBD.
+   * Generates animation data for a given frame rate.
+   * @param {number} frameRate - The target frame rate.
+   * @param {object[]} data - The array to store the generated data in.
+   * @returns {object[]} The populated data array.
    */
   generateData(frameRate = 60, data = []) {
     if (this.game === null || this.target === null) {
@@ -454,8 +470,8 @@ export class Tween {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the total duration of all timeline entries.
+   * @returns {number} The total duration in milliseconds.
    */
   get totalDuration() {
     let total = 0;

package/src/phaser/core/tween_data.js

@@ -3,8 +3,8 @@ import { TWEEN_COMPLETE, TWEEN_LOOPED, TWEEN_PENDING, TWEEN_RUNNING } from './co
 
 export class TweenData {
   /**
-   * TBD.
-   * @param {import('./tween.js').Tween} parent - TBD.
+   * Creates a new TweenData instance.
+   * @param {import('./tween.js').Tween} parent - The parent Tween instance.
    */
   constructor(parent) {
     this.parent = parent;
@@ -34,14 +34,14 @@ export class TweenData {
   }
 
   /**
-   * TBD.
-   * @param {object} properties - TBD.
-   * @param {number} duration - TBD.
-   * @param {(number) => number} ease - TBD.
-   * @param {number} delay - TBD.
-   * @param {number} repeat - TBD.
-   * @param {boolean} yoyo - TBD.
-   * @returns {TweenData} TBD.
+   * Sets the target properties to tween to.
+   * @param {object} properties - The properties to tween to.
+   * @param {number} duration - The duration of the tween in milliseconds.
+   * @param {(number) => number} ease - The easing function to use.
+   * @param {number} delay - The delay before starting the tween in milliseconds.
+   * @param {number} repeat - The number of times to repeat the tween (0 = no repeat, -1 = infinite).
+   * @param {boolean} yoyo - Whether to reverse the tween on each repeat.
+   * @returns {TweenData} This TweenData object for chaining.
    */
   to(properties, duration, ease, delay, repeat, yoyo) {
     this.vEnd = properties;
@@ -55,14 +55,14 @@ export class TweenData {
   }
 
   /**
-   * TBD.
-   * @param {object} properties - TBD.
-   * @param {number} duration - TBD.
-   * @param {(number) => number} ease - TBD.
-   * @param {number} delay - TBD.
-   * @param {number} repeat - TBD.
-   * @param {boolean} yoyo - TBD.
-   * @returns {TweenData} TBD.
+   * Sets the target properties to tween from (in reverse).
+   * @param {object} properties - The properties to tween from.
+   * @param {number} duration - The duration of the tween in milliseconds.
+   * @param {(number) => number} ease - The easing function to use.
+   * @param {number} delay - The delay before starting the tween in milliseconds.
+   * @param {number} repeat - The number of times to repeat the tween (0 = no repeat, -1 = infinite).
+   * @param {boolean} yoyo - Whether to reverse the tween on each repeat.
+   * @returns {TweenData} This TweenData object for chaining.
    */
   from(properties, duration, ease, delay, repeat, yoyo) {
     this.vEnd = properties;
@@ -76,8 +76,8 @@ export class TweenData {
   }
 
   /**
-   * TBD.
-   * @returns {TweenData} TBD.
+   * Starts the tween.
+   * @returns {TweenData} This TweenData object for chaining.
    */
   start() {
     this.startTime = this.game.time.time + this.delay;
@@ -108,8 +108,8 @@ export class TweenData {
   }
 
   /**
-   * TBD.
-   * @returns {TweenData} TBD.
+   * Loads the tween values from the parent object.
+   * @returns {TweenData} This TweenData object for chaining.
    */
   loadValues() {
     const keys = Object.keys(this.parent.properties);
@@ -145,9 +145,9 @@ export class TweenData {
   }
 
   /**
-   * TBD.
-   * @param {number} time - TBD.
-   * @returns {number} TBD.
+   * Updates the tween at a given time.
+   * @param {number} time - The current time in milliseconds.
+   * @returns {number} The tween status (TWEEN_PENDING, TWEEN_RUNNING, or TWEEN_COMPLETE).
    */
   update(time) {
     if (!this.isRunning) {
@@ -188,9 +188,9 @@ export class TweenData {
   }
 
   /**
-   * TBD.
-   * @param {number} frameRate - TBD.
-   * @returns {object[]} TBD.
+   * Generates an array of tween data points for a given frame rate.
+   * @param {number} frameRate - The frame rate to generate data for.
+   * @returns {object[]} An array of tween data points.
    */
   generateData(frameRate) {
     if (this.parent.reverse) {
@@ -237,8 +237,8 @@ export class TweenData {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Handles tween repetition logic.
+   * @returns {number} The tween status (TWEEN_LOOPED or TWEEN_COMPLETE).
    */
   repeat() {
     //  If not a yoyo and repeatCounter = 0 then we're done

package/src/phaser/core/tween_manager.js

@@ -36,13 +36,16 @@ import {
 
 export class TweenManager {
   /**
-   * TBD.
-   * @param {import('./game.js').Game} game - TBD.
+   * Creates a new TweenManager instance.
+   * @param {import('./game.js').Game} game - The game instance this manager belongs to.
    */
   constructor(game) {
     this.game = game;
+    /** @type {Tween[]} */
     this._tweens = [];
+    /** @type {Tween[]} */
     this._add = [];
+    /** @type {{[key: string]: (k: number) => number}} */
     this.easeMap = {
       Linear: LinearNone,
       Quad: QuadraticOut,
@@ -92,15 +95,16 @@ export class TweenManager {
   }
 
   /**
-   * TBD.
-   * @returns {Tween[]} TBD.
+   * Get all tweens managed by this manager.
+   * @returns {Tween[]} An array of all active tweens.
    */
   getAll() {
     return this._tweens;
   }
 
   /**
-   * TBD.
+   * Remove all tweens from the manager.
+   * This method removes all active and pending tweens.
    */
   removeAll() {
     for (let i = 0; i < this._tweens.length; i += 1) {
@@ -110,9 +114,9 @@ export class TweenManager {
   }
 
   /**
-   * TBD.
-   * @param {object} obj - TBD.
-   * @param {object[]} children - TBD.
+   * Remove tweens associated with an object or its children.
+   * @param {object} obj - The object to remove tweens from.
+   * @param {object[]} children - Optional array of child objects to remove tweens from.
    */
   removeFrom(obj, children = null) {
     let i;
@@ -140,8 +144,8 @@ export class TweenManager {
   }
 
   /**
-   * TBD.
-   * @param {Tween} tween - TBD.
+   * Add a tween to the manager.
+   * @param {Tween} tween - The tween to add.
    */
   add(tween) {
     tween.manager = this;
@@ -149,17 +153,17 @@ export class TweenManager {
   }
 
   /**
-   * TBD.
-   * @param {object} object - TBD.
-   * @returns {Tween} TBD.
+   * Create a new tween for an object.
+   * @param {object} object - The object to create a tween for.
+   * @returns {Tween} The created Tween object.
    */
   create(object) {
     return new Tween(object, this.game, this);
   }
 
   /**
-   * TBD.
-   * @param {Tween | null | undefined} tween - TBD.
+   * Remove a tween from the manager.
+   * @param {Tween | null | undefined} tween - The tween to remove.
    */
   remove(tween) {
     let i = this._tweens.indexOf(tween);
@@ -174,8 +178,8 @@ export class TweenManager {
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Update all tweens managed by this manager.
+   * @returns {boolean} True if any tweens were updated, false otherwise.
    */
   update() {
     const addTweens = this._add.length;
@@ -201,16 +205,17 @@ export class TweenManager {
   }
 
   /**
-   * TBD.
-   * @param {object} object - TBD.
-   * @returns {boolean} TBD.
+   * Check if an object is currently being tweened.
+   * @param {object} object - The object to check.
+   * @returns {boolean} True if the object is being tweened, false otherwise.
    */
   isTweening(object) {
     return this._tweens.some((tween) => tween.target === object);
   }
 
   /**
-   * TBD.
+   * Pause all tweens managed by this manager.
+   * This method pauses all active tweens.
    */
   _pauseAll() {
     for (let i = this._tweens.length - 1; i >= 0; i -= 1) {
@@ -219,7 +224,8 @@ export class TweenManager {
   }
 
   /**
-   * TBD.
+   * Resume all tweens managed by this manager.
+   * This method resumes all paused tweens.
    */
   _resumeAll() {
     for (let i = this._tweens.length - 1; i >= 0; i -= 1) {
@@ -228,7 +234,8 @@ export class TweenManager {
   }
 
   /**
-   * TBD.
+   * Pause all tweens managed by this manager.
+   * This method pauses all active tweens.
    */
   pauseAll() {
     for (let i = this._tweens.length - 1; i >= 0; i -= 1) {
@@ -237,7 +244,8 @@ export class TweenManager {
   }
 
   /**
-   * TBD.
+   * Resume all tweens managed by this manager.
+   * This method resumes all paused tweens.
    */
   resumeAll() {
     for (let i = this._tweens.length - 1; i >= 0; i -= 1) {

package/src/phaser/core/world.js

@@ -2,15 +2,16 @@ import { Group } from '../display/group.js';
 
 export class World extends Group {
   /**
-   * TBD.
-   * @param {import('./game.js').Game} game - TBD.
+   * Creates a new World instance.
+   * @param {import('./game.js').Game} game - The game instance this world belongs to.
    */
   constructor(game) {
     super(game, null, '__world', false);
   }
 
   /**
-   * TBD.
+   * Initialize the world.
+   * This method is called when the game boots and sets up the world.
    */
   boot() {
     this.game.stage.addChild(this);