@vpmedia/phaser 1.94.0 → 1.96.0

package/src/phaser/display/group.js

@@ -8,19 +8,22 @@ export const SORT_DESCENDING = 1;
 
 export class Group extends DisplayObject {
   /**
-   * TBD.
-   * @param {import('../core/game.js').Game} game - TBD.
-   * @param {DisplayObject} parent - TBD.
-   * @param {string} name - TBD.
-   * @param {boolean} addToStage - TBD.
+   * Creates a new Group object.
+   * @param {import('../core/game.js').Game} game - The game instance this group belongs to.
+   * @param {DisplayObject} parent - The parent display object.
+   * @param {string} name - The name of this group.
+   * @param {boolean} addToStage - Whether to add this group to the stage.
    */
   constructor(game, parent = null, name = null, addToStage = false) {
     super(game);
+    /** @type {number} */
     this.type = GROUP;
     if (!parent) {
       parent = game.world;
     }
+    /** @type {string} */
     this.name = name || 'group';
+    /** @type {number} */
     this.z = 0;
     if (addToStage) {
       this.game.stage.addChild(this);
@@ -29,24 +32,34 @@ export class Group extends DisplayObject {
       parent.addChild(this);
       this.z = parent.children.length;
     }
+    /** @type {boolean} */
     this.ignoreDestroy = false;
+    /** @type {boolean} */
     this.pendingDestroy = false;
     this.classType = Image;
     this.cursor = null;
+    /** @type {boolean} */
     this.inputEnableChildren = false;
+    /** @type {Signal} */
     this.onChildInputDown = new Signal();
+    /** @type {Signal} */
     this.onChildInputUp = new Signal();
+    /** @type {Signal} */
     this.onChildInputOver = new Signal();
+    /** @type {Signal} */
     this.onChildInputOut = new Signal();
+    /** @type {Signal} */
     this.onDestroy = new Signal();
+    /** @type {number} */
     this.cursorIndex = 0;
+    /** @type {string} */
     this._sortProperty = 'z';
   }
 
   /**
-   * TBD.
-   * @param {boolean} destroyChildren - TBD.
-   * @param {boolean} soft - TBD.
+   * Destroys this group and cleans up resources.
+   * @param {boolean} destroyChildren - Whether to destroy children as well.
+   * @param {boolean} soft - Whether to perform a soft destroy (leaving the group in the parent's children list).
    */
   destroy(destroyChildren = true, soft = false) {
     if (this.game === null || this.ignoreDestroy) {
@@ -67,11 +80,11 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {DisplayObject} child - TBD.
-   * @param {boolean} silent - TBD.
-   * @param {number} index - TBD.
-   * @returns {DisplayObject} TBD.
+   * Adds a child to this group.
+   * @param {DisplayObject} child - The child to add.
+   * @param {boolean} silent - Whether to dispatch events.
+   * @param {number} index - The index to add the child at.
+   * @returns {DisplayObject} The added child.
    */
   add(child, silent = false, index = -1) {
     if (child.parent === this) {
@@ -97,19 +110,19 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {DisplayObject} child - TBD.
-   * @param {number} index - TBD.
-   * @param {boolean} silent - TBD.
+   * Adds a child to this group at a specific index.
+   * @param {DisplayObject} child - The child to add.
+   * @param {number} index - The index to add the child at.
+   * @param {boolean} silent - Whether to dispatch events.
    */
   addAt(child, index, silent) {
     this.add(child, silent, index);
   }
 
   /**
-   * TBD.
-   * @param {number} index - TBD.
-   * @returns {DisplayObject} TBD.
+   * Gets a child at the specified index.
+   * @param {number} index - The index of the child to get.
+   * @returns {DisplayObject} The child at the specified index, or -1 if not found.
    */
   getAt(index) {
     if (index < 0 || index >= this.children.length) {
@@ -119,7 +132,7 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Updates the Z indices of all children in this group.
    */
   updateZ() {
     let i = this.children.length;
@@ -130,8 +143,8 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {DisplayObject} TBD.
+   * Gets the next child in this group (with circular wrapping).
+   * @returns {DisplayObject} The next child, or null if no children exist.
    */
   next() {
     if (this.cursor) {
@@ -148,8 +161,8 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {DisplayObject} TBD.
+   * Gets the previous child in this group (with circular wrapping).
+   * @returns {DisplayObject} The previous child, or null if no children exist.
    */
   previous() {
     if (this.cursor) {
@@ -166,9 +179,9 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {DisplayObject} child1 - TBD.
-   * @param {DisplayObject} child2 - TBD.
+   * Swaps the positions of two children in this group.
+   * @param {DisplayObject} child1 - The first child to swap.
+   * @param {DisplayObject} child2 - The second child to swap.
    */
   swap(child1, child2) {
     this.swapChildren(child1, child2);
@@ -176,9 +189,9 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {DisplayObject} child - TBD.
-   * @returns {DisplayObject} TBD.
+   * Brings a child to the top of this group.
+   * @param {DisplayObject} child - The child to bring to the top.
+   * @returns {DisplayObject} The child that was brought to the top.
    */
   bringToTop(child) {
     if (child.parent === this && this.getIndex(child) < this.children.length) {
@@ -189,9 +202,9 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {DisplayObject} child - TBD.
-   * @returns {DisplayObject} TBD.
+   * Sends a child to the back of this group.
+   * @param {DisplayObject} child - The child to send to the back.
+   * @returns {DisplayObject} The child that was sent to the back.
    */
   sendToBack(child) {
     if (child.parent === this && this.getIndex(child) > 0) {
@@ -202,7 +215,7 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Reverses the order of children in this group.
    */
   reverse() {
     this.children.reverse();
@@ -210,16 +223,16 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {DisplayObject} child - TBD.
-   * @returns {number} TBD.
+   * Gets the index of a child in this group.
+   * @param {DisplayObject} child - The child to get the index of.
+   * @returns {number} The index of the child, or -1 if not found.
    */
   getIndex(child) {
     return this.children.indexOf(child);
   }
 
   /**
-   * TBD.
+   * Updates the Z indices of all children in this group before the update cycle.
    */
   preUpdate() {
     if (this.pendingDestroy) {
@@ -236,7 +249,7 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Updates all children in this group during the update cycle.
    */
   update() {
     let i = this.children.length;
@@ -247,7 +260,7 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Updates all children in this group after the update cycle.
    */
   postUpdate() {
     for (let i = 0; i < this.children.length; i += 1) {
@@ -256,11 +269,11 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {DisplayObject} child - TBD.
-   * @param {boolean} destroy - TBD.
-   * @param {boolean} silent - TBD.
-   * @returns {boolean} TBD.
+   * Removes a child from this group.
+   * @param {DisplayObject} child - The child to remove.
+   * @param {boolean} destroy - Whether to destroy the child after removing it.
+   * @param {boolean} silent - Whether to dispatch events.
+   * @returns {boolean} True if the child was removed, false otherwise.
    */
   remove(child, destroy = true, silent = false) {
     if (this.children.length === 0 || this.children.indexOf(child) === -1) {
@@ -281,10 +294,10 @@ export class Group extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {boolean} destroy - TBD.
-   * @param {boolean} silent - TBD.
-   * @param {boolean} destroyTexture - TBD.
+   * Removes all children from this group.
+   * @param {boolean} destroy - Whether to destroy children as well.
+   * @param {boolean} silent - Whether to dispatch events.
+   * @param {boolean} destroyTexture - Whether to destroy textures as well.
    */
   removeAll(destroy = true, silent = false, destroyTexture = false) {
     if (this.children.length === 0) {

package/src/phaser/display/image.js

@@ -9,41 +9,55 @@ import { Texture } from './webgl/texture.js';
 
 export class Image extends DisplayObject {
   /**
-   * TBD.
-   * @param {import('../core/game.js').Game} game - TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @param {string} key - TBD.
-   * @param {string | number} frame - TBD.
+   * Creates a new Image instance.
+   * @param {import('../core/game.js').Game} game - The game instance this image belongs to.
+   * @param {number} x - The x position of the image.
+   * @param {number} y - The y position of the image.
+   * @param {string | number | Texture} key - The texture key or texture to use.
+   * @param {string | number} frame - The frame identifier (name or index) to use.
    */
   constructor(game, x, y, key, frame = 0) {
     super(game);
+    /** @type {number} */
     this.type = IMAGE;
+    /** @type {boolean} */
     this.renderable = true;
+    /** @type {string | number | Texture} */
     this.key = key;
     this.texture = window.PhaserRegistry.CACHE_MISSING_IMAGE;
     /** @type {object} */
     this.data = {};
+    /** @type {number} */
     this._width = 0;
+    /** @type {number} */
     this._height = 0;
+    /** @type {number} */
     this.tint = 0xffffff;
+    /** @type {number} */
     this.cachedTint = -1;
+    /** @type {Texture | null} */
+    this.tilingTexture = null;
+    /** @type {Texture | null} */
     this.tintedTexture = null;
+    /** @type {number} */
     this.blendMode = BLEND_NORMAL;
     this.shader = null;
     this._frame = null;
+    /** @type {boolean} */
     this.pendingDestroy = false;
     /* if (this.texture.baseTexture.hasLoaded) {
       this.onTextureUpdate();
     } */
     this.position.setTo(x, y);
+    /** @type {EventManager} */
     this.events = new EventManager(this);
+    /** @type {AnimationManager} */
     this.animations = new AnimationManager(this);
     this.loadTexture(key, frame);
   }
 
   /**
-   * TBD.
+   * Destroys this image and cleans up resources.
    */
   destroy() {
     this.game = null;
@@ -67,7 +81,7 @@ export class Image extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Called before the update cycle for this image.
    */
   preUpdate() {
     if (this.pendingDestroy) {
@@ -93,10 +107,10 @@ export class Image extends DisplayObject {
   // LoadTexture
 
   /**
-   * TBD.
-   * @param {string | number | Texture} key - TBD.
-   * @param {string | number | null | undefined} frame - TBD.
-   * @param {boolean} stopAnimation - TBD.
+   * Loads a texture for this image.
+   * @param {string | number | Texture} key - The texture key or texture to use.
+   * @param {string | number | null | undefined} frame - The frame identifier (name or index) to use.
+   * @param {boolean} stopAnimation - Whether to stop the animation when changing textures.
    */
   loadTexture(key, frame = 0, stopAnimation = true) {
     if (key === PENDING_ATLAS) {
@@ -137,8 +151,8 @@ export class Image extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {import('../core/frame.js').Frame} frame - TBD.
+   * Sets the current frame of this image.
+   * @param {import('../core/frame.js').Frame} frame - The frame to set.
    */
   setFrame(frame) {
     this._frame = frame;
@@ -182,10 +196,10 @@ export class Image extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {DisplayObject} parent - TBD.
-   * @param {number} width - TBD.
-   * @param {number} height - TBD.
+   * Resizes the frame of this image.
+   * @param {DisplayObject} parent - The parent display object.
+   * @param {number} width - The new width of the frame.
+   * @param {number} height - The new height of the frame.
    */
   resizeFrame(parent, width, height) {
     this.texture.frame.resize(width, height);
@@ -193,7 +207,7 @@ export class Image extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Resets the frame of this image to its original frame.
    */
   resetFrame() {
     if (this._frame) {
@@ -202,30 +216,32 @@ export class Image extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the current frame index of this image.
+   * @returns {number} The current frame index.
    */
   get frame() {
     return this.animations.frame;
   }
 
   /**
-   * TBD.
+   * Sets the current frame index of this image.
+   * @param {number} value - The new frame index to set.
    */
   set frame(value) {
     this.animations.frame = value;
   }
 
   /**
-   * TBD.
-   * @returns {string} TBD.
+   * Gets the current frame name of this image.
+   * @returns {string} The current frame name.
    */
   get frameName() {
     return this.animations.frameName;
   }
 
   /**
-   * TBD.
+   * Sets the current frame name of this image.
+   * @param {string} value - The new frame name to set.
    */
   set frameName(value) {
     this.animations.frameName = value;
@@ -234,9 +250,9 @@ export class Image extends DisplayObject {
   // Crop
 
   /**
-   * TBD.
-   * @param {Rectangle} rect - TBD.
-   * @param {boolean} copy - TBD.
+   * Crops the texture of this image.
+   * @param {Rectangle} rect - The rectangle to crop to.
+   * @param {boolean} copy - Whether to copy the rect or use it directly.
    */
   crop(rect, copy = false) {
     if (rect) {
@@ -256,7 +272,7 @@ export class Image extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Updates the crop rectangle of this image.
    */
   updateCrop() {
     if (!this.cropRect) {
@@ -288,15 +304,16 @@ export class Image extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the width of this image.
+   * @returns {number} The width in pixels.
    */
   get width() {
     return this.scale.x * this.texture.frame.width;
   }
 
   /**
-   * TBD.
+   * Sets the width of this image.
+   * @param {number} value - The new width in pixels.
    */
   set width(value) {
     this.scale.x = value / this.texture.frame.width;
@@ -304,15 +321,16 @@ export class Image extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the height of this image.
+   * @returns {number} The height in pixels.
    */
   get height() {
     return this.scale.y * this.texture.frame.height;
   }
 
   /**
-   * TBD.
+   * Sets the height of this image.
+   * @param {number} value - The new height in pixels.
    */
   set height(value) {
     this.scale.y = value / this.texture.frame.height;
@@ -320,7 +338,7 @@ export class Image extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Called when the texture of this image is updated.
    */
   onTextureUpdate() {
     // so if _width is 0 then width was not set..
@@ -333,44 +351,44 @@ export class Image extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {Texture} texture - TBD.
-   * @param {boolean} destroyBase - TBD.
+   * Sets the texture for this image.
+   * @param {Texture} texture - The new texture to set.
+   * @param {boolean} destroyBase - Whether to destroy the base texture.
    */
   setTexture(texture, destroyBase = false) {
     setTexture(this, texture, destroyBase);
   }
 
   /**
-   * TBD.
-   * @param {import('../geom/matrix.js').Matrix} matrix - TBD.
-   * @returns {Rectangle} TBD.
+   * Gets the bounds of this image.
+   * @param {import('../geom/matrix.js').Matrix} matrix - The transformation matrix to use.
+   * @returns {Rectangle} The bounds rectangle of this image.
    */
   getBounds(matrix = null) {
     return getBounds(this, matrix);
   }
 
   /**
-   * TBD.
-   * @returns {Rectangle} TBD.
+   * Gets the local bounds of this image.
+   * @returns {Rectangle} The local bounds rectangle of this image.
    */
   getLocalBounds() {
     return getLocalBounds(this);
   }
 
   /**
-   * TBD.
-   * @param {object} renderSession - TBD.
-   * @param {import('../geom/matrix.js').Matrix} matrix - TBD.
+   * Renders this image using WebGL.
+   * @param {object} renderSession - The WebGL rendering session.
+   * @param {import('../geom/matrix.js').Matrix} matrix - The transformation matrix to use.
    */
   renderWebGL(renderSession, matrix = null) {
     renderWebGL(this, renderSession, matrix);
   }
 
   /**
-   * TBD.
-   * @param {object} renderSession - TBD.
-   * @param {import('../geom/matrix.js').Matrix} matrix - TBD.
+   * Renders this image using Canvas.
+   * @param {object} renderSession - The Canvas rendering session.
+   * @param {import('../geom/matrix.js').Matrix} matrix - The transformation matrix to use.
    */
   renderCanvas(renderSession, matrix = null) {
     renderCanvas(this, renderSession, matrix);

package/src/phaser/display/sprite_batch.js

@@ -2,8 +2,8 @@ import { DisplayObject } from './display_object.js';
 
 export class SpriteBatch extends DisplayObject {
   /**
-   * TBD.
-   * @param {import('../core/game.js').Game} game - TBD.
+   * Creates a new SpriteBatch object.
+   * @param {import('../core/game.js').Game} game - The game instance.
    */
   constructor(game) {
     super(game);

package/src/phaser/display/sprite_util.js

@@ -3,10 +3,10 @@ import { getIdentityMatrix } from '../geom/util/matrix.js';
 import { getTintedTexture } from './canvas/tinter.js';
 
 /**
- * TBD.
- * @param {import('./image.js').Image} target - TBD.
- * @param {import('./webgl/texture.js').Texture} texture - TBD.
- * @param {boolean} destroyBase - TBD.
+ * Sets the texture of a sprite.
+ * @param {import('./image.js').Image} target - The target image to set the texture on.
+ * @param {import('./webgl/texture.js').Texture} texture - The new texture to set.
+ * @param {boolean} destroyBase - Whether to destroy the base texture.
  */
 export const setTexture = (target, texture, destroyBase = false) => {
   if (destroyBase) {
@@ -19,10 +19,10 @@ export const setTexture = (target, texture, destroyBase = false) => {
 };
 
 /**
- * TBD.
- * @param {import('./image.js').Image} target - TBD.
- * @param {object} matrix - TBD.
- * @returns {import('../geom/rectangle.js').Rectangle} TBD.
+ * Gets the bounds of a sprite.
+ * @param {import('./image.js').Image} target - The target image to get bounds for.
+ * @param {object} matrix - The transformation matrix.
+ * @returns {import('../geom/rectangle.js').Rectangle} The bounds rectangle.
  */
 export const getBounds = (target, matrix = null) => {
   // TODO verify
@@ -102,9 +102,9 @@ export const getBounds = (target, matrix = null) => {
 };
 
 /**
- * TBD.
- * @param {import('./image.js').Image} target - TBD.
- * @returns {import('../geom/rectangle.js').Rectangle} TBD.
+ * Gets the local bounds of a sprite.
+ * @param {import('./image.js').Image} target - The target image to get local bounds for.
+ * @returns {import('../geom/rectangle.js').Rectangle} The local bounds rectangle.
  */
 export const getLocalBounds = (target) => {
   const matrixCache = target.worldTransform;
@@ -122,10 +122,10 @@ export const getLocalBounds = (target) => {
 };
 
 /**
- * TBD.
- * @param {import('./image.js').Image} target - TBD.
- * @param {object} renderSession - TBD.
- * @param {import('../geom/matrix.js').Matrix | null | undefined} matrix - TBD.
+ * Renders a sprite using WebGL.
+ * @param {import('./image.js').Image} target - The target image to render.
+ * @param {object} renderSession - The render session object.
+ * @param {import('../geom/matrix.js').Matrix | null | undefined} matrix - The transformation matrix.
  */
 export const renderWebGL = (target, renderSession, matrix = null) => {
   // if the sprite is not visible or the alpha is 0 then no need to render this element
@@ -171,10 +171,10 @@ export const renderWebGL = (target, renderSession, matrix = null) => {
 };
 
 /**
- * TBD.
- * @param {import('./image.js').Image} target - TBD.
- * @param {object} renderSession - TBD.
- * @param {import('../geom/matrix.js').Matrix | null | undefined} matrix - TBD.
+ * Renders a sprite using Canvas.
+ * @param {import('./image.js').Image} target - The target image to render.
+ * @param {object} renderSession - The render session object.
+ * @param {import('../geom/matrix.js').Matrix | null | undefined} matrix - The transformation matrix.
  */
 export const renderCanvas = (target, renderSession, matrix = null) => {
   // If the sprite is not visible or the alpha is 0 then no need to render this element