@vpmedia/phaser 1.94.0 → 1.96.0

package/src/phaser/core/factory.js

@@ -7,21 +7,21 @@ import { Text } from '../display/text.js';
 
 export class GameObjectFactory {
   /**
-   * TBD.
-   * @param {import('./game.js').Game} game - TBD.
+   * Creates a new GameObjectFactory instance.
+   * @param {import('./game.js').Game} game - The game instance this factory belongs to.
    */
   constructor(game) {
     this.game = game;
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @param {string} key - TBD.
-   * @param {string|number} frame - TBD.
-   * @param {Group} group - TBD.
-   * @returns {Image} TBD.
+   * Creates a new Image object.
+   * @param {number} x - The x coordinate of the image.
+   * @param {number} y - The y coordinate of the image.
+   * @param {string} key - The texture key for the image.
+   * @param {string|number} frame - The frame to display.
+   * @param {Group} group - The parent group for the image.
+   * @returns {Image} The created Image object.
    */
   image(x, y, key, frame, group = null) {
     if (!group) {
@@ -31,24 +31,24 @@ export class GameObjectFactory {
   }
 
   /**
-   * TBD.
-   * @param {Group | null} parent - TBD.
-   * @param {string | null} name - TBD.
-   * @param {boolean} addToStage - TBD.
-   * @returns {Group} TBD.
+   * Creates a new Group object.
+   * @param {Group | null} parent - The parent group for the new group.
+   * @param {string | null} name - The name of the group.
+   * @param {boolean} addToStage - Whether to add the group to the stage.
+   * @returns {Group} The created Group object.
    */
   group(parent = null, name = null, addToStage = false) {
     return new Group(this.game, parent, name, addToStage);
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @param {string} text - TBD.
-   * @param {object} style - TBD.
-   * @param {Group | null} group - TBD.
-   * @returns {Text} TBD.
+   * Creates a new Text object.
+   * @param {number} x - The x coordinate of the text.
+   * @param {number} y - The y coordinate of the text.
+   * @param {string} text - The text content to display.
+   * @param {object} style - The style configuration for the text.
+   * @param {Group | null} group - The parent group for the text.
+   * @returns {Text} The created Text object.
    */
   text(x, y, text, style, group = null) {
     const parent = group || this.game.world;
@@ -56,18 +56,18 @@ export class GameObjectFactory {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @param {string} key - TBD.
-   * @param {Function | null} callback - TBD.
-   * @param {object | null} callbackContext - TBD.
-   * @param {string | null} overFrame - TBD.
-   * @param {string | null} outFrame - TBD.
-   * @param {string | null} downFrame - TBD.
-   * @param {string | null} upFrame - TBD.
-   * @param {Group | null} group - TBD.
-   * @returns {Button} TBD.
+   * Creates a new Button object.
+   * @param {number} x - The x coordinate of the button.
+   * @param {number} y - The y coordinate of the button.
+   * @param {string} key - The texture key for the button.
+   * @param {Function | null} callback - The function to call when the button is clicked.
+   * @param {object | null} callbackContext - The context to apply when calling the callback.
+   * @param {string | null} overFrame - The frame to display when the mouse is over the button.
+   * @param {string | null} outFrame - The frame to display when the mouse is not over the button.
+   * @param {string | null} downFrame - The frame to display when the button is pressed.
+   * @param {string | null} upFrame - The frame to display when the button is released.
+   * @param {Group | null} group - The parent group for the button.
+   * @returns {Button} The created Button object.
    */
   button(
     x,
@@ -88,11 +88,11 @@ export class GameObjectFactory {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @param {Group | null} group - TBD.
-   * @returns {Graphics} TBD.
+   * Creates a new Graphics object.
+   * @param {number} x - The x coordinate of the graphics object.
+   * @param {number} y - The y coordinate of the graphics object.
+   * @param {Group | null} group - The parent group for the graphics object.
+   * @returns {Graphics} The created Graphics object.
    */
   graphics(x = 0, y = 0, group = null) {
     const parent = group || this.game.world;
@@ -100,15 +100,15 @@ export class GameObjectFactory {
   }
 
   /**
-   * TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @param {string} font - TBD.
-   * @param {string} text - TBD.
-   * @param {number} size - TBD.
-   * @param {Group | null} group - TBD.
-   * @param {string} align - TBD.
-   * @returns {BitmapText} TBD.
+   * Creates a new BitmapText object.
+   * @param {number} x - The x coordinate of the bitmap text.
+   * @param {number} y - The y coordinate of the bitmap text.
+   * @param {string} font - The font key for the bitmap text.
+   * @param {string} text - The text content to display.
+   * @param {number} size - The font size.
+   * @param {Group | null} group - The parent group for the bitmap text.
+   * @param {string} align - The alignment of the text.
+   * @returns {BitmapText} The created BitmapText object.
    */
   bitmapText(x, y, font, text, size, group = null, align = 'left') {
     const parent = group || this.game.world;

package/src/phaser/core/frame.js

@@ -4,26 +4,26 @@ import { cloneFrame } from './frame_util.js';
 
 export class Frame {
   /**
-   * TBD.
-   * @param {number} index - TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @param {number} width - TBD.
-   * @param {number} height - TBD.
-   * @param {string} name - TBD.
+   * Creates a new Frame instance.
+   * @param {number} index - The index of this frame in the animation.
+   * @param {number} x - The x coordinate of this frame's position in the texture.
+   * @param {number} y - The y coordinate of this frame's position in the texture.
+   * @param {number} width - The width of this frame in pixels.
+   * @param {number} height - The height of this frame in pixels.
+   * @param {string} name - The name of this frame.
    */
   constructor(index, x, y, width, height, name) {
     this.initialize(index, x, y, width, height, name);
   }
 
   /**
-   * TBD.
-   * @param {number} index - TBD.
-   * @param {number} x - TBD.
-   * @param {number} y - TBD.
-   * @param {number} width - TBD.
-   * @param {number} height - TBD.
-   * @param {string} name - TBD.
+   * Initializes this frame with the specified properties.
+   * @param {number} index - The index of this frame in the animation.
+   * @param {number} x - The x coordinate of this frame's position in the texture.
+   * @param {number} y - The y coordinate of this frame's position in the texture.
+   * @param {number} width - The width of this frame in pixels.
+   * @param {number} height - The height of this frame in pixels.
+   * @param {string} name - The name of this frame.
    */
   initialize(index, x, y, width, height, name) {
     this.index = index;
@@ -49,9 +49,9 @@ export class Frame {
   }
 
   /**
-   * TBD.
-   * @param {number} width - TBD.
-   * @param {number} height - TBD.
+   * Resizes this frame to the specified dimensions.
+   * @param {number} width - The new width of this frame in pixels.
+   * @param {number} height - The new height of this frame in pixels.
    */
   resize(width, height) {
     this.width = width;
@@ -66,14 +66,14 @@ export class Frame {
   }
 
   /**
-   * TBD.
-   * @param {boolean} trimmed - TBD.
-   * @param {number} actualWidth - TBD.
-   * @param {number} actualHeight - TBD.
-   * @param {number} destX - TBD.
-   * @param {number} destY - TBD.
-   * @param {number} destWidth - TBD.
-   * @param {number} destHeight - TBD.
+   * Sets the trim properties for this frame.
+   * @param {boolean} trimmed - Whether this frame is trimmed.
+   * @param {number} actualWidth - The actual width of the trimmed frame.
+   * @param {number} actualHeight - The actual height of the trimmed frame.
+   * @param {number} destX - The destination x coordinate for the trimmed frame.
+   * @param {number} destY - The destination y coordinate for the trimmed frame.
+   * @param {number} destWidth - The destination width of the trimmed frame.
+   * @param {number} destHeight - The destination height of the trimmed frame.
    */
   setTrim(trimmed, actualWidth, actualHeight, destX, destY, destWidth, destHeight) {
     this.trimmed = trimmed;
@@ -90,17 +90,17 @@ export class Frame {
   }
 
   /**
-   * TBD.
-   * @returns {Frame} TBD.
+   * Creates a clone of this frame.
+   * @returns {Frame} A new Frame instance with the same properties.
    */
   clone() {
     return cloneFrame(this);
   }
 
   /**
-   * TBD.
-   * @param {Rectangle} output - TBD.
-   * @returns {Rectangle} TBD.
+   * Gets the rectangle bounds of this frame.
+   * @param {Rectangle} output - The rectangle to use for the result (optional).
+   * @returns {Rectangle} A Rectangle object representing this frame's bounds.
    */
   getRect(output = null) {
     const result = output || new Rectangle();

package/src/phaser/core/frame_data.js

@@ -2,7 +2,8 @@ import { cloneFrameData } from './frame_util.js';
 
 export class FrameData {
   /**
-   * TBD.
+   * Creates a new FrameData instance.
+   * This class holds data about frames in a texture atlas or sprite sheet.
    */
   constructor() {
     /**
@@ -16,9 +17,9 @@ export class FrameData {
   }
 
   /**
-   * TBD.
-   * @param {import('./frame.js').Frame} frame - TBD.
-   * @returns {import('./frame.js').Frame} TBD.
+   * Add a frame to the frame data collection.
+   * @param {import('./frame.js').Frame} frame - The frame to add.
+   * @returns {import('./frame.js').Frame} The added frame.
    */
   addFrame(frame) {
     frame.index = this._frames.length;
@@ -30,9 +31,9 @@ export class FrameData {
   }
 
   /**
-   * TBD.
-   * @param {number} index - TBD.
-   * @returns {import('./frame.js').Frame} TBD.
+   * Get a frame by its index.
+   * @param {number} index - The index of the frame to get.
+   * @returns {import('./frame.js').Frame} The frame at the specified index, or the first frame if index is out of bounds.
    */
   getFrame(index = 0) {
     if (index >= this._frames.length) {
@@ -42,9 +43,9 @@ export class FrameData {
   }
 
   /**
-   * TBD.
-   * @param {string} name - TBD.
-   * @returns {import('./frame.js').Frame} TBD.
+   * Get a frame by its name.
+   * @param {string} name - The name of the frame to get.
+   * @returns {import('./frame.js').Frame} The frame with the specified name, or null if not found.
    */
   getFrameByName(name) {
     if (typeof this._frameNames[name] === 'number') {
@@ -54,9 +55,9 @@ export class FrameData {
   }
 
   /**
-   * TBD.
-   * @param {string} name - TBD.
-   * @returns {boolean} TBD.
+   * Check if a frame with the given name exists.
+   * @param {string} name - The name of the frame to check.
+   * @returns {boolean} True if a frame with this name exists, false otherwise.
    */
   checkFrameName(name) {
     if (this._frameNames[name] == null) {
@@ -66,19 +67,19 @@ export class FrameData {
   }
 
   /**
-   * TBD.
-   * @returns {FrameData} TBD.
+   * Create a clone of this FrameData instance.
+   * @returns {FrameData} A new FrameData instance with cloned frames.
    */
   clone() {
     return cloneFrameData(this);
   }
 
   /**
-   * TBD.
-   * @param {number} start - TBD.
-   * @param {number} end - TBD.
-   * @param {import('./frame.js').Frame[]} output - TBD.
-   * @returns {import('./frame.js').Frame[]} TBD.
+   * Get a range of frames by index.
+   * @param {number} start - The starting index of the frame range.
+   * @param {number} end - The ending index of the frame range.
+   * @param {import('./frame.js').Frame[]} output - Optional array to populate with frames.
+   * @returns {import('./frame.js').Frame[]} An array of frames in the specified range.
    */
   getFrameRange(start, end, output = null) {
     const result = output || [];
@@ -89,11 +90,11 @@ export class FrameData {
   }
 
   /**
-   * TBD.
-   * @param {number[]|string[]} frames - TBD.
-   * @param {boolean} useNumericIndex - TBD.
-   * @param {number[]} output - TBD.
-   * @returns {number[]} TBD.
+   * Get frame indexes from an array of frame names or indices.
+   * @param {number[]|string[]} frames - An array of frame names or indices.
+   * @param {boolean} useNumericIndex - Whether to treat numeric values as frame indices.
+   * @param {number[]} output - Optional array to populate with frame indexes.
+   * @returns {number[]} An array of frame indexes.
    */
   getFrameIndexes(frames, useNumericIndex = true, output = null) {
     const result = output || [];
@@ -114,7 +115,8 @@ export class FrameData {
   }
 
   /**
-   * TBD.
+   * Destroy this FrameData instance and clean up resources.
+   * This method clears internal arrays and releases references to frames.
    */
   destroy() {
     this._frames = null;
@@ -122,8 +124,8 @@ export class FrameData {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Get the total number of frames in this FrameData instance.
+   * @returns {number} The total number of frames.
    */
   get total() {
     return this._frames.length;

package/src/phaser/core/frame_util.js

@@ -2,10 +2,10 @@ import { Frame } from './frame.js';
 import { FrameData } from './frame_data.js';
 
 /**
- * TBD.
- * @param {Frame} frame - TBD.
- * @param {Frame} output - TBD.
- * @returns {Frame} TBD.
+ * Clone a Frame object.
+ * @param {Frame} frame - The frame to clone.
+ * @param {Frame} output - Optional output frame to populate.
+ * @returns {Frame} The cloned frame or the provided output frame.
  */
 export const cloneFrame = (frame, output = null) => {
   const result = output || new Frame(frame.index, frame.x, frame.y, frame.width, frame.height);
@@ -14,10 +14,10 @@ export const cloneFrame = (frame, output = null) => {
 };
 
 /**
- * TBD.
- * @param {FrameData} frameData - TBD.
- * @param {FrameData} output - TBD.
- * @returns {FrameData} TBD.
+ * Clone a FrameData object.
+ * @param {FrameData} frameData - The frame data to clone.
+ * @param {FrameData} output - Optional output frame data to populate.
+ * @returns {FrameData} The cloned frame data or the provided output frame data.
  */
 export const cloneFrameData = (frameData, output = null) => {
   const result = output || new FrameData();

package/src/phaser/core/game.js

@@ -21,8 +21,24 @@ import { World } from './world.js';
 
 export class Game {
   /**
-   * TBD.
-   * @param {object} gameConfig - TBD.
+   * Creates a new Game instance.
+   * @param {object} gameConfig - The configuration object for the game.
+   * @param {number} gameConfig.width - The width of the game canvas (default: 800).
+   * @param {number} gameConfig.height - The height of the game canvas (default: 600).
+   * @param {string} gameConfig.backgroundColor - The background color of the canvas (default: 0x000000).
+   * @param {string} gameConfig.canvasID - The ID of the canvas element (default: '').
+   * @param {object} gameConfig.canvasStyle - CSS styles to apply to the canvas.
+   * @param {number} gameConfig.resolution - The resolution scale factor (default: 1).
+   * @param {boolean} gameConfig.transparent - Whether the canvas should be transparent (default: false).
+   * @param {boolean} gameConfig.antialias - Whether to enable antialiasing (default: false).
+   * @param {boolean} gameConfig.preserveDrawingBuffer - Whether to preserve the drawing buffer (default: false).
+   * @param {boolean} gameConfig.clearBeforeRender - Whether to clear the canvas before rendering (default: true).
+   * @param {boolean} gameConfig.roundPixels - Whether to round pixel values (default: true).
+   * @param {number} gameConfig.renderType - The rendering type to use (default: RENDER_AUTO).
+   * @param {boolean} gameConfig.isForceDisabledAudio - Whether to force disable audio (default: false).
+   * @param {number} gameConfig.maxParallelDownloads - Maximum parallel downloads (default: 16).
+   * @param {string|HTMLElement} gameConfig.parent - The parent element to append the canvas to.
+   * @param {object} gameConfig.state - The initial state object or class.
    */
   constructor(gameConfig = {}) {
     if (!window.PhaserRegistry) {
@@ -53,7 +69,7 @@ export class Game {
     this.logger = null;
     /** @type {HTMLCanvasElement} */
     this.canvas = null;
-    /** @type {RenderingContext} */
+    /** @type {CanvasRenderingContext2D | ImageBitmapRenderingContext | WebGLRenderingContext | WebGL2RenderingContext} */
     this.context = null;
     this.onPause = new Signal();
     this.onResume = new Signal();
@@ -77,7 +93,7 @@ export class Game {
   }
 
   /**
-   * TBD.
+   * Boots the game and initializes all systems.
    */
   boot() {
     if (this.isBooted) {
@@ -113,7 +129,7 @@ export class Game {
   }
 
   /**
-   * TBD.
+   * Creates the renderer canvas element.
    */
   createRendererCanvas() {
     this.logger.info('createRendererCanvas');
@@ -136,7 +152,7 @@ export class Game {
   }
 
   /**
-   * TBD.
+   * Initializes the renderer and sets up the rendering context.
    */
   initRenderer() {
     let isWebGlReady = false;
@@ -184,10 +200,10 @@ export class Game {
   }
 
   /**
-   * TBD.
-   * @param {object} config - TBD.
-   * @param {string} key - TBD.
-   * @param {*} defaultValue - TBD.
+   * Parses a configuration element and sets it on the game config.
+   * @param {object} config - The configuration object to parse from.
+   * @param {string} key - The configuration key to parse.
+   * @param {*} defaultValue - The default value if the key is not found in config.
    */
   parseConfigElement(config, key, defaultValue) {
     if (config[key] !== undefined) {
@@ -198,8 +214,8 @@ export class Game {
   }
 
   /**
-   * TBD.
-   * @param {object} config - TBD.
+   * Parses the configuration object and sets up game properties.
+   * @param {object} config - The configuration object to parse.
    */
   parseConfig(config) {
     this.logger = config.logger ?? new Logger('phaser');
@@ -229,8 +245,8 @@ export class Game {
   }
 
   /**
-   * TBD.
-   * @param {WebGLContextEvent | Event} event - TBD.
+   * Called when the WebGL context is lost.
+   * @param {WebGLContextEvent | Event} event - The WebGL context loss event.
    */
   contextLost(event) {
     this.logger.info('contextLost', event);
@@ -241,8 +257,8 @@ export class Game {
   }
 
   /**
-   * TBD.
-   * @param {WebGLContextEvent | Event} event - TBD.
+   * Called when the WebGL context is restored.
+   * @param {WebGLContextEvent | Event} event - The WebGL context restore event.
    */
   contextRestored(event) {
     this.logger.info('contextRestored', event);
@@ -254,8 +270,8 @@ export class Game {
   }
 
   /**
-   * TBD.
-   * @param {number} time - TBD.
+   * Updates the game state.
+   * @param {number} time - The current timestamp.
    */
   update(time) {
     this.time.update(time);
@@ -278,7 +294,7 @@ export class Game {
   }
 
   /**
-   * TBD.
+   * Destroys the game and cleans up all resources.
    */
   destroy() {
     this.logger.info('destroy');

package/src/phaser/core/input_pointer.js

@@ -19,8 +19,10 @@ export class Pointer {
   constructor(game, id, pointerMode) {
     this.game = game;
     this.id = id;
+    /** @type {number} */
     this.type = POINTER;
     this.exists = true;
+    /** @type {number} */
     this.identifier = 0;
     this.pointerId = null;
     this.pointerMode = pointerMode || POINTER_CURSOR | POINTER_CONTACT;
@@ -28,27 +30,43 @@ export class Pointer {
     this.button = null;
     this._holdSent = false;
     this._history = [];
+    /** @type {number} */
     this._nextDrop = 0;
     this._stateReset = false;
     this.withinGame = false;
     this.clientX = -1;
+    /** @type {number} */
     this.clientY = -1;
+    /** @type {number} */
     this.pageX = -1;
+    /** @type {number} */
     this.pageY = -1;
+    /** @type {number} */
     this.screenX = -1;
+    /** @type {number} */
     this.screenY = -1;
+    /** @type {number} */
     this.rawMovementX = 0;
+    /** @type {number} */
     this.rawMovementY = 0;
+    /** @type {number} */
     this.movementX = 0;
+    /** @type {number} */
     this.movementY = 0;
+    /** @type {number} */
     this.x = -1;
+    /** @type {number} */
     this.y = -1;
     this.isMouse = id === 0;
     this.isDown = false;
     this.isUp = true;
+    /** @type {number} */
     this.timeDown = 0;
+    /** @type {number} */
     this.timeUp = 0;
+    /** @type {number} */
     this.previousTapTime = 0;
+    /** @type {number} */
     this.totalTouches = 0;
     this.msSinceLastClick = Number.MAX_VALUE;
     this.targetObject = null;