@vpmedia/phaser 1.94.0 → 1.96.0

package/src/phaser/display/bitmap_text.js

@@ -5,36 +5,47 @@ import { Image } from './image.js';
 
 export class BitmapText extends DisplayObject {
   /**
-   * TBD.
-   * @param {import('../core/game.js').Game} game - TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @param {string} font - TBD.
-   * @param {string} text - TBD.
-   * @param {number} size - TBD.
-   * @param {string} align - TBD.
+   * Creates a new BitmapText instance.
+   * @param {import('../core/game.js').Game} game - The game instance this bitmap text belongs to.
+   * @param {number} x - The x position of the bitmap text.
+   * @param {number} y - The y position of the bitmap text.
+   * @param {string} font - The key of the bitmap font to use.
+   * @param {string} text - The text to display.
+   * @param {number} size - The font size.
+   * @param {string} align - The text alignment (left, center, right).
    */
   constructor(game, x = 0, y = 0, font = '', text = '', size = 32, align = 'left') {
     super(game);
+    /** @type {number} */
     this.type = BITMAP_TEXT;
     this.position.setTo(x, y);
+    /** @type {number} */
     this.textWidth = 0;
+    /** @type {number} */
     this.textHeight = 0;
+    /** @type {Point} */
     this._prevAnchor = new Point();
     this._glyphs = [];
+    /** @type {number} */
     this._maxWidth = 0;
+    /** @type {string} */
     this._text = text.toString() || '';
     this._data = game.cache.getBitmapFont(font);
+    /** @type {string} */
     this._font = font;
+    /** @type {number} */
     this._fontSize = size;
+    /** @type {string} */
     this._align = align;
+    /** @type {number} */
     this._tint = 0xffffff;
     this.updateText();
+    /** @type {boolean} */
     this.dirty = false;
   }
 
   /**
-   * TBD.
+   * Destroys this bitmap text and cleans up resources.
    */
   destroy() {
     this._prevAnchor = null;
@@ -45,7 +56,7 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Called before the update cycle for this bitmap text.
    */
   preUpdate() {
     if (this.pendingDestroy) {
@@ -67,19 +78,19 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {string} text - TBD.
+   * Sets the text to display.
+   * @param {string} text - The new text to display.
    */
   setText(text) {
     this.text = text;
   }
 
   /**
-   * TBD.
-   * @param {object} data - TBD.
-   * @param {number} scale - TBD.
-   * @param {string} text - TBD.
-   * @returns {object} TBD.
+   * Scans a line of text to calculate its width and other properties.
+   * @param {object} data - The font data for this bitmap text.
+   * @param {number} scale - The scaling factor to apply to the font size.
+   * @param {string} text - The text to scan.
+   * @returns {{width: number, text: string, end: boolean, chars: number[]}} An object containing the width, processed text, end status, and character positions.
    */
   scanLine(data, scale, text) {
     let x = 0;
@@ -143,10 +154,10 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {string} text - TBD.
-   * @param {string} replace - TBD.
-   * @returns {string} TBD.
+   * Cleans the provided text by removing invalid characters and replacing them with a specified character.
+   * @param {string} text - The text to clean.
+   * @param {string} replace - The character to use for replacement of invalid characters (default: '').
+   * @returns {string} The cleaned text.
    */
   cleanText(text, replace = '') {
     const data = this._data.font;
@@ -171,7 +182,7 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Updates the internal text rendering based on current properties and content.
    */
   updateText() {
     const data = this._data.font;
@@ -242,8 +253,8 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Removes unused glyphs from the pool and returns the number removed.
+   * @returns {number} The number of glyphs that were removed from the pool.
    */
   purgeGlyphs() {
     const len = this._glyphs.length;
@@ -263,7 +274,7 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Updates the transform of this bitmap text, updating its text if needed.
    */
   updateTransform() {
     if (this.dirty || !this.anchor.equals(this._prevAnchor)) {
@@ -275,10 +286,10 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {string} value - TBD.
-   * @param {number} position - TBD.
-   * @returns {BitmapText} TBD.
+   * Adds a color to a specific position in the text.
+   * @param {string} value - The color to apply (in hex format or CSS color name).
+   * @param {number} position - The character position to apply the color to.
+   * @returns {BitmapText} This bitmap text instance for chaining.
    */
   addColor(value, position) {
     const color = typeof value === 'string' ? Number.parseInt(value.replace('#', ''), 16) : value;
@@ -290,15 +301,16 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {string} TBD.
+   * Gets the text alignment property.
+   * @returns {string} The current text alignment (left, center, right).
    */
   get align() {
     return this._align;
   }
 
   /**
-   * TBD.
+   * Sets the text alignment property.
+   * @param {string} value - The new text alignment (left, center, right).
    */
   set align(value) {
     if (value !== this._align && (value === 'left' || value === 'center' || value === 'right')) {
@@ -308,15 +320,16 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the tint color of this bitmap text.
+   * @returns {number} The current tint color in RGB format.
    */
   get tint() {
     return this._tint;
   }
 
   /**
-   * TBD.
+   * Sets the tint color of this bitmap text.
+   * @param {number} value - The new tint color in RGB format.
    */
   set tint(value) {
     if (value !== this._tint) {
@@ -326,8 +339,8 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {string} TBD.
+   * Gets the fill color of this bitmap text as a hex string.
+   * @returns {string} The current fill color in hex format.
    */
   get fill() {
     if (typeof this.tint === 'number') {
@@ -341,22 +354,24 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Sets the fill color of this bitmap text.
+   * @param {string} value - The new fill color in hex format or CSS color name.
    */
   set fill(value) {
     this.tint = typeof value === 'string' ? Number.parseInt(value.replace('#', ''), 16) : value;
   }
 
   /**
-   * TBD.
-   * @returns {string} TBD.
+   * Gets the font key used by this bitmap text.
+   * @returns {string} The current font key.
    */
   get font() {
     return this._font;
   }
 
   /**
-   * TBD.
+   * Sets the font key used by this bitmap text.
+   * @param {string} value - The new font key to use.
    */
   set font(value) {
     const trimmedValue = value.trim();
@@ -368,15 +383,16 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the font size of this bitmap text.
+   * @returns {number} The current font size.
    */
   get fontSize() {
     return this._fontSize;
   }
 
   /**
-   * TBD.
+   * Sets the font size of this bitmap text.
+   * @param {number} value - The new font size to use.
    */
   set fontSize(value) {
     value = Number.parseInt(value, 10);
@@ -387,16 +403,16 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {string} TBD.
+   * Gets the text content of this bitmap text.
+   * @returns {string} The current text content.
    */
   get text() {
     return this._text;
   }
 
   /**
-   * TBD.
-   * @param {string | number | boolean | Date} value - TBD.
+   * Sets the text content of this bitmap text.
+   * @param {string | number | boolean | Date} value - The new text content to set.
    */
   set text(value) {
     const typedValue = value.toString();
@@ -407,15 +423,16 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the maximum width of this bitmap text.
+   * @returns {number} The current maximum width.
    */
   get maxWidth() {
     return this._maxWidth;
   }
 
   /**
-   * TBD.
+   * Sets the maximum width of this bitmap text.
+   * @param {number} value - The new maximum width to set.
    */
   set maxWidth(value) {
     if (value !== this._maxWidth) {
@@ -425,15 +442,16 @@ export class BitmapText extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Gets whether smoothing is enabled for this bitmap text's font.
+   * @returns {boolean} True if smoothing is enabled, false otherwise.
    */
   get smoothed() {
     return !this._data.base.scaleMode;
   }
 
   /**
-   * TBD.
+   * Sets whether smoothing is enabled for this bitmap text's font.
+   * @param {boolean} value - Whether to enable smoothing (true) or not (false).
    */
   set smoothed(value) {
     if (value) {

package/src/phaser/display/button.js

@@ -11,18 +11,18 @@ const STATE_DISABLED = 'Disabled';
 
 export class Button extends Image {
   /**
-   * TBD.
-   * @param {import('../core/game.js').Game} game - TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @param {string} key - TBD.
-   * @param {Function} callback - TBD.
-   * @param {object} callbackContext - TBD.
-   * @param {string} overFrame - TBD.
-   * @param {string} outFrame - TBD.
-   * @param {string} downFrame - TBD.
-   * @param {string} upFrame - TBD.
-   * @param {string} disabledFrame - TBD.
+   * Creates a new Button instance.
+   * @param {import('../core/game.js').Game} game - The game instance this button belongs to.
+   * @param {number} x - The x position of the button.
+   * @param {number} y - The y position of the button.
+   * @param {string} key - The texture key to use for the button.
+   * @param {Function} callback - The function to call when the button is clicked.
+   * @param {object} callbackContext - The context in which to call the callback function.
+   * @param {string} overFrame - The frame identifier to use when the mouse is over the button.
+   * @param {string} outFrame - The frame identifier to use when the mouse is outside the button.
+   * @param {string} downFrame - The frame identifier to use when the button is pressed.
+   * @param {string} upFrame - The frame identifier to use when the button is released.
+   * @param {string} disabledFrame - The frame identifier to use when the button is disabled.
    */
   constructor(
     game,
@@ -67,7 +67,7 @@ export class Button extends Image {
   }
 
   /**
-   * TBD.
+   * Destroys this button and cleans up resources.
    */
   destroy() {
     this._onOverFrame = null;
@@ -93,9 +93,9 @@ export class Button extends Image {
   }
 
   /**
-   * TBD.
-   * @param {boolean} isEnabled - TBD.
-   * @param {boolean} isImmediate - TBD.
+   * Sets whether this button is enabled or disabled.
+   * @param {boolean} isEnabled - Whether the button should be enabled (true) or disabled (false).
+   * @param {boolean} isImmediate - Whether to change the state immediately or with a delay (default: false).
    */
   setEnabled(isEnabled, isImmediate = false) {
     this.input.enabled = isEnabled;
@@ -109,24 +109,24 @@ export class Button extends Image {
   }
 
   /**
-   * TBD.
+   * Clears all the frame settings for this button.
    */
   clearFrames() {
     this.setFrames(null, null, null, null, null);
   }
 
   /**
-   * TBD.
+   * Called when this button is removed from the world.
    */
   removedFromWorld() {
     this.inputEnabled = false;
   }
 
   /**
-   * TBD.
-   * @param {string} state - TBD.
-   * @param {string} frame - TBD.
-   * @param {boolean} switchImmediately - TBD.
+   * Sets a specific frame for a particular state of this button.
+   * @param {string} state - The state name (Over, Out, Down, Up, Disabled).
+   * @param {string} frame - The frame identifier to set for this state.
+   * @param {boolean} switchImmediately - Whether to switch to the new frame immediately (default: false).
    */
   setStateFrame(state, frame, switchImmediately = false) {
     const frameKey = `_on${state}Frame`;
@@ -141,9 +141,9 @@ export class Button extends Image {
   }
 
   /**
-   * TBD.
-   * @param {string} newState - TBD.
-   * @returns {boolean} TBD.
+   * Changes the frame of this button to match the specified state.
+   * @param {string} newState - The new state to change to (Over, Out, Down, Up, Disabled).
+   * @returns {boolean} True if the frame was changed, false otherwise.
    */
   changeStateFrame(newState) {
     if (this.freezeFrames) {
@@ -163,12 +163,12 @@ export class Button extends Image {
   }
 
   /**
-   * TBD.
-   * @param {string} overFrame - TBD.
-   * @param {string} outFrame - TBD.
-   * @param {string} downFrame - TBD.
-   * @param {string} upFrame - TBD.
-   * @param {string} disabledFrame - TBD.
+   * Sets the frame identifiers for all states of this button.
+   * @param {string} overFrame - The frame identifier to use when the mouse is over the button.
+   * @param {string} outFrame - The frame identifier to use when the mouse is outside the button.
+   * @param {string} downFrame - The frame identifier to use when the button is pressed.
+   * @param {string} upFrame - The frame identifier to use when the button is released.
+   * @param {string} disabledFrame - The frame identifier to use when the button is disabled.
    */
   setFrames(overFrame, outFrame, downFrame, upFrame, disabledFrame = null) {
     this.setStateFrame(STATE_OVER, overFrame, this.input.pointerOver());
@@ -181,9 +181,9 @@ export class Button extends Image {
   }
 
   /**
-   * TBD.
-   * @param {object} sprite - TBD.
-   * @param {object} pointer - TBD.
+   * Handles the input over event for this button.
+   * @param {object} sprite - The sprite that triggered the event.
+   * @param {object} pointer - The pointer that triggered the event.
    */
   onInputOverHandler(sprite, pointer) {
     if (pointer.justReleased() && (this.justReleasedPreventsOver & pointer.pointerMode) === pointer.pointerMode) {
@@ -200,9 +200,9 @@ export class Button extends Image {
   }
 
   /**
-   * TBD.
-   * @param {object} sprite - TBD.
-   * @param {object} pointer - TBD.
+   * Handles the input out event for this button.
+   * @param {object} sprite - The sprite that triggered the event.
+   * @param {object} pointer - The pointer that triggered the event.
    */
   onInputOutHandler(sprite, pointer) {
     this.changeStateFrame(STATE_OUT);
@@ -212,9 +212,9 @@ export class Button extends Image {
   }
 
   /**
-   * TBD.
-   * @param {object} sprite - TBD.
-   * @param {object} pointer - TBD.
+   * Handles the input down event for this button.
+   * @param {object} sprite - The sprite that triggered the event.
+   * @param {object} pointer - The pointer that triggered the event.
    */
   onInputDownHandler(sprite, pointer) {
     this.changeStateFrame(STATE_DOWN);
@@ -224,10 +224,10 @@ export class Button extends Image {
   }
 
   /**
-   * TBD.
-   * @param {object} sprite - TBD.
-   * @param {object} pointer - TBD.
-   * @param {boolean} isOver - TBD.
+   * Handles the input up event for this button.
+   * @param {object} sprite - The sprite that triggered the event.
+   * @param {object} pointer - The pointer that triggered the event.
+   * @param {boolean} isOver - Whether the pointer is currently over the button (default: true).
    */
   onInputUpHandler(sprite, pointer, isOver) {
     if (this.onInputUp) {
@@ -252,15 +252,16 @@ export class Button extends Image {
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Gets whether input is currently enabled for this button.
+   * @returns {boolean} True if input is enabled, false otherwise.
    */
   get inputEnabled() {
     return this.input && this.input.enabled;
   }
 
   /**
-   * TBD.
+   * Sets whether input is currently enabled for this button.
+   * @param {boolean} value - Whether to enable (true) or disable (false) input.
    */
   set inputEnabled(value) {
     if (value) {

package/src/phaser/display/canvas/buffer.js

@@ -2,9 +2,9 @@ import { create, removeByCanvas } from './pool.js';
 
 export class CanvasBuffer {
   /**
-   * TBD.
-   * @param {number} width - TBD.
-   * @param {number} height - TBD.
+   * Creates a new CanvasBuffer instance.
+   * @param {number} width - The width of the canvas buffer.
+   * @param {number} height - The height of the canvas buffer.
    */
   constructor(width, height) {
     this.width = width;
@@ -16,7 +16,7 @@ export class CanvasBuffer {
   }
 
   /**
-   * TBD.
+   * Clears the canvas buffer.
    */
   clear() {
     this.context.setTransform(1, 0, 0, 1, 0, 0);
@@ -24,9 +24,9 @@ export class CanvasBuffer {
   }
 
   /**
-   * TBD.
-   * @param {number} width - TBD.
-   * @param {number} height - TBD.
+   * Resizes the canvas buffer.
+   * @param {number} width - The new width of the canvas buffer.
+   * @param {number} height - The new height of the canvas buffer.
    */
   resize(width, height) {
     this.width = width;
@@ -36,7 +36,7 @@ export class CanvasBuffer {
   }
 
   /**
-   * TBD.
+   * Destroys the canvas buffer and cleans up resources.
    */
   destroy() {
     try {

package/src/phaser/display/canvas/graphics.js

@@ -1,8 +1,8 @@
 import { GEOM_CIRCLE, GEOM_ELLIPSE, GEOM_POLYGON, GEOM_RECTANGLE, GEOM_ROUNDED_RECTANGLE } from '../../core/const.js';
 
 /**
- * TBD.
- * @param {object} graphics - TBD.
+ * Renders a graphics object to canvas.
+ * @param {import('../graphics.js').Graphics} graphics - The graphics object to render.
  */
 export const updateGraphicsTint = (graphics) => {
   if (graphics.tint === 0xffffff) {
@@ -27,9 +27,9 @@ export const updateGraphicsTint = (graphics) => {
 };
 
 /**
- * TBD.
- * @param {object} graphics - TBD.
- * @param {object} context - TBD.
+ * Renders a graphics object to canvas.
+ * @param {import('../graphics.js').Graphics} graphics - The graphics object to render.
+ * @param {object} context - The canvas rendering context.
  */
 export const renderGraphics = (graphics, context) => {
   const worldAlpha = graphics.worldAlpha;
@@ -156,9 +156,9 @@ export const renderGraphics = (graphics, context) => {
 };
 
 /**
- * TBD.
- * @param {object} graphics - TBD.
- * @param {object} context - TBD.
+ * Renders a graphics object to canvas.
+ * @param {import('../graphics.js').Graphics} graphics - The graphics object to render.
+ * @param {object} context - The canvas rendering context.
  */
 export const renderGraphicsMask = (graphics, context) => {
   const len = graphics.graphicsData.length;

package/src/phaser/display/canvas/masker.js

@@ -1,9 +1,9 @@
 import { renderGraphicsMask } from './graphics.js';
 
 /**
- * TBD.
- * @param {object} maskData - TBD.
- * @param {object} renderSession - TBD.
+ * Pushes a mask onto the rendering stack.
+ * @param {object} maskData - The mask data to apply.
+ * @param {object} renderSession - The rendering session object.
  */
 export const pushMask = (maskData, renderSession) => {
   const context = renderSession.context;
@@ -25,8 +25,8 @@ export const pushMask = (maskData, renderSession) => {
 };
 
 /**
- * TBD.
- * @param {object} renderSession - TBD.
+ * Pops a mask from the rendering stack.
+ * @param {object} renderSession - The rendering session object.
  */
 export const popMask = (renderSession) => {
   renderSession.context.restore();

package/src/phaser/display/canvas/pool.js

@@ -1,6 +1,6 @@
 /**
- * TBD.
- * @returns {object[]} TBD.
+ * Gets the canvas pool array.
+ * @returns {{canvas: HTMLCanvasElement, parent: object}[]} The canvas pool array.
  */
 export const getPool = () => {
   if (!window.PhaserRegistry) {
@@ -13,8 +13,8 @@ export const getPool = () => {
 };
 
 /**
- * TBD.
- * @returns {object} TBD.
+ * Gets the current size of the canvas pool.
+ * @returns {number} The current size of the canvas pool.
  */
 export const getFirst = () => {
   const pool = getPool();
@@ -27,8 +27,8 @@ export const getFirst = () => {
 };
 
 /**
- * TBD.
- * @param {object} parent - TBD.
+ * Adds a canvas to the pool with the specified parent.
+ * @param {object} parent - The parent object for the canvas.
  */
 export const remove = (parent) => {
   const pool = getPool();
@@ -42,8 +42,8 @@ export const remove = (parent) => {
 };
 
 /**
- * TBD.
- * @param {HTMLCanvasElement} canvas - TBD.
+ * Removes a canvas from the pool.
+ * @param {HTMLCanvasElement} canvas - The canvas to remove from the pool.
  */
 export const removeByCanvas = (canvas) => {
   const pool = getPool();
@@ -57,8 +57,8 @@ export const removeByCanvas = (canvas) => {
 };
 
 /**
- * TBD.
- * @returns {number} TBD.
+ * Gets the total count of canvases in the pool.
+ * @returns {number} The total count of canvases in the pool.
  */
 export const getTotal = () => {
   const pool = getPool();
@@ -72,8 +72,8 @@ export const getTotal = () => {
 };
 
 /**
- * TBD.
- * @returns {number} TBD.
+ * Gets the number of free canvases in the pool.
+ * @returns {number} The number of free canvases in the pool.
  */
 export const getFree = () => {
   const pool = getPool();
@@ -87,12 +87,12 @@ export const getFree = () => {
 };
 
 /**
- * TBD.
- * @param {object} parent - TBD.
- * @param {number} width - TBD.
- * @param {number} height - TBD.
- * @param {boolean} skipPool - TBD.
- * @returns {HTMLCanvasElement} TBD.
+ * Gets a canvas from the pool or creates a new one.
+ * @param {object} parent - The parent object for the canvas.
+ * @param {number} [width] - Optional width of the canvas.
+ * @param {number} [height] - Optional height of the canvas.
+ * @param {boolean} skipPool - True to skip using the pool and create a new canvas.
+ * @returns {HTMLCanvasElement} The canvas from the pool or a newly created one.
  */
 export const create = (parent, width, height, skipPool = false) => {
   if (parent === undefined) {